@feugene/granularity 0.18.0 → 0.20.0

package/dist/types/theme/extendTheme.d.ts

@@ -0,0 +1,63 @@
+import type { GrThemeName } from '../tokens/types';
+import { type GrThemeTokens } from './roles';
+import { type GrThemeIssue } from './validate';
+export interface GrTheme {
+    name: string;
+    /** Селектор, под которым тема объявлена: по умолчанию `[data-theme='<name>']`. */
+    selector: string;
+    /** Полный набор ролей: своё поверх базы. */
+    tokens: GrThemeTokens;
+    /** Покомпонентные токены темы, если заданы. */
+    componentTokens: GrThemeTokens;
+    /** Готовый CSS, включая фолбэк производных для браузеров без `color-mix`. */
+    css: string;
+}
+export interface ExtendThemeOptions {
+    name: string;
+    /** Готовая тема пакета, чужая тема или просто набор ролей. */
+    base: GrThemeName | GrTheme | GrThemeTokens;
+    selector?: string;
+    /** Что меняем. Всё, чего здесь нет, приходит из базы. */
+    tokens?: GrThemeTokens;
+    /**
+     * Покомпонентные токены (`--gr-button-primary-bg`) — у них своя природа:
+     * пакет держит для них отдельный слой и **не** наследует их между темами.
+     * Поэтому они не достраиваются из базы, а просто едут в тот же селектор:
+     * заданы — переопределены, не заданы — работает дефолт компонента.
+     */
+    componentTokens?: GrThemeTokens;
+    /**
+     * Проверка контраста и различимости тонов перед выдачей. Включена: тема,
+     * которая не читается, — это дефект, и узнать о нём на сборке дешевле, чем от
+     * пользователя. Выключать осознанно, для заведомо декоративных тем.
+     */
+    validate?: boolean;
+}
+export declare class GrThemeError extends Error {
+    issues: GrThemeIssue[];
+    constructor(name: string, issues: GrThemeIssue[]);
+}
+export declare function renderThemeCss(theme: Pick<GrTheme, 'name' | 'selector' | 'tokens'> & Partial<Pick<GrTheme, 'componentTokens'>>): string;
+/**
+ * Тема поверх готовой: объявляем только то, что меняем.
+ *
+ * Роль, которую тема не объявила, наследуется не от «своей» базы, а из `:root`,
+ * то есть из светлой темы: тёмная тема с забытой ролью получает светлое пятно.
+ * Поэтому здесь тема достраивается до полного набора **всех** ролей пакета — и
+ * роль, добавленная пакетом завтра, приедет в неё сама, без правок потребителя.
+ */
+export declare function extendTheme(options: ExtendThemeOptions): GrTheme;
+/**
+ * Тема с нуля: без базы, все роли свои.
+ *
+ * «Без базы» — это не «ни от чего не наследуется»: в CSS так нельзя. Роль,
+ * которую тема не объявила, придёт из `:root`, а `:root` — это **светлая тема
+ * пакета**. Независимой тема становится ровно тогда, когда объявляет все роли
+ * сама, и здесь это проверяется: не хватает — сборка падает со списком, а не
+ * молча подмешивает чужую палитру.
+ *
+ * Цена честная и её видно: `extendTheme` получает новую роль пакета
+ * автоматически, а тема с нуля — упадёт на следующей сборке и потребует решения.
+ * Это и есть смысл выбора: полный контроль в обмен на сопровождение.
+ */
+export declare function createTheme(options: Omit<ExtendThemeOptions, 'base'>): GrTheme;

package/dist/types/theme/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Композиция тем — `@feugene/granularity/theme`.
+ *
+ * Тема объявляет только то, что меняет: остальное приезжает из базы, а не из
+ * `:root` (то есть не из светлой темы, как было бы у CSS-файла с пропущенной
+ * ролью). Роль, добавленная пакетом завтра, попадёт в собранную тему сама.
+ *
+ * Точка входа сборочная: она тянет справочник токенов, и место ей в скрипте
+ * или конфиге, а не в бандле приложения. Подключение готового CSS в браузере —
+ * `@feugene/granularity/theme/apply`.
+ *
+ * Документация: `docs/theming.md`.
+ */
+export { createTheme, extendTheme, GrThemeError, renderThemeCss } from './extendTheme';
+export type { ExtendThemeOptions, GrTheme } from './extendTheme';
+export { GrToneError, tone } from './tone';
+export type { ToneOptions, ToneRole } from './tone';
+export { validateTheme } from './validate';
+export type { GrThemeIssue } from './validate';
+export { resolveRole, themeRoleNames } from './roles';
+export type { GrThemeTokens } from './roles';
+export { contrast, deltaE, mixSrgb } from './color';

