@feugene/granularity 0.18.0 → 0.20.0

package/dist/chunks/context-CTbuwcYs.js

@@ -0,0 +1,133 @@
+import { computed, getCurrentInstance, inject } from "vue";
+//#region src/components/GrConfigProvider/context.ts
+var GR_CONFIG_KEY = Symbol("gr-config");
+/**
+* Пустой конфиг: когда провайдера в дереве нет, всё разрешается в `undefined`,
+* а компоненты падают на собственные дефолты.
+*
+* `computed` здесь не роскошь: контекст типизирован рефами, и потребитель вправе
+* прогнать `size` через `unref()` или `watch()`. Плоский объект `{ value: … }`
+* не пройдёт проверку `isRef`, и такой код молча получит сам объект вместо
+* значения — поэтому «просто константа» тут не подходит.
+*
+* А вот пустые значения заморожены, и это не педантизм: `computed` без
+* зависимостей вычисляется один раз и отдаёт **один и тот же** объект всем
+* компонентам без провайдера. Незамороженный, он позволил бы одному потребителю
+* записать в него ключ и тем самым подменить дефолты всему приложению.
+*/
+var EMPTY_COMPONENT_DEFAULTS = Object.freeze({});
+var EMPTY_CONFIG = {
+	size: computed(() => void 0),
+	componentDefaults: computed(() => EMPTY_COMPONENT_DEFAULTS),
+	theme: computed(() => void 0),
+	portalTarget: computed(() => void 0)
+};
+/** Возвращает ближайший `GrConfigProvider` или пустой конфиг, если провайдера нет. */
+function useGrConfig() {
+	return inject(GR_CONFIG_KEY, EMPTY_CONFIG);
+}
+function isGrConfigContext(source) {
+	return typeof source?.componentDefaults?.value === "object";
+}
+/**
+* Конфиг там, где `inject` недоступен — вне `setup`: в директивах, императивных
+* сервисах, утилитах. Порядок: явный контекст → `provides` источника → `inject`
+* (если есть активный инстанс) → пустой конфиг.
+*
+* Важно понимать границу: `provides` у `AppContext` содержит только то, что
+* роздано через `app.provide()`. Значения от `<GrConfigProvider>` живут в дереве
+* компонентов, и достать их можно лишь оттуда, где это дерево ещё есть — то есть
+* захватом в `setup`. Просто передать `appContext` в отрыве от дерева
+* недостаточно; см. `SPEC-GrConfig-resolver.md`.
+*/
+function resolveGrConfig(source) {
+	if (isGrConfigContext(source)) return source;
+	const provides = source?.provides;
+	if (provides) {
+		const fromProvides = provides[GR_CONFIG_KEY];
+		return isGrConfigContext(fromProvides) ? fromProvides : EMPTY_CONFIG;
+	}
+	if (getCurrentInstance()) return inject(GR_CONFIG_KEY, EMPTY_CONFIG);
+	return EMPTY_CONFIG;
+}
+var warnedUnsupportedSizes = /* @__PURE__ */ new Set();
+function warnUnsupportedSize(size, supported) {
+	const key = `${size}|${supported.join(",")}`;
+	if (warnedUnsupportedSizes.has(key)) return;
+	warnedUnsupportedSizes.add(key);
+	console.warn(`[granularity] GrConfigProvider size="${size}" is not supported by this component (supported: ${supported.join(", ")}); falling back to its own default.`);
+}
+/**
+* Эффективный размер компонента. Приоритет:
+* локальный проп → `componentDefaults[Component].size` → глобальный `size`
+* провайдера → `fallback`. Точечная настройка компонента должна побеждать
+* общую — иначе `componentDefaults` нельзя было бы использовать как исключение
+* из глобального правила.
+*
+* Передавайте `size` геттером, чтобы сохранить реактивность.
+*
+* Локальный проп не проверяется по `supported`: он уже сужен типом пропа самого
+* компонента, и передать туда лишнее — явная ошибка вызывающего кода. Проверка
+* нужна конфигу: это глобальный канал, который не знает, кто его читает.
+*/
+function useGrComponentSize(localSize, options = {}) {
+	const { component, fallback = "md", supported } = options;
+	const config = useGrConfig();
+	return computed(() => {
+		const local = localSize();
+		if (local !== void 0) return local;
+		const fromConfig = (component ? config.componentDefaults.value[component]?.size : void 0) ?? config.size.value;
+		if (fromConfig === void 0) return fallback;
+		if (supported && !supported.includes(fromConfig)) {
+			if (typeof process !== "undefined" && process.env.NODE_ENV !== "production") warnUnsupportedSize(fromConfig, supported);
+			return fallback;
+		}
+		return fromConfig;
+	});
+}
+/** Дефолтные пропсы конкретного компонента из ближайшего провайдера. */
+function useGrComponentDefaults(name) {
+	const config = useGrConfig();
+	return computed(() => config.componentDefaults.value[name] ?? EMPTY_COMPONENT_DEFAULTS);
+}
+/**
+* Эффективное значение «оформительского» пропа: локальный проп →
+* `componentDefaults[Component][prop]` → собственный дефолт компонента.
+*
+* Обязательное условие на стороне компонента: у такого пропа в `withDefaults`
+* должен стоять `undefined`, а «настоящий» дефолт — переехать сюда, в `fallback`.
+* Иначе конфиг не сработает никогда: Vue отдаёт `props.x` уже с подставленным
+* дефолтом, и отличить «пользователь передал значение» от «сработал дефолт»
+* изнутри компонента невозможно.
+*/
+function useGrComponentProp(component, prop, localValue, fallback) {
+	const config = useGrConfig();
+	return computed(() => {
+		const local = localValue();
+		if (local !== void 0) return local;
+		return config.componentDefaults.value[component]?.[prop] ?? fallback;
+	});
+}
+/**
+* Атрибут темы для **телепортируемого** корня панели.
+*
+* Панель уезжает в `body`, то есть вне DOM-поддерева провайдера, и `data-theme`
+* с его обёртки на неё не наследуется. В дереве компонентов она при этом
+* остаётся внутри — `inject` работает, — поэтому тему панель ставит себе сама.
+* Без этого «тёмный остров» ломался бы на первом же открытом дропдауне.
+*
+* ```vue
+* <teleport to="body">
+*   <div v-bind="themeAttrs">…</div>
+* </teleport>
+* ```
+*/
+function useGrThemeAttrs() {
+	const config = useGrConfig();
+	return computed(() => {
+		const theme = config.theme?.value;
+		return theme ? { "data-theme": theme } : {};
+	});
+}
+//#endregion
+export { useGrComponentSize as a, useGrComponentProp as i, resolveGrConfig as n, useGrConfig as o, useGrComponentDefaults as r, useGrThemeAttrs as s, GR_CONFIG_KEY as t };

