@cuby-ui/cdk 0.0.562 → 0.0.564

package/README.md

@@ -1,392 +1,392 @@
-# Cuby UI - агентская документация (RU)
-
-Документ для кодовых агентов. Описывает публичный API пакета `@cuby-ui/cdk`, а также примеры использования.
-
-## Оглавление
-- [CDK: директивы](#cdk-директивы)
-- [CDK: пайпы](#cdk-пайпы)
-- [CDK: сервисы](#cdk-сервисы)
-- [CDK: токены](#cdk-токены)
-- [CDK: интерфейсы и типы](#cdk-интерфейсы-и-типы)
-- [CDK: утилиты и константы](#cdk-утилиты-и-константы)
-- [Анти-паттерны](#анти-паттерны)
-- [Линт и форматирование](#линт-и-форматирование)
-- [Версии и совместимость](#версии-и-совместимость)
-
-## CDK: директивы
-
-### Feature: CuiAutoResizingDirective (`textarea[cuiAutoResizing]`)
-Описание: автоматический ресайз textarea по контенту.
-Публичный API:
-- Standalone: да
-Пример:
-```html
-<textarea cuiAutoResizing [formControl]="notesControl" style="max-height: 200px;"></textarea>
-```
-
-### Feature: CuiClickOutsideDirective (`(cuiClickOutside)`)
-Описание: эмитит событие при клике вне элемента.
-Публичный API:
-- Standalone: да
-- Output: `cuiClickOutside: EventEmitter<HTMLElement>`
-Пример:
-```html
-<div (cuiClickOutside)="onOutside()">
-  ...
-</div>
-```
-
-### Feature: CuiContentEditableValueAccessorDirective
-Описание: связывает contenteditable с Angular формами.
-Публичный API:
-- Standalone: да
-- Селектор: `[contenteditable][formControlName|formControl|ngModel]`
-Пример:
-```html
-<div contenteditable [formControl]="bioControl"></div>
-```
-
-### Feature: CuiDimensionsObserverDirective (`[cuiResizeObserver]`)
-Описание: отдаёт размеры элемента при изменениях.
-Публичный API:
-- Standalone: да
-- Output: `cuiResizeObserver: EventEmitter<CuiDimensions>`
-Пример:
-```html
-<div cuiResizeObserver (cuiResizeObserver)="onResize($event)"></div>
-```
-
-### Feature: CuiElementDirective (`[cuiElement]`)
-Описание: экспортирует `ElementRef` как `elementRef` в шаблоне.
-Публичный API:
-- Standalone: да
-- exportAs: `elementRef`
-Пример:
-```html
-<button cuiElement #btn="elementRef">Open</button>
-<cui-context-menu [target]="btn.nativeElement" [items]="items"></cui-context-menu>
-```
-
-### Feature: CuiFocusTrapDirective (`[cuiFocusTrap]`)
-Описание: запирает фокус внутри контейнера.
-Публичный API:
-- Standalone: да
-Пример:
-```html
-<div cuiFocusTrap>
-  <input />
-  <button>OK</button>
-</div>
-```
-
-### Feature: CuiItemDirective (`[cuiItem]`)
-Описание: метка элемента коллекции, используется в `cui-breadcrumbs`.
-Публичный API:
-- Standalone: да
-Пример:
-```html
-<a cuiBreadcrumb *cuiItem>Раздел</a>
-```
-
-### Feature: CuiLetDirective (`*cuiLet`)
-Описание: структурная директива для удобного alias значения.
-Публичный API:
-- Standalone: да
-Пример:
-```html
-<ng-container *cuiLet="user$ | async as user">
-  {{ user?.name }}
-</ng-container>
-```
-
-### Feature: CuiLetContext
-Описание: контекст для `cuiLet`, полезен для типизации.
-Публичный API:
-- Класс: `CuiLetContext<T>`
-Пример:
-```ts
-type Ctx = CuiLetContext<User>;
-```
-
-### Feature: CuiTargetDirective (`[ccTarget]`)
-Описание: слушает клики на внешнем DOM-элементе.
-Публичный API:
-- Standalone: да
-- Input: `ccTarget: HTMLElement`
-- Output: `clicked: EventEmitter<MouseEvent>`
-Пример:
-```html
-<div [ccTarget]="buttonRef.nativeElement" (clicked)="onTargetClick($event)"></div>
-```
-
-## CDK: пайпы
-
-### Feature: CuiFilterPipe (`| cuiFilter`)
-Описание: фильтрация массива по matcher функции.
-Публичный API:
-- Standalone: да
-Пример:
-```html
-<li *ngFor="let item of items | cuiFilter: isVisible: filterValue">
-  {{ item.label }}
-</li>
-```
-
-## CDK: сервисы
-
-### Feature: CuiDestroyService
-Описание: Subject, который автоматически завершает подписки в `ngOnDestroy`.
-Публичный API:
-- Использование: `takeUntil(destroy$)`
-Пример:
-```ts
-@Component({ providers: [CuiDestroyService] })
-export class ExampleComponent {
-  private destroy$ = inject(CuiDestroyService);
-
-  ngOnInit() {
-    this.stream$.pipe(takeUntil(this.destroy$)).subscribe();
-  }
-}
-```
-
-### Feature: CuiIdService
-Описание: генератор уникальных id.
-Публичный API:
-- Метод: `generate(): string`
-Пример:
-```ts
-const id = inject(CuiIdService).generate();
-```
-
-### Feature: CuiPopoverService
-Описание: абстрактный сервис для поповеров/оверлеев.
-Публичный API:
-- Метод: `open(content, options?) -> Observable`
-- Типы: `CuiPopoverContext`, `CuiPopover<T>`
-Пример:
-```ts
-class MyPopoverService extends CuiPopoverService<MyOptions> {
-  constructor() {
-    super(MY_ITEMS_TOKEN, MyPopoverComponent, MY_DEFAULT_OPTIONS);
-  }
-}
-```
-
-### Feature: CuiPopoverContext
-Описание: контекст поповера (`id`, `component`, `content`, `completeWith`).
-Публичный API:
-- Поля: `$implicit`, `id`, `component`, `content`, `completeWith`
-Пример:
-```ts
-const ctx: CuiPopoverContext = {
-  $implicit: observer,
-  id: 'id',
-  component: MyComponent,
-  content: 'text',
-  completeWith: () => {}
-};
-```
-
-### Feature: CuiPopover
-Описание: тип поповера (опции + контекст).
-Пример:
-```ts
-type AlertPopover = CuiPopover<CuiAlertOptions>;
-```
-
-## CDK: токены
-
-### Feature: CUI_WINDOW
-Описание: DI токен для `window`.
-Пример:
-```ts
-const win = inject(CUI_WINDOW);
-```
-
-### Feature: CUI_LOCAL_STORAGE
-Описание: DI токен для `localStorage`.
-Пример:
-```ts
-const storage = inject(CUI_LOCAL_STORAGE);
-```
-
-### Feature: CUI_SESSION_STORAGE
-Описание: DI токен для `sessionStorage`.
-Пример:
-```ts
-const storage = inject(CUI_SESSION_STORAGE);
-```
-
-### Feature: CUI_HISTORY
-Описание: DI токен для `history`.
-Пример:
-```ts
-const history = inject(CUI_HISTORY);
-```
-
-## CDK: интерфейсы и типы
-
-### Feature: CuiDimensions
-Описание: размеры элемента.
-Публичный API:
-- Поля: `width`, `height`
-Пример:
-```ts
-function onResize(dim: CuiDimensions) { console.log(dim.width); }
-```
-
-### Feature: CuiOnChange
-Описание: сигнатура функции onChange для ControlValueAccessor.
-Пример:
-```ts
-const onChange: CuiOnChange<string> = (value) => console.log(value);
-```
-
-### Feature: CuiOnTouched
-Описание: сигнатура функции onTouched.
-Пример:
-```ts
-const onTouched: CuiOnTouched = () => console.log('touched');
-```
-
-### Feature: CuiTimeMode
-Описание: формат времени для `CuiTime`.
-Публичный API:
-- Значения: `HH:MM`, `HH:MM:SS`, `HH:MM:SS.MSS`
-Пример:
-```ts
-const mode: CuiTimeMode = 'HH:MM:SS';
-```
-
-### Feature: CuiInputType
-Описание: типы инпутов, используемые в core.
-Публичный API:
-- Значения: `text | password`
-Пример:
-```ts
-const type: CuiInputType = 'password';
-```
-
-### Feature: Mapper
-Описание: тип функции-отображения.
-Пример:
-```ts
-const map: Mapper<[number, number], number> = (a, b) => a + b;
-```
-
-### Feature: CuiMatcher
-Описание: тип функции-предиката для фильтрации.
-Пример:
-```ts
-const matcher: CuiMatcher<[number, number]> = (item, min) => item > min;
-```
-
-### Feature: CuiNullable
-Описание: `T | null | undefined`.
-Пример:
-```ts
-const value: CuiNullable<string> = null;
-```
-
-### Feature: CuiValueOf
-Описание: значение union по ключам объекта.
-Пример:
-```ts
-type Modes = CuiValueOf<{ a: 'x'; b: 'y' }>;
-```
-
-### Feature: CuiTime
-Описание: класс времени с парсингом и форматированием.
-Публичный API:
-- Методы: `fromString`, `fromPT`, `toString`, `toPT`
-Пример:
-```ts
-const time = CuiTime.fromString('12:30');
-time.toString('HH:MM'); // "12:30"
-```
-
-## CDK: утилиты и константы
-
-### Feature: svgNodeFilter
-Описание: фильтр узлов для TreeWalker, исключает SVG.
-Пример:
-```ts
-document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT, svgNodeFilter);
-```
-
-### Feature: cuiContainsOrAfter
-Описание: проверка, что узел внутри или после другого.
-Пример:
-```ts
-cuiContainsOrAfter(container, node);
-```
-
-### Feature: cuiIsHTMLElement
-Описание: type guard для HTMLElement.
-Пример:
-```ts
-if (cuiIsHTMLElement(node)) node.focus();
-```
-
-### Feature: cuiBlurNativeFocused
-Описание: blur активного элемента.
-Пример:
-```ts
-cuiBlurNativeFocused(document);
-```
-
-### Feature: cuiGetClosestFocusable
-Описание: поиск ближайшего фокусируемого элемента.
-Пример:
-```ts
-const next = cuiGetClosestFocusable({ initial, root });
-```
-
-### Feature: cuiGetNativeFocused
-Описание: получение активного элемента с учетом shadow DOM.
-Пример:
-```ts
-const active = cuiGetNativeFocused(document);
-```
-
-### Feature: cuiIsNativeKeyboardFocusable
-Описание: проверка фокуса по клавиатуре.
-Пример:
-```ts
-cuiIsNativeKeyboardFocusable(element);
-```
-
-### Feature: cuiIsNativeMouseFocusable
-Описание: проверка фокуса по клику мыши.
-Пример:
-```ts
-cuiIsNativeMouseFocusable(element);
-```
-
-### Feature: cuiCreateToken / cuiCreateTokenFromFactory
-Описание: хелперы для создания `InjectionToken`.
-Пример:
-```ts
-export const MY_TOKEN = cuiCreateToken({ enabled: true });
-```
-
-### Feature: cuiProvide
-Описание: хелпер для `ExistingProvider`.
-Пример:
-```ts
-providers: [cuiProvide(NG_VALUE_ACCESSOR, MyComponent, true)]
-```
-
-## Анти-паттерны
-- Анти-паттерн: передавать строку вместо `CuiTime` в `cui-input-time`. Описание: компонент ожидает `CuiTime`.
-
-## Линт и форматирование
-- Явных конфигураций ESLint/Prettier в репозитории нет. Ориентируйтесь на текущий стиль файлов и типичные правила Angular/TypeScript.
-
-## Версии и совместимость
-- Angular: `>=18.0.0`
-- RxJS: `>=7.0.0`
-- `@maskito/*`: `^2.5.0` (input number/time)
-- `@tinkoff/ng-polymorpheus`: `^4.3.0` (dialog header)
-- Пакеты `@cuby-ui/*`: версия `0.0.177` (см. `projects/*/package.json`)
+# Cuby UI - агентская документация (RU)
+
+Документ для кодовых агентов. Описывает публичный API пакета `@cuby-ui/cdk`, а также примеры использования.
+
+## Оглавление
+- [CDK: директивы](#cdk-директивы)
+- [CDK: пайпы](#cdk-пайпы)
+- [CDK: сервисы](#cdk-сервисы)
+- [CDK: токены](#cdk-токены)
+- [CDK: интерфейсы и типы](#cdk-интерфейсы-и-типы)
+- [CDK: утилиты и константы](#cdk-утилиты-и-константы)
+- [Анти-паттерны](#анти-паттерны)
+- [Линт и форматирование](#линт-и-форматирование)
+- [Версии и совместимость](#версии-и-совместимость)
+
+## CDK: директивы
+
+### Feature: CuiAutoResizingDirective (`textarea[cuiAutoResizing]`)
+Описание: автоматический ресайз textarea по контенту.
+Публичный API:
+- Standalone: да
+Пример:
+```html
+<textarea cuiAutoResizing [formControl]="notesControl" style="max-height: 200px;"></textarea>
+```
+
+### Feature: CuiClickOutsideDirective (`(cuiClickOutside)`)
+Описание: эмитит событие при клике вне элемента.
+Публичный API:
+- Standalone: да
+- Output: `cuiClickOutside: EventEmitter<HTMLElement>`
+Пример:
+```html
+<div (cuiClickOutside)="onOutside()">
+  ...
+</div>
+```
+
+### Feature: CuiContentEditableValueAccessorDirective
+Описание: связывает contenteditable с Angular формами.
+Публичный API:
+- Standalone: да
+- Селектор: `[contenteditable][formControlName|formControl|ngModel]`
+Пример:
+```html
+<div contenteditable [formControl]="bioControl"></div>
+```
+
+### Feature: CuiDimensionsObserverDirective (`[cuiResizeObserver]`)
+Описание: отдаёт размеры элемента при изменениях.
+Публичный API:
+- Standalone: да
+- Output: `cuiResizeObserver: EventEmitter<CuiDimensions>`
+Пример:
+```html
+<div cuiResizeObserver (cuiResizeObserver)="onResize($event)"></div>
+```
+
+### Feature: CuiElementDirective (`[cuiElement]`)
+Описание: экспортирует `ElementRef` как `elementRef` в шаблоне.
+Публичный API:
+- Standalone: да
+- exportAs: `elementRef`
+Пример:
+```html
+<button cuiElement #btn="elementRef">Open</button>
+<cui-context-menu [target]="btn.nativeElement" [items]="items"></cui-context-menu>
+```
+
+### Feature: CuiFocusTrapDirective (`[cuiFocusTrap]`)
+Описание: запирает фокус внутри контейнера.
+Публичный API:
+- Standalone: да
+Пример:
+```html
+<div cuiFocusTrap>
+  <input />
+  <button>OK</button>
+</div>
+```
+
+### Feature: CuiItemDirective (`[cuiItem]`)
+Описание: метка элемента коллекции, используется в `cui-breadcrumbs`.
+Публичный API:
+- Standalone: да
+Пример:
+```html
+<a cuiBreadcrumb *cuiItem>Раздел</a>
+```
+
+### Feature: CuiLetDirective (`*cuiLet`)
+Описание: структурная директива для удобного alias значения.
+Публичный API:
+- Standalone: да
+Пример:
+```html
+<ng-container *cuiLet="user$ | async as user">
+  {{ user?.name }}
+</ng-container>
+```
+
+### Feature: CuiLetContext
+Описание: контекст для `cuiLet`, полезен для типизации.
+Публичный API:
+- Класс: `CuiLetContext<T>`
+Пример:
+```ts
+type Ctx = CuiLetContext<User>;
+```
+
+### Feature: CuiTargetDirective (`[ccTarget]`)
+Описание: слушает клики на внешнем DOM-элементе.
+Публичный API:
+- Standalone: да
+- Input: `ccTarget: HTMLElement`
+- Output: `clicked: EventEmitter<MouseEvent>`
+Пример:
+```html
+<div [ccTarget]="buttonRef.nativeElement" (clicked)="onTargetClick($event)"></div>
+```
+
+## CDK: пайпы
+
+### Feature: CuiFilterPipe (`| cuiFilter`)
+Описание: фильтрация массива по matcher функции.
+Публичный API:
+- Standalone: да
+Пример:
+```html
+<li *ngFor="let item of items | cuiFilter: isVisible: filterValue">
+  {{ item.label }}
+</li>
+```
+
+## CDK: сервисы
+
+### Feature: CuiDestroyService
+Описание: Subject, который автоматически завершает подписки в `ngOnDestroy`.
+Публичный API:
+- Использование: `takeUntil(destroy$)`
+Пример:
+```ts
+@Component({ providers: [CuiDestroyService] })
+export class ExampleComponent {
+  private destroy$ = inject(CuiDestroyService);
+
+  ngOnInit() {
+    this.stream$.pipe(takeUntil(this.destroy$)).subscribe();
+  }
+}
+```
+
+### Feature: CuiIdService
+Описание: генератор уникальных id.
+Публичный API:
+- Метод: `generate(): string`
+Пример:
+```ts
+const id = inject(CuiIdService).generate();
+```
+
+### Feature: CuiPopoverService
+Описание: абстрактный сервис для поповеров/оверлеев.
+Публичный API:
+- Метод: `open(content, options?) -> Observable`
+- Типы: `CuiPopoverContext`, `CuiPopover<T>`
+Пример:
+```ts
+class MyPopoverService extends CuiPopoverService<MyOptions> {
+  constructor() {
+    super(MY_ITEMS_TOKEN, MyPopoverComponent, MY_DEFAULT_OPTIONS);
+  }
+}
+```
+
+### Feature: CuiPopoverContext
+Описание: контекст поповера (`id`, `component`, `content`, `completeWith`).
+Публичный API:
+- Поля: `$implicit`, `id`, `component`, `content`, `completeWith`
+Пример:
+```ts
+const ctx: CuiPopoverContext = {
+  $implicit: observer,
+  id: 'id',
+  component: MyComponent,
+  content: 'text',
+  completeWith: () => {}
+};
+```
+
+### Feature: CuiPopover
+Описание: тип поповера (опции + контекст).
+Пример:
+```ts
+type AlertPopover = CuiPopover<CuiAlertOptions>;
+```
+
+## CDK: токены
+
+### Feature: CUI_WINDOW
+Описание: DI токен для `window`.
+Пример:
+```ts
+const win = inject(CUI_WINDOW);
+```
+
+### Feature: CUI_LOCAL_STORAGE
+Описание: DI токен для `localStorage`.
+Пример:
+```ts
+const storage = inject(CUI_LOCAL_STORAGE);
+```
+
+### Feature: CUI_SESSION_STORAGE
+Описание: DI токен для `sessionStorage`.
+Пример:
+```ts
+const storage = inject(CUI_SESSION_STORAGE);
+```
+
+### Feature: CUI_HISTORY
+Описание: DI токен для `history`.
+Пример:
+```ts
+const history = inject(CUI_HISTORY);
+```
+
+## CDK: интерфейсы и типы
+
+### Feature: CuiDimensions
+Описание: размеры элемента.
+Публичный API:
+- Поля: `width`, `height`
+Пример:
+```ts
+function onResize(dim: CuiDimensions) { console.log(dim.width); }
+```
+
+### Feature: CuiOnChange
+Описание: сигнатура функции onChange для ControlValueAccessor.
+Пример:
+```ts
+const onChange: CuiOnChange<string> = (value) => console.log(value);
+```
+
+### Feature: CuiOnTouched
+Описание: сигнатура функции onTouched.
+Пример:
+```ts
+const onTouched: CuiOnTouched = () => console.log('touched');
+```
+
+### Feature: CuiTimeMode
+Описание: формат времени для `CuiTime`.
+Публичный API:
+- Значения: `HH:MM`, `HH:MM:SS`, `HH:MM:SS.MSS`
+Пример:
+```ts
+const mode: CuiTimeMode = 'HH:MM:SS';
+```
+
+### Feature: CuiInputType
+Описание: типы инпутов, используемые в core.
+Публичный API:
+- Значения: `text | password`
+Пример:
+```ts
+const type: CuiInputType = 'password';
+```
+
+### Feature: Mapper
+Описание: тип функции-отображения.
+Пример:
+```ts
+const map: Mapper<[number, number], number> = (a, b) => a + b;
+```
+
+### Feature: CuiMatcher
+Описание: тип функции-предиката для фильтрации.
+Пример:
+```ts
+const matcher: CuiMatcher<[number, number]> = (item, min) => item > min;
+```
+
+### Feature: CuiNullable
+Описание: `T | null | undefined`.
+Пример:
+```ts
+const value: CuiNullable<string> = null;
+```
+
+### Feature: CuiValueOf
+Описание: значение union по ключам объекта.
+Пример:
+```ts
+type Modes = CuiValueOf<{ a: 'x'; b: 'y' }>;
+```
+
+### Feature: CuiTime
+Описание: класс времени с парсингом и форматированием.
+Публичный API:
+- Методы: `fromString`, `fromPT`, `toString`, `toPT`
+Пример:
+```ts
+const time = CuiTime.fromString('12:30');
+time.toString('HH:MM'); // "12:30"
+```
+
+## CDK: утилиты и константы
+
+### Feature: svgNodeFilter
+Описание: фильтр узлов для TreeWalker, исключает SVG.
+Пример:
+```ts
+document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT, svgNodeFilter);
+```
+
+### Feature: cuiContainsOrAfter
+Описание: проверка, что узел внутри или после другого.
+Пример:
+```ts
+cuiContainsOrAfter(container, node);
+```
+
+### Feature: cuiIsHTMLElement
+Описание: type guard для HTMLElement.
+Пример:
+```ts
+if (cuiIsHTMLElement(node)) node.focus();
+```
+
+### Feature: cuiBlurNativeFocused
+Описание: blur активного элемента.
+Пример:
+```ts
+cuiBlurNativeFocused(document);
+```
+
+### Feature: cuiGetClosestFocusable
+Описание: поиск ближайшего фокусируемого элемента.
+Пример:
+```ts
+const next = cuiGetClosestFocusable({ initial, root });
+```
+
+### Feature: cuiGetNativeFocused
+Описание: получение активного элемента с учетом shadow DOM.
+Пример:
+```ts
+const active = cuiGetNativeFocused(document);
+```
+
+### Feature: cuiIsNativeKeyboardFocusable
+Описание: проверка фокуса по клавиатуре.
+Пример:
+```ts
+cuiIsNativeKeyboardFocusable(element);
+```
+
+### Feature: cuiIsNativeMouseFocusable
+Описание: проверка фокуса по клику мыши.
+Пример:
+```ts
+cuiIsNativeMouseFocusable(element);
+```
+
+### Feature: cuiCreateToken / cuiCreateTokenFromFactory
+Описание: хелперы для создания `InjectionToken`.
+Пример:
+```ts
+export const MY_TOKEN = cuiCreateToken({ enabled: true });
+```
+
+### Feature: cuiProvide
+Описание: хелпер для `ExistingProvider`.
+Пример:
+```ts
+providers: [cuiProvide(NG_VALUE_ACCESSOR, MyComponent, true)]
+```
+
+## Анти-паттерны
+- Анти-паттерн: передавать строку вместо `CuiTime` в `cui-input-time`. Описание: компонент ожидает `CuiTime`.
+
+## Линт и форматирование
+- Явных конфигураций ESLint/Prettier в репозитории нет. Ориентируйтесь на текущий стиль файлов и типичные правила Angular/TypeScript.
+
+## Версии и совместимость
+- Angular: `>=18.0.0`
+- RxJS: `>=7.0.0`
+- `@maskito/*`: `^2.5.0` (input number/time)
+- `@tinkoff/ng-polymorpheus`: `^4.3.0` (dialog header)
+- Пакеты `@cuby-ui/*`: версия `0.0.177` (см. `projects/*/package.json`)