@feugene/granularity 0.12.0 → 0.16.0

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

@@ -0,0 +1,13 @@
+/**
+ * Справочник токенов как данные: `@feugene/granularity/tokens`.
+ *
+ * Источник — `tokens/*.json` пакета, из них же генерируются CSS-файлы, так что
+ * этот модуль не может разойтись с реальными значениями (гейт — тест
+ * `src/__tests__/tokens.generated.test.ts`).
+ *
+ * Намеренно НЕ реэкспортируется из корневого `src/index.ts`: это данные для
+ * доков и инструментов, приложениям в рантайме они не нужны, и тащить их в
+ * основной бандл было бы прямым нарушением идеологии гранулярности.
+ */
+export { grComponentTokens, grDerivedTokens, grFoundationTokens, grThemeNames, grThemeTokens } from './generated';
+export type { GrComponentToken, GrComponentTokenKind, GrDerivedToken, GrFoundationToken, GrThemeName, GrThemeToken, GrTokenValues, } from './types';

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

@@ -0,0 +1,54 @@
+/**
+ * Типы справочника токенов. Данные генерируются (`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;
+    values: GrTokenValues;
+}

package/dist/vue/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/vue/plugin.ts"],"sourcesContent":["import type {App, Component, Directive, Plugin} from 'vue'\n\n/**\n * Лёгкий контейнер, который может быть зарегистрирован в Vue:\n * - SFC-компонент (Vue сам компилирует `__name` из имени файла) — достаточно просто передать сам компонент,\n * - SFC-компонент с опциональным `install` (по аналогии с Element Plus / Naive UI),\n * - объект с собственным `install`,\n * - либо объект `{ name, component }`, если имя нужно задать явно.\n */\nexport type GranularityInstallableComponent =\n    | (Component & { name?: string; __name?: string; install?: (app: App) => void })\n    | { install: (app: App) => void }\n    | { name: string; component: Component }\n\n/**\n * Директива — либо пара `{ name, directive }`, либо объект с `install`.\n */\nexport type GranularityInstallableDirective =\n    | { name: string; directive: Directive }\n    | { install: (app: App) => void }\n\nexport interface CreateGranularityOptions {\n    /**\n     * Список компонентов для глобальной регистрации.\n     * Пакет сам по себе ничего не импортирует — пользователь передаёт сюда только те компоненты,\n     * которые ему действительно нужны. За счёт этого tree-shaking остаётся полным.\n     */\n    components?: GranularityInstallableComponent[]\n    /**\n     * Список директив. Передавайте ровно те, что нужны, по аналогии с компонентами.\n     */\n    directives?: GranularityInstallableDirective[]\n    /**\n     * Произвольные `provide`-значения. Ключи могут быть `symbol` или строкой.\n     * Пакет не навязывает конкретные ключи (например, i18n) — выбор за пользователем.\n     */\n    provides?: Array<{ key: string | symbol; value: unknown }>\n    /**\n     * Произвольные `app.config.globalProperties` — по умолчанию ничего не ставим.\n     */\n    globalProperties?: Record<string, unknown>\n}\n\n/**\n * Вспомогательная обёртка: превращает произвольный компонент в `GranularityInstallableComponent`\n * с явным именем регистрации.\n *\n * ```ts\n * import { GrButton } from '@feugene/granularity/components/GrButton'\n * import { defineInstallable } from '@feugene/granularity/vue'\n *\n * const installable = defineInstallable(GrButton, 'GrButton')\n * ```\n */\nexport function defineInstallable<T extends Component>(component: T, name: string): GranularityInstallableComponent {\n    return {\n        install(app: App) {\n            app.component(name, component)\n        },\n    }\n}\n\nfunction installComponent(app: App, c: GranularityInstallableComponent): void {\n    if (typeof (c as any).install === 'function') {\n        ;(c as any).install(app)\n        return\n    }\n\n    // Форма `{ name, component }` — явное указание имени для произвольного компонента.\n    // Допускаем как object-компоненты (SFC / options), так и functional-компоненты.\n    if (\n        typeof (c as any).name === 'string'\n        && (c as any).component\n        && (typeof (c as any).component === 'object' || typeof (c as any).component === 'function')\n    ) {\n        const {name, component} = c as { name: string; component: Component }\n        app.component(name, component)\n        return\n    }\n\n    // SFC: Vue 3 компилирует имя компонента из имени файла в поле `__name`\n    // (например, `GrButton.vue` → `__name: 'GrButton'`). Также поддерживаем явное `name`.\n    const resolvedName\n        = (c as Component & { name?: string }).name\n            ?? (c as { __name?: string }).__name\n    if (resolvedName) {\n        app.component(resolvedName, c as Component)\n        return\n    }\n\n    // Сознательно без throw — просто сообщаем в dev-режиме.\n     \n    console.warn('[granularity] component passed to createGranularity has no `install`, `name`, or `__name` — skipped.')\n}\n\nfunction installDirective(app: App, d: GranularityInstallableDirective): void {\n    if ('install' in d && typeof d.install === 'function') {\n        d.install(app)\n        return\n    }\n\n    if ('name' in d && 'directive' in d) {\n        app.directive(d.name, d.directive)\n        return\n    }\n\n    // Сознательно без throw — согласовано с `installComponent`.\n     \n    console.warn('[granularity] directive passed to createGranularity has no `install` or `{ name, directive }` — skipped.')\n}\n\n/**\n * Применяет опции к переданному приложению. Экспортируется отдельно от фабрики —\n * удобно, когда плагин не нужен (например, в тестах).\n */\nexport function installGranularity(app: App, options: CreateGranularityOptions = {}): void {\n    for (const c of options.components ?? [])\n        installComponent(app, c)\n\n    for (const d of options.directives ?? [])\n        installDirective(app, d)\n\n    for (const {key, value} of options.provides ?? [])\n        app.provide(key as any, value)\n\n    if (options.globalProperties) {\n        for (const [key, value] of Object.entries(options.globalProperties))\n            app.config.globalProperties[key] = value\n    }\n}\n\n/**\n * Создаёт Vue-плагин `{ install }`, который при `app.use(...)` зарегистрирует переданные\n * компоненты, директивы и provide-значения. Сам модуль НЕ импортирует ни компонентов,\n * ни директив из пакета — всё приходит снаружи. Это сохраняет гранулярность:\n * бандлер увидит только те символы, которые вы реально передали.\n *\n * ```ts\n * import { createApp } from 'vue'\n * import { createGranularity } from '@feugene/granularity/vue'\n * import { GrButton } from '@feugene/granularity/components/GrButton'\n * import { GrInput }  from '@feugene/granularity/components/GrInput'\n * import { vHotkey }  from '@feugene/granularity/directives/hotkey'\n *\n * createApp(App)\n *   .use(createGranularity({\n *     // Достаточно передать сами компоненты — имя будет взято из `__name` (Vue SFC)\n *     // или из `name`; можно также указать явно через `{ name, component }`.\n *     components: [GrButton, GrInput],\n *     directives: [{ name: 'hotkey', directive: vHotkey }],\n *   }))\n *   .mount('#app')\n * ```\n */\nexport function createGranularity(options: CreateGranularityOptions = {}): Plugin {\n    return {\n        install(app: App) {\n            installGranularity(app, options)\n        },\n    }\n}\n"],"mappings":";;;;;;;;;;;;AAsDA,SAAgB,kBAAuC,WAAc,MAA+C;CAChH,OAAO,EACH,QAAQ,KAAU;EACd,IAAI,UAAU,MAAM,SAAS;CACjC,EACJ;AACJ;AAEA,SAAS,iBAAiB,KAAU,GAA0C;CAC1E,IAAI,OAAQ,EAAU,YAAY,YAAY;EACzC,EAAW,QAAQ,GAAG;EACvB;CACJ;CAIA,IACI,OAAQ,EAAU,SAAS,YACvB,EAAU,cACV,OAAQ,EAAU,cAAc,YAAY,OAAQ,EAAU,cAAc,aAClF;EACE,MAAM,EAAC,MAAM,cAAa;EAC1B,IAAI,UAAU,MAAM,SAAS;EAC7B;CACJ;CAIA,MAAM,eACC,EAAoC,QAC/B,EAA0B;CACtC,IAAI,cAAc;EACd,IAAI,UAAU,cAAc,CAAc;EAC1C;CACJ;CAIA,QAAQ,KAAK,sGAAsG;AACvH;AAEA,SAAS,iBAAiB,KAAU,GAA0C;CAC1E,IAAI,aAAa,KAAK,OAAO,EAAE,YAAY,YAAY;EACnD,EAAE,QAAQ,GAAG;EACb;CACJ;CAEA,IAAI,UAAU,KAAK,eAAe,GAAG;EACjC,IAAI,UAAU,EAAE,MAAM,EAAE,SAAS;EACjC;CACJ;CAIA,QAAQ,KAAK,0GAA0G;AAC3H;;;;;AAMA,SAAgB,mBAAmB,KAAU,UAAoC,CAAC,GAAS;CACvF,KAAK,MAAM,KAAK,QAAQ,cAAc,CAAC,GACnC,iBAAiB,KAAK,CAAC;CAE3B,KAAK,MAAM,KAAK,QAAQ,cAAc,CAAC,GACnC,iBAAiB,KAAK,CAAC;CAE3B,KAAK,MAAM,EAAC,KAAK,WAAU,QAAQ,YAAY,CAAC,GAC5C,IAAI,QAAQ,KAAY,KAAK;CAEjC,IAAI,QAAQ,kBACR,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,QAAQ,gBAAgB,GAC9D,IAAI,OAAO,iBAAiB,OAAO;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,SAAgB,kBAAkB,UAAoC,CAAC,GAAW;CAC9E,OAAO,EACH,QAAQ,KAAU;EACd,mBAAmB,KAAK,OAAO;CACnC,EACJ;AACJ"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/vue/plugin.ts"],"sourcesContent":["import type { App, Component, Directive, Plugin } from 'vue'\n\n/**\n * Лёгкий контейнер, который может быть зарегистрирован в Vue:\n * - SFC-компонент (Vue сам компилирует `__name` из имени файла) — достаточно просто передать сам компонент,\n * - SFC-компонент с опциональным `install` (по аналогии с Element Plus / Naive UI),\n * - объект с собственным `install`,\n * - либо объект `{ name, component }`, если имя нужно задать явно.\n */\nexport type GranularityInstallableComponent =\n    | (Component & { name?: string; __name?: string; install?: (app: App) => void })\n    | { install: (app: App) => void }\n    | { name: string; component: Component }\n\n/**\n * Директива — либо пара `{ name, directive }`, либо объект с `install`.\n */\nexport type GranularityInstallableDirective =\n    | { name: string; directive: Directive }\n    | { install: (app: App) => void }\n\nexport interface CreateGranularityOptions {\n    /**\n     * Список компонентов для глобальной регистрации.\n     * Пакет сам по себе ничего не импортирует — пользователь передаёт сюда только те компоненты,\n     * которые ему действительно нужны. За счёт этого tree-shaking остаётся полным.\n     */\n    components?: GranularityInstallableComponent[]\n    /**\n     * Список директив. Передавайте ровно те, что нужны, по аналогии с компонентами.\n     */\n    directives?: GranularityInstallableDirective[]\n    /**\n     * Произвольные `provide`-значения. Ключи могут быть `symbol` или строкой.\n     * Пакет не навязывает конкретные ключи (например, i18n) — выбор за пользователем.\n     */\n    provides?: Array<{ key: string | symbol; value: unknown }>\n    /**\n     * Произвольные `app.config.globalProperties` — по умолчанию ничего не ставим.\n     */\n    globalProperties?: Record<string, unknown>\n}\n\n/**\n * Вспомогательная обёртка: превращает произвольный компонент в `GranularityInstallableComponent`\n * с явным именем регистрации.\n *\n * ```ts\n * import { GrButton } from '@feugene/granularity/components/GrButton'\n * import { defineInstallable } from '@feugene/granularity/vue'\n *\n * const installable = defineInstallable(GrButton, 'GrButton')\n * ```\n */\nexport function defineInstallable<T extends Component>(component: T, name: string): GranularityInstallableComponent {\n    return {\n        install(app: App) {\n            app.component(name, component)\n        },\n    }\n}\n\nfunction installComponent(app: App, c: GranularityInstallableComponent): void {\n    if (typeof (c as any).install === 'function') {\n        ;(c as any).install(app)\n        return\n    }\n\n    // Форма `{ name, component }` — явное указание имени для произвольного компонента.\n    // Допускаем как object-компоненты (SFC / options), так и functional-компоненты.\n    if (\n        typeof (c as any).name === 'string'\n        && (c as any).component\n        && (typeof (c as any).component === 'object' || typeof (c as any).component === 'function')\n    ) {\n        const {name, component} = c as { name: string; component: Component }\n        app.component(name, component)\n        return\n    }\n\n    // SFC: Vue 3 компилирует имя компонента из имени файла в поле `__name`\n    // (например, `GrButton.vue` → `__name: 'GrButton'`). Также поддерживаем явное `name`.\n    const resolvedName\n        = (c as Component & { name?: string }).name\n            ?? (c as { __name?: string }).__name\n    if (resolvedName) {\n        app.component(resolvedName, c as Component)\n        return\n    }\n\n    // Сознательно без throw — просто сообщаем в dev-режиме.\n     \n    console.warn('[granularity] component passed to createGranularity has no `install`, `name`, or `__name` — skipped.')\n}\n\nfunction installDirective(app: App, d: GranularityInstallableDirective): void {\n    if ('install' in d && typeof d.install === 'function') {\n        d.install(app)\n        return\n    }\n\n    if ('name' in d && 'directive' in d) {\n        app.directive(d.name, d.directive)\n        return\n    }\n\n    // Сознательно без throw — согласовано с `installComponent`.\n     \n    console.warn('[granularity] directive passed to createGranularity has no `install` or `{ name, directive }` — skipped.')\n}\n\n/**\n * Применяет опции к переданному приложению. Экспортируется отдельно от фабрики —\n * удобно, когда плагин не нужен (например, в тестах).\n */\nexport function installGranularity(app: App, options: CreateGranularityOptions = {}): void {\n    for (const c of options.components ?? [])\n        installComponent(app, c)\n\n    for (const d of options.directives ?? [])\n        installDirective(app, d)\n\n    for (const {key, value} of options.provides ?? [])\n        app.provide(key as any, value)\n\n    if (options.globalProperties) {\n        for (const [key, value] of Object.entries(options.globalProperties))\n            app.config.globalProperties[key] = value\n    }\n}\n\n/**\n * Создаёт Vue-плагин `{ install }`, который при `app.use(...)` зарегистрирует переданные\n * компоненты, директивы и provide-значения. Сам модуль НЕ импортирует ни компонентов,\n * ни директив из пакета — всё приходит снаружи. Это сохраняет гранулярность:\n * бандлер увидит только те символы, которые вы реально передали.\n *\n * ```ts\n * import { createApp } from 'vue'\n * import { createGranularity } from '@feugene/granularity/vue'\n * import { GrButton } from '@feugene/granularity/components/GrButton'\n * import { GrInput }  from '@feugene/granularity/components/GrInput'\n * import { vHotkey }  from '@feugene/granularity/directives/hotkey'\n *\n * createApp(App)\n *   .use(createGranularity({\n *     // Достаточно передать сами компоненты — имя будет взято из `__name` (Vue SFC)\n *     // или из `name`; можно также указать явно через `{ name, component }`.\n *     components: [GrButton, GrInput],\n *     directives: [{ name: 'hotkey', directive: vHotkey }],\n *   }))\n *   .mount('#app')\n * ```\n */\nexport function createGranularity(options: CreateGranularityOptions = {}): Plugin {\n    return {\n        install(app: App) {\n            installGranularity(app, options)\n        },\n    }\n}\n"],"mappings":";;;;;;;;;;;;AAsDA,SAAgB,kBAAuC,WAAc,MAA+C;CAChH,OAAO,EACH,QAAQ,KAAU;EACd,IAAI,UAAU,MAAM,SAAS;CACjC,EACJ;AACJ;AAEA,SAAS,iBAAiB,KAAU,GAA0C;CAC1E,IAAI,OAAQ,EAAU,YAAY,YAAY;EACzC,EAAW,QAAQ,GAAG;EACvB;CACJ;CAIA,IACI,OAAQ,EAAU,SAAS,YACvB,EAAU,cACV,OAAQ,EAAU,cAAc,YAAY,OAAQ,EAAU,cAAc,aAClF;EACE,MAAM,EAAC,MAAM,cAAa;EAC1B,IAAI,UAAU,MAAM,SAAS;EAC7B;CACJ;CAIA,MAAM,eACC,EAAoC,QAC/B,EAA0B;CACtC,IAAI,cAAc;EACd,IAAI,UAAU,cAAc,CAAc;EAC1C;CACJ;CAIA,QAAQ,KAAK,sGAAsG;AACvH;AAEA,SAAS,iBAAiB,KAAU,GAA0C;CAC1E,IAAI,aAAa,KAAK,OAAO,EAAE,YAAY,YAAY;EACnD,EAAE,QAAQ,GAAG;EACb;CACJ;CAEA,IAAI,UAAU,KAAK,eAAe,GAAG;EACjC,IAAI,UAAU,EAAE,MAAM,EAAE,SAAS;EACjC;CACJ;CAIA,QAAQ,KAAK,0GAA0G;AAC3H;;;;;AAMA,SAAgB,mBAAmB,KAAU,UAAoC,CAAC,GAAS;CACvF,KAAK,MAAM,KAAK,QAAQ,cAAc,CAAC,GACnC,iBAAiB,KAAK,CAAC;CAE3B,KAAK,MAAM,KAAK,QAAQ,cAAc,CAAC,GACnC,iBAAiB,KAAK,CAAC;CAE3B,KAAK,MAAM,EAAC,KAAK,WAAU,QAAQ,YAAY,CAAC,GAC5C,IAAI,QAAQ,KAAY,KAAK;CAEjC,IAAI,QAAQ,kBACR,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,QAAQ,gBAAgB,GAC9D,IAAI,OAAO,iBAAiB,OAAO;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,SAAgB,kBAAkB,UAAoC,CAAC,GAAW;CAC9E,OAAO,EACH,QAAQ,KAAU;EACd,mBAAmB,KAAK,OAAO;CACnC,EACJ;AACJ"}