Каталог блоков: девять групп, один реестр

Каталог определяет, что может выразить документ страницы. Каждый блок — одна запись в реестре @fiberfx/content; contentRegistry() содержит их все.

Каталог

CATALOG — таблица каталога: девять групп и 51 имя в них. catalogEntries() возвращает сами зарегистрированные записи, добавляя одну внутреннюю часть Column, из которой строится Columns.

Каждая запись содержит пример, а exampleDocument(entry) превращает его в документ страницы с одним блоком. Проверка каталога в пакете разбирает каждый пример по contentSchema() и рендерит его; ни один результат не должен быть пустым или неподдерживаемым. Тот же обход можно выполнить самостоятельно:

import { catalogEntries, contentSchema, exampleDocument, renderDocument } from "@fiberfx/content";
import { parseDocument } from "@fiberfx/schema";

for (const entry of catalogEntries().filter((entry) => entry.group !== "Internal")) {
  const parsed = parseDocument(exampleDocument(entry), contentSchema());
  if (!parsed.ok) throw new Error(`${entry.name}: ${parsed.code} at ${parsed.path}`);
  const { report } = renderDocument(parsed.document, { mode: "preview", revision: 1 });
  console.log(entry.group, entry.name, entry.type, report.unsupported.length);
}

Что объявляет запись

BlockEntry содержит:

• name: имя в каталоге, например RichText display;
• group: одну из девяти групп либо Internal;
• type: тип блока, используемый документами, например rich-text;
• definition: схему, по которой проверяет @fiberfx/schema;
• capabilities: разрешения окружения, embed либо form; большинству блоков они не нужны;
• render: рендерер, вызываемый с { node, props, context };
• example: свойства и дочерние элементы слотов для проверки каталога.

В таблицах ниже ? отмечает необязательное свойство, число после текстового свойства — максимальную длину. Блок без слотов не содержит потомков.

Структура

Размеры задают отступы: sm — 12, md — 24, lg — 48, xl — 72. У Columns свойство reverse записывается в атрибуты data-reverse (по одному на переопределение точки перелома), которые может читать таблица стилей; DOM сохраняет порядок документа. Пока ни одна таблица стилей репозитория не читает эти атрибуты, поэтому сам по себе reverse раскладку не меняет; подробнее — в уроке о ссылках.

Текст

Свойство level заголовка задаёт его уровень в структуре. Визуальный size не выбирает этот уровень; если размер не задан, он следует уровню. Форматированный текст содержит только фрагменты и метки, без сырого HTML.

Медиа

Изображение не запрашивает свой ресурс. Если окружение не разрешило адрес, вместо изображения показывается текст alt с role="img"; декоративное изображение (пустой alt) без разрешённого адреса ничего не выводит. Встраивание во фрейм допускается только для абсолютного URL https, только при разрешённом окружением embed, с sandbox="allow-scripts" и без предоставления origin окружения. Если хотя бы одно из двух условий не выполнено, заголовок выводится ссылкой.

Навигация

Хлебные крошки — статическая разметка. Последний элемент обозначает текущую страницу (aria-current="page") и не бывает ссылкой.

Композиция

Button остаётся <a>: автор задаёт переход, поэтому это ссылка, выглядящая как кнопка.

Интерактивное содержимое

Все панели и слайды входят в статическую разметку, поэтому страница читается целиком без JavaScript. Tabs и Carousel сначала выводят ту же статическую форму, чтобы первый клиентский рендеринг совпадал. Карусель с autoAdvance переключается каждые 6 секунд и имеет переключатель паузы; при предпочтении уменьшенного движения она изначально приостановлена.

Формы

Свойство kind поля принимает text, email, tel, number, url, textarea, checkbox либо select. Форма отправляется нативно и только если окружение разрешило form и разрешило ссылку на маршрут. Иначе она сообщает «This form can't be sent from here.», отключает все поля и отклоняет отправку: ничего не загружается, не сохраняется и не имитируется. Состояние отправки state задаёт окружение после реальной отправки: сообщение об успехе имеет роль status, об ошибке — alert.

Содержимое на основе данных

Блок на основе данных показывает снимок сущности, разрешённый окружением, и не запрашивает его сам. Под заголовком отображается одно из четырёх состояний, записанное в data-state:

• error: сообщение об ошибке окружения с ролью alert;
• unavailable: ничего не разрешено — «This list isn't available right now.»;
• empty: в снимке нет элементов — «Nothing here yet.»;
• ready: элементы.

Редакционная страница

Ссылки автора

Каждый href, введённый автором (у кнопки, фрагмента форматированного текста, карточки, пункта навигации или хлебных крошек), проходит одну проверку; то же относится к каждому href в разрешённой коллекции. Относительные пути, фрагменты, запросы и ссылки http, https, mailto и tel сохраняются. Любая другая схема, адрес без схемы вида //host либо ссылка с управляющим символом отбрасываются; подпись выводится без href.