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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yuri Soldatov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,126 @@
-# Temporary Holding Version
+# @soxa-ui/plugins
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Runtime behavior installed into a plugin bundle: DOM, focus, keyboard, overlay.**
+
+Part of [Soxa UI](https://github.com/youra-h/soxa-ui) — UI components with the logic written once: a
+framework-agnostic core and thin adapters that render it in Vue, React, Angular, Svelte, Solid and
+Web Components.
+
+Models in `@soxa-ui/core` have no access to the DOM. Everything that needs a live node — listening
+for events, moving focus, measuring and positioning an overlay, normalizing keyboard activation —
+is a plugin here, written once for all six adapters.
+
+## Component availability and DOM readiness
+
+`TReadyPlugin` reports that a component is loaded and available: its instance exists and its
+root DOM element has been announced. It maintains `instance.ready` and the model's `ready`
+event. The instance itself is created before the DOM root becomes available.
+
+| Signal                   | Meaning                                                                                                                |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
+| `element:ready(element)` | The bound root is announced in the next animation frame. DOM plugins can attach listeners, measure, or observe it.     |
+| `element:removed()`      | An announced root was removed or replaced. DOM plugins detach their behavior.                                          |
+| `ready(true / false)`    | Component availability changed. `TReadyPlugin` translates element readiness and removal into this boolean model state. |
+
+The `element:` prefix is the public plugin namespace. Inside a plugin, subscribe to
+`bundle.get(TElementPlugin)?.events.on('ready', handler)` and `'removed'` on the same bus.
+The model's `ready` event carries a boolean rather than a DOM node:
+
+```ts
+import { TButton } from '@soxa-ui/core'
+
+const button = new TButton({ text: 'Save' })
+
+// Subscribe before mounting this controller with an adapter.
+button.events.on('ready', (available) => {
+  console.log(available ? 'Component available' : 'Component unavailable')
+})
+```
+
+`ready` starts as `false`. Removing an announced root sets it to `false`; announcing a root
+again sets it to `true`. Replacing an announced root follows the same cycle: `false`
+synchronously, then `true` in the next animation frame. A binding removed before its first
+announcement emits neither element event. Server rendering does not announce a DOM root.
+
+Availability does not imply visibility or completion of every plugin's DOM handler,
+asynchronous initialization, layout observation, or animation. A `ready(true)` handler can run
+before other plugins' handlers of the same element announcement. The events do not replay:
+when subscribing after mounting, read `instance.ready` for current availability. DOM plugins
+can also read `TElementPlugin.element`, which is assigned immediately, before its announcement.
+
+`TLayer` continues to use `instance.ready` to expose `zIndex` and `data-layer` while the
+component is available; on the server or without an announced root, its exposed `zIndex` is `0`.
+
+## Install
+
+```bash
+npm install @soxa-ui/plugins
+```
+
+An adapter assembles the bundle for you, so you rarely install this package on its own — it comes
+with `@soxa-ui/setup`.
+
+## Usage
+
+Reach a plugin of a mounted component from its instance — the bundle announces itself on the same
+event bus the template uses:
+
+```ts
+import { TButton } from '@soxa-ui/core'
+import { TActionPlugin, TPluginBundle } from '@soxa-ui/plugins'
+
+const button = new TButton({ text: 'Save' })
+
+button.events.on('bundle:create', (bundle: unknown) => {
+  if (bundle instanceof TPluginBundle) {
+    // press is a normalized activation: a click, or Enter/Space on any tag
+    bundle.get(TActionPlugin)?.events.on('press', () => console.log('pressed'))
+  }
+})
+```
+
+Add a plugin of your own to every component of a type — see
+[Plugins and extensions from outside](https://github.com/youra-h/soxa-ui/blob/main/AGENTS.md):
+
+```ts
+import { usePlugins } from '@soxa-ui/setup'
+import { TButton } from '@soxa-ui/core'
+
+usePlugins(TButton, [TRipplePlugin])
+```
+
+Set the motion mode of the whole library at the entry point of the application. By default motion
+follows the system's reduced-motion setting:
+
+```ts
+import { useMotion } from '@soxa-ui/plugins'
+
+useMotion('full') // motion even when the system asks to reduce it; 'reduce' — never
+```
+
+The language and the strings of the library are one value — a locale — that comes from the
+nearest `LocaleProvider` of the framework adapter. A component has neither of its own: the
+language and name plugins write them on mount and on every change, so the first render — the
+server one too — is already in the subtree's language. This package ships the locales and the tools
+to make your own:
+
+```ts
+import { enUS, esES, ruRU, extendLocale, formatName } from '@soxa-ui/plugins'
+import type { TLocale } from '@soxa-ui/plugins'
+
+const esMX = extendLocale(esES, { tag: 'es-MX' }) // another region of a ready language
+const mn: TLocale = extendLocale(enUS, { tag: 'mn-MN', translations: { modal: { close: 'Хаах' } } })
+
+formatName(ruRU.translations.tabs.close, 'Почта') // 'Закрыть Почта'
+```
+
+## Documentation
+
+- [Soxa UI README](https://github.com/youra-h/soxa-ui#readme) — what the library is and how it is
+  put together.
+- [Architecture overview](https://github.com/youra-h/soxa-ui/blob/main/docs/architecture.md) —
+  layers, descriptors, plugins, collections, adapters.
+
+## License
+
+[MIT](https://github.com/youra-h/soxa-ui/blob/main/LICENSE)

package/dist/base/base.class.d.ts

@@ -0,0 +1,54 @@
+import type { IListenable, IPlugin, IPluginContext, TPluginEvents } from './types';
+import { TEvented } from '@soxa-ui/core';
+import type { TEventSink } from '@soxa-ui/core';
+export declare abstract class TBasePlugin<TInstance = any, TEvents extends TPluginEvents = TPluginEvents> implements IPlugin<TInstance, TEvents> {
+    readonly events: TEvented<TEvents>;
+    /**
+     * Отписки от чужих шин, на которые плагин подписался через
+     * {@link _listenTo}. Их снимает `destroy()` — тот же приём, что `_relays`
+     * у `TEvented.relay`.
+     */
+    private _unsubscribes;
+    install(ctx: IPluginContext, options?: unknown): void;
+    /** Run the internal creation announcement after the bundle becomes available. */
+    created(): void;
+    /**
+     * Снимает подписки {@link _listenTo} и сообщает об уничтожении. Список
+     * очищается, поэтому повторный вызов отписываться уже не будет.
+     */
+    destroy(): void;
+    /**
+     * Эмит собственных событий базы — без приведения `this.events` к
+     * конкретной карте (см. `TEventSink` в `@soxa-ui/core`). Эмит звучит за
+     * счёт констрейнта: карта наследника включает `TPluginEvents`.
+     */
+    protected get _sink(): TEventSink<TPluginEvents>;
+    /**
+     * Подписаться на шину, которая живёт дольше плагина: подписку снимет
+     * `destroy()`.
+     *
+     * Такая шина — у владельца (`ctx.getInstance()`): свой `ctrl` приложения
+     * переживает перемонтирование, и каждое монтирование ставит ему новый набор.
+     * Такие же — у расширений движка коллекции, когда движок пришёл снаружи
+     * (`engine`), и у любого инстанса ядра, которого плагин не создавал.
+     * Подписка прямым `on` копила бы на них обработчики уничтоженных плагинов.
+     *
+     * На шину плагина — своего набора (`ctx.get(...)`) или набора элемента —
+     * подписываются прямым `on`: она умирает вместе с набором.
+     *
+     * Метод, а не пара `on`/`off` в каждом плагине: той паре нужно поле под
+     * каждый обработчик, а забытый `off` не виден — обработчик уничтоженного
+     * плагина ничего не делает, и шина копит его молча.
+     *
+     * Шины нет (у набора нет владельца, у движка нет расширения) —
+     * подписываться не на что. Имя события и обработчик сверяются по карте
+     * шины, как у `TEvented.on`.
+     *
+     * `TEvented` в типе шины — ради вывода карты, а не второй вид шины: из
+     * `TEvented<X>` в `IListenable` TypeScript карту не выводит (методы у
+     * `IListenable` обобщённые), а из `TEvented<X>` в `TEvented` — выводит.
+     * `IListenable` нужен шине владельца, которого плагин знает по контракту
+     * (`TListHeightPlugin`).
+     */
+    protected _listenTo<TSource extends Record<string, (...args: any) => any>, K extends keyof TSource>(source: TEvented<TSource> | IListenable<TSource> | null | undefined, event: K, handler: TSource[K]): void;
+}

package/dist/base/base.class.js

@@ -0,0 +1,69 @@
+import { TEvented } from "@soxa-ui/core";
+//#region src/base/base.class.ts
+var TBasePlugin = class {
+	events = new TEvented();
+	/**
+	* Отписки от чужих шин, на которые плагин подписался через
+	* {@link _listenTo}. Их снимает `destroy()` — тот же приём, что `_relays`
+	* у `TEvented.relay`.
+	*/
+	_unsubscribes = [];
+	install(ctx, options) {
+		this._sink.emit("install", ctx, options);
+	}
+	/** Run the internal creation announcement after the bundle becomes available. */
+	created() {
+		this._sink.emit("create", this);
+	}
+	/**
+	* Снимает подписки {@link _listenTo} и сообщает об уничтожении. Список
+	* очищается, поэтому повторный вызов отписываться уже не будет.
+	*/
+	destroy() {
+		for (const unsubscribe of this._unsubscribes) unsubscribe();
+		this._unsubscribes = [];
+		this._sink.emit("destroy");
+	}
+	/**
+	* Эмит собственных событий базы — без приведения `this.events` к
+	* конкретной карте (см. `TEventSink` в `@soxa-ui/core`). Эмит звучит за
+	* счёт констрейнта: карта наследника включает `TPluginEvents`.
+	*/
+	get _sink() {
+		return this.events;
+	}
+	/**
+	* Подписаться на шину, которая живёт дольше плагина: подписку снимет
+	* `destroy()`.
+	*
+	* Такая шина — у владельца (`ctx.getInstance()`): свой `ctrl` приложения
+	* переживает перемонтирование, и каждое монтирование ставит ему новый набор.
+	* Такие же — у расширений движка коллекции, когда движок пришёл снаружи
+	* (`engine`), и у любого инстанса ядра, которого плагин не создавал.
+	* Подписка прямым `on` копила бы на них обработчики уничтоженных плагинов.
+	*
+	* На шину плагина — своего набора (`ctx.get(...)`) или набора элемента —
+	* подписываются прямым `on`: она умирает вместе с набором.
+	*
+	* Метод, а не пара `on`/`off` в каждом плагине: той паре нужно поле под
+	* каждый обработчик, а забытый `off` не виден — обработчик уничтоженного
+	* плагина ничего не делает, и шина копит его молча.
+	*
+	* Шины нет (у набора нет владельца, у движка нет расширения) —
+	* подписываться не на что. Имя события и обработчик сверяются по карте
+	* шины, как у `TEvented.on`.
+	*
+	* `TEvented` в типе шины — ради вывода карты, а не второй вид шины: из
+	* `TEvented<X>` в `IListenable` TypeScript карту не выводит (методы у
+	* `IListenable` обобщённые), а из `TEvented<X>` в `TEvented` — выводит.
+	* `IListenable` нужен шине владельца, которого плагин знает по контракту
+	* (`TListHeightPlugin`).
+	*/
+	_listenTo(source, event, handler) {
+		if (!source) return;
+		source.on(event, handler);
+		this._unsubscribes.push(() => source.off(event, handler));
+	}
+};
+//#endregion
+export { TBasePlugin };

package/dist/base/bundle.class.d.ts

@@ -0,0 +1,25 @@
+import { TEvented } from '@soxa-ui/core';
+import type { ILocaleSource } from '../locale/types';
+import type { IPlugin, IPluginBundle, IPluginConstructor, TPluginBundleEvents } from './types';
+export declare class TPluginBundle implements IPluginBundle {
+    private readonly _instance;
+    readonly events: TEvented<TPluginBundleEvents>;
+    private _plugins;
+    /** Набор объявлен наружу (`created()`): плагин, поставленный позже, объявляется сразу. */
+    private _created;
+    /** Набор уничтожен (`destroy()`): объявлять его наружу больше нельзя. */
+    private _destroyed;
+    /** Id монтирования, которому принадлежит набор (`createId`). */
+    private readonly _mountId;
+    readonly locale: ILocaleSource;
+    constructor(_instance: object, mountId?: string, locale?: ILocaleSource);
+    get destroyed(): boolean;
+    /** Компонент, которому принадлежит набор. */
+    getInstance<T>(): T | null;
+    createId(part: string): string;
+    use<P extends IPlugin<any, any>>(PluginCtor: IPluginConstructor<any, any, P>, options?: object): this;
+    get<P extends IPlugin<any, any>>(ctor: IPluginConstructor<any, any, P>): P | undefined;
+    remove<P extends IPlugin<any, any>>(PluginCtor: IPluginConstructor<any, any, P>): void;
+    created(): void;
+    destroy(): void;
+}

package/dist/base/bundle.class.js

@@ -0,0 +1,68 @@
+import { enUS } from "../locale/locales/en.js";
+import { TLocaleSource } from "../locale/source.class.js";
+import { TEvented } from "@soxa-ui/core";
+//#region src/base/bundle.class.ts
+/** Наборов без id монтирования от адаптера: номер такого монтирования в процессе. */
+var unnamedMounts = 0;
+var TPluginBundle = class {
+	_instance;
+	events = new TEvented();
+	_plugins = /* @__PURE__ */ new Map();
+	/** Набор объявлен наружу (`created()`): плагин, поставленный позже, объявляется сразу. */
+	_created = false;
+	/** Набор уничтожен (`destroy()`): объявлять его наружу больше нельзя. */
+	_destroyed = false;
+	/** Id монтирования, которому принадлежит набор (`createId`). */
+	_mountId;
+	locale;
+	constructor(_instance, mountId, locale) {
+		this._instance = _instance;
+		this._mountId = mountId || `so-${++unnamedMounts}`;
+		this.locale = locale ?? new TLocaleSource(enUS);
+	}
+	get destroyed() {
+		return this._destroyed;
+	}
+	/** Компонент, которому принадлежит набор. */
+	getInstance() {
+		return this._instance ?? null;
+	}
+	createId(part) {
+		return `${this._mountId}-${part}`;
+	}
+	use(PluginCtor, options) {
+		const plugin = new PluginCtor();
+		this._plugins.set(PluginCtor, plugin);
+		plugin.install({
+			get: this.get.bind(this),
+			getInstance: this.getInstance.bind(this),
+			createId: this.createId.bind(this),
+			locale: this.locale
+		}, options);
+		if (this._created) plugin.created();
+		this.events.emit("use", PluginCtor, plugin);
+		return this;
+	}
+	get(ctor) {
+		return this._plugins.get(ctor);
+	}
+	remove(PluginCtor) {
+		const plugin = this._plugins.get(PluginCtor);
+		if (!plugin) return;
+		this.events.emit("remove", PluginCtor, plugin);
+		plugin.destroy();
+		this._plugins.delete(PluginCtor);
+	}
+	created() {
+		if (this._created || this._destroyed) return;
+		this._created = true;
+		for (const plugin of [...this._plugins.values()]) plugin.created();
+	}
+	destroy() {
+		this._destroyed = true;
+		for (const plugin of [...this._plugins.values()].reverse()) plugin.destroy();
+		this._plugins.clear();
+	}
+};
+//#endregion
+export { TPluginBundle };

package/dist/base/index.d.ts

@@ -0,0 +1,3 @@
+export type { IListenable, IPlugin, IPluginContext, IPluginConstructor, IPluginBundle, TPluginBundleEvents, TPluginEvents, TPluginInternalEvents, } from './types';
+export { TBasePlugin } from './base.class';
+export { TPluginBundle } from './bundle.class';

package/dist/base/types.d.ts

@@ -0,0 +1,147 @@
+import type { TEvented } from '@soxa-ui/core';
+import type { ILocaleSource } from '../locale/types';
+/**
+ * Контекст, передаваемый плагину при установке.
+ */
+export interface IPluginContext {
+    get<P extends IPlugin<any, any>>(ctor: IPluginConstructor<any, any, P>): P | undefined;
+    getInstance<T>(): T | null;
+    /**
+     * `id` части компонента в документе — тот же метод набора
+     * (`IPluginBundle.createId`).
+     */
+    createId(part: string): string;
+    /** Локаль поддерева — та же, что у набора (`IPluginBundle.locale`). */
+    readonly locale: ILocaleSource;
+}
+export type TPluginEvents = {
+    install: (ctx: IPluginContext, options?: unknown) => void;
+    /**
+     * Плагин уничтожается. Без аргументов, как и сам `destroy()`: контекста
+     * при уничтожении у плагина нет.
+     */
+    destroy: () => void;
+    /** Internal announcement after bundle:create, once adapters can subscribe. */
+    create: (plugin: IPlugin<any, any>) => void;
+};
+/** Base lifecycle events stay internal to the plugin bundle. */
+export type TPluginInternalEvents = TPluginEvents;
+/**
+ * Плагин — независимая единица логики, устанавливаемая на компонент.
+ */
+export interface IPlugin<TInstance = any, TEvents extends Record<string, (...args: any) => any> = TPluginEvents> {
+    readonly events: TEvented<TEvents>;
+    install(ctx: IPluginContext, options?: unknown): void;
+    /** Объявить плагин доступным снаружи. Вызывается adapter-слоем. */
+    created(): void;
+    destroy(): void;
+}
+/**
+ * Чужая шина глазами плагина: подписка и отписка по одной карте событий.
+ *
+ * Так плагин описывает шину владельца, которого знает по контракту, а не по
+ * классу: `TListHeightPlugin` стоит и на ListBox, и на Select, общего предка у
+ * них нет, а `TEvented` инвариантен по карте событий — `TEvented` одного из них
+ * в `TEvented` общей карты не присваивается. Любой `TEvented`, чья карта
+ * содержит эти события, под этот вид подходит.
+ */
+export interface IListenable<TEvents extends Record<string, (...args: any) => any>> {
+    on<K extends keyof TEvents>(event: K, handler: TEvents[K]): void;
+    off<K extends keyof TEvents>(event: K, handler: TEvents[K]): void;
+}
+/**
+ * Конструктор плагина (со статическим namespace).
+ */
+export interface IPluginConstructor<TInstance = any, TEvents extends Record<string, (...args: any) => any> = TPluginEvents, P extends IPlugin<TInstance, TEvents> = IPlugin<TInstance, TEvents>> {
+    new (): P;
+    /**
+     * Умолчания опций, которые плагин объявляет пропами, — тот же приём, что
+     * `static defaultValues` у классов ядра.
+     *
+     * С них плагин стартует, если опция не задана, и из них же setup собирает
+     * умолчание в описание пропа (`TPropSpec.default`), откуда его
+     * берёт адаптер. Умолчание в приватном поле метаданные не видят: адаптер
+     * подставил бы отсутствующему пропу своё значение и записал его в плагин.
+     */
+    readonly defaultValues?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Контейнер плагинов.
+ */
+/**
+ * События набора: плагин встал и плагин снят — в любой момент жизни
+ * компонента, не только при сборке. По ним setup подхватывает контракт
+ * плагина, поставленного снаружи (`pluginProps`, `plugin:event`).
+ */
+export type TPluginBundleEvents = {
+    /** Плагин установлен: после `install`. */
+    use: (ctor: IPluginConstructor<any, any, any>, plugin: IPlugin<any, any>) => void;
+    /** Плагин снимается: до его `destroy`. */
+    remove: (ctor: IPluginConstructor<any, any, any>, plugin: IPlugin<any, any>) => void;
+};
+export interface IPluginBundle {
+    /** Шина набора: `use`, `remove` (`TPluginBundleEvents`). */
+    readonly events: TEvented<TPluginBundleEvents>;
+    /**
+     * Компонент, которому принадлежит набор.
+     *
+     * Тот же метод, что плагин внутри бандла видит как `ctx.getInstance()` —
+     * контекст отдаёт именно его, связанным. Одно имя и одна сигнатура снаружи
+     * и изнутри.
+     *
+     * Наружу нужен потому, что владельческий плагин получает от
+     * `TCollectionBundlesPlugin` бандлы элементов, а дотянуться должен до самих
+     * элементов — например, чтобы проставить им `data-*`.
+     */
+    getInstance<T>(): T | null;
+    /**
+     * `id` части компонента в документе: `<mountId>-<part>`.
+     *
+     * `mountId` — id монтирования, которому принадлежит набор. Его даёт адаптер
+     * от `useId` фреймворка: тот выводит его из места компонента в дереве, и на
+     * сервере и в браузере он один. Поэтому `id`, ссылки на них и пометки
+     * панелей сходятся при гидратации. Монтирование, а не экземпляр: свой id
+     * монтирования есть и у внешнего `ctrl`, и у элемента коллекции из данных —
+     * их конструктор адаптер не зовёт.
+     *
+     * Адаптер без `useId` id монтирования не даёт, и набор берёт его из своего
+     * счётчика процесса — серверный рендер с таким адаптером по `id` не сойдётся.
+     */
+    createId(part: string): string;
+    /**
+     * Локаль поддерева, в котором смонтирован компонент: тег для Intl и строки
+     * библиотеки, с событием смены.
+     *
+     * Её даёт адаптер — от провайдера локали фреймворка, ближайшего выше по
+     * дереву, как id монтирования — от `useId`: язык знает место компонента в
+     * дереве, а не экземпляр. Поэтому сервер рисует параллельные запросы каждый
+     * на своём языке, а вложенный провайдер даёт поддереву свой. Без провайдера
+     * у набора своя английская локаль (`enUS`).
+     *
+     * Читают её плагины языка и имён (`TLocalePlugin`, `TNamesPlugin`): пишут
+     * при установке и подписываются на смену.
+     */
+    readonly locale: ILocaleSource;
+    use<P extends IPlugin<any, any>>(PluginCtor: IPluginConstructor<any, any, P>, options?: object): this;
+    get<P extends IPlugin<any, any>>(ctor: IPluginConstructor<any, any, P>): P | undefined;
+    remove<P extends IPlugin<any, any>>(PluginCtor: IPluginConstructor<any, any, P>): void;
+    /**
+     * Объявить набор наружу: `created()` у каждого плагина, в порядке установки.
+     * Плагин, поставленный после этого, объявляется сразу в `use()`. Повторный
+     * вызов и вызов на уничтоженном наборе ничего не делают. Вызывает setup
+     * (`assembleBundle`).
+     */
+    created(): void;
+    /**
+     * Уничтожить набор: `destroy()` у каждого плагина, в обратном порядке
+     * установки, — и выставить `destroyed`. Вызывает владелец набора —
+     * адаптерный контекст, который его создал.
+     */
+    destroy(): void;
+    /**
+     * Набор уничтожен (`destroy()`) и наружу больше не объявляется: плагин,
+     * который подписчик поставил бы в него, уничтожать уже некому. По нему
+     * setup не шлёт `bundle:create`, если набор уничтожили раньше, чем объявили.
+     */
+    readonly destroyed: boolean;
+}

package/dist/custom/accordion/header.d.ts

@@ -0,0 +1,19 @@
+import type { IPluginContext } from '../../base';
+/**
+ * Заголовок секции в её узле. `null` — узла нет или заголовка в нём нет.
+ *
+ * Узел фокуса `Accordion.Item` (`focusTarget` плагина действия): запись
+ * `focused = true` ставит фокус на заголовок, а не на обёртку секции.
+ */
+export declare function headerIn(node: Element | null): Element | null;
+/**
+ * Заголовок первой секции, на которую можно перейти, — узел фокуса Accordion
+ * (`focusTarget` плагина действия). Остановок у аккордеона столько же, сколько
+ * заголовков, и запись `focused = true` ставит фокус на первую из них — туда
+ * же, куда ведёт Tab. Секции — по коллекции, в порядке показа; заголовок —
+ * тем же правилом, что у самой секции (`headerIn`).
+ *
+ * `null` — секций, на которые можно перейти, нет, или узла секции нет в
+ * документе.
+ */
+export declare function firstHeaderOf(_root: Element, ctx: IPluginContext): Element | null;

package/dist/custom/accordion/header.js

@@ -0,0 +1,38 @@
+import { TCollectionElements } from "../collection/collection-elements.plugin.js";
+import { isReachable } from "../collection/reachable.js";
+import { batchOf } from "@soxa-ui/core";
+//#region src/custom/accordion/header.ts
+/**
+* Заголовок секции внутри её узла. Корень секции — обёртка для темы вокруг
+* заголовка и панели, а заголовком является вложенная кнопка: на ней набор
+* `aria` секции, и раскрытость панели по APG Accordion объявляет её
+* `aria-expanded`. Заголовок — первый такой узел: панель и всё, что в ней
+* лежит, идут за ним.
+*/
+var HEADER_SELECTOR = "[aria-expanded]";
+/**
+* Заголовок секции в её узле. `null` — узла нет или заголовка в нём нет.
+*
+* Узел фокуса `Accordion.Item` (`focusTarget` плагина действия): запись
+* `focused = true` ставит фокус на заголовок, а не на обёртку секции.
+*/
+function headerIn(node) {
+	return node?.querySelector(HEADER_SELECTOR) ?? null;
+}
+/**
+* Заголовок первой секции, на которую можно перейти, — узел фокуса Accordion
+* (`focusTarget` плагина действия). Остановок у аккордеона столько же, сколько
+* заголовков, и запись `focused = true` ставит фокус на первую из них — туда
+* же, куда ведёт Tab. Секции — по коллекции, в порядке показа; заголовок —
+* тем же правилом, что у самой секции (`headerIn`).
+*
+* `null` — секций, на которые можно перейти, нет, или узла секции нет в
+* документе.
+*/
+function firstHeaderOf(_root, ctx) {
+	const elements = ctx.get(TCollectionElements) ?? null;
+	const section = batchOf(elements?.engine)?.shown.find(isReachable);
+	return section ? headerIn(elements?.getElementByItem(section) ?? null) : null;
+}
+//#endregion
+export { firstHeaderOf, headerIn };

package/dist/custom/accordion/index.d.ts

@@ -0,0 +1,2 @@
+export * from './item-ids';
+export { firstHeaderOf, headerIn } from './header';

package/dist/custom/accordion/item-ids/index.d.ts

@@ -0,0 +1 @@
+export * from './item-ids.plugin';

package/dist/custom/accordion/item-ids/item-ids.plugin.d.ts

@@ -0,0 +1,24 @@
+import { TBasePlugin } from '../../../base';
+import type { IPluginContext } from '../../../base';
+/**
+ * TAccordionItemIdsPlugin — связка «заголовок ↔ панель» секции Accordion в
+ * документе.
+ *
+ * Обе стороны — в наборах секции. В `aria` (он стоит на заголовке) — `id`
+ * заголовка и `aria-controls` на панель. В `contentAria` (он стоит на панели) —
+ * `id` панели и `aria-labelledby` на заголовок. Формула одна, здесь.
+ *
+ * `id` заголовка, заданный приложением (`TIdPlugin` секции), главнее: он и
+ * встаёт на заголовок, и на него ссылается панель. Сменили — плагин
+ * переписывает обе стороны ссылки на заголовок, сняли — снова `id` от
+ * монтирования. У панели `id` приложения нет, её `id` — формула.
+ *
+ * Без него — `id` от монтирования секции (`createId`), а не от экземпляра: он
+ * нужен только документу, и на сервере и в браузере обязан совпасть. Секция
+ * из данных рисуется с готовым экземпляром (`ctrl`), и его конструктор адаптер
+ * не зовёт, а монтирование у неё своё. Пишется при установке, синхронно, —
+ * связка есть уже в первой (и серверной) отрисовке.
+ */
+export declare class TAccordionItemIdsPlugin extends TBasePlugin {
+    install(ctx: IPluginContext): void;
+}