Уровни блоков

Уровни (levels) — каталоги, в которых движок ищет файлы блоков (.nu.ts, CSS, JS). Порядок уровней задаёт приоритет при переопределении: если блок есть на нескольких уровнях, шаблон .nu.ts берётся с более позднего. CSS и JavaScript собираются со всех уровней.

levels.json

Уровни заданы в config/levels.json:

["content", "blocks"]

Записи levels.json — каталоги относительно корня проекта. Первый из них также задаёт корень контента (см. внешние репозитории). Сначала движок добавляет уровни расширений, затем — уровни из этого файла. Типичный порядок поиска блоков:

Переопределение через уровни

Если блок button есть и в расширении, и в blocks/ сайта, движок выбирает тот, что на более позднем уровне. Так сайт переопределяет блоки расширений, не создавая ответвления репозитория расширения:

уровень 0: nuckty-ext-block-root/blocks/root/root.nu.ts   (базовый root)
уровень 1: blocks/root/root.nu.ts                          (переопределение сайта)

При сборке движок выбирает blocks/root/root.nu.ts с более позднего уровня — версию сайта. Порядок уровней и есть приоритет.

Уровни расширений

block-расширение поставляет свои блоки в каталоге blocks/. Движок добавляет этот каталог как уровень через env.levels.add(dir):

import { fileURLToPath } from 'node:url';
import type { NucktyEnv } from 'nuckty';

export function register(env: NucktyEnv): void {
    env.levels.add(fileURLToPath(new URL('../blocks/', import.meta.url)));
}

Движок загружает блоки расширения по зависимостям, как и блоки сайта. Подробнее — block-расширение.

Поиск файла блока

Когда зависимости требуют блок menu, движок ищет <уровень>/menu/menu.nu.ts и загружает только последний найденный файл. Декларации предыдущего файла не сохраняются автоматически: next() работает лишь с декларациями, зарегистрированными в текущей коллекции. Для дополнения базового шаблона явно вызовите его функцию регистрации в своём файле; см. устройство блока.

CSS и JS собираются из файлов объявленного блока на всех уровнях. Для CSS действует обычный каскад: поздние правила могут переопределять ранние, но конфликты не исключаются. Файлы JS всех уровней включаются в бандл.

Имя файла совпадает с именем блока, имя каталога — тоже, поэтому движок находит блок по имени:

blocks/
  menu/
    menu.nu.ts
    menu.css
    menu.bemdecl.js
  button/
    button.nu.ts
    button.css

Зачем нужны уровни

Уровни дают основу переопределения в БЭМ: базовый блок приходит с раннего уровня, а сайт добавляет свою версию на более позднем. Без уровней расширение не могло бы поставлять блоки, а сайт — переопределять их. Так расширяемость и переопределение разделены: расширение даёт базу, сайт при необходимости заменяет её своей версией.