@cuby-ui/cdk 0.0.485 → 0.0.488

package/README.md

@@ -1,25 +1,392 @@
-# Cdk
+# Cuby UI - агентская документация (RU)
 
-This library was generated with [Angular CLI](https://github.com/angular/angular-cli) version 15.2.0.
+Документ для кодовых агентов. Описывает публичный API пакета `@cuby-ui/cdk`, а также примеры использования.
 
-## Code scaffolding
+## Оглавление
+- [CDK: директивы](#cdk-директивы)
+- [CDK: пайпы](#cdk-пайпы)
+- [CDK: сервисы](#cdk-сервисы)
+- [CDK: токены](#cdk-токены)
+- [CDK: интерфейсы и типы](#cdk-интерфейсы-и-типы)
+- [CDK: утилиты и константы](#cdk-утилиты-и-константы)
+- [Анти-паттерны](#анти-паттерны)
+- [Линт и форматирование](#линт-и-форматирование)
+- [Версии и совместимость](#версии-и-совместимость)
 
-Run `ng generate component component-name --project cdk` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module --project cdk`.
+## CDK: директивы
 
-> Note: Don't forget to add `--project cdk` or else it will be added to the default project in your `angular.json` file.
+### Feature: CuiAutoResizingDirective (`textarea[cuiAutoResizing]`)
+Описание: автоматический ресайз textarea по контенту.
+Публичный API:
+- Standalone: да
+Пример:
+```html
+<textarea cuiAutoResizing [formControl]="notesControl" style="max-height: 200px;"></textarea>
+```
 
-## Build
+### Feature: CuiClickOutsideDirective (`(cuiClickOutside)`)
+Описание: эмитит событие при клике вне элемента.
+Публичный API:
+- Standalone: да
+- Output: `cuiClickOutside: EventEmitter<HTMLElement>`
+Пример:
+```html
+<div (cuiClickOutside)="onOutside()">
+  ...
+</div>
+```
 
-Run `ng build cdk` to build the project. The build artifacts will be stored in the `dist/` directory.
+### Feature: CuiContentEditableValueAccessorDirective
+Описание: связывает contenteditable с Angular формами.
+Публичный API:
+- Standalone: да
+- Селектор: `[contenteditable][formControlName|formControl|ngModel]`
+Пример:
+```html
+<div contenteditable [formControl]="bioControl"></div>
+```
 
-## Publishing
+### Feature: CuiDimensionsObserverDirective (`[cuiResizeObserver]`)
+Описание: отдаёт размеры элемента при изменениях.
+Публичный API:
+- Standalone: да
+- Output: `cuiResizeObserver: EventEmitter<CuiDimensions>`
+Пример:
+```html
+<div cuiResizeObserver (cuiResizeObserver)="onResize($event)"></div>
+```
 
-After building your library with `ng build cdk`, go to the dist folder `cd dist/cdk` and run `npm publish`.
+### 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>
+```
 
-## Running unit tests
+### Feature: CuiFocusTrapDirective (`[cuiFocusTrap]`)
+Описание: запирает фокус внутри контейнера.
+Публичный API:
+- Standalone: да
+Пример:
+```html
+<div cuiFocusTrap>
+  <input />
+  <button>OK</button>
+</div>
+```
 
-Run `ng test cdk` to execute the unit tests via [Karma](https://karma-runner.github.io).
+### Feature: CuiItemDirective (`[cuiItem]`)
+Описание: метка элемента коллекции, используется в `cui-breadcrumbs`.
+Публичный API:
+- Standalone: да
+Пример:
+```html
+<a cuiBreadcrumb *cuiItem>Раздел</a>
+```
 
-## Further help
+### Feature: CuiLetDirective (`*cuiLet`)
+Описание: структурная директива для удобного alias значения.
+Публичный API:
+- Standalone: да
+Пример:
+```html
+<ng-container *cuiLet="user$ | async as user">
+  {{ user?.name }}
+</ng-container>
+```
 
-To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI Overview and Command Reference](https://angular.io/cli) page.
+### 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`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cuby-ui/cdk",
-  "version": "0.0.485",
+  "version": "0.0.488",
   "peerDependencies": {
     "@angular/common": ">=18.0.0",
     "@angular/core": ">=18.0.0",