package/dist/types/theme/roles.d.ts

@@ -0,0 +1,16 @@
+/** Значения ролей темы: `--gr-bg` → `#041e2b`. */
+export type GrThemeTokens = Record<string, string>;
+/** Роли, известные пакету, в порядке объявления. */
+export declare function themeRoleNames(): string[];
+/**
+ * Значение роли, годное для арифметики.
+ *
+ * Роль вправе ссылаться на другую (`--gr-invalid-brd: var(--gr-danger)`) — такую
+ * ссылку разворачиваем, иначе фолбэк и проверки считать не из чего. Всё, что не
+ * разворачивается в hex (`rgb(… / .45)` у подложки, `var()` за пределы темы),
+ * возвращается как `null`: посчитать нельзя, и выдумывать не надо.
+ *
+ * Цикл рвём с ошибкой: тема потребителя вправе ошибиться, и упасть надо с
+ * именами ролей, а не переполнением стека.
+ */
+export declare function resolveRole(tokens: GrThemeTokens, name: string, seen?: string[]): string | null;

package/dist/types/theme/tone.d.ts

@@ -0,0 +1,32 @@
+import type { GrThemeName } from '../tokens/types';
+import { type GrThemeTokens } from './roles';
+export type ToneRole = 'fill' | 'solid' | 'light' | 'text';
+export interface ToneOptions {
+    /** Тема, в которой тон будет жить: от неё зависят фон, текст и направление сдвигов. */
+    base: GrThemeName | {
+        tokens: GrThemeTokens;
+    } | GrThemeTokens;
+    /**
+     * Что выводить. По умолчанию — ровно те роли, которые у этого тона есть **в
+     * реестре пакета**: у `--gr-accent` это только `-fg`, у `--gr-primary` нет
+     * `-light`. Для имени, которого в реестре нет, выводится полная семья.
+     */
+    roles?: ToneRole[];
+}
+export declare class GrToneError extends Error {
+    constructor(role: string, actual: number, expected: number);
+}
+/**
+ * Семья ролей тона из одного цвета.
+ *
+ * Без неё композиция снимает только объём работы: перекрасив `--gr-success`, вы
+ * оставляете `-light`, `-text` и `-solid*` от базовой темы, и они расходятся с
+ * новым тоном по контрасту — ловушка №3 из `docs/theming.md`. Правила вывода
+ * взяты оттуда же (§«Суффиксы ролей»), пороги проверяются на каждом шаге:
+ * не вышло — падаем с именем роли, а не отдаём нечитаемое.
+ *
+ * ```ts
+ * extendTheme({ name: 'ocean', base: 'dark', tokens: { ...tone('success', '#3ddc97', { base: 'dark' }) } })
+ * ```
+ */
+export declare function tone(name: string, seed: string, options: ToneOptions): GrThemeTokens;

package/dist/types/theme/validate.d.ts

@@ -0,0 +1,16 @@
+import type { GrTheme } from './extendTheme';
+import { type GrThemeTokens } from './roles';
+export interface GrThemeIssue {
+    kind: 'contrast' | 'distance';
+    /** Роль, из-за которой всё встало. */
+    token: string;
+    /** На чём проверяли: поверхность либо второй тон. */
+    against: string;
+    actual: number;
+    expected: number;
+    message: string;
+}
+export declare function validateTheme(theme: GrTheme | {
+    name: string;
+    tokens: GrThemeTokens;
+}): GrThemeIssue[];

