@feugene/granularity 0.18.0 → 0.19.0

package/dist/types/src/components/GrBreadcrumbs/grBreadcrumbsStyles.d.ts

@@ -7,8 +7,11 @@ export type GrBreadcrumbItem = {
     href?: string;
     /** Цель роутерной ссылки: уезжает в `GrLink` через `attrs` вместе с `as`. */
     to?: unknown;
-    /** Класс иконки перед подписью (`i-lucide-*`) — иконка декоративна. */
-    icon?: string;
+    /**
+     * Иконка перед подписью — декоративна. Vue-компонент либо класс иконки вашей
+     * UnoCSS-сборки (`i-lucide-*` требует вашего `presetIcons`).
+     */
+    icon?: string | Component;
     disabled?: boolean;
     /** Доступное имя пункта, когда подписи недостаточно («Настройки» → «Настройки проекта»). */
     ariaLabel?: string;

package/dist/types/src/components/GrCommandPalette/GrCommandPalette.vue.d.ts

@@ -64,18 +64,18 @@ import './defaults';
 declare function open(): void;
 declare function close(): void;
 declare function toggle(): void;
-declare var __VLS_15: {
+declare var __VLS_25: {
     item: GrCommandItem;
     active: boolean;
-}, __VLS_22: {
+}, __VLS_37: {
     query: string;
-}, __VLS_24: {};
+}, __VLS_39: {};
 type __VLS_Slots = {} & {
-    item?: (props: typeof __VLS_15) => any;
+    item?: (props: typeof __VLS_25) => any;
 } & {
-    empty?: (props: typeof __VLS_22) => any;
+    empty?: (props: typeof __VLS_37) => any;
 } & {
-    footer?: (props: typeof __VLS_24) => any;
+    footer?: (props: typeof __VLS_39) => any;
 };
 declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToOption<GrCommandPaletteProps>, {
     items: undefined;

package/dist/types/src/components/GrCommandPalette/filtering.d.ts

@@ -1,11 +1,15 @@
+import type { Component } from 'vue';
 /** Команда палитры. `id` обязателен — он же ключ рендера и цель `aria-activedescendant`. */
 export type GrCommandItem = {
     id: string;
     label: string;
     /** Пояснение под меткой. */
     description?: string;
-    /** UnoCSS-класс иконки (например `i-lucide-file-plus`). */
-    icon?: string;
+    /**
+     * Иконка команды: Vue-компонент либо класс иконки вашей UnoCSS-сборки
+     * (`'i-lucide-file-plus'` — тогда нужен ваш `presetIcons`).
+     */
+    icon?: string | Component;
     /** Подсказка сочетания клавиш — массив клавиш, каждая рисуется отдельным `GrKbd`. */
     shortcut?: string[];
     /** Заголовок группы, под которой команда показывается в списке. */

package/dist/types/src/components/GrDataTable/grDataTableStyles.d.ts

@@ -18,7 +18,6 @@ export declare const placeholderPaddings: Record<GrDataTableSize, string>;
  */
 export declare const columnHandleClass = "inline-flex shrink-0 cursor-grab items-center text-[var(--gr-datatable-drag-handle,var(--gr-muted-fg))] opacity-0 [touch-action:none] transition-opacity duration-[var(--gr-duration-fast)] focus:outline-none focus-visible:opacity-100 focus-visible:ring-2 focus-visible:ring-[var(--gr-ring)] rounded-[var(--gr-radius-sm)] group-hover:opacity-100";
 export declare const columnHandleActiveClass = "opacity-100";
-export declare const columnHandleIconClass = "i-lucide-grip-vertical block";
 /** Переносимая колонка гасится, чтобы было видно, что она «поднята». */
 export declare const columnDraggingClass = "bg-[var(--gr-muted)]";
 /**

package/dist/types/src/components/GrRating/GrRating.vue.d.ts

@@ -1,3 +1,4 @@
+import { type Component } from 'vue';
 import { type GrRatingSize, type GrRatingTone } from './grRatingStyles';
 export type { GrRatingSize, GrRatingTone, } from './grRatingStyles';
 /**
@@ -10,7 +11,7 @@ export type { GrRatingSize, GrRatingTone, } from './grRatingStyles';
  *
  * Символ по умолчанию рисуется инлайновым SVG (звезда с `fill="currentColor"`) —
  * иконочные шрифты-маски `i-lucide-star` дают только контур. Свой символ
- * задаётся пропом `icon` (UnoCSS-класс иконки) или слотом `#symbol`.
+ * задаётся пропом `icon` (Vue-компонент или класс иконки) либо слотом `#symbol`.
  */
 export interface GrRatingProps {
     /** Текущая оценка. Дробная (`3.5`) поддерживается при `allowHalf`. */
@@ -31,8 +32,12 @@ export interface GrRatingProps {
     required?: boolean;
     /** Повторный клик по текущей оценке сбрасывает её в `0`. */
     clearable?: boolean;
-    /** UnoCSS-класс иконки вместо встроенной звезды (например `i-lucide-heart`). */
-    icon?: string;
+    /**
+     * Символ вместо встроенной звезды: Vue-компонент либо класс иконки вашей
+     * UnoCSS-сборки (`'i-lucide-heart'` — тогда нужен ваш `presetIcons`,
+     * см. `docs/installation.md`).
+     */
+    icon?: string | Component;
     /** Показывать числовую подпись справа от шкалы. */
     showText?: boolean;
     /** Формат подписи. По умолчанию — само значение. Сильнее `texts`. */
@@ -131,7 +136,7 @@ declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPro
     tone: GrRatingTone;
     size: GrRatingSize;
     clearable: boolean;
-    icon: string;
+    icon: string | Component;
     readonly: boolean;
     name: string;
     invalid: boolean;

package/dist/types/src/components/GrSortableList/grSortableListStyles.d.ts

@@ -28,7 +28,6 @@ export declare const emptyClass = "px-4 py-6 text-center text-[length:var(--gr-t
  */
 export declare const handleClass = "flex shrink-0 items-center justify-center rounded-[var(--gr-radius-sm)] text-[var(--gr-sortable-handle-color,var(--gr-muted-fg))] size-[var(--gr-sortable-handle-size,1.5rem)] cursor-grab [touch-action:none] focus:outline-none";
 export declare const handleDisabledClass = "cursor-not-allowed text-[var(--gr-muted-fg)]";
-export declare const handleIconClass = "i-lucide-grip-vertical";
 export declare const contentClass = "min-w-0 flex-1 text-[length:var(--gr-text-sm)]";
 /**
  * Куда встанет строка — псевдоэлемент самой строки, а не отдельный узел:

package/dist/types/src/components/GrStatistic/GrStatistic.vue.d.ts

@@ -29,8 +29,11 @@ export interface GrStatisticProps {
     prefix?: string;
     /** Приписка после значения (единица измерения, `%`). */
     suffix?: string;
-    /** UnoCSS-класс иконки слева от блока (например `i-lucide-users`). */
-    icon?: string;
+    /**
+     * Иконка слева от блока: Vue-компонент либо класс иконки вашей UnoCSS-сборки
+     * (`'i-lucide-users'` — тогда нужен ваш `presetIcons`, см. `docs/installation.md`).
+     */
+    icon?: string | Component;
     size?: GrStatisticSize;
     /** Тон значения; точечно перекрывается `--gr-statistic-value-color`. */
     tone?: GrStatisticTone;
@@ -61,19 +64,19 @@ export interface GrStatisticProps {
 export interface GrStatisticEmits {
     (e: 'click', event: MouseEvent): void;
 }
-declare var __VLS_10: {}, __VLS_18: {}, __VLS_37: {}, __VLS_39: {}, __VLS_41: {}, __VLS_43: {};
+declare var __VLS_10: {}, __VLS_23: {}, __VLS_42: {}, __VLS_44: {}, __VLS_46: {}, __VLS_48: {};
 type __VLS_Slots = {} & {
     icon?: (props: typeof __VLS_10) => any;
 } & {
-    title?: (props: typeof __VLS_18) => any;
+    title?: (props: typeof __VLS_23) => any;
 } & {
-    prefix?: (props: typeof __VLS_37) => any;
+    prefix?: (props: typeof __VLS_42) => any;
 } & {
-    default?: (props: typeof __VLS_39) => any;
+    default?: (props: typeof __VLS_44) => any;
 } & {
-    suffix?: (props: typeof __VLS_41) => any;
+    suffix?: (props: typeof __VLS_46) => any;
 } & {
-    trend?: (props: typeof __VLS_43) => any;
+    trend?: (props: typeof __VLS_48) => any;
 };
 declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToOption<GrStatisticProps>, {
     title: undefined;
@@ -121,7 +124,7 @@ declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPro
     tone: GrStatisticTone;
     size: GrStatisticSize;
     title: string;
-    icon: string;
+    icon: string | Component;
     animate: boolean;
     href: string;
     loading: boolean;

package/dist/types/src/components/GrStatistic/grStatisticStyles.d.ts

@@ -17,7 +17,6 @@ export declare const statisticPlaceholderHeightBySize: Record<GrStatisticSize, s
 export declare const statisticTrendSizeBySize: Record<GrStatisticSize, string>;
 export declare const statisticValueClassByTone: Record<GrStatisticTone, string>;
 export declare const statisticTrendClassByTrend: Record<GrStatisticTrend, string>;
-export declare const statisticTrendIconByTrend: Record<GrStatisticTrend, string>;
 export declare const statisticTitleClass = "font-medium tracking-wide text-[var(--gr-statistic-title-color,var(--gr-muted-fg))]";
 export declare const statisticRootBase = "flex items-start gap-3 text-left";
 /**

package/dist/types/src/components/GrTabs/GrTabs.vue.d.ts

@@ -1,10 +1,14 @@
+import { type Component } from 'vue';
 import { type GrTabsOrientation, type GrTabsSize, type GrTabsVariant } from './grTabsStyles';
 export interface GrTab {
     value: string;
     label: string;
     badge?: string;
-    /** UnoCSS-класс иконки слева от подписи (например `i-lucide-user`). */
-    icon?: string;
+    /**
+     * Иконка слева от подписи: Vue-компонент либо класс иконки вашей UnoCSS-сборки
+     * (`'i-lucide-user'` — тогда нужен ваш `presetIcons`, см. `docs/installation.md`).
+     */
+    icon?: string | Component;
     disabled?: boolean;
     /** Перекрывает `closable` ряда в обе стороны: закрепить вкладку или закрыть одну её. */
     closable?: boolean;

package/dist/types/src/components/GrTree/grTreeProps.d.ts

@@ -1,4 +1,4 @@
-import type { HTMLAttributes } from 'vue';
+import type { Component, HTMLAttributes } from 'vue';
 import type { GrTreeSize } from './grTreeStyles';
 import type { GrTreeAllowDropType, GrTreeKey, GrTreeNode } from './grTreeTypes';
 export type NodeKeyProp<T extends object> = Extract<keyof T, string>;
@@ -71,8 +71,14 @@ export type GrTreeViewProps<T extends object> = {
     /** Максимальная высота дерева со своим скроллером. Число — пиксели. */
     maxHeight?: number | string;
     highlightCurrent?: boolean;
-    expandIcon?: string;
-    collapseIcon?: string;
+    /**
+     * Иконка свёрнутого узла: Vue-компонент либо класс иконки вашей UnoCSS-сборки
+     * (`'i-lucide-plus'` — тогда нужен ваш `presetIcons`, см. `docs/installation.md`).
+     * Не задана — встроенная стрелка.
+     */
+    expandIcon?: string | Component;
+    /** Иконка раскрытого узла. Не задана — та же встроенная стрелка, повёрнутая. */
+    collapseIcon?: string | Component;
     toggleIconRotate?: boolean;
     branchLine?: boolean;
     branchLineColor?: GrTreeBranchLineColor<T>;
@@ -96,7 +102,8 @@ export type GrTreeInteractionProps<T extends object> = {
     /** На каждом уровне раскрыт максимум один узел. */
     accordion?: boolean;
     draggable?: boolean;
-    dragHandleIcon?: string;
+    /** Иконка ручки переноса: компонент, класс иконки или ничего — тогда встроенная. */
+    dragHandleIcon?: string | Component;
     allowDrop?: (draggingNode: GrTreeNode<T>, dropNode: GrTreeNode<T>, type: GrTreeAllowDropType) => boolean;
     allowDrag?: (draggingNode: GrTreeNode<T>) => boolean;
 };

package/dist/types/src/components/GrTree/safelist.d.ts

@@ -1 +1 @@
-export declare const grTreeSafelist: readonly ["i-lucide-chevron-right", "i-lucide-grip-vertical"];
+export declare const grTreeSafelist: readonly [];

package/dist/types/src/components/shared/icon.d.ts

@@ -0,0 +1,13 @@
+import type { Component } from 'vue';
+/**
+ * Иконку компонент получает двумя способами, и рисуются они разными тегами.
+ *
+ * Vue-компонент пакет рисует сам — он ни от чего не зависит. Класс иконки
+ * (`i-lucide-*`) генерирует не пакет, а UnoCSS-сборка приложения: без своего
+ * `presetIcons` потребитель получит пустое место вместо картинки
+ * (`docs/installation.md`). Поэтому класс уезжает в `:class` пустого `span`,
+ * а компонент — в `:is`.
+ */
+export declare function iconTag(icon: string | Component | undefined, fallback?: string | Component): string | Component;
+/** Класс иконки, если она задана строкой; для компонента классов нет. */
+export declare function iconClass(icon: string | Component | undefined): string;

package/dist/types/src/testing/announcer.d.ts

@@ -0,0 +1,10 @@
+import type { GrAnnouncerPoliteness } from '../composables/useAnnouncer';
+/**
+ * Текст живого региона.
+ *
+ * Ждать здесь обязательно: `announce` пишет в регион **отложенным** макротаском,
+ * и это не деталь реализации, а условие работы. Регион, в котором текст
+ * появился в том же кадре, что и сам регион, часть AT не объявляет вовсе;
+ * поэтому синхронное чтение сразу после действия покажет пустую строку.
+ */
+export declare function announced(politeness?: GrAnnouncerPoliteness): Promise<string>;

package/dist/types/src/testing/context.d.ts

@@ -0,0 +1,36 @@
+import { type Ref } from 'vue';
+import { type GrComponentDefaults, type GrComponentSize } from '../components/GrConfigProvider/context';
+import { type GranularityI18nAdapter, type GranularityI18nParams } from '../i18n/adapter';
+export interface I18nAdapterOptions {
+    /** Перевод по ключу. По умолчанию — сам ключ: видно, что спросили. */
+    t?: (key: string, params?: GranularityI18nParams) => string;
+    te?: (key: string) => boolean;
+    locale?: string | Ref<string>;
+}
+/** Адаптер перевода для теста: словарь или своя функция. */
+export declare function i18nAdapter(options?: I18nAdapterOptions | Record<string, string>): GranularityI18nAdapter;
+export interface GranularityGlobalOptions {
+    size?: GrComponentSize;
+    componentDefaults?: GrComponentDefaults;
+    theme?: string;
+    portalTarget?: string | HTMLElement;
+    /** Адаптер перевода: готовый, словарь `{ ключ: перевод }` или опции `i18nAdapter`. */
+    i18n?: GranularityI18nAdapter | I18nAdapterOptions | Record<string, string>;
+}
+/**
+ * Окружение пакета для монтирования — то, что `<GrConfigProvider>` раздаёт
+ * через `provide`.
+ *
+ * Отдаётся объектом, а не компонентом-обёрткой, намеренно: провайдер тянет за
+ * собой лишний корневой элемент, а искать компонент внутри чужой разметки в
+ * каждом тесте дороже, чем передать `global`. Проверять **сам** провайдер
+ * (`data-gr-config-provider`, тема на корне) этим нельзя и не нужно — для этого
+ * его и монтируют.
+ *
+ * ```ts
+ * mount(GrSelect, { props, global: granularityGlobal({ size: 'sm' }) })
+ * ```
+ */
+export declare function granularityGlobal(options?: GranularityGlobalOptions): {
+    provide: Record<symbol, unknown>;
+};

package/dist/types/src/testing/env.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Уборка между тестами.
+ *
+ * `document.body.innerHTML = ''` сам по себе оставляет пакет в разобранном
+ * состоянии: корень портала и хост живого региона закэшированы модулями, и
+ * после очистки `body` они указывают на узлы **вне документа**. Следующий
+ * монтаж телепортирует туда оверлеи, тест ищет их в документе и не находит —
+ * без единой ошибки в консоли. Очередь тостов переживает размонтирование по
+ * замыслу, поэтому её тоже гасим.
+ */
+export declare function resetGranularityDom(): void;
+export interface StubMatchMediaOptions {
+    /** Ответ на `(prefers-reduced-motion: reduce)`. */
+    reducedMotion?: boolean;
+    /** Ответ на остальные запросы. */
+    matches?: boolean;
+}
+/**
+ * Ответ `matchMedia` — например «пользователь просил меньше движения».
+ *
+ * Не для того, чтобы «не падало»: сам пакет зовёт `matchMedia` опционально и без
+ * него живёт. Нужно, когда проверяется поведение **под** медиазапросом.
+ * Возвращает функцию отката: глобальное состояние обязано уйти вместе с тестом.
+ */
+export declare function stubMatchMedia(options?: StubMatchMediaOptions): () => void;

package/dist/types/src/testing/geometry.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Геометрия в jsdom.
+ *
+ * Раскладки в jsdom нет: `getBoundingClientRect` у любого элемента возвращает
+ * нули. Всё, что считает попадание указателя — слайдер, сплиттер, перестановка,
+ * ширины колонок таблицы, — на нулевом прямоугольнике проверять не на чем,
+ * поэтому геометрия задаётся руками.
+ */
+export type MockRect = Partial<Omit<DOMRect, 'toJSON'>>;
+/** Прямоугольник элемента. Незаданные стороны выводятся из заданных. */
+export declare function mockRect(target: Element, rect: MockRect): void;
+export interface StackRectsOptions {
+    /** Размер элемента вдоль оси. */
+    size: number;
+    /** Ось раскладки. По умолчанию вертикальная — так лежат списки и строки. */
+    axis?: 'vertical' | 'horizontal';
+    /** Смещение первого элемента. */
+    start?: number;
+    /** Размер поперёк оси. */
+    cross?: number;
+}
+/** Элементы подряд, встык, без зазоров: строки списка, ячейки шапки, деления шкалы. */
+export declare function stackRects(targets: Iterable<Element>, options: StackRectsOptions): void;

package/dist/types/src/testing/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Тестовые утилиты пакета — `@feugene/granularity/testing`.
+ *
+ * Ни `vitest`, ни `@vue/test-utils` здесь нет и не будет: утилиты отдают данные
+ * и действия над DOM, а монтирует и утверждает потребитель — своим раннером.
+ * Документация: `docs/testing.md`.
+ */
+export { cancelPointer, drag, move, pointer, press, release } from './pointer';
+export { mockRect, type MockRect, stackRects, type StackRectsOptions } from './geometry';
+export { resetGranularityDom, stubMatchMedia, type StubMatchMediaOptions } from './env';
+export { granularityGlobal, type GranularityGlobalOptions, i18nAdapter, type I18nAdapterOptions } from './context';
+export { announced } from './announcer';

package/dist/types/src/testing/pointer.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Указательные жесты в тестах.
+ *
+ * Две вещи, которые ломают наивную запись жеста, и обе неочевидны:
+ *
+ * 1. **`pointerdown` идёт в элемент, а `pointermove`/`pointerup`/`pointercancel` — в `window`.**
+ *    Так слушает `useDragGesture` (и всё, что на нём стоит: слайдер, сплиттер,
+ *    перестановка, смахивание тоста): нажатие приходит от разметки, а движение
+ *    ловится глобально, иначе жест обрывался бы на выходе курсора за элемент.
+ *    Тест, отправивший движение в тот же элемент, ничего не проверяет — и молча.
+ * 2. **`PointerEvent` в jsdom нет**, а `wrapper.trigger('pointerdown', { clientY })`
+ *    падает на попытке записать `clientY`. Поэтому события собираются
+ *    `MouseEvent`-ом и отправляются через `dispatchEvent`.
+ *
+ * Плюс `button: 0` по умолчанию: жест игнорирует неосновную кнопку, и без этого
+ * «перетаскивание» в тесте не начинается вовсе.
+ */
+/** Событие указателя: `MouseEvent`, потому что `PointerEvent` в jsdom не реализован. */
+export declare function pointer(type: string, init?: MouseEventInit): MouseEvent;
+/** Нажатие: единственное событие жеста, которое адресуется элементу. */
+export declare function press(target: Element, init?: MouseEventInit): void;
+export declare function move(init?: MouseEventInit): void;
+export declare function release(init?: MouseEventInit): void;
+/**
+ * Обрыв жеста: система забрала указатель (системный жест, звонок, потеря окна).
+ * Отдельная ветка поведения у всех потребителей — смахивание возвращает тост,
+ * перестановка откатывает порядок, — поэтому проверяется отдельно от `release`.
+ */
+export declare function cancelPointer(init?: MouseEventInit): void;
+/** Жест целиком: нажали на элементе, провели, отпустили. */
+export declare function drag(target: Element, from: MouseEventInit, to: MouseEventInit): void;

package/dist/types/src/theme/apply.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Подключение темы в рантайме — `@feugene/granularity/theme/apply`.
+ *
+ * Отдельный подпуть от `@feugene/granularity/theme` не по вкусу, а по весу:
+ * там справочник токенов (сотня килобайт данных), нужный, чтобы тему
+ * **собрать**. Чтобы её **подключить**, не нужно ничего, кроме готовой строки,
+ * — и приложению незачем платить за первое, если оно делает второе.
+ *
+ * Штатный путь всё же другой: собрать тему на сборке и отдать браузеру обычный
+ * CSS-файл. Этот модуль — для случаев, когда тема появляется только в браузере:
+ * редактор тем, превью, тема из пользовательских настроек.
+ */
+export interface ApplyThemeOptions {
+    /**
+     * Имя, под которым тема живёт в документе. Повторный вызов с тем же именем
+     * заменяет её содержимое, а не добавляет второй `<style>`: иначе редактор
+     * темы за минуту работы оставил бы в `<head>` сотню слоёв, и побеждал бы
+     * последний — то есть результат зависел бы от истории правок.
+     */
+    name?: string;
+    /** Куда вставлять. По умолчанию `document.head`. */
+    target?: HTMLElement | null;
+}
+/** Подключает CSS темы и возвращает функцию, которая его снимает. */
+export declare function applyTheme(css: string, options?: ApplyThemeOptions): () => void;
+/** Снимает тему, подключённую `applyTheme`. */
+export declare function removeTheme(name?: string, target?: HTMLElement | null): void;

package/dist/types/src/theme/color.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Цветовая математика пакета — один источник на всех.
+ *
+ * Одну и ту же формулу считают три разных потребителя: генератор токенов
+ * (фолбэки `@supports not (color-mix)`), композиция тем (`extendTheme`, `tone`)
+ * и гейты контраста. Расхождение здесь не абстрактно: фолбэки уже жили
+ * отдельной копией из сорока хексов, которые обязаны были совпадать с живым
+ * `color-mix` до байта, и не совпадали.
+ *
+ * Модуль читает и генератор (`scripts/generate-tokens.mjs`, запускается
+ * `node --experimental-strip-types`), поэтому синтаксис здесь только стираемый:
+ * ни `enum`, ни `namespace`, ни параметров-свойств в конструкторах.
+ */
+export type Rgb = [number, number, number];
+export declare function parseHex(value: string): Rgb;
+export declare function toHex(channels: Rgb): string;
+/**
+ * `color-mix(in srgb, base <amount>%, other)` для непрозрачных цветов — это
+ * линейная интерполяция в gamma-кодированном sRGB, то есть ровно то, что делает
+ * браузер. Поэтому посчитанный здесь фолбэк совпадает с живым `color-mix`.
+ */
+export declare function mixSrgb(baseHex: string, otherHex: string, amount: number): string;
+export declare function luminance(color: string | Rgb): number;
+/** Отношение контраста по WCAG 2.1: от 1 (одинаковые) до 21 (чёрное на белом). */
+export declare function contrast(foreground: string | Rgb, background: string | Rgb): number;
+/**
+ * Воспринимаемое расстояние между цветами (ΔE, CIE76).
+ *
+ * Контраст отвечает на вопрос «читается ли текст», а этот — на вопрос
+ * «различит ли человек два тона рядом». Порог заметности около 2.3; всё, что
+ * ниже, для глаза один цвет, каким бы разным ни выглядел hex.
+ */
+export declare function deltaE(first: string | Rgb, second: string | Rgb): number;
+/** Цвет — это hex, а не `var()`/`rgb()`: производные и контраст считаются только по нему. */
+export declare function isHex(value: string): boolean;

package/dist/types/src/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/src/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/src/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/src/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/src/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/src/tokens/types.d.ts

@@ -50,5 +50,13 @@ export interface GrDerivedToken {
     section: string;
     description: string;
     formula: string;
+    /**
+     * Слагаемые формулы отдельно от её текста: по ним пересчитывается фолбэк
+     * `@supports not (color-mix)` для темы, которой на момент сборки пакета не
+     * существовало (`extendTheme`).
+     */
+    base: string;
+    amount: number;
+    mixWith: string;
     values: GrTokenValues;
 }