Архитектура GriffinJS

Ядро и реестры

Ядро не знает ни одного виджета. Оно держит два реестра — GriffinJS.engines и GriffinJS.widgets, — куда модули регистрируются, а не патчат его: defineEngine(name, factory) и defineWidget(name, factory). Ядро монтирует виджеты на элементы с data-gr-<виджет> и ведёт жизненный цикл: start() поднимает всё, destroy() снимает всё до последнего атрибута.

Участник жизненного цикла (G.use) кроме start и destroy может объявить init(root): ядро зовёт его после подъёма виджетов в корне — на старте и на каждой порции сканера. На этом стоит догрузка бандла полей — griffinjs-loader.js, общая часть вне ядра: единственное, что она знает поимённо, — не виджет, а файл поставки, девять имён второго бандла griffinjs-fields.js (список тот же, что в сборке, и тест сверяет их). Встретив data-gr-<поле> без зарегистрированного виджета, она вставляет <script> из GriffinJS.config.fields = { src, countries } — или из data-fields / data-countries на теге — один раз, с nonce с тега, и поднимает поля после загрузки; без config предупреждает раз на имя. Ядро по-прежнему не знает, что делает маска, — и даже откуда её взять: оно даёт хук и объект config. Подробно — «Догрузка по потребности».

GriffinJS.defineWidget('counter', function (el, opts, G) {
  var attrs = G.recorder();        // всё, что ставится на элементы, снимется restore()
  var events = G.listeners();      // все подписки снимутся removeAll()

  attrs.set(el, 'data-gr-state', 'ready');
  events.add(el, 'click', function () { /* … */ });

  return { destroy: function () { events.removeAll(); attrs.restore(); } };
});

GriffinJS.mount(el, 'counter', { step: 2 });   // или <div data-gr-counter="step: 2">
GriffinJS.instance(el, 'counter');             // живой экземпляр
GriffinJS.unmount(el, 'counter');

Прогресс как валюта: motion

Всё движение в слое сводится к одному числу — прогрессу 0…1 между двумя состояниями, который публикуется на элементе как --gr-progress. Источники разные, потребитель их не знает:

Отсюда главный запрет слоя: JS никогда не пишет transform и opacity. Иначе fade и параллакс стали бы нестилизуемыми — эффект был бы зашит в скрипт, а не открыт в CSS. Проверка стоит в check-dist по исходникам.

Дорожка: состояние и движок

track разделён на состояние — индекс, число слайдов, цикл, страницы, синхронизация с другой дорожкой, aria, клавиатура, inert неактивных — и движок за интерфейсом из трёх частей:

engine = {
  goTo(index, { instant }),   // доехать до слайда
  onChange(index, progress),  // сообщить дорожке, где мы
  layout()                    // пересчитать геометрию (брейкпоинт, мутация)
};

Индекс дорожки виртуальный: он никогда не равен позиции в DOM, между ними всегда physical(index). Поэтому бесконечная прокрутка — режим дорожки, а не движок: у scroll это клоны краёв и мгновенный перескок, у fade — индекс по модулю. Движок объявляет engine.loop; без него loop честно вырождается в rewind.

Шесть требований к дорожке для iOS Safari — в спецификации, не «по жалобам»: scrollend только за 'onscrollend' in window, плавность только из JS, очередь команд на время инерционного жеста, overscroll-behavior-x: contain, перепривязка после мутации, inert на неактивных слайдах.

Второй вектор: контроллеры поверх платформы

«Показать, спрятать, позиционировать» для окон и выпадающего делает платформа — <dialog> и popover. Различия между дропдауном, комбобоксом и мегаменю лежат в ролях и клавиатуре, не в показе, поэтому общего «класса окна» в слое нет: каждый контроллер — тонкая обёртка над примитивом, добавляющая то, чего у него нет (наведение с задержкой, роли, стек, hash, ajax).

Положение панели в верхнем слое считается в JS — core/anchor.js, getBoundingClientRect → top/left, переворот при нехватке места. CSS anchor positioning зависимостью не является, развилки @supports в слое нет: в Firefox и Chromium панель стоит одинаково. Эта часть лежит в core/, но в griffinjs-core.js не входит: нужна она только дропдауну и подсказке — см. «Модульную сборку» ниже.

Контракт с CSS

