@soxa-ui/setup 0.0.0-stage → 0.3.0-beta.1

package/dist/protected/naming/strategy.types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Профиль фреймворка: стратегия имён, которую даёт адаптер, а применяет общий слой.
+ *
+ * Ядро и дескриптор говорят на одном языке (`text`, `aria:label`,
+ * `change:text`), каждый фреймворк — на своём. Всё, чем фреймворки различаются
+ * в именах, собрано в одной константе адаптера (`VueProfile`, `ReactProfile`,
+ * …); её идентичность — ключ кэша поверхности.
+ */
+import type { TName } from '../define/name.class';
+/** Правила имён пропсов и событий во фреймворке. */
+export interface INamingStrategy {
+    /** Имя пропа: одно во всех фреймворках — `text`, `aria_label` (`underscorePropNaming`). */
+    prop(name: TName): string;
+    /** Имя события: `change:text` у Vue, `onChangeText` у React, `soChangeText` у Angular. */
+    event(name: TName): string;
+}
+export interface IAdapterProfile {
+    readonly naming: INamingStrategy;
+    /** Как фреймворк называет слот по умолчанию (`children`); не задано — имя не переводится. */
+    readonly defaultSlot?: string;
+    /**
+     * Событие двусторонней привязки по имени пропа во фреймворке (`update:text` у
+     * Vue). Привязка — свойство фреймворка: у остальных поля нет, и события
+     * привязки у них не существует.
+     */
+    readonly model?: (exportName: string) => string;
+}

package/dist/protected/registry/extensions.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Реестр расширений коллекции, поставленных снаружи на все компоненты типа.
+ *
+ *   useExtensions(TTabs, [(owner) => new TTabsHistoryExtension({ owner })])
+ *
+ * Пара к `usePlugins`: тип — класс ядра владельца коллекции, кому достаётся
+ * регистрация, решает тот же список регистраций. Регистрируется фабрика, а не
+ * экземпляр: у каждого движка своё расширение. Фабрика получает владельца —
+ * как детали владельца в `custom/<component>/collection/factory.ts` ядра.
+ *
+ * Ставит расширения слой setup (`TCollectionExtension`), когда движок привязан
+ * к компоненту: движок и ядро о реестре не знают (AGENTS.md, «Движок не знает о
+ * конкретных расширениях»). Расширение только добавляет: имя, занятое
+ * расширением другого класса, — ошибка; то же расширение в том же движке
+ * (движок передан двум компонентам) второй раз не ставится.
+ */
+import type { TCollectionEngine } from '@soxa-ui/core';
+import type { IBundleContext } from '../define';
+import type { IPluginRegistrationOptions, TExtensionFactory } from './types';
+/**
+ * Поставить расширения в движок каждого компонента типа. Возвращает отмену
+ * регистрации; уже поставленные расширения отмена не трогает.
+ */
+export declare function useExtensions<TOwner extends object>(type: abstract new (...args: any[]) => TOwner, factories: readonly TExtensionFactory<TOwner>[], options?: IPluginRegistrationOptions): () => void;
+/**
+ * Поставить в движок расширения реестра, подходящие владельцу, в порядке
+ * регистрации. Зовёт setup при привязке движка к компоненту.
+ */
+export declare function applyRegisteredExtensions(owner: object, engine: TCollectionEngine<any, any>, context?: IBundleContext): void;

package/dist/protected/registry/extensions.js

@@ -0,0 +1,28 @@
+import { createRegistrations } from "./registrations.js";
+//#region protected/registry/extensions.ts
+var registrations = createRegistrations();
+/**
+* Поставить расширения в движок каждого компонента типа. Возвращает отмену
+* регистрации; уже поставленные расширения отмена не трогает.
+*/
+function useExtensions(type, factories, options = {}) {
+	return registrations.add(type, factories, options);
+}
+/**
+* Поставить в движок расширения реестра, подходящие владельцу, в порядке
+* регистрации. Зовёт setup при привязке движка к компоненту.
+*/
+function applyRegisteredExtensions(owner, engine, context = {}) {
+	for (const factory of registrations.select(owner, context)) {
+		const extension = factory(owner);
+		const present = engine.extensions[extension.name];
+		if (present === void 0) {
+			engine.use(extension);
+			continue;
+		}
+		if (present instanceof Object && present.constructor === extension.constructor) continue;
+		throw new Error(`Расширение «${extension.name}» уже есть в коллекции ${owner.constructor.name}: расширение реестра только добавляет`);
+	}
+}
+//#endregion
+export { applyRegisteredExtensions, useExtensions };

