Cuby UI - агентская документация (RU)

Документ для кодовых агентов. Описывает публичный API пакета @cuby-ui/cdk, а также примеры использования.

Оглавление

• CDK: директивы
• CDK: пайпы
• CDK: сервисы
• CDK: токены
• CDK: интерфейсы и типы
• CDK: утилиты и константы
• Анти-паттерны
• Линт и форматирование
• Версии и совместимость

CDK: директивы

Feature: CuiAutoResizingDirective (textarea[cuiAutoResizing])

Описание: автоматический ресайз textarea по контенту. Публичный API:

• Standalone: да Пример:

<textarea cuiAutoResizing [formControl]="notesControl" style="max-height: 200px;"></textarea>

Feature: CuiClickOutsideDirective ((cuiClickOutside))

Описание: эмитит событие при клике вне элемента. Публичный API:

• Standalone: да
• Output: cuiClickOutside: EventEmitter<HTMLElement> Пример:

<div (cuiClickOutside)="onOutside()">
  ...
</div>

Feature: CuiContentEditableValueAccessorDirective

Описание: связывает contenteditable с Angular формами. Публичный API:

• Standalone: да
• Селектор: [contenteditable][formControlName|formControl|ngModel] Пример:

<div contenteditable [formControl]="bioControl"></div>

Feature: CuiDimensionsObserverDirective ([cuiResizeObserver])

Описание: отдаёт размеры элемента при изменениях. Публичный API:

• Standalone: да
• Output: cuiResizeObserver: EventEmitter<CuiDimensions> Пример:

<div cuiResizeObserver (cuiResizeObserver)="onResize($event)"></div>

Feature: CuiElementDirective ([cuiElement])

Описание: экспортирует ElementRef как elementRef в шаблоне. Публичный API:

• Standalone: да
• exportAs: elementRef Пример:

<button cuiElement #btn="elementRef">Open</button>
<cui-context-menu [target]="btn.nativeElement" [items]="items"></cui-context-menu>

Feature: CuiFocusTrapDirective ([cuiFocusTrap])

Описание: запирает фокус внутри контейнера. Публичный API:

• Standalone: да Пример:

<div cuiFocusTrap>
  <input />
  <button>OK</button>
</div>

Feature: CuiItemDirective ([cuiItem])

Описание: метка элемента коллекции, используется в cui-breadcrumbs. Публичный API:

• Standalone: да Пример:

<a cuiBreadcrumb *cuiItem>Раздел</a>

Feature: CuiLetDirective (*cuiLet)

Описание: структурная директива для удобного alias значения. Публичный API:

• Standalone: да Пример:

<ng-container *cuiLet="user$ | async as user">
  {{ user?.name }}
</ng-container>

Feature: CuiLetContext

Описание: контекст для cuiLet, полезен для типизации. Публичный API:

• Класс: CuiLetContext<T> Пример:

type Ctx = CuiLetContext<User>;

Feature: CuiTargetDirective ([ccTarget])

Описание: слушает клики на внешнем DOM-элементе. Публичный API:

• Standalone: да
• Input: ccTarget: HTMLElement
• Output: clicked: EventEmitter<MouseEvent> Пример:

<div [ccTarget]="buttonRef.nativeElement" (clicked)="onTargetClick($event)"></div>

CDK: пайпы

Feature: CuiFilterPipe (| cuiFilter)

Описание: фильтрация массива по matcher функции. Публичный API:

• Standalone: да Пример:

<li *ngFor="let item of items | cuiFilter: isVisible: filterValue">
  {{ item.label }}
</li>

CDK: сервисы

Feature: CuiDestroyService

Описание: Subject, который автоматически завершает подписки в ngOnDestroy. Публичный API:

• Использование: takeUntil(destroy$) Пример:

@Component({ providers: [CuiDestroyService] })
export class ExampleComponent {
  private destroy$ = inject(CuiDestroyService);

  ngOnInit() {
    this.stream$.pipe(takeUntil(this.destroy$)).subscribe();
  }
}

Feature: CuiIdService

Описание: генератор уникальных id. Публичный API:

• Метод: generate(): string Пример:

const id = inject(CuiIdService).generate();

Feature: CuiPopoverService

Описание: абстрактный сервис для поповеров/оверлеев. Публичный API:

• Метод: open(content, options?) -> Observable
• Типы: CuiPopoverContext, CuiPopover<T> Пример:

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 Пример:

const ctx: CuiPopoverContext = {
  $implicit: observer,
  id: 'id',
  component: MyComponent,
  content: 'text',
  completeWith: () => {}
};

Feature: CuiPopover

Описание: тип поповера (опции + контекст). Пример:

type AlertPopover = CuiPopover<CuiAlertOptions>;

CDK: токены

Feature: CUI_WINDOW

Описание: DI токен для window. Пример:

const win = inject(CUI_WINDOW);

Feature: CUI_LOCAL_STORAGE

Описание: DI токен для localStorage. Пример:

const storage = inject(CUI_LOCAL_STORAGE);

Feature: CUI_SESSION_STORAGE

Описание: DI токен для sessionStorage. Пример:

const storage = inject(CUI_SESSION_STORAGE);

Feature: CUI_HISTORY

Описание: DI токен для history. Пример:

const history = inject(CUI_HISTORY);

CDK: интерфейсы и типы

Feature: CuiDimensions

Описание: размеры элемента. Публичный API:

• Поля: width, height Пример:

function onResize(dim: CuiDimensions) { console.log(dim.width); }

Feature: CuiOnChange

Описание: сигнатура функции onChange для ControlValueAccessor. Пример:

const onChange: CuiOnChange<string> = (value) => console.log(value);

Feature: CuiOnTouched

Описание: сигнатура функции onTouched. Пример:

const onTouched: CuiOnTouched = () => console.log('touched');

Feature: CuiTimeMode

Описание: формат времени для CuiTime. Публичный API:

• Значения: HH:MM, HH:MM:SS, HH:MM:SS.MSS Пример:

const mode: CuiTimeMode = 'HH:MM:SS';

Feature: CuiInputType

Описание: типы инпутов, используемые в core. Публичный API:

• Значения: text | password Пример:

const type: CuiInputType = 'password';

Feature: Mapper

Описание: тип функции-отображения. Пример:

const map: Mapper<[number, number], number> = (a, b) => a + b;

Feature: CuiMatcher

Описание: тип функции-предиката для фильтрации. Пример:

const matcher: CuiMatcher<[number, number]> = (item, min) => item > min;

Feature: CuiNullable

Описание: T | null | undefined. Пример:

const value: CuiNullable<string> = null;

Feature: CuiValueOf

Описание: значение union по ключам объекта. Пример:

type Modes = CuiValueOf<{ a: 'x'; b: 'y' }>;

Feature: CuiTime

Описание: класс времени с парсингом и форматированием. Публичный API:

• Методы: fromString, fromPT, toString, toPT Пример:

const time = CuiTime.fromString('12:30');
time.toString('HH:MM'); // "12:30"

CDK: утилиты и константы

Feature: svgNodeFilter

Описание: фильтр узлов для TreeWalker, исключает SVG. Пример:

document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT, svgNodeFilter);

Feature: cuiContainsOrAfter

Описание: проверка, что узел внутри или после другого. Пример:

cuiContainsOrAfter(container, node);

Feature: cuiIsHTMLElement

Описание: type guard для HTMLElement. Пример:

if (cuiIsHTMLElement(node)) node.focus();

Feature: cuiBlurNativeFocused

Описание: blur активного элемента. Пример:

cuiBlurNativeFocused(document);

Feature: cuiGetClosestFocusable

Описание: поиск ближайшего фокусируемого элемента. Пример:

const next = cuiGetClosestFocusable({ initial, root });

Feature: cuiGetNativeFocused

Описание: получение активного элемента с учетом shadow DOM. Пример:

const active = cuiGetNativeFocused(document);

Feature: cuiIsNativeKeyboardFocusable

Описание: проверка фокуса по клавиатуре. Пример:

cuiIsNativeKeyboardFocusable(element);

Feature: cuiIsNativeMouseFocusable

Описание: проверка фокуса по клику мыши. Пример:

cuiIsNativeMouseFocusable(element);

Feature: cuiCreateToken / cuiCreateTokenFromFactory

Описание: хелперы для создания InjectionToken. Пример:

export const MY_TOKEN = cuiCreateToken({ enabled: true });

Feature: cuiProvide

Описание: хелпер для ExistingProvider. Пример:

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)