package/dist/chunks/context-CTbuwcYs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-CTbuwcYs.js","names":[],"sources":["../../src/components/GrConfigProvider/context.ts"],"sourcesContent":["import { computed, getCurrentInstance, inject, type ComputedRef, type InjectionKey } from 'vue'\n\nimport type { GrComponentDefaultsRegistry } from '../../composables/useGrComponentConfig'\n\n/**\n * Контекст `GrConfigProvider` — глобальные дефолты для вложенных GR-компонентов:\n * размер контролов и per-component дефолтные пропсы.\n *\n * Компоненты читают его через {@link useGrConfig} (или хелперы ниже) и используют\n * как fallback, когда соответствующий проп не задан на самом компоненте. Провайдер\n * можно вкладывать — дочерний мержится поверх родительского.\n */\n\n/**\n * Размеры, которыми оперирует провайдер. Это «размеры контролов» — общий\n * знаменатель формных компонентов, а не объединение всех size-шкал пакета\n * (у оверлеев есть свои `xl`/`full`, у слайдера нет `xs`).\n */\nexport const GR_COMPONENT_SIZES = ['xs', 'sm', 'md', 'lg'] as const\n\nexport type GrComponentSize = typeof GR_COMPONENT_SIZES[number]\n\n/**\n * Реестр компонентов с настраиваемыми через конфиг пропами.\n *\n * Объявлен в `composables/useGrComponentConfig` — там же, куда его дополняют\n * и компоненты пакета, и companion-пакеты. Здесь только реэкспорт для тех, кто\n * работает с контекстом провайдера напрямую.\n */\nexport type { GrComponentDefaultsRegistry }\n\n/** Имя компонента, у которого есть настраиваемые через конфиг пропы. */\nexport type GrConfigurableComponent = keyof GrComponentDefaultsRegistry\n\n/**\n * Дефолтные пропсы по имени компонента: `{ GrButton: { variant: 'secondary' } }`.\n *\n * Набор ключей закрыт реестром, а не `Record<string, unknown>`: через конфиг\n * должны настраиваться только «оформительские» пропы. Пустить туда что угодно —\n * значит разрешить задать глобальный `modelValue` или обработчик и получить баг,\n * который ищется часами.\n */\nexport type GrComponentDefaults = {\n  [TComponent in GrConfigurableComponent]?: Partial<GrComponentDefaultsRegistry[TComponent]>\n}\n\ntype GrDefaultsOf<TComponent extends GrConfigurableComponent> = Partial<GrComponentDefaultsRegistry[TComponent]>\n\nexport interface GrConfigContext {\n  /** Дефолтный размер контролов (если проп `size` не задан на компоненте). */\n  size: ComputedRef<GrComponentSize | undefined>\n  /** Дефолтные пропсы по компонентам. */\n  componentDefaults: ComputedRef<GrComponentDefaults>\n  /**\n   * Тема поддерева (`data-theme`). Необязательна: тип публичный, и контекст\n   * строят руками — например хост императивных диалогов.\n   */\n  theme?: ComputedRef<string | undefined>\n  /**\n   * Куда монтируются оверлеи поддерева (`usePortalTarget`). Необязательно, как\n   * и `theme`: контекст строят руками — например хост императивных диалогов.\n   */\n  portalTarget?: ComputedRef<string | HTMLElement | undefined>\n}\n\nexport const GR_CONFIG_KEY: InjectionKey<GrConfigContext> = Symbol('gr-config')\n\n/**\n * Пустой конфиг: когда провайдера в дереве нет, всё разрешается в `undefined`,\n * а компоненты падают на собственные дефолты.\n *\n * `computed` здесь не роскошь: контекст типизирован рефами, и потребитель вправе\n * прогнать `size` через `unref()` или `watch()`. Плоский объект `{ value: … }`\n * не пройдёт проверку `isRef`, и такой код молча получит сам объект вместо\n * значения — поэтому «просто константа» тут не подходит.\n *\n * А вот пустые значения заморожены, и это не педантизм: `computed` без\n * зависимостей вычисляется один раз и отдаёт **один и тот же** объект всем\n * компонентам без провайдера. Незамороженный, он позволил бы одному потребителю\n * записать в него ключ и тем самым подменить дефолты всему приложению.\n */\nconst EMPTY_COMPONENT_DEFAULTS: GrComponentDefaults = Object.freeze({})\n\nconst EMPTY_CONFIG: GrConfigContext = {\n  size: computed(() => undefined),\n  componentDefaults: computed(() => EMPTY_COMPONENT_DEFAULTS),\n  theme: computed(() => undefined),\n  portalTarget: computed(() => undefined),\n}\n\n/** Возвращает ближайший `GrConfigProvider` или пустой конфиг, если провайдера нет. */\nexport function useGrConfig(): GrConfigContext {\n  return inject(GR_CONFIG_KEY, EMPTY_CONFIG)\n}\n\n/**\n * Источник конфига для {@link resolveGrConfig}: сам контекст, `AppContext` или\n * инстанс компонента — у двух последних читается `provides`.\n */\nexport type GrConfigSource = GrConfigContext | { provides?: Record<symbol | string, unknown> }\n\nfunction isGrConfigContext(source: unknown): source is GrConfigContext {\n  return typeof (source as GrConfigContext | null)?.componentDefaults?.value === 'object'\n}\n\n/**\n * Конфиг там, где `inject` недоступен — вне `setup`: в директивах, императивных\n * сервисах, утилитах. Порядок: явный контекст → `provides` источника → `inject`\n * (если есть активный инстанс) → пустой конфиг.\n *\n * Важно понимать границу: `provides` у `AppContext` содержит только то, что\n * роздано через `app.provide()`. Значения от `<GrConfigProvider>` живут в дереве\n * компонентов, и достать их можно лишь оттуда, где это дерево ещё есть — то есть\n * захватом в `setup`. Просто передать `appContext` в отрыве от дерева\n * недостаточно; см. `SPEC-GrConfig-resolver.md`.\n */\nexport function resolveGrConfig(source?: GrConfigSource | null): GrConfigContext {\n  if (isGrConfigContext(source)) return source\n\n  const provides = source?.provides\n  if (provides) {\n    const fromProvides = provides[GR_CONFIG_KEY as symbol] as GrConfigContext | undefined\n    return isGrConfigContext(fromProvides) ? fromProvides : EMPTY_CONFIG\n  }\n\n  if (getCurrentInstance()) return inject(GR_CONFIG_KEY, EMPTY_CONFIG)\n\n  return EMPTY_CONFIG\n}\n\nexport type UseGrComponentSizeOptions<TSize extends string> = {\n  /**\n   * Имя компонента, чтобы учесть точечный `componentDefaults[Component].size`.\n   * Без него читается только глобальный `size` провайдера.\n   */\n  component?: GrConfigurableComponent\n  /** Размер, когда ни проп, ни конфиг ничего не дали. По умолчанию `md`. */\n  fallback?: TSize\n  /**\n   * Размеры, которые компонент реально умеет. Значение из конфига вне этого\n   * списка игнорируется в пользу `fallback`.\n   *\n   * Обязателен для компонентов, у которых size-шкала уже общей (`GrSlider`,\n   * `GrRating`, `GrSwitch`, `GrLink`, `GrStatistic` не знают про `xs`): без него\n   * `<GrConfigProvider size=\"xs\">` дал бы `sizeMap['xs'] === undefined`, то есть\n   * компонент без размерных классов — молча, без ошибки сборки.\n   */\n  supported?: readonly TSize[]\n}\n\n// Предупреждаем один раз на уникальную пару «размер + список поддерживаемых»,\n// иначе список из сотни контролов зальёт консоль одинаковыми сообщениями.\nconst warnedUnsupportedSizes = new Set<string>()\n\n/** Сброс дедупликации предупреждений. Внутреннее API — нужно тестам. */\nexport function resetUnsupportedSizeWarnings(): void {\n  warnedUnsupportedSizes.clear()\n}\n\nfunction warnUnsupportedSize(size: string, supported: readonly string[]): void {\n  const key = `${size}|${supported.join(',')}`\n  if (warnedUnsupportedSizes.has(key)) return\n  warnedUnsupportedSizes.add(key)\n\n  console.warn(\n    `[granularity] GrConfigProvider size=\"${size}\" is not supported by this component `\n    + `(supported: ${supported.join(', ')}); falling back to its own default.`,\n  )\n}\n\n/**\n * Эффективный размер компонента. Приоритет:\n * локальный проп → `componentDefaults[Component].size` → глобальный `size`\n * провайдера → `fallback`. Точечная настройка компонента должна побеждать\n * общую — иначе `componentDefaults` нельзя было бы использовать как исключение\n * из глобального правила.\n *\n * Передавайте `size` геттером, чтобы сохранить реактивность.\n *\n * Локальный проп не проверяется по `supported`: он уже сужен типом пропа самого\n * компонента, и передать туда лишнее — явная ошибка вызывающего кода. Проверка\n * нужна конфигу: это глобальный канал, который не знает, кто его читает.\n */\nexport function useGrComponentSize<TSize extends string = GrComponentSize>(\n  localSize: () => TSize | undefined,\n  options: UseGrComponentSizeOptions<TSize> = {},\n): ComputedRef<TSize> {\n  // Все size-шкалы пакета содержат `md`, поэтому он безопасен как общий дефолт.\n  const { component, fallback = 'md' as TSize, supported } = options\n  const config = useGrConfig()\n\n  return computed(() => {\n    const local = localSize()\n    if (local !== undefined) return local\n\n    const fromComponentDefaults = component\n      ? (config.componentDefaults.value[component] as { size?: TSize } | undefined)?.size\n      : undefined\n\n    const fromConfig = fromComponentDefaults ?? config.size.value\n    if (fromConfig === undefined) return fallback\n\n    if (supported && !supported.includes(fromConfig as TSize)) {\n      // Проверку окружения держим инлайном: бандлер потребителя подставляет\n      // `process.env.NODE_ENV`, сворачивает условие в `false` и выкидывает\n      // и текст предупреждения, и дедуп-Set. Через промежуточную константу\n      // это не работает — межмодульную свёртку esbuild/rollup не делают, и\n      // DX-сообщение осталось бы в каждом бандле (проверено замером).\n      // `typeof process` — страховка для сборок, где `process` не определён.\n      if (typeof process !== 'undefined' && process.env.NODE_ENV !== 'production')\n        warnUnsupportedSize(fromConfig, supported)\n      return fallback\n    }\n\n    return fromConfig as TSize\n  })\n}\n\n/** Дефолтные пропсы конкретного компонента из ближайшего провайдера. */\nexport function useGrComponentDefaults<TComponent extends GrConfigurableComponent>(\n  name: TComponent,\n): ComputedRef<GrDefaultsOf<TComponent>> {\n  const config = useGrConfig()\n  return computed(() => (config.componentDefaults.value[name] ?? EMPTY_COMPONENT_DEFAULTS) as GrDefaultsOf<TComponent>)\n}\n\n/**\n * Эффективное значение «оформительского» пропа: локальный проп →\n * `componentDefaults[Component][prop]` → собственный дефолт компонента.\n *\n * Обязательное условие на стороне компонента: у такого пропа в `withDefaults`\n * должен стоять `undefined`, а «настоящий» дефолт — переехать сюда, в `fallback`.\n * Иначе конфиг не сработает никогда: Vue отдаёт `props.x` уже с подставленным\n * дефолтом, и отличить «пользователь передал значение» от «сработал дефолт»\n * изнутри компонента невозможно.\n */\nexport function useGrComponentProp<\n  TComponent extends GrConfigurableComponent,\n  TProp extends keyof GrDefaultsOf<TComponent>,\n>(\n  component: TComponent,\n  prop: TProp,\n  localValue: () => GrDefaultsOf<TComponent>[TProp],\n  fallback: NonNullable<GrDefaultsOf<TComponent>[TProp]>,\n): ComputedRef<NonNullable<GrDefaultsOf<TComponent>[TProp]>> {\n  const config = useGrConfig()\n\n  return computed(() => {\n    const local = localValue()\n    if (local !== undefined) return local as NonNullable<GrDefaultsOf<TComponent>[TProp]>\n\n    // Промежуточная аннотация (а не `as`) нужна, чтобы TS не разворачивал\n    // `GrComponentDefaults[TComponent]` в объединение всех блоков — по нему\n    // generic-ключ `TProp` уже не проиндексировать.\n    const defaults: GrDefaultsOf<TComponent> | undefined = config.componentDefaults.value[component]\n    return defaults?.[prop] ?? fallback\n  })\n}\n\n/**\n * Атрибут темы для **телепортируемого** корня панели.\n *\n * Панель уезжает в `body`, то есть вне DOM-поддерева провайдера, и `data-theme`\n * с его обёртки на неё не наследуется. В дереве компонентов она при этом\n * остаётся внутри — `inject` работает, — поэтому тему панель ставит себе сама.\n * Без этого «тёмный остров» ломался бы на первом же открытом дропдауне.\n *\n * ```vue\n * <teleport to=\"body\">\n *   <div v-bind=\"themeAttrs\">…</div>\n * </teleport>\n * ```\n */\nexport function useGrThemeAttrs(): ComputedRef<{ 'data-theme'?: string }> {\n  const config = useGrConfig()\n  return computed(() => {\n    const theme = config.theme?.value\n    return theme ? { 'data-theme': theme } : {}\n  })\n}\n"],"mappings":";;AAiEA,IAAa,gBAA+C,OAAO,WAAW;;;;;;;;;;;;;;;AAgB9E,IAAM,2BAAgD,OAAO,OAAO,CAAC,CAAC;AAEtE,IAAM,eAAgC;CACpC,MAAM,eAAe,KAAA,CAAS;CAC9B,mBAAmB,eAAe,wBAAwB;CAC1D,OAAO,eAAe,KAAA,CAAS;CAC/B,cAAc,eAAe,KAAA,CAAS;AACxC;;AAGA,SAAgB,cAA+B;CAC7C,OAAO,OAAO,eAAe,YAAY;AAC3C;AAQA,SAAS,kBAAkB,QAA4C;CACrE,OAAO,OAAQ,QAAmC,mBAAmB,UAAU;AACjF;;;;;;;;;;;;AAaA,SAAgB,gBAAgB,QAAiD;CAC/E,IAAI,kBAAkB,MAAM,GAAG,OAAO;CAEtC,MAAM,WAAW,QAAQ;CACzB,IAAI,UAAU;EACZ,MAAM,eAAe,SAAS;EAC9B,OAAO,kBAAkB,YAAY,IAAI,eAAe;CAC1D;CAEA,IAAI,mBAAmB,GAAG,OAAO,OAAO,eAAe,YAAY;CAEnE,OAAO;AACT;AAwBA,IAAM,yCAAyB,IAAI,IAAY;AAO/C,SAAS,oBAAoB,MAAc,WAAoC;CAC7E,MAAM,MAAM,GAAG,KAAK,GAAG,UAAU,KAAK,GAAG;CACzC,IAAI,uBAAuB,IAAI,GAAG,GAAG;CACrC,uBAAuB,IAAI,GAAG;CAE9B,QAAQ,KACN,wCAAwC,KAAK,mDAC5B,UAAU,KAAK,IAAI,EAAE,oCACxC;AACF;;;;;;;;;;;;;;AAeA,SAAgB,mBACd,WACA,UAA4C,CAAC,GACzB;CAEpB,MAAM,EAAE,WAAW,WAAW,MAAe,cAAc;CAC3D,MAAM,SAAS,YAAY;CAE3B,OAAO,eAAe;EACpB,MAAM,QAAQ,UAAU;EACxB,IAAI,UAAU,KAAA,GAAW,OAAO;EAMhC,MAAM,cAJwB,YACzB,OAAO,kBAAkB,MAAM,UAAU,EAAmC,OAC7E,KAAA,MAEwC,OAAO,KAAK;EACxD,IAAI,eAAe,KAAA,GAAW,OAAO;EAErC,IAAI,aAAa,CAAC,UAAU,SAAS,UAAmB,GAAG;GAOzD,IAAI,OAAO,YAAY,eAAA,QAAA,IAAA,aAAwC,cAC7D,oBAAoB,YAAY,SAAS;GAC3C,OAAO;EACT;EAEA,OAAO;CACT,CAAC;AACH;;AAGA,SAAgB,uBACd,MACuC;CACvC,MAAM,SAAS,YAAY;CAC3B,OAAO,eAAgB,OAAO,kBAAkB,MAAM,SAAS,wBAAqD;AACtH;;;;;;;;;;;AAYA,SAAgB,mBAId,WACA,MACA,YACA,UAC2D;CAC3D,MAAM,SAAS,YAAY;CAE3B,OAAO,eAAe;EACpB,MAAM,QAAQ,WAAW;EACzB,IAAI,UAAU,KAAA,GAAW,OAAO;EAMhC,OADuD,OAAO,kBAAkB,MAAM,UAC/E,GAAW,SAAS;CAC7B,CAAC;AACH;;;;;;;;;;;;;;;AAgBA,SAAgB,kBAA0D;CACxE,MAAM,SAAS,YAAY;CAC3B,OAAO,eAAe;EACpB,MAAM,QAAQ,OAAO,OAAO;EAC5B,OAAO,QAAQ,EAAE,cAAc,MAAM,IAAI,CAAC;CAC5C,CAAC;AACH"}