package/dist/protected/registry/icons.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Реестр иконок: роли как данные, без разметки.
+ *
+ * Механика одна на все шесть адаптеров: приложение кладёт сюда пакет иконок,
+ * компоненты берут значок по роли. Сам список обязательных ролей — контракт,
+ * который растёт вместе с компонентами, — лежит в наполнении
+ * (`content/icons/roles.ts`): реестр о нём не знает и работает с любой строкой.
+ *
+ * Живёт в `setup`, потому что фреймворки сюда не импортируются: и пакет, и
+ * реестр обязаны работать одинаково во всех шести адаптерах.
+ */
+import type { TIconSource } from './types';
+/**
+ * Заглушка для отсутствующей роли.
+ *
+ * Пустая, но валидная иконка: разметка не ломается, а `console.warn` говорит,
+ * чего не хватает. Бросать исключение нельзя — из-за одной иконки упало бы
+ * всё приложение.
+ */
+export declare const MISSING_ICON: TIconSource;
+/**
+ * Подключает пакет иконок или отдельные роли.
+ *
+ * Вызывается один раз при старте приложения. Повторный вызов дополняет и
+ * перекрывает уже зарегистрированное — так точечная подмена одной иконки не
+ * требует пересобирать весь набор:
+ *
+ * ```ts
+ * useIcons(material)
+ * useIcons({ close: myCloseIcon })
+ * ```
+ */
+export declare function useIcons(pack: Partial<Record<string, TIconSource>>): void;
+/**
+ * Иконка по роли.
+ *
+ * Никогда не возвращает `undefined`: у отсутствующей роли своя заглушка, и
+ * предупреждение печатается один раз, а не на каждый кадр отрисовки.
+ */
+export declare function getIcon(role: string): TIconSource;
+/** Есть ли роль в реестре. */
+export declare function hasIcon(role: string): boolean;
+/** Очищает реестр. Нужен тестам, чтобы не тянуть состояние между кейсами. */
+export declare function resetIcons(): void;

package/dist/protected/registry/icons.js

@@ -0,0 +1,59 @@
+//#region protected/registry/icons.ts
+/**
+* Заглушка для отсутствующей роли.
+*
+* Пустая, но валидная иконка: разметка не ломается, а `console.warn` говорит,
+* чего не хватает. Бросать исключение нельзя — из-за одной иконки упало бы
+* всё приложение.
+*/
+var MISSING_ICON = {
+	viewBox: "0 0 24 24",
+	body: ""
+};
+var registry = /* @__PURE__ */ new Map();
+var reported = /* @__PURE__ */ new Set();
+/**
+* Подключает пакет иконок или отдельные роли.
+*
+* Вызывается один раз при старте приложения. Повторный вызов дополняет и
+* перекрывает уже зарегистрированное — так точечная подмена одной иконки не
+* требует пересобирать весь набор:
+*
+* ```ts
+* useIcons(material)
+* useIcons({ close: myCloseIcon })
+* ```
+*/
+function useIcons(pack) {
+	for (const [role, source] of Object.entries(pack)) {
+		if (!source) continue;
+		registry.set(role, source);
+		reported.delete(role);
+	}
+}
+/**
+* Иконка по роли.
+*
+* Никогда не возвращает `undefined`: у отсутствующей роли своя заглушка, и
+* предупреждение печатается один раз, а не на каждый кадр отрисовки.
+*/
+function getIcon(role) {
+	const source = registry.get(role);
+	if (source) return source;
+	if (!reported.has(role)) {
+		reported.add(role);
+		console.warn(`[soxa] Иконка «${role}» не зарегистрирована. Вызовите useIcons().`);
+	}
+	return MISSING_ICON;
+}
+/** Есть ли роль в реестре. */
+function hasIcon(role) {
+	return registry.has(role);
+}
+/** Очищает реестр. Нужен тестам, чтобы не тянуть состояние между кейсами. */
+function resetIcons() {
+	registry.clear();
+	reported.clear();
+}
+//#endregion
+export { MISSING_ICON, getIcon, hasIcon, resetIcons, useIcons };

package/dist/protected/registry/index.d.ts

@@ -0,0 +1,5 @@
+export { usePlugins, resolveRegisteredPlugins } from './plugins';
+export { useExtensions, applyRegisteredExtensions } from './extensions';
+export { defineTheme, useTheme } from './theme';
+export { MISSING_ICON, getIcon, hasIcon, resetIcons, useIcons } from './icons';
+export type { IPluginRegistrationOptions, IResolvedPlugin, ITheme, IThemeExtensions, IThemePlugins, TExtensionFactory, TIconSource, TPluginScope, TRegisteredPlugin, } from './types';

