Узлы

Модель узлов

Что общего у всех узлов, чем они различаются и где описан каждый из них.

Документ — это дерево узлов. Каждый узел есть три вещи: id, вид и правило, по которому получается содержимое.

<Paragraph          // the kind
  id="greeting"     // the address
>
  Dear {state.name},  {/* the rule */}
</Paragraph>

Разрешённый на ваших данных, он превращается в обычный JSON:

{ "id": "greeting", "kind": "paragraph", "mode": "static", "text": "Dear Adaeze Nkemelu," }

Ни стилей, ни вёрстки. Это дело рендерера.

Каталог

У каждого типа есть своя страница со всеми принимаемыми опциями и предпросмотром каждого способа записи.

export const Opening: Section = () => (
  <Section id="opening" title="Your renewal">
    <Greeting />
    <PriceChange />
  </Section>
);

export const Contents: TableOfContents = () => (
  <TableOfContents id="contents" title="What is in this letter" />
);

export const Greeting: Paragraph = () => {
  const [state] = useState((data: SampleData) => ({ name: data.memberName }));

  return <Paragraph id="greeting">Dear {state.name},</Paragraph>;
};

export const Signature: Image = () => {
  const [state] = useState((data: SampleData) => ({
    src: data.signatureUrl,
    manager: data.managerName,
  }));

  return (
    <Image
      id="signature"
      src={state.src}
      alt={`Signed by ${state.manager}`}
      width={180}
      height={60}
    />
  );
};

export const RenewalBanner: ShapeComponent = () => {
  const { date } = useFormat("en-GB");
  const [state] = useState((data: SampleData) => ({
    plan: data.plan,
    renewsOn: data.renewsOn,
  }));

  return (
    <Shape id="renewal-banner" variant="bannerAttention" height={44}>
      <Paragraph id="renewal-banner-line">
        {state.plan} renews on {date(state.renewsOn)}
      </Paragraph>
    </Shape>
  );
};

export const VisitsByMonth: Graph = () => {
  const [state] = useState((data: SampleData) => ({
    centreName: data.centreName,
    months: data.visitsByMonth.map((entry) => entry.month),
    visits: data.visitsByMonth.map((entry) => entry.visits),
  }));

  return (
    <Graph
      id="visits-by-month"
      title={`Visits to ${state.centreName}`}
      graphType="bar"
      valueAxisTitle="Visits"
      data={{
        categories: state.months,
        series: [{ label: "Visits", values: state.visits }],
      }}
      caption={`Your visits to ${state.centreName}, last six months`}
    />
  );
};

export const VisitLog: Table = () => {
  const { number } = useFormat("en-GB");
  const [state] = useState((data: SampleData) => ({ months: data.visitsByMonth }));

  return (
    <Table id="visit-log" columns={[{ width: "auto" }, { width: 28, align: "right" }]}>
      <Row header>
        <Cell>Month</Cell>
        <Cell>Visits</Cell>
      </Row>
      {state.months.map((entry) => (
        <Row>
          <Cell>{entry.month}</Cell>
          <Cell>{number(entry.visits)}</Cell>
        </Row>
      ))}
    </Table>
  );
};

Идентификаторы — это адреса

Идентификатор узла — то, чем эндпоинт генерации адресует именно этот абзац, и то, по чему два артефакта сборки выстраиваются друг против друга в диффе. Переименование ломает всё, что ссылается на узел извне, — ровно как переименование маршрута API.

Держите их уникальными в пределах документа. Это ничего не стоит и делает логи читаемыми.

Откуда берётся содержимое

У каждого узла есть либо его содержимое, либо промпты, чтобы его получить, и решает это компонент, а не какое-то объявление. Дайте абзацу текст — или Image его src, или Graph его data — и он разрешится на вашей машине. Дайте вместо этого промпты и заполнитель — и он будет заполнен во время запроса.

Оба разрешаются в один и тот же kind и различаются в собранном документе значением mode. mode — это выход, а не вход: сборка выводит его из того, что задал компонент, а пакет сообщает движку, какие узлы тому предстоит разрешить. Указать и то и другое на одном элементе — ошибка, а не подбрасывание монетки.

О слотах промптов и о том, что предпросмотр показывает на их месте, — как писать узлы.

Вложенность

section — сегодня единственный узел, содержащий дочерние, и он принимает любой вид, включая другие разделы. Следующим будет узел таблицы с узлами в ячейках, по тому же принципу: контейнеры содержат те компоненты, которые вы и так пишете, а не вторую модель содержимого рядом с ними.

Об этих предпросмотрах

Каждый предпросмотр здесь — настоящая сборка. В src/nodes/ репозитория этого сайта лежит по файлу на вариант, написанному против опубликованного пакета; шаг сборки разрешает каждый из них через buildDocument и отрисовывает тем же рендерером, который отдаёт dxcl dev. Показанный исходник — это тот файл, который выполнялся, а JSON — то, что вернулось. Поэтому такие страницы ломаются громко, а не устаревают тихо.

Изменить эту страницу на GitHub ↗ Читать эту страницу в Markdown