@tuidom/elements 0.1.0

package/dist/list/listViewElement.d.ts

@@ -0,0 +1,232 @@
+import { BoxConstraints, Point, Size } from "@tuidom/core/common/geometryPromitives";
+import type { TUIEventBase } from "@tuidom/core/dom/events/tuiEventBase";
+import type { StyleResolutionContext } from "@tuidom/core/dom/styles/tuiStyle";
+import type { RenderContext } from "@tuidom/core/dom/tuiElement";
+import { TUIElement } from "@tuidom/core/dom/tuiElement";
+import { ScrollableElement, type ScrollViewportInfo } from "../scrollbar/scrollableElement.js";
+/**
+ * Состояние «строка под указателем ИЛИ под курсором сфокусированного списка» —
+ * то, что в вебе назвали бы «строка в фокусе внимания». Ставится на обёртку
+ * строки, поэтому потомкам доступно селектором `in:rowActive` и методом
+ * {@link TUIElement.hasStyleStateWithin} — так строка раскрывает свои
+ * инлайн-кнопки, ничего не зная про список.
+ *
+ * Почему не `hover`: диспатчер мыши ставит hover на ВСЮ цепочку target→root, а
+ * строки презентационные — target'ом всегда оказывается сам список. То есть
+ * `in:hover` у потомка строки был бы истиной для всех строк разом, стоит мыши
+ * оказаться где угодно над списком.
+ */
+export declare const LIST_ROW_ACTIVE_STATE = "rowActive";
+export interface IListRowOptions {
+    /** Родительская строка; глубина/отступ выводятся из цепочки родителей. */
+    readonly parentId?: string;
+    /**
+     * Текст для typeahead-поиска; строки без label быстрый поиск пропускает.
+     * Сам typeahead выключается опцией конструктора `typeahead: false`.
+     */
+    readonly label?: string;
+}
+/**
+ * Виртуализирующий список: настоящие TUIElement-дети высотой ровно 1 строка.
+ *
+ * Потребитель императивно собирает произвольные строки-элементы и добавляет их
+ * через {@link appendRow}; контейнер прячет внутри виртуализацию (layout и render
+ * получают только строки видимого окна), иерархию со сворачиванием (`parentId` +
+ * {@link setCollapsed}), скрытие ({@link setRowHidden}) и общие механики списка:
+ * курсор, множественный выбор, клавиатуру, hover, typeahead и сигнал контекстного
+ * меню. У каждой строки обязан быть непустой `element.id` — без него appendRow
+ * бросает ошибку.
+ *
+ * Контракт строк: строки — презентационные. Хит-тест всегда возвращает сам
+ * контейнер, поэтому строки не получают mouse-событий и фокуса; вся семантика
+ * клика/клавиатуры принадлежит списку. Единственное исключение — делегация
+ * левого клика без модификаторов: контейнер ре-диспатчит click/dblclick в
+ * поддерево видимой строки, и если чей-то listener вызвал `preventDefault()`,
+ * клик считается потреблённым — курсор, выделение и активация не трогаются.
+ * Так строка может нести инлайн-кнопки (обычные элементы с click-listener'ом),
+ * не зная ничего про список. Фокуса такая кнопка не берёт (строки вне Tab-обхода),
+ * поэтому «строка в фокусе внимания» выражена состоянием
+ * {@link LIST_ROW_ACTIVE_STATE} на обёртке строки — по нему кнопка решает,
+ * показываться ли ей. Выделение и hover рисуются пост-оверлеем
+ * поверх отрендеренной строки: перекрашиваются только ячейки, чьи цвета совпадают
+ * с унаследованными fg/bg контейнера, так что собственные цвета строки (подсветка
+ * совпадения, приглушённый номер) выделение переживают. Строка, явно выставившая
+ * цвет, равный унаследованному, неотличима от ненастроенной и тоже будет
+ * перекрашена — это осознанное ограничение механизма.
+ */
+export declare class ListViewElement extends ScrollableElement {
+    private readonly indentSize;
+    private readonly typeaheadEnabled;
+    private rowById;
+    /** Дети по родителю в порядке добавления; ключ null — верхний уровень. */
+    private childIds;
+    private collapsedIds;
+    /** Ленивая DFS-проекция видимых строк; null = требуется пересборка. */
+    private visibleRows;
+    private visibleIndexById;
+    private hasCollapsibleRows;
+    /**
+     * Окно строк, реально разложенное последним performLayout. Делегация кликов
+     * (см. {@link delegateToRowChild}) доверяет позициям детей только внутри него:
+     * скролл или пересборка проекции между кадрами делают layout недействительным
+     * (-1), и незалейаученные строки с ленивыми позициями (0,0)/80×24 не ловят
+     * чужие клики.
+     */
+    private lastLayoutScrollTop;
+    private lastLayoutViewportHeight;
+    private cursorIndex;
+    private anchorIndex;
+    private selectedIds;
+    private hoveredIndex;
+    /** Курсор, запомненный по id на время грязной проекции (restoreSelection дерева). */
+    private pendingCursorId;
+    private pendingCursorIndex;
+    private typeaheadBuffer;
+    private typeaheadTimer;
+    onSelect: ((element: TUIElement) => void) | null;
+    onActivate: ((element: TUIElement) => void) | null;
+    onCollapsedChanged: ((element: TUIElement, collapsed: boolean) => void) | null;
+    onContextMenu: ((element: TUIElement, screenX: number, screenY: number) => void) | null;
+    constructor(options?: {
+        indentSize?: number;
+        typeahead?: boolean;
+    });
+    appendRow(element: TUIElement, options?: IListRowOptions): void;
+    clear(): void;
+    get rowCount(): number;
+    setCollapsed(id: string, collapsed: boolean): void;
+    toggleCollapsed(id: string): void;
+    isCollapsed(id: string): boolean;
+    /** Снимок свёрнутых строк — восстановление состояния после полной пересборки. */
+    getCollapsedIds(): readonly string[];
+    /**
+     * Есть ли в видимой проекции развёрнутая строка с детьми — семантика
+     * VS Code `viewHasSomeCollapsibleResult` (тумблер Collapse All/Expand All).
+     */
+    hasVisibleExpandedRow(): boolean;
+    setRowHidden(id: string, hidden: boolean): void;
+    getCursorElement(): TUIElement | null;
+    /**
+     * Все выбранные строки. Если множественный выбор пуст, возвращает строку под
+     * курсором (в виде массива из одного элемента). Порядок — как в списке.
+     */
+    getSelectedElements(): TUIElement[];
+    /** Ставит курсор на строку, раскрывая свёрнутых предков, и проматывает к ней. */
+    setCursorTo(id: string): void;
+    focusPageDown(): void;
+    focusPageUp(): void;
+    focusFirst(): void;
+    focusLast(): void;
+    get contentHeight(): number;
+    get contentWidth(): number;
+    /**
+     * Строки презентационные: в хит-тест не спускаемся — вся семантика мыши
+     * живёт в контейнере (и закуленные строки с непосчитанным layout не крадут
+     * хиты у чужих углов экрана).
+     */
+    protected hitTestChildren(_point: Point): TUIElement | null;
+    /** Строки не участвуют в Tab-обходе — фокусируется только сам список. */
+    getDepthFirstFocusableOrder(): TUIElement[];
+    /**
+     * Damage-обход не заходит в строки: их тысячи, офскрин-хосты держат
+     * протухшие layout-позиции (виртуализация), а любая смена состояния списка
+     * (скролл, курсор, данные) метит сам список — повреждается rect вьюпорта.
+     */
+    protected get paintsSubtreeAtomically(): boolean;
+    protected performLayout(constraints: BoxConstraints): Size;
+    /**
+     * Строки, которые были в окне прошлого layout и выпали из нынешнего, несут
+     * устаревшую геометрию (прежняя ширина/позиция). Помечаем их
+     * layout-грязными — тем же флагом, с которым живут ни разу не разложенные
+     * строки: он и вернёт им честный layout при въезде в окно, и выведет их
+     * из-под геометрических проверок `validateTree`.
+     *
+     * Окно умеет не только ехать, но и **сжиматься** — например, когда
+     * `ScrollBarDecorator` спрашивает `contentWidth` у ещё не разложенного
+     * списка: ленивый layout проходит по дефолтным 80×24, а следующий за ним
+     * настоящий кладёт лишь пару видимых строк. Без этой уборки хвост остался
+     * бы «чистым» с шириной 80 внутри 28-колоночного списка.
+     *
+     * Цена — O(окна), а не O(N): переcборка проекции сюда не попадает (там
+     * строки и так новые, а `lastLayoutScrollTop` сброшен в -1).
+     */
+    private invalidateRowsLeavingWindow;
+    /**
+     * Стилевой проход виртуализирован, как layout/render/hitTest: резолвится
+     * только видимое окно строк, O(вьюпорта) вместо O(N) на кадр. Офскрин-
+     * строки остаются style-dirty до въезда в окно (см. performLayout).
+     */
+    protected performChildrenStyleResolution(context: StyleResolutionContext): void;
+    inspectState(): Record<string, unknown>;
+    protected performDefaultAction(event: TUIEventBase): void;
+    /**
+     * Единый вход контекстного меню: от мыши — строка под кликом (мультивыбор по
+     * выбранной строке не сбрасывается), от клавиатуры — строка курсора с якорем
+     * на её глобальной позиции. Виджет только сигналит {@link onContextMenu} —
+     * сборка и показ меню на стороне владельца.
+     */
+    private handleContextMenu;
+    protected renderViewport(context: RenderContext, viewport: ScrollViewportInfo): void;
+    private ensureProjection;
+    /**
+     * Инкрементальное дополнение живой проекции при appendRow: стрим результатов
+     * (SearchPerformance.md, случай 6) не платит полную пересборку O(N) на кадр.
+     * Быстрые случаи: строка под невидимым/свёрнутым родителем — проекция не
+     * меняется вовсе; строка в хвосте проекции (последний топ-левел или новый
+     * последний ребёнок раскрытой группы, чьё поддерево замыкает проекцию) —
+     * push в конец: индексы существующих строк стабильны, курсор, выделение и
+     * якорь Shift-диапазона не трогаются (полная пересборка якорь сбрасывает —
+     * инкрементальный append его сохраняет). Остальное (вставка в середину) —
+     * фоллбек на полную инвалидацию.
+     */
+    private appendToProjection;
+    /**
+     * Замыкает ли поддерево строки текущую проекцию: последняя видимая строка —
+     * она сама или её потомок (walk по цепочке родителей, O(глубины)). Именно
+     * тогда новый последний ребёнок строки встаёт в самый хвост проекции.
+     */
+    private isProjectionTail;
+    private invalidateProjection;
+    private rowIdAt;
+    private requireRow;
+    private rowHasChildren;
+    private rowContentX;
+    private setSelectedIndex;
+    /** Двигает курсор и расширяет множественный выбор диапазоном от якоря (Shift+стрелки). */
+    private extendSelectionTo;
+    private selectRange;
+    /** Переключает выбор одной строки (Ctrl/Cmd+клик), не сбрасывая остальное. */
+    private toggleSelectionAt;
+    private applyCursor;
+    private ensureVisible;
+    private handleKeypress;
+    /**
+     * Быстрый поиск по набору: печатаешь символы — курсор перепрыгивает к первой строке,
+     * чей label начинается с набранной последовательности. Повтор одного и того же
+     * символа циклически перебирает совпадения; набор из разных символов уточняет
+     * префикс, начиная с текущей строки. Буфер копится, пока не выйдет тайм-аут.
+     */
+    private handleTypeahead;
+    private restartTypeaheadTimer;
+    private jumpToTypeaheadMatch;
+    private handleExpandOrMoveToChild;
+    private handleCollapseOrMoveToParent;
+    private activateCursorRow;
+    private toggleCursorRow;
+    /**
+     * Ре-диспатчит click/dblclick в поддерево видимой строки; true = ребёнок
+     * потребил событие (какой-то listener вызвал `preventDefault()`).
+     *
+     * Хит-тест идёт от элемента строки, так что результат по построению лежит в её
+     * поддереве. Доверять позициям детей можно только строкам, разложенным последним
+     * performLayout на своих местах: скролл или пересборка проекции между кадрами
+     * инвалидируют окно, и делегация отключается до следующего кадра — иначе
+     * незалейаученная строка с ленивыми (0,0)/80×24 поймала бы чужой клик.
+     */
+    private delegateToRowChild;
+    private handleClick;
+    private handleDblClick;
+    private handleMouseMove;
+    private handleMouseLeave;
+    private handleWheel;
+}