package/dist/protected/registry/plugins.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Реестр плагинов, поставленных снаружи на все компоненты одного типа.
+ *
+ *   usePlugins(TButton, [TTimerPlugin])                    // кнопки пользователя
+ *   usePlugins(TButton, [TRipplePlugin], { scope: 'all' }) // и вложенные тоже
+ *   usePlugins(TButton, [AnchorPluginDescriptor])          // определением — см. ниже
+ *
+ * Кому достаётся регистрация — тип, `scope` и признак `embedded`, — решает
+ * общий список регистраций (`registrations.ts`).
+ *
+ * Плагины регистрации ставятся после плагинов дескриптора, в порядке
+ * регистрации, до `bundle:create` (`TOwnBundle`). Внешний плагин
+ * только добавляет — заменить плагин из состава компонента он не может.
+ *
+ * Поверхность компонента реестр не меняет. Пропсы и события внешнего плагина —
+ * по его контракту (`definePlugin`), через `pluginProps` и `plugin:event`
+ * (AGENTS.md, «Внешний плагин: пропсы — `pluginProps`, события — `plugin:event`»). Настраивается
+ * он и опциями регистрации.
+ *
+ * **Плагин с объявленным контрактом ставьте определением, а не классом.**
+ * Контракт записывает вызов `definePlugin` при импорте модуля определения, а
+ * пакет объявлен `sideEffects: false`: модуль, из которого ничего не взяли,
+ * сборщик выбрасывает — вместе с записью контракта. Поставленный по классу,
+ * такой плагин работал бы, но `pluginProps` до него молча не доходили бы, и
+ * только в продакшен-сборке. Импорт определения держит модуль в бандле.
+ */
+import type { IBundleContext } from '../define';
+import type { IPluginRegistrationOptions, IResolvedPlugin, TRegisteredPlugin } from './types';
+/**
+ * Поставить плагины на все компоненты типа. Возвращает отмену регистрации:
+ * её зовут, когда плагины больше не нужны новым компонентам (модуль выгружен,
+ * тест закончился). Уже собранные наборы отмена не трогает.
+ */
+export declare function usePlugins(type: abstract new (...args: any[]) => object, plugins: readonly TRegisteredPlugin[], options?: IPluginRegistrationOptions): () => void;
+/**
+ * Плагины реестра для компонента, в порядке регистрации. Один класс плагина —
+ * один раз: у повторной регистрации побеждают опции последней, как у
+ * приложения, которое донастраивает плагин темы.
+ */
+export declare function resolveRegisteredPlugins(instance: object, context?: IBundleContext): IResolvedPlugin[];

package/dist/protected/registry/plugins.js

@@ -0,0 +1,29 @@
+import { createRegistrations } from "./registrations.js";
+//#region protected/registry/plugins.ts
+var registrations = createRegistrations();
+/**
+* Поставить плагины на все компоненты типа. Возвращает отмену регистрации:
+* её зовут, когда плагины больше не нужны новым компонентам (модуль выгружен,
+* тест закончился). Уже собранные наборы отмена не трогает.
+*/
+function usePlugins(type, plugins, options = {}) {
+	return registrations.add(type, plugins.map((plugin) => "ctor" in plugin ? {
+		ctor: plugin.ctor,
+		options: plugin.options
+	} : { ctor: plugin }), options);
+}
+/**
+* Плагины реестра для компонента, в порядке регистрации. Один класс плагина —
+* один раз: у повторной регистрации побеждают опции последней, как у
+* приложения, которое донастраивает плагин темы.
+*/
+function resolveRegisteredPlugins(instance, context = {}) {
+	const resolved = /* @__PURE__ */ new Map();
+	for (const plugin of registrations.select(instance, context)) {
+		resolved.delete(plugin.ctor);
+		resolved.set(plugin.ctor, plugin);
+	}
+	return [...resolved.values()];
+}
+//#endregion
+export { resolveRegisteredPlugins, usePlugins };

package/dist/protected/registry/registrations.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Список регистраций на тип компонента: отмена и выбор подходящих компоненту.
+ *
+ * Одно правило на оба реестра — плагинов и расширений коллекции. Компонент
+ * получает регистрацию, если он `instanceof` её типа: так подходит и
+ * наследник, переданный через `ctrl`. Вложенный компонент — деталь чужой
+ * разметки, помеченная признаком `embedded`, — получает только регистрации со
+ * `scope: 'all'`; по умолчанию `scope` — `'own'`.
+ *
+ * Регистрация действует на компоненты, собранные после неё: уже собранных не
+ * касаются ни она, ни её отмена.
+ */
+import type { IRegistrations } from './types';
+/** Пустой список регистраций; у каждого реестра свой. */
+export declare function createRegistrations<TEntry>(): IRegistrations<TEntry>;