Оформление привязывается к состояниям: .gr-slide[aria-current], [data-gr-state="open"], var(--gr-progress). Стили контроллеров в griffinjs.css стоят под [data-gr-state] — без скрипта состояния нет, и правила компонентов ui не тронуты.

Инварианты

1. Состояние дорожки не выводится из scrollLeft нигде, кроме движка scroll.
2. JS не пишет transform и opacity.
3. Модуль регистрируется в реестре, а не патчит ядро.
4. Ни одной развилки по User-Agent; по возможностям — только 'onscrollend' in window; указатель — по pointerType события.
5. Разметка без скрипта остаётся рабочей: у каждого виджета есть «база без JS».
6. Всё, что рантайм ставит на элемент, снимается destroy().
7. JS читает только data-gr-* и пишет только состояния. Расширение, объявленное явно: поля второго бандла — маска, телефон, дата, сумма, одноразовый код, файл, мультивыбор комбобокса — пишут value контрола (иначе форматировать набранное нельзя). Договор такого поля: после каждой своей записи оно шлёт input, а по уходу фокуса change; не пишет в контрол, на котором не смонтировано; destroy() возвращает нативный тип, имя и значение. Второе расширение: поле, пишущее value, пишет и валидность контрола — маска ставит setCustomValidity на недоборе и aria-invalid по уходу фокуса, дата так же помечает невозможное значение и выход за границы, сумма — выход за границы через спутник type="number", — и destroy() возвращает валидность вместе со значением. Третье: виджет пишет min/max чужого поля только через собственный API соседа (limit у пары дат «с — по»), и авторская граница при этом остаётся, если она уже. Кто форматирует набранное, тот отвечает и за то, отправится ли оно. Ввод оценки расширением не является — он пишет --gr-rating, число для CSS, которое разрешает второй инвариант.

Модульная сборка и размеры

Исходники — ES2020 без модулей, самодостаточные IIFE; склейка в порядке списка без бандлера, затем terser. На выходе griffinjs.js целиком, griffinjs-core.js и по файлу на движок, общую часть и виджет — подключаются после ядра в любом наборе.

В ядре — только то, чем пользуются все. Дорожка нужна трём виджетам из двенадцати, анимация — двум, жест — одному движку, медиазапросы — одному виджету: держать их в ядре значило бы брать плату со всех за то, чем пользуется меньшинство. Каждая такая часть уезжает своим файлом, а что модуль из них берёт, он объявляет сам — вторым аргументом defineWidget ({ needs: ['track', 'motion'] }) или G.needs(), если модуль ничего не регистрирует. На старте start() сверяет объявленное со сборкой и предупреждает в консоли: отказ из-за забытого файла обязан быть слышен, а не проявиться у читателя страницы. Новая общая возможность кладётся в SHARED и переезжает в ядро, только когда ею пользуются все. Таблица «виджет → что подключить» на странице «Слой GriffinJS» собрана из этих объявлений при сборке.

Ориентиры измерены 2026-08-30 (gzip уровня 9): uikit.min.js — 49,4 КБ, uikit-core.min.js — 33,1 КБ, swiper-bundle.min.js — 41,0 КБ плюс 4,7 КБ своего CSS. Слой легче полного UIkit в 2,6 раза на потолке, набор слайдера легче связки Swiper в 5,9 раза. Потолок полного файла рос только под названные покупки: сортируемая таблица (724 Б), мультивыбор в комбобоксе (+495 Б — единственная правка старого бандла ради полей: сами поля лежат вторым файлом со своими потолками), затем 19,3 КБ под догрузку бандла полей (общей частью, не ядром), закрытие <details> с анимацией темы у мегаменю и дропдауна и плавный рост окна. У ядра и набора слайдера запаса нет: рост в них не планируется, новая общая возможность кладётся в общие модули, а не в ядро — так и легла догрузка полей, ядру достались 37 Б хука. Бюджеты проверяет check-dist; слой в griffincss-all.js не входит и в бюджет рантаймов не считается.

Проверка

Состояние, разбор параметров и синхронизация проверяются на node:test с мок-DOM без зависимостей; клавиатура, фокус в верхнем слое и snap — Playwright на трёх движках по странице-полигону «Полигон», включая прогон с заблокированным griffinjs.js: каждый пример без бейджа обязан работать и так.