@rt-tools/ui-kit-v2 0.17.0 → 0.19.0

package/types/rt-tools-ui-kit-v2-select.d.ts

@@ -0,0 +1,215 @@
+import * as i0 from '@angular/core';
+import { TemplateRef, Signal, ElementRef, WritableSignal, InputSignal, InputSignalWithTransform, OutputEmitterRef } from '@angular/core';
+import { TRtKitLabelMap, IRtInput, IRtIcon } from '@rt-tools/ui-kit-v2/core';
+import { RtFormControlBase } from '@rt-tools/ui-kit-v2/form-control';
+import { RtPopoverDirective, IRtPopover } from '@rt-tools/ui-kit-v2/popover';
+import * as i1 from '@rt-tools/ui-kit-v2/radius';
+
+/**
+ * Модель `<rt-select>`: один корневой неймспейс с префиксом `I`.
+ * Generic-параметр `TValue` повторяет тип значения, который сидит в опциях.
+ */
+declare namespace IRtSelect {
+    /** Одна опция dropdown'а. */
+    interface Option<TValue> {
+        label: string;
+        value: TValue;
+        disabled?: boolean;
+        /** Дети опции того же вида. Хотя бы одна опция с детьми делает список деревом. */
+        children?: ReadonlyArray<Option<TValue>>;
+    }
+    /** Видимая строка дерева: опция, её уровень и то, ветка ли она и раскрыта ли. */
+    interface Row<TValue> {
+        readonly option: Option<TValue>;
+        readonly level: number;
+        readonly branch: boolean;
+        readonly open: boolean;
+        readonly parent: TValue | null;
+    }
+    /** Сколько включённых листьев ветки выбрано: все, часть или ни одного. */
+    type TBranchState = 'all' | 'some' | 'none';
+    /** Что делать по боковой стрелке: какую ветку переключить и куда увести подсветку. */
+    interface SideKeyAnswer<TValue> {
+        readonly toggle: TValue | null;
+        readonly index: number;
+    }
+    /**
+     * Что кит отдаёт своей разметке указателя. Три значения и не больше: большее привязало бы
+     * разметку потребителя к устройству семьи, и семью стало бы не поправить, не сломав её.
+     */
+    interface TriggerState<TValue> {
+        /** Открыт ли список: по нему потребитель крутит шеврон. */
+        readonly isOpen: boolean;
+        /** Что выбрано. У выбора нескольких это все выбранные значения. */
+        readonly value: TValue | null;
+        /** Подпись выбранного — та же, что кит рисует в своём указателе. */
+        readonly label: string;
+        /** Отключён ли выбор. */
+        readonly isDisabled: boolean;
+    }
+    /** Обстановка шаблона указателя: состояние приходит как `$implicit`. */
+    interface TriggerContext<TValue> {
+        readonly $implicit: TriggerState<TValue>;
+    }
+}
+
+/**
+ * Маркер своей разметки указателя — того, что человек нажимает, чтобы открыть список.
+ *
+ * Поведение указателя остаётся киту: открытие панели, её ширина, приметы доступности,
+ * отключённость, клавиши и закрытие висят на кнопке. Потребитель даёт только то, что рисуется
+ * внутри неё, и получает три значения обстановки: открыт ли список, что выбрано, отключён ли выбор.
+ *
+ * Один маркер на обе семьи выбора: они отличаются только разметкой внутри кнопки, и два маркера
+ * разошлись бы на первой же правке.
+ *
+ * @example
+ * ```html
+ * <rt-select [options]="options">
+ *     <ng-template rtSelectTrigger let-state>
+ *         <rt-tag [value]="state.label" [icon]="state.isOpen ? 'chevron-up' : 'chevron-down'" />
+ *     </ng-template>
+ * </rt-select>
+ * ```
+ */
+declare class RtSelectTriggerDirective<TValue = unknown> {
+    readonly templateRef: TemplateRef<IRtSelect.TriggerContext<TValue>>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<RtSelectTriggerDirective<any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<RtSelectTriggerDirective<any>, "[rtSelectTrigger]", never, {}, {}, never, never, true, never>;
+}
+
+type TBooleanInput = boolean | string;
+/**
+ * Single-select dropdown с опциональным filter input.
+ *
+ * Panel рендерится через CDK Overlay (директива `[rtPopover]` на trigger'е) —
+ * не обрезается `overflow: hidden` предками (таблицы, aside, карточки) и
+ * авто-flip'ается у края viewport. CVA через общий `RtFormControlBase`. Крестик
+ * (`clearable`) слева от шеврона — виден при наличии значения, очищает выбор.
+ *
+ * Keyboard-nav (activedescendant): фокус на trigger'е, ArrowUp/Down двигают
+ * виртуальный highlight (`aria-activedescendant`), Enter выбирает, Escape
+ * закрывает. Home/End/typeahead — deferred.
+ */
+declare class RtSelectComponent<TValue> extends RtFormControlBase<TValue | null> {
+    #private;
+    protected readonly t: Signal<TRtKitLabelMap>;
+    protected readonly panelId: string;
+    protected readonly filterPlaceholderText: Signal<string>;
+    protected readonly popover: Signal<RtPopoverDirective>;
+    protected readonly triggerEl: Signal<ElementRef<HTMLButtonElement> | undefined>;
+    protected readonly filterTerm: WritableSignal<string>;
+    protected readonly activeIndex: WritableSignal<number>;
+    /** Раскрытые ветки дерева. Живут, пока открыта панель: при открытии раскрыты ветки над выбранным. */
+    protected readonly openBranches: WritableSignal<ReadonlySet<TValue>>;
+    protected readonly isOpen: Signal<boolean>;
+    /** Идентификатор подсвеченной опции — тот же, что уходит в `aria-activedescendant`. */
+    protected readonly activeOptionId: Signal<string | null>;
+    /**
+     * Своя разметка указателя, если потребитель её объявил. Не объявил — кит рисует свою, и ни один
+     * нынешний потребитель не двигается.
+     */
+    protected readonly triggerTpl: Signal<RtSelectTriggerDirective<TValue> | undefined>;
+    protected readonly hasValue: Signal<boolean>;
+    protected readonly selectedLabel: Signal<string>;
+    /** Дерево ли список: тогда у строк есть место под стрелку и отступ по уровню. */
+    protected readonly isTree: Signal<boolean>;
+    /** Видимые строки: плоский список — как прежде, дерево — по раскрытым веткам и поисковому слову. */
+    protected readonly rows: Signal<ReadonlyArray<IRtSelect.Row<TValue>>>;
+    /** Три значения, которые кит отдаёт своей разметке указателя, и не больше. */
+    protected readonly triggerState: Signal<IRtSelect.TriggerState<TValue>>;
+    /** Вид рамки: `outline` — рамка со всех сторон, `fill` — залитое поле с чертой снизу. */
+    readonly appearance: InputSignal<IRtInput.Appearance>;
+    readonly displayText: Signal<string>;
+    readonly options: InputSignal<ReadonlyArray<IRtSelect.Option<TValue>>>;
+    readonly placeholder: InputSignal<string>;
+    readonly iconLeft: InputSignal<IRtIcon.Name | null>;
+    readonly filter: InputSignalWithTransform<boolean, TBooleanInput>;
+    /** Пусто — берётся переведённая подпись по умолчанию */
+    readonly filterPlaceholder: InputSignal<string>;
+    /**
+     * Чем мерится панель. По умолчанию она не уже кнопки и дальше растёт по содержимому:
+     * со своим указателем кнопка бывает узкой, и панель по её ширине давила бы содержимое.
+     * `trigger` возвращает прежнее — ровно по кнопке, `auto` пускает панель по содержимому
+     * целиком. Предел высоты назначается входом `panelMaxHeight`.
+     */
+    readonly panelWidth: InputSignal<IRtPopover.Width>;
+    /**
+     * Предел высоты панели — длина как в стилях, например `20rem`. Пусто — предел кита
+     * `--rt-input-panel-max-height`, и длинный список прокручивается внутри панели: без предела
+     * он уходил за нижний край экрана, и пункты за краем были недостижимы. `none` снимает предел —
+     * для короткого списка, который должен открываться целиком, без прокрутки. Значение ставится
+     * на саму панель: она рисуется в наложении, вне поддерева блока.
+     */
+    readonly panelMaxHeight: InputSignal<string | null>;
+    readonly selectionChange: OutputEmitterRef<TValue | null>;
+    constructor();
+    setDisabledState(disabled: boolean): void;
+    protected getEmptyValue(): TValue | null;
+    protected focusAfterClear(): void;
+    protected clear(event?: Event): void;
+    protected onOpened(): void;
+    protected toggleBranch(event: Event, value: TValue): void;
+    protected onClosed(): void;
+    protected select(opt: IRtSelect.Option<TValue>): void;
+    protected setFilter(term: string): void;
+    protected onTriggerKeydown(event: KeyboardEvent): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<RtSelectComponent<any>, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<RtSelectComponent<any>, "rt-select", never, { "appearance": { "alias": "appearance"; "required": false; "isSignal": true; }; "options": { "alias": "options"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "iconLeft": { "alias": "iconLeft"; "required": false; "isSignal": true; }; "filter": { "alias": "filter"; "required": false; "isSignal": true; }; "filterPlaceholder": { "alias": "filterPlaceholder"; "required": false; "isSignal": true; }; "panelWidth": { "alias": "panelWidth"; "required": false; "isSignal": true; }; "panelMaxHeight": { "alias": "panelMaxHeight"; "required": false; "isSignal": true; }; }, { "selectionChange": "selectionChange"; }, ["triggerTpl"], never, true, [{ directive: typeof i1.RtRadiusDirective; inputs: { "radius": "radius"; }; outputs: {}; }]>;
+}
+
+/**
+ * Держит подсвеченную клавишами опцию в видимой части панели.
+ *
+ * Панель списка ограничена по высоте, и длинный список прокручивается внутри неё. Клавиши двигают
+ * подсветку, но фокус остаётся на поле: браузер сам панель не прокручивает, и подсветка уходила
+ * за нижний край — человек выбирал Enter'ом то, чего не видел. После каждой отрисовки, в которой
+ * сменилась подсвеченная опция, она прокручивается ровно настолько, чтобы встать в панель.
+ *
+ * Панель рисуется в наложении, вне поддерева семьи, поэтому опция ищется в документе по своему
+ * идентификатору — тому же, что стоит в `aria-activedescendant`. На сервере отрисовки нет, и
+ * эффект не выполняется; среда без `scrollIntoView` пропускается.
+ *
+ * Зовётся в контексте внедрения — полем или конструктором семьи.
+ *
+ * @param activeOptionId идентификатор подсвеченной опции; `null` — подсветки нет или панель закрыта
+ */
+declare function rtScrollActiveOptionIntoView(activeOptionId: () => string | null): void;
+
+/**
+ * Дерево опций выбора из списка — общее для `rt-select` и `rt-multiselect`.
+ *
+ * Обе семьи раскладывают, ищут и считают дерево одинаково, поэтому это чистые функции в одном
+ * месте: две копии разошлись бы на первой правке. Состояние — какие ветки раскрыты — живёт в семье,
+ * здесь только расчёт по нему.
+ */
+type TOption<TValue> = IRtSelect.Option<TValue>;
+type TRow<TValue> = IRtSelect.Row<TValue>;
+/** Список — дерево, если хоть у одной опции есть дети. Плоский список рисуется как прежде. */
+declare function rtTreeIsTree<TValue>(options: ReadonlyArray<TOption<TValue>>): boolean;
+/** Опция по значению на любой глубине. */
+declare function rtTreeFind<TValue>(options: ReadonlyArray<TOption<TValue>>, value: TValue): TOption<TValue> | undefined;
+/**
+ * Включённые листья под опцией; у самого листа — он сам. Отключённая ветка не отдаёт никого: её
+ * листья выбрать нельзя, как и её саму.
+ */
+declare function rtTreeLeaves<TValue>(option: TOption<TValue>): ReadonlyArray<TValue>;
+/** Сколько включённых листьев ветки выбрано. Флажок ветки выводится из этого, а не хранится. */
+declare function rtTreeBranchState<TValue>(option: TOption<TValue>, chosen: ReadonlyArray<TValue>): IRtSelect.TBranchState;
+/** Ветки, под которыми лежит выбранное значение: они раскрыты, когда список открывается. */
+declare function rtTreeOpenFor<TValue>(options: ReadonlyArray<TOption<TValue>>, chosen: ReadonlyArray<TValue>): ReadonlySet<TValue>;
+/**
+ * Видимые строки по уровням. Без поискового слова раскрыты ветки из `open`. Со словом строка
+ * остаётся, если совпала она сама или кто-то под ней, и путь к совпадению показан раскрытым.
+ * Ветка, совпавшая сама, держит детей такими, какими они были.
+ */
+declare function rtTreeRows<TValue>(options: ReadonlyArray<TOption<TValue>>, open: ReadonlySet<TValue>, rawTerm?: string): ReadonlyArray<TRow<TValue>>;
+/**
+ * Ответ на боковую стрелку. Вправо: свёрнутая ветка раскрывается, раскрытая уводит подсветку на
+ * первого ребёнка. Влево: раскрытая ветка сворачивается, иначе подсветка уходит на родителя.
+ */
+declare function rtTreeSideKey<TValue>(rows: ReadonlyArray<TRow<TValue>>, index: number, key: string): IRtSelect.SideKeyAnswer<TValue>;
+/** Набор раскрытых веток с переключённой одной. */
+declare function rtTreeToggle<TValue>(open: ReadonlySet<TValue>, value: TValue): ReadonlySet<TValue>;
+
+export { IRtSelect, RtSelectComponent, RtSelectTriggerDirective, rtScrollActiveOptionIntoView, rtTreeBranchState, rtTreeFind, rtTreeIsTree, rtTreeLeaves, rtTreeOpenFor, rtTreeRows, rtTreeSideKey, rtTreeToggle };