package/dist/protected/registry/registrations.js

@@ -0,0 +1,30 @@
+//#region protected/registry/registrations.ts
+/** Пустой список регистраций; у каждого реестра свой. */
+function createRegistrations() {
+	const registrations = [];
+	return {
+		add(type, entries, options) {
+			const registration = {
+				type,
+				entries,
+				scope: options.scope ?? "own"
+			};
+			registrations.push(registration);
+			return () => {
+				const index = registrations.indexOf(registration);
+				if (index !== -1) registrations.splice(index, 1);
+			};
+		},
+		select(instance, context) {
+			const selected = [];
+			for (const { type, entries, scope } of registrations) {
+				if (!(instance instanceof type)) continue;
+				if (scope === "own" && context.embedded !== void 0) continue;
+				selected.push(...entries);
+			}
+			return selected;
+		}
+	};
+}
+//#endregion
+export { createRegistrations };

package/dist/protected/registry/theme.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Тема как набор регистраций: плагины и расширения, без которых её CSS не работает.
+ *
+ *   // @soxa-ui/theme-oren/setup
+ *   export default defineTheme({
+ *     name: 'oren',
+ *     plugins: [{ type: TTabs, plugins: [TTabsViewPlugin] }],
+ *   })
+ *
+ *   // точка входа приложения
+ *   useTheme(oren)
+ *
+ * Тема отдаёт CSS и `index.d.ts` (значения оформления), а то, что пишет для её
+ * CSS данные в разметку, — плагины — отдаёт этим объектом. Явным экспортом, а
+ * не раскладкой файлов по соглашению: сборщик не обходит файлы чужого пакета, и
+ * забытый файл не молчал бы, а просто не подключился.
+ *
+ * `useTheme` — те же `usePlugins`/`useExtensions`, одним вызовом. Умолчание
+ * `scope` у темы — `'all'`: тема рисует компонент и там, где он деталь чужой
+ * разметки (Tags в поле Select).
+ */
+import type { ITheme } from './types';
+/** Объявить тему. Ничего не регистрирует: подключает её `useTheme`. */
+export declare function defineTheme<T extends ITheme>(theme: T): T;
+/**
+ * Подключить тему: зарегистрировать её плагины и расширения. Возвращает
+ * отмену всех регистраций темы.
+ */
+export declare function useTheme(theme: ITheme): () => void;

package/dist/protected/registry/theme.js

@@ -0,0 +1,40 @@
+import { usePlugins } from "./plugins.js";
+import { useExtensions } from "./extensions.js";
+//#region protected/registry/theme.ts
+/**
+* Тема как набор регистраций: плагины и расширения, без которых её CSS не работает.
+*
+*   // @soxa-ui/theme-oren/setup
+*   export default defineTheme({
+*     name: 'oren',
+*     plugins: [{ type: TTabs, plugins: [TTabsViewPlugin] }],
+*   })
+*
+*   // точка входа приложения
+*   useTheme(oren)
+*
+* Тема отдаёт CSS и `index.d.ts` (значения оформления), а то, что пишет для её
+* CSS данные в разметку, — плагины — отдаёт этим объектом. Явным экспортом, а
+* не раскладкой файлов по соглашению: сборщик не обходит файлы чужого пакета, и
+* забытый файл не молчал бы, а просто не подключился.
+*
+* `useTheme` — те же `usePlugins`/`useExtensions`, одним вызовом. Умолчание
+* `scope` у темы — `'all'`: тема рисует компонент и там, где он деталь чужой
+* разметки (Tags в поле Select).
+*/
+/** Объявить тему. Ничего не регистрирует: подключает её `useTheme`. */
+function defineTheme(theme) {
+	return theme;
+}
+/**
+* Подключить тему: зарегистрировать её плагины и расширения. Возвращает
+* отмену всех регистраций темы.
+*/
+function useTheme(theme) {
+	const disposers = [...(theme.plugins ?? []).map(({ type, plugins, scope }) => usePlugins(type, plugins, { scope: scope ?? "all" })), ...(theme.extensions ?? []).map(({ type, extensions, scope }) => useExtensions(type, extensions, { scope: scope ?? "all" }))];
+	return () => {
+		for (const dispose of disposers) dispose();
+	};
+}
+//#endregion
+export { defineTheme, useTheme };