package/dist/types/tokens/types.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Типы справочника токенов. Данные генерируются (`generated.ts`), типы — нет:
+ * контракт описывает человек, значения — генератор.
+ */
+/** Имя темы, объявленной в `tokens/themes/*.json`. */
+export type GrThemeName = 'light' | 'dark';
+/** Значение токена в каждой теме. */
+export type GrTokenValues = Record<GrThemeName, string>;
+/** Примитив: не зависит от темы, живёт в `:root`. */
+export interface GrFoundationToken {
+    /** Полное имя CSS custom property, включая `--`. */
+    name: string;
+    value: string;
+    /** Заголовок группы, в которой токен объявлен (`Typography: font sizes`). */
+    section: string;
+    description: string;
+}
+/** Семантическая роль: своё значение в каждой теме. */
+export interface GrThemeToken {
+    name: string;
+    section: string;
+    description: string | null;
+    values: GrTokenValues;
+}
+/**
+ * Природа покомпонентного токена — она же отвечает на вопрос, что будет, если
+ * его не задать: `theme`/`css`/`inline` компонент присваивает сам, `hook` не
+ * присваивается нигде и работает дефолтом из `var(--gr-x, дефолт)`.
+ */
+export type GrComponentTokenKind = 'theme' | 'css' | 'inline' | 'hook';
+/**
+ * Точка кастомизации отдельного компонента. Источник — `tokens.json` рядом с
+ * его кодом; в CSS отсюда ничего не генерируется.
+ */
+export interface GrComponentToken {
+    /** Компонент-владелец (`GrTree`) либо `composables` для того, что ставит композабл. */
+    owner: string;
+    name: string;
+    kind: GrComponentTokenKind;
+    /** Значение, которое действует, пока токен не переопределён. */
+    default: string;
+    description: string;
+}
+/**
+ * Производное состояние: в CSS живёт формулой `color-mix`, а `values` — тот же
+ * результат, посчитанный заранее (он же уходит в `@supports not (color-mix)`).
+ */
+export interface GrDerivedToken {
+    name: string;
+    section: string;
+    description: string;
+    formula: string;
+    /**
+     * Слагаемые формулы отдельно от её текста: по ним пересчитывается фолбэк
+     * `@supports not (color-mix)` для темы, которой на момент сборки пакета не
+     * существовало (`extendTheme`).
+     */
+    base: string;
+    amount: number;
+    mixWith: string;
+    values: GrTokenValues;
+}

package/dist/web-types.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/JetBrains/web-types/master/schema/web-types.json",
   "name": "@feugene/granularity",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "framework": "vue",
   "js-types-syntax": "typescript",
   "description-markup": "markdown",
@@ -7024,11 +7024,11 @@
             },
             {
               "name": "icon",
-              "description": "UnoCSS-класс иконки вместо встроенной звезды (например `i-lucide-heart`).",
+              "description": "Символ вместо встроенной звезды: Vue-компонент либо класс иконки вашей UnoCSS-сборки (`'i-lucide-heart'` — тогда нужен ваш `presetIcons`, см. `docs/installation.md`).",
               "default": "undefined",
               "value": {
                 "kind": "expression",
-                "type": "string | undefined"
+                "type": "string | Component | undefined"
               }
             },
             {
@@ -7904,10 +7904,6 @@
                 "name": "update:open",
                 "description": "Панель открылась/закрылась (`v-model:open`)."
               },
-              {
-                "name": "visibleChange",
-                "description": "Панель открылась/закрылась."
-              },
               {
                 "name": "update:search",
                 "description": "Текст поиска как контролируемое значение (`v-model:search`)."
@@ -8554,11 +8550,11 @@
             },
             {
               "name": "icon",
-              "description": "UnoCSS-класс иконки слева от блока (например `i-lucide-users`).",
+              "description": "Иконка слева от блока: Vue-компонент либо класс иконки вашей UnoCSS-сборки (`'i-lucide-users'` — тогда нужен ваш `presetIcons`, см. `docs/installation.md`).",
               "default": "undefined",
               "value": {
                 "kind": "expression",
-                "type": "string | undefined"
+                "type": "string | Component | undefined"
               }
             },
             {
@@ -9852,18 +9848,20 @@
             },
             {
               "name": "expandIcon",
-              "default": "\"i-lucide-chevron-right\"",
+              "description": "Иконка свёрнутого узла: Vue-компонент либо класс иконки вашей UnoCSS-сборки (`'i-lucide-plus'` — тогда нужен ваш `presetIcons`, см. `docs/installation.md`). Не задана — встроенная стрелка.",
+              "default": "undefined",
               "value": {
                 "kind": "expression",
-                "type": "string | undefined"
+                "type": "string | Component | undefined"
               }
             },
             {
               "name": "collapseIcon",
-              "default": "\"i-lucide-chevron-right\"",
+              "description": "Иконка раскрытого узла. Не задана — та же встроенная стрелка, повёрнутая.",
+              "default": "undefined",
               "value": {
                 "kind": "expression",
-                "type": "string | undefined"
+                "type": "string | Component | undefined"
               }
             },
             {
@@ -10036,10 +10034,11 @@
             },
             {
               "name": "dragHandleIcon",
-              "default": "\"i-lucide-grip-vertical\"",
+              "description": "Иконка ручки переноса: компонент, класс иконки или ничего — тогда встроенная.",
+              "default": "undefined",
               "value": {
                 "kind": "expression",
-                "type": "string | undefined"
+                "type": "string | Component | undefined"
               }
             },
             {
@@ -10417,10 +10416,6 @@
                 "name": "update:open",
                 "description": "Панель открылась/закрылась (`v-model:open`)."
               },
-              {
-                "name": "visibleChange",
-                "description": "Панель открылась/закрылась."
-              },
               {
                 "name": "clear"
               },