package/dist/protected/registry/types.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Контракты реестра: что приложение регистрирует на тип компонента и с какими опциями.
+ */
+import type { IExtension } from '@soxa-ui/core';
+import type { IPluginConstructor } from '@soxa-ui/plugins';
+import type { IBundleContext } from '../define';
+/**
+ * Иконка как данные, без разметки.
+ *
+ * `body` — содержимое `<svg>` без самого тега. Так адаптер сам решает, какие
+ * атрибуты повесить на корень: размер, `aria-hidden`, классы. Отдай пакет
+ * целую строку `<svg>…</svg>` — и всё это стало бы недоступно.
+ *
+ * Формат намеренно не привязан ни к фреймворку, ни к сборщику: обычные данные,
+ * которые собираются любым бандлером и читаются в Node. Прежний
+ * `import '...svg?raw'` понимал только Vite.
+ */
+export type TIconSource = {
+    /** Система координат: `viewBox` корневого `<svg>`. */
+    viewBox: string;
+    /** Содержимое `<svg>`: пути, группы, что угодно. */
+    body: string;
+};
+/**
+ * Тип компонента — класс ядра. Сравнение через `instanceof`: объект
+ * дескриптора строится заново на каждом монтировании, а класс один.
+ */
+export type TComponentType = abstract new (...args: any[]) => object;
+/** Какие компоненты типа получают плагин. */
+export type TPluginScope = 'own' | 'all';
+export interface IPluginRegistrationOptions {
+    /**
+     * `'own'` — только компоненты, которые поставил пользователь; `'all'` — и
+     * вложенные в разметку других компонентов.
+     */
+    scope?: TPluginScope;
+}
+/** Регистрация: записи реестра на тип компонента. */
+export interface IRegistration<TEntry> {
+    readonly type: TComponentType;
+    readonly entries: readonly TEntry[];
+    readonly scope: TPluginScope;
+}
+/** Список регистраций одного реестра. */
+export interface IRegistrations<TEntry> {
+    /** Зарегистрировать записи на тип; возвращает отмену регистрации. */
+    add(type: TComponentType, entries: readonly TEntry[], options: IPluginRegistrationOptions): () => void;
+    /** Записи регистраций, подходящих компоненту, в порядке регистрации. */
+    select(instance: object, context: IBundleContext): TEntry[];
+}
+/**
+ * Плагин регистрации: класс, класс с опциями установки или определение
+ * `definePlugin` (у него те же `ctor` и `options`).
+ *
+ * Поверхность компонента определение не меняет: её объявляет только
+ * дескриптор. Определение нужно ради импорта — он держит в бандле модуль, где
+ * записан контракт плагина (см. `registry/plugins.ts`).
+ */
+export type TRegisteredPlugin = IPluginConstructor<any, any, any> | {
+    readonly ctor: IPluginConstructor<any, any, any>;
+    readonly options?: object;
+};
+/** Плагин, который компонент получает из реестра. */
+export interface IResolvedPlugin {
+    readonly ctor: IPluginConstructor<any, any, any>;
+    readonly options?: object;
+}
+/** Фабрика расширения: владелец коллекции → расширение для его движка. */
+export type TExtensionFactory<TOwner extends object = any> = (owner: TOwner) => IExtension<any>;
+/** Плагины темы на тип компонента. */
+export interface IThemePlugins extends IPluginRegistrationOptions {
+    readonly type: TComponentType;
+    readonly plugins: readonly TRegisteredPlugin[];
+}
+/** Расширения коллекции темы на тип владельца. */
+export interface IThemeExtensions extends IPluginRegistrationOptions {
+    readonly type: TComponentType;
+    readonly extensions: readonly TExtensionFactory[];
+}
+export interface ITheme {
+    /** Имя темы — для сообщений и отладки. */
+    readonly name: string;
+    readonly plugins?: readonly IThemePlugins[];
+    readonly extensions?: readonly IThemeExtensions[];
+}

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@soxa-ui/setup",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0-beta.1",
+  "description": "Общее для всех адаптеров: дескрипторы компонентов, их сборка на монтирование и связывание с фреймворком",
+  "keywords": [
+    "soxa",
+    "headless",
+    "ui",
+    "descriptors"
+  ],
+  "license": "MIT",
+  "author": "Yuri Soldatov",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/youra-h/soxa-ui.git",
+    "directory": "packages/setup"
+  },
+  "homepage": "https://github.com/youra-h/soxa-ui",
+  "bugs": {
+    "url": "https://github.com/youra-h/soxa-ui/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@soxa-ui/core": "0.3.0-beta.1",
+    "@soxa-ui/plugins": "0.3.0-beta.1"
+  },
+  "scripts": {
+    "build": "vite build -c vite.lib.config.ts && tsc -p tsconfig.build.json",
+    "test": "vitest run"
+  }
+}