@tuidom/elements 0.1.0

package/dist/list/listViewElement.js

@@ -0,0 +1,944 @@
+import { BoxConstraints, Offset, Point, Rect, Size } from "@tuidom/core/common/geometryPromitives";
+import { TUIMouseEvent } from "@tuidom/core/dom/events/tuiMouseEvent";
+import { TUIElement } from "@tuidom/core/dom/tuiElement";
+import { ScrollableElement } from "../scrollbar/scrollableElement.js";
+const DEFAULT_INDENT_SIZE = 2;
+// Окно, в течение которого напечатанные символы складываются в одну последовательность
+// быстрого поиска; после паузы буфер сбрасывается (как в VS Code / файловых менеджерах).
+const TYPEAHEAD_TIMEOUT_MS = 800;
+/**
+ * Состояние «строка под указателем ИЛИ под курсором сфокусированного списка» —
+ * то, что в вебе назвали бы «строка в фокусе внимания». Ставится на обёртку
+ * строки, поэтому потомкам доступно селектором `in:rowActive` и методом
+ * {@link TUIElement.hasStyleStateWithin} — так строка раскрывает свои
+ * инлайн-кнопки, ничего не зная про список.
+ *
+ * Почему не `hover`: диспатчер мыши ставит hover на ВСЮ цепочку target→root, а
+ * строки презентационные — target'ом всегда оказывается сам список. То есть
+ * `in:hover` у потомка строки был бы истиной для всех строк разом, стоит мыши
+ * оказаться где угодно над списком.
+ */
+export const LIST_ROW_ACTIVE_STATE = "rowActive";
+const ICON_EXPANDED = ""; //  nf-fa-angle_down — chevron, как в TreeViewElement
+const ICON_COLLAPSED = ""; //  nf-fa-angle_right
+/**
+ * Внутренняя обёртка строки: владеет when-вариантами состояний
+ * (hover < selected < selected+in:focus — порядок = приоритет) и сдвигом
+ * контента (гуттер иерархии). Состояния ставит список; in:focus видит
+ * focus-состояние самого списка (строки презентационные и фокуса не имеют).
+ * Пост-рендерный оверлей прежней реализации умер: смена состояния меняет
+ * resolvedStyle строки, дети без собственных цветов наследуют результат, а
+ * явные посимвольные подсветки (match highlight) выделение переживают.
+ */
+class ListRowHostElement extends TUIElement {
+    contentX = 0;
+    child;
+    constructor(child) {
+        super();
+        this.child = child;
+        this.appendChild(child);
+        this.style = {
+            when: [
+                { states: ["hover"], bg: "list.hoverBackground" },
+                {
+                    states: ["selected"],
+                    fg: "list.inactiveSelectionForeground",
+                    bg: "list.inactiveSelectionBackground",
+                },
+                {
+                    states: ["selected", "in:focus"],
+                    fg: "list.activeSelectionForeground",
+                    bg: "list.activeSelectionBackground",
+                },
+            ],
+        };
+    }
+    performLayout(constraints) {
+        const size = super.performLayout(constraints);
+        this.layoutChild(this.child, this.contentX, 0, BoxConstraints.tight(new Size(Math.max(0, size.width - this.contentX), 1)));
+        return size;
+    }
+}
+/**
+ * Виртуализирующий список: настоящие 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 class ListViewElement extends ScrollableElement {
+    indentSize;
+    typeaheadEnabled;
+    rowById = new Map();
+    /** Дети по родителю в порядке добавления; ключ null — верхний уровень. */
+    childIds = new Map();
+    collapsedIds = new Set();
+    /** Ленивая DFS-проекция видимых строк; null = требуется пересборка. */
+    visibleRows = null;
+    visibleIndexById = new Map();
+    hasCollapsibleRows = false;
+    /**
+     * Окно строк, реально разложенное последним performLayout. Делегация кликов
+     * (см. {@link delegateToRowChild}) доверяет позициям детей только внутри него:
+     * скролл или пересборка проекции между кадрами делают layout недействительным
+     * (-1), и незалейаученные строки с ленивыми позициями (0,0)/80×24 не ловят
+     * чужие клики.
+     */
+    lastLayoutScrollTop = -1;
+    lastLayoutViewportHeight = 0;
+    cursorIndex = 0;
+    anchorIndex = 0;
+    selectedIds = new Set();
+    hoveredIndex = null;
+    /** Курсор, запомненный по id на время грязной проекции (restoreSelection дерева). */
+    pendingCursorId = null;
+    pendingCursorIndex = 0;
+    typeaheadBuffer = "";
+    typeaheadTimer = null;
+    onSelect = null;
+    onActivate = null;
+    onCollapsedChanged = null;
+    onContextMenu = null;
+    constructor(options) {
+        super();
+        this.focusable = true;
+        this.indentSize = options?.indentSize ?? DEFAULT_INDENT_SIZE;
+        this.typeaheadEnabled = options?.typeahead ?? true;
+        // Смена фокуса входит в LIST_ROW_ACTIVE_STATE курсорной строки, а
+        // FocusManager метит поддерево только style-грязным — раскрытие же
+        // меняет ГЕОМЕТРИЮ строки, поэтому нужен пересчёт layout.
+        this.addEventListener("focus", () => {
+            this.markDirty();
+        });
+        this.addEventListener("blur", () => {
+            this.markDirty();
+        });
+    }
+    // ─── Rows ───
+    appendRow(element, options) {
+        const id = element.id;
+        if (id === undefined || id === "") {
+            throw new Error(`ListViewElement: every row element must have a non-empty id (row #${this.rowById.size} has none)`);
+        }
+        if (this.rowById.has(id)) {
+            throw new Error(`ListViewElement: duplicate row id "${id}"`);
+        }
+        const parentId = options?.parentId ?? null;
+        let depth = 0;
+        if (parentId !== null) {
+            const parent = this.rowById.get(parentId);
+            if (!parent) {
+                throw new Error(`ListViewElement: unknown parentId "${parentId}" for row "${id}"`);
+            }
+            depth = parent.depth + 1;
+        }
+        const host = new ListRowHostElement(element);
+        const row = { element, host, id, parentId, depth, label: options?.label, hidden: false };
+        this.rowById.set(id, row);
+        let siblings = this.childIds.get(parentId);
+        if (!siblings) {
+            siblings = [];
+            this.childIds.set(parentId, siblings);
+        }
+        siblings.push(id);
+        this.appendChild(host);
+        this.appendToProjection(row);
+        this.markDirty();
+    }
+    clear() {
+        this.setChildren([]);
+        this.rowById.clear();
+        this.childIds.clear();
+        this.collapsedIds.clear();
+        this.selectedIds.clear();
+        this.visibleRows = null;
+        this.visibleIndexById.clear();
+        this.lastLayoutScrollTop = -1;
+        this.cursorIndex = 0;
+        this.anchorIndex = 0;
+        this.hoveredIndex = null;
+        this.pendingCursorId = null;
+        this.pendingCursorIndex = 0;
+        this.scrollTop = 0;
+        this.scrollLeft = 0;
+        this.markDirty();
+    }
+    get rowCount() {
+        return this.rowById.size;
+    }
+    // ─── Visibility: collapse / hide ───
+    setCollapsed(id, collapsed) {
+        const row = this.requireRow(id);
+        if (!this.rowHasChildren(id))
+            return;
+        if (this.collapsedIds.has(id) === collapsed)
+            return;
+        if (collapsed) {
+            this.collapsedIds.add(id);
+        }
+        else {
+            this.collapsedIds.delete(id);
+        }
+        this.onCollapsedChanged?.(row.element, collapsed);
+        this.invalidateProjection();
+        this.markDirty();
+    }
+    toggleCollapsed(id) {
+        this.setCollapsed(id, !this.collapsedIds.has(id));
+    }
+    isCollapsed(id) {
+        return this.collapsedIds.has(id);
+    }
+    /** Снимок свёрнутых строк — восстановление состояния после полной пересборки. */
+    getCollapsedIds() {
+        return [...this.collapsedIds];
+    }
+    /**
+     * Есть ли в видимой проекции развёрнутая строка с детьми — семантика
+     * VS Code `viewHasSomeCollapsibleResult` (тумблер Collapse All/Expand All).
+     */
+    hasVisibleExpandedRow() {
+        return this.ensureProjection().some((row) => this.rowHasChildren(row.id) && !this.collapsedIds.has(row.id));
+    }
+    setRowHidden(id, hidden) {
+        const row = this.requireRow(id);
+        if (row.hidden === hidden)
+            return;
+        row.hidden = hidden;
+        this.invalidateProjection();
+        this.markDirty();
+    }
+    // ─── Cursor / selection ───
+    getCursorElement() {
+        const rows = this.ensureProjection();
+        if (this.cursorIndex >= 0 && this.cursorIndex < rows.length) {
+            return rows[this.cursorIndex].element;
+        }
+        return null;
+    }
+    /**
+     * Все выбранные строки. Если множественный выбор пуст, возвращает строку под
+     * курсором (в виде массива из одного элемента). Порядок — как в списке.
+     */
+    getSelectedElements() {
+        const rows = this.ensureProjection();
+        if (this.selectedIds.size === 0) {
+            const cursor = this.getCursorElement();
+            return cursor ? [cursor] : [];
+        }
+        const result = [];
+        for (const row of rows) {
+            if (this.selectedIds.has(row.id)) {
+                result.push(row.element);
+            }
+        }
+        return result;
+    }
+    /** Ставит курсор на строку, раскрывая свёрнутых предков, и проматывает к ней. */
+    setCursorTo(id) {
+        const row = this.requireRow(id);
+        for (let parentId = row.parentId; parentId !== null;) {
+            const parent = this.rowById.get(parentId);
+            /* v8 ignore start -- defensive: parent chains are validated at appendRow time */
+            if (!parent)
+                break;
+            /* v8 ignore stop */
+            if (this.collapsedIds.has(parent.id)) {
+                this.setCollapsed(parent.id, false);
+            }
+            parentId = parent.parentId;
+        }
+        this.ensureProjection();
+        const index = this.visibleIndexById.get(id);
+        if (index !== undefined) {
+            this.setSelectedIndex(index);
+        }
+    }
+    focusPageDown() {
+        const pageSize = Math.max(1, this.layoutSize.height - 1);
+        this.setSelectedIndex(this.cursorIndex + pageSize);
+    }
+    focusPageUp() {
+        const pageSize = Math.max(1, this.layoutSize.height - 1);
+        this.setSelectedIndex(this.cursorIndex - pageSize);
+    }
+    focusFirst() {
+        this.setSelectedIndex(0);
+    }
+    focusLast() {
+        this.setSelectedIndex(this.ensureProjection().length - 1);
+    }
+    // ─── ScrollableElement contract ───
+    get contentHeight() {
+        return this.ensureProjection().length;
+    }
+    get contentWidth() {
+        // Горизонтального скролла нет: строки живут в ширине вьюпорта и клипятся справа.
+        return this.layoutSize.width;
+    }
+    // ─── TUIElement overrides ───
+    /**
+     * Строки презентационные: в хит-тест не спускаемся — вся семантика мыши
+     * живёт в контейнере (и закуленные строки с непосчитанным layout не крадут
+     * хиты у чужих углов экрана).
+     */
+    hitTestChildren(_point) {
+        return null;
+    }
+    /** Строки не участвуют в Tab-обходе — фокусируется только сам список. */
+    getDepthFirstFocusableOrder() {
+        return this.focusable ? [this] : [];
+    }
+    /**
+     * Damage-обход не заходит в строки: их тысячи, офскрин-хосты держат
+     * протухшие layout-позиции (виртуализация), а любая смена состояния списка
+     * (скролл, курсор, данные) метит сам список — повреждается rect вьюпорта.
+     */
+    get paintsSubtreeAtomically() {
+        return true;
+    }
+    performLayout(constraints) {
+        const size = super.performLayout(constraints);
+        const rows = this.ensureProjection();
+        const start = this.scrollTop;
+        const end = Math.min(rows.length, start + size.height);
+        const listFocused = this.isFocused;
+        for (let i = start; i < end; i++) {
+            const row = rows[i];
+            const y = i - start;
+            row.host.contentX = this.rowContentX(row);
+            // Состояния строк синхронизируются здесь: layout идёт в кадре ДО
+            // резолва стилей. Вариант ДЛЯ layout — без markDirty, иначе кадр
+            // оставлял бы корень грязным и следующий ввод рендерил бы пустой кадр.
+            row.host.setStyleStateDuringLayout("selected", i === this.cursorIndex || this.selectedIds.has(row.id));
+            row.host.setStyleStateDuringLayout("hover", i === this.hoveredIndex);
+            row.host.setStyleStateDuringLayout(LIST_ROW_ACTIVE_STATE, i === this.hoveredIndex || (i === this.cursorIndex && listFocused));
+            this.layoutChild(row.host, 0, y, BoxConstraints.tight(new Size(size.width, 1)));
+        }
+        this.invalidateRowsLeavingWindow(rows, start, end);
+        this.lastLayoutScrollTop = start;
+        this.lastLayoutViewportHeight = size.height;
+        // Окно могло сместиться (скролл, пересборка проекции) — стилевой проход
+        // этого же кадра обязан зайти в список и дорезолвить въехавшие строки,
+        // остававшиеся style-dirty за кадром (смена темы/фокуса метит ВСЕ
+        // строки, а резолвится только окно). Чистые строки отсеет ранний выход.
+        this.markSubtreeStyleDirty();
+        return size;
+    }
+    /**
+     * Строки, которые были в окне прошлого layout и выпали из нынешнего, несут
+     * устаревшую геометрию (прежняя ширина/позиция). Помечаем их
+     * layout-грязными — тем же флагом, с которым живут ни разу не разложенные
+     * строки: он и вернёт им честный layout при въезде в окно, и выведет их
+     * из-под геометрических проверок `validateTree`.
+     *
+     * Окно умеет не только ехать, но и **сжиматься** — например, когда
+     * `ScrollBarDecorator` спрашивает `contentWidth` у ещё не разложенного
+     * списка: ленивый layout проходит по дефолтным 80×24, а следующий за ним
+     * настоящий кладёт лишь пару видимых строк. Без этой уборки хвост остался
+     * бы «чистым» с шириной 80 внутри 28-колоночного списка.
+     *
+     * Цена — O(окна), а не O(N): переcборка проекции сюда не попадает (там
+     * строки и так новые, а `lastLayoutScrollTop` сброшен в -1).
+     */
+    invalidateRowsLeavingWindow(rows, start, end) {
+        if (this.lastLayoutScrollTop < 0)
+            return;
+        const prevEnd = Math.min(rows.length, this.lastLayoutScrollTop + this.lastLayoutViewportHeight);
+        for (let i = this.lastLayoutScrollTop; i < prevEnd; i++) {
+            if (i < start || i >= end) {
+                // Именно флаг, а не markDirty(): тот пошёл бы вверх и оставил
+                // корень грязным после кадра (см. setStyleStateDuringLayout).
+                rows[i].host.isLayoutDirty = true;
+            }
+        }
+    }
+    /**
+     * Стилевой проход виртуализирован, как layout/render/hitTest: резолвится
+     * только видимое окно строк, O(вьюпорта) вместо O(N) на кадр. Офскрин-
+     * строки остаются style-dirty до въезда в окно (см. performLayout).
+     */
+    performChildrenStyleResolution(context) {
+        const rows = this.ensureProjection();
+        const end = Math.min(rows.length, this.scrollTop + this.layoutSize.height);
+        for (let i = this.scrollTop; i < end; i++) {
+            rows[i].host.performStyleResolution(context);
+        }
+    }
+    inspectState() {
+        const rows = this.ensureProjection();
+        return {
+            cursorId: this.rowIdAt(this.cursorIndex),
+            selectedIds: [...this.selectedIds].sort(),
+            collapsedIds: [...this.collapsedIds].sort(),
+            visibleCount: rows.length,
+            totalCount: this.rowById.size,
+            scrollTop: this.scrollTop,
+        };
+    }
+    performDefaultAction(event) {
+        if (event.type === "keypress") {
+            this.handleKeypress(event);
+        }
+        else if (event.type === "click") {
+            this.handleClick(event);
+        }
+        else if (event.type === "contextmenu") {
+            this.handleContextMenu(event);
+        }
+        else if (event.type === "dblclick") {
+            this.handleDblClick(event);
+        }
+        else if (event.type === "wheel") {
+            this.handleWheel(event);
+        }
+        else if (event.type === "mousemove") {
+            this.handleMouseMove(event);
+        }
+        else if (event.type === "mouseleave") {
+            this.handleMouseLeave();
+        }
+        else {
+            super.performDefaultAction(event);
+        }
+    }
+    /**
+     * Единый вход контекстного меню: от мыши — строка под кликом (мультивыбор по
+     * выбранной строке не сбрасывается), от клавиатуры — строка курсора с якорем
+     * на её глобальной позиции. Виджет только сигналит {@link onContextMenu} —
+     * сборка и показ меню на стороне владельца.
+     */
+    handleContextMenu(event) {
+        const rows = this.ensureProjection();
+        if (event.trigger === "mouse") {
+            const index = this.scrollTop + event.localY;
+            if (index < 0 || index >= rows.length)
+                return;
+            const row = rows[index];
+            // Не сбрасываем множественный выбор, если кликнули по уже выбранной строке.
+            if (!this.selectedIds.has(row.id)) {
+                this.setSelectedIndex(index);
+            }
+            else {
+                this.cursorIndex = index;
+                this.applyCursor(index);
+            }
+            this.onContextMenu?.(row.element, event.screenX, event.screenY);
+            return;
+        }
+        if (this.cursorIndex < 0 || this.cursorIndex >= rows.length)
+            return;
+        this.onContextMenu?.(rows[this.cursorIndex].element, this.globalPosition.x, this.globalPosition.y + (this.cursorIndex - this.scrollTop));
+    }
+    // ─── Render ───
+    renderViewport(context, viewport) {
+        const rows = this.ensureProjection();
+        const { scrollTop, viewportWidth, viewportHeight } = viewport;
+        const resolved = this.resolvedStyle;
+        // Границы клипа в локальных строках вьюпорта: строки вне клипа не льём
+        // и не рендерим — при частичном damage-кадре список платит только за
+        // пересечение со своим rect'ом.
+        const clipTopY = Math.max(0, context.clipRect.y - context.offset.dy);
+        const clipBottomY = Math.min(viewportHeight, context.clipRect.bottom - context.offset.dy);
+        for (let screenY = clipTopY; screenY < clipBottomY; screenY++) {
+            const rowIndex = scrollTop + screenY;
+            // 1. Заливка строки фоном списка (гуттер и область за строками).
+            for (let x = 0; x < viewportWidth; x++) {
+                context.setCell(x, screenY, { char: " ", fg: resolved.fg, bg: resolved.bg, width: 1 });
+            }
+            if (rowIndex >= rows.length)
+                continue;
+            const row = rows[rowIndex];
+            // 2. Строка-обёртка: её when-состояния (hover/selected) уже
+            // отрезолвлены каскадом — фон льёт база, дети наследуют результат.
+            const host = row.host;
+            const hostOffset = new Offset(host.localPosition.dx, host.localPosition.dy);
+            const hostClip = new Rect(host.globalPosition, host.layoutSize);
+            // Пустым hostClip быть не может: цикл уже ограничен строками клипа,
+            // а по горизонтали строка-хост занимает всю ширину вьюпорта.
+            host.render(context.withOffset(hostOffset).withClip(hostClip));
+            // 3. Шеврон сворачиваемой строки — поверх, на фоне строки.
+            if (this.hasCollapsibleRows && this.rowHasChildren(row.id)) {
+                const icon = this.collapsedIds.has(row.id) ? ICON_COLLAPSED : ICON_EXPANDED;
+                context.setCell(row.depth * this.indentSize, screenY, {
+                    char: icon,
+                    fg: this.styleVar("list.deemphasizedForeground"),
+                    bg: host.resolvedStyle.bg,
+                    width: 1,
+                });
+            }
+        }
+    }
+    // ─── Private: projection ───
+    ensureProjection() {
+        if (this.visibleRows !== null)
+            return this.visibleRows;
+        const out = [];
+        this.visibleIndexById.clear();
+        let hasCollapsible = false;
+        const walk = (parentId) => {
+            const ids = this.childIds.get(parentId);
+            if (!ids)
+                return;
+            for (const id of ids) {
+                /* v8 ignore next -- defensive: childIds and rowById are mutated in lock-step */
+                const row = this.rowById.get(id);
+                if (!row || row.hidden)
+                    continue;
+                if (this.rowHasChildren(id))
+                    hasCollapsible = true;
+                this.visibleIndexById.set(id, out.length);
+                out.push(row);
+                if (!this.collapsedIds.has(id))
+                    walk(id);
+            }
+        };
+        walk(null);
+        this.visibleRows = out;
+        this.hasCollapsibleRows = hasCollapsible;
+        // Курсор возвращается на прежнюю строку по id; если она пропала (скрыта,
+        // свёрнута под родителя) — на ближайший оставшийся индекс, не прыгая наверх.
+        if (this.pendingCursorId !== null && this.visibleIndexById.has(this.pendingCursorId)) {
+            this.cursorIndex = this.visibleIndexById.get(this.pendingCursorId);
+        }
+        else if (out.length === 0) {
+            this.cursorIndex = 0;
+        }
+        else {
+            this.cursorIndex = Math.min(Math.max(this.pendingCursorIndex, 0), out.length - 1);
+        }
+        this.anchorIndex = this.cursorIndex;
+        this.pendingCursorId = null;
+        return out;
+    }
+    /**
+     * Инкрементальное дополнение живой проекции при appendRow: стрим результатов
+     * (SearchPerformance.md, случай 6) не платит полную пересборку O(N) на кадр.
+     * Быстрые случаи: строка под невидимым/свёрнутым родителем — проекция не
+     * меняется вовсе; строка в хвосте проекции (последний топ-левел или новый
+     * последний ребёнок раскрытой группы, чьё поддерево замыкает проекцию) —
+     * push в конец: индексы существующих строк стабильны, курсор, выделение и
+     * якорь Shift-диапазона не трогаются (полная пересборка якорь сбрасывает —
+     * инкрементальный append его сохраняет). Остальное (вставка в середину) —
+     * фоллбек на полную инвалидацию.
+     */
+    appendToProjection(row) {
+        const rows = this.visibleRows;
+        if (rows === null) {
+            // Проекция уже грязная — пересборка и так предстоит.
+            this.invalidateProjection();
+            return;
+        }
+        if (row.parentId !== null) {
+            if (!this.visibleIndexById.has(row.parentId)) {
+                // Родитель сам не виден (скрыт или под свёрнутым предком) — строка
+                // невидима, проекция не меняется. Порядок при последующем раскрытии
+                // обеспечит пересборка из setCollapsed/setRowHidden.
+                return;
+            }
+            // Видимый родитель теперь точно с детьми — шеврон обязан появиться
+            // (существенно для первого ребёнка: пересборки, которая выставила бы
+            // hasCollapsibleRows, при инкрементальном пути не будет).
+            this.hasCollapsibleRows = true;
+            if (this.collapsedIds.has(row.parentId))
+                return; // строка невидима
+            if (!this.isProjectionTail(row.parentId)) {
+                // Вставка в середину проекции — редкий для стрима случай.
+                this.invalidateProjection();
+                return;
+            }
+        }
+        this.visibleIndexById.set(row.id, rows.length);
+        rows.push(row);
+        // Строка попала в разложенное окно (контент короче вьюпорта), но сама ещё
+        // не разложена — делегация кликов не должна доверять её ленивой позиции.
+        // Append за окном делегацию не трогает: гард по концу окна отсеет индекс.
+        if (rows.length - 1 < this.lastLayoutScrollTop + this.lastLayoutViewportHeight) {
+            this.lastLayoutScrollTop = -1;
+        }
+    }
+    /**
+     * Замыкает ли поддерево строки текущую проекцию: последняя видимая строка —
+     * она сама или её потомок (walk по цепочке родителей, O(глубины)). Именно
+     * тогда новый последний ребёнок строки встаёт в самый хвост проекции.
+     */
+    isProjectionTail(id) {
+        // Вызывается при видимом родителе — проекция материализована и непуста.
+        let cursor = this.visibleRows[this.visibleRows.length - 1];
+        while (cursor) {
+            if (cursor.id === id)
+                return true;
+            cursor = cursor.parentId !== null ? this.rowById.get(cursor.parentId) : undefined;
+        }
+        return false;
+    }
+    invalidateProjection() {
+        this.lastLayoutScrollTop = -1;
+        if (this.visibleRows !== null) {
+            this.pendingCursorId = this.rowIdAt(this.cursorIndex);
+            this.pendingCursorIndex = this.cursorIndex;
+            this.visibleRows = null;
+        }
+    }
+    rowIdAt(index) {
+        if (this.visibleRows !== null && index >= 0 && index < this.visibleRows.length) {
+            return this.visibleRows[index].id;
+        }
+        return null;
+    }
+    requireRow(id) {
+        const row = this.rowById.get(id);
+        if (!row) {
+            throw new Error(`ListViewElement: unknown row id "${id}"`);
+        }
+        return row;
+    }
+    rowHasChildren(id) {
+        const ids = this.childIds.get(id);
+        return ids !== undefined && ids.length > 0;
+    }
+    rowContentX(row) {
+        // Гуттер под шевроны резервируется, только если в списке вообще есть что сворачивать.
+        return row.depth * this.indentSize + (this.hasCollapsibleRows ? 2 : 0);
+    }
+    // ─── Private: selection ───
+    setSelectedIndex(index) {
+        const rows = this.ensureProjection();
+        if (index < 0)
+            index = 0;
+        if (index >= rows.length)
+            index = rows.length - 1;
+        if (index < 0)
+            return;
+        this.cursorIndex = index;
+        this.anchorIndex = index;
+        this.selectedIds.clear();
+        this.applyCursor(index);
+    }
+    /** Двигает курсор и расширяет множественный выбор диапазоном от якоря (Shift+стрелки). */
+    extendSelectionTo(index) {
+        const rows = this.ensureProjection();
+        if (index < 0)
+            index = 0;
+        if (index >= rows.length)
+            index = rows.length - 1;
+        if (index < 0)
+            return;
+        this.cursorIndex = index;
+        this.selectRange(this.anchorIndex, index);
+        this.applyCursor(index);
+    }
+    selectRange(anchor, cursor) {
+        const rows = this.ensureProjection();
+        const lo = Math.min(anchor, cursor);
+        const hi = Math.max(anchor, cursor);
+        this.selectedIds.clear();
+        for (let i = lo; i <= hi; i++) {
+            this.selectedIds.add(rows[i].id);
+        }
+    }
+    /** Переключает выбор одной строки (Ctrl/Cmd+клик), не сбрасывая остальное. */
+    toggleSelectionAt(index) {
+        const rows = this.ensureProjection();
+        /* v8 ignore start -- defensive: the mouse handler bounds-checks the row before calling */
+        if (index < 0 || index >= rows.length)
+            return;
+        /* v8 ignore stop */
+        // Первый Ctrl+клик: включаем в набор текущий курсор, чтобы он не потерялся.
+        if (this.selectedIds.size === 0 && this.cursorIndex < rows.length) {
+            this.selectedIds.add(rows[this.cursorIndex].id);
+        }
+        const id = rows[index].id;
+        if (this.selectedIds.has(id)) {
+            this.selectedIds.delete(id);
+        }
+        else {
+            this.selectedIds.add(id);
+        }
+        this.cursorIndex = index;
+        this.anchorIndex = index;
+        this.applyCursor(index);
+    }
+    applyCursor(index) {
+        this.ensureVisible(index);
+        const rows = this.ensureProjection();
+        this.onSelect?.(rows[index].element);
+        this.markDirty();
+    }
+    ensureVisible(index) {
+        const viewportHeight = this.layoutSize.height;
+        if (index < this.scrollTop) {
+            this.scrollTo(this.scrollLeft, index);
+        }
+        else if (index >= this.scrollTop + viewportHeight) {
+            this.scrollTo(this.scrollLeft, index - viewportHeight + 1);
+        }
+    }
+    // ─── Private: input handlers ───
+    handleKeypress(event) {
+        switch (event.key) {
+            case "ArrowUp":
+                if (event.shiftKey) {
+                    this.extendSelectionTo(this.cursorIndex - 1);
+                }
+                else {
+                    this.setSelectedIndex(this.cursorIndex - 1);
+                }
+                break;
+            case "ArrowDown":
+                if (event.shiftKey) {
+                    this.extendSelectionTo(this.cursorIndex + 1);
+                }
+                else {
+                    this.setSelectedIndex(this.cursorIndex + 1);
+                }
+                break;
+            case "ArrowRight":
+                this.handleExpandOrMoveToChild();
+                break;
+            case "ArrowLeft":
+                this.handleCollapseOrMoveToParent();
+                break;
+            case "Enter":
+                this.activateCursorRow();
+                break;
+            case " ":
+                this.toggleCursorRow();
+                break;
+            // Page/Home/End дублируются здесь при живых глобальных командах list.*:
+            // в workbench команда съедает keydown, а диспатчер гасит парный keypress,
+            // так что сюда клавиша не доходит; standalone-использование контейнера
+            // вне workbench не должно терять навигацию.
+            case "PageDown":
+                this.focusPageDown();
+                break;
+            case "PageUp":
+                this.focusPageUp();
+                break;
+            case "Home":
+                this.focusFirst();
+                break;
+            case "End":
+                this.focusLast();
+                break;
+            default:
+                this.handleTypeahead(event);
+                return;
+        }
+    }
+    // ─── Private: type-ahead поиск ───
+    /**
+     * Быстрый поиск по набору: печатаешь символы — курсор перепрыгивает к первой строке,
+     * чей label начинается с набранной последовательности. Повтор одного и того же
+     * символа циклически перебирает совпадения; набор из разных символов уточняет
+     * префикс, начиная с текущей строки. Буфер копится, пока не выйдет тайм-аут.
+     */
+    handleTypeahead(event) {
+        if (!this.typeaheadEnabled)
+            return;
+        if (event.ctrlKey || event.altKey || event.metaKey)
+            return;
+        const ch = event.key;
+        // Только одиночные печатные символы: имена клавиш ("Enter", "F1"), управляющие
+        // символы и пробел (уже занят сворачиванием) в поиск не идут.
+        if (ch.length !== 1 || ch === " " || ch.charCodeAt(0) < 0x20)
+            return;
+        this.typeaheadBuffer += ch;
+        this.restartTypeaheadTimer();
+        this.jumpToTypeaheadMatch();
+    }
+    restartTypeaheadTimer() {
+        if (this.typeaheadTimer !== null) {
+            clearTimeout(this.typeaheadTimer);
+        }
+        this.typeaheadTimer = setTimeout(() => {
+            this.typeaheadTimer = null;
+            this.typeaheadBuffer = "";
+        }, TYPEAHEAD_TIMEOUT_MS);
+        // Незавершённый таймер поиска не должен удерживать процесс от выхода.
+        this.typeaheadTimer.unref();
+    }
+    jumpToTypeaheadMatch() {
+        const rows = this.ensureProjection();
+        const count = rows.length;
+        if (count === 0)
+            return;
+        const buffer = this.typeaheadBuffer.toLowerCase();
+        // Повтор одного символа ("aa", "aaa") трактуем как перебор совпадений по одной
+        // букве, а не как буквальный префикс — так работает быстрый поиск в проводниках.
+        const allSameChar = Array.from(buffer).every((c) => c === buffer[0]);
+        const prefix = allSameChar ? buffer[0] : buffer;
+        const cycling = buffer.length >= 2 && allSameChar;
+        const start = cycling ? this.cursorIndex + 1 : this.cursorIndex;
+        for (let i = 0; i < count; i++) {
+            const idx = (start + i) % count;
+            const label = rows[idx].label;
+            if (label !== undefined && label.toLowerCase().startsWith(prefix)) {
+                this.setSelectedIndex(idx);
+                return;
+            }
+        }
+    }
+    handleExpandOrMoveToChild() {
+        const rows = this.ensureProjection();
+        const row = rows[this.cursorIndex];
+        if (!row || !this.rowHasChildren(row.id))
+            return;
+        if (this.collapsedIds.has(row.id)) {
+            this.setCollapsed(row.id, false);
+        }
+        else if (this.cursorIndex + 1 < rows.length && rows[this.cursorIndex + 1].depth > row.depth) {
+            // Уже раскрыта — перейти на первого ребёнка.
+            this.setSelectedIndex(this.cursorIndex + 1);
+        }
+    }
+    handleCollapseOrMoveToParent() {
+        const rows = this.ensureProjection();
+        const row = rows[this.cursorIndex];
+        if (!row)
+            return;
+        if (this.rowHasChildren(row.id) && !this.collapsedIds.has(row.id)) {
+            this.setCollapsed(row.id, true);
+        }
+        else if (row.parentId !== null) {
+            const parentIndex = this.visibleIndexById.get(row.parentId);
+            /* v8 ignore start -- defensive: a visible child's parent is always visible too */
+            if (parentIndex !== undefined) {
+                this.setSelectedIndex(parentIndex);
+            }
+            /* v8 ignore stop */
+        }
+    }
+    activateCursorRow() {
+        const rows = this.ensureProjection();
+        const row = rows[this.cursorIndex];
+        if (!row)
+            return;
+        this.onActivate?.(row.element);
+    }
+    toggleCursorRow() {
+        const rows = this.ensureProjection();
+        const row = rows[this.cursorIndex];
+        if (!row || !this.rowHasChildren(row.id))
+            return;
+        this.toggleCollapsed(row.id);
+    }
+    /**
+     * Ре-диспатчит click/dblclick в поддерево видимой строки; true = ребёнок
+     * потребил событие (какой-то listener вызвал `preventDefault()`).
+     *
+     * Хит-тест идёт от элемента строки, так что результат по построению лежит в её
+     * поддереве. Доверять позициям детей можно только строкам, разложенным последним
+     * performLayout на своих местах: скролл или пересборка проекции между кадрами
+     * инвалидируют окно, и делегация отключается до следующего кадра — иначе
+     * незалейаученная строка с ленивыми (0,0)/80×24 поймала бы чужой клик.
+     */
+    delegateToRowChild(index, row, event) {
+        if (this.scrollTop !== this.lastLayoutScrollTop)
+            return false;
+        if (index >= this.lastLayoutScrollTop + this.lastLayoutViewportHeight)
+            return false;
+        const hit = row.element.elementFromPoint(new Point(event.screenX, event.screenY));
+        if (hit === null || hit === row.element)
+            return false;
+        const synthetic = new TUIMouseEvent(event.type, {
+            button: event.button,
+            screenX: event.screenX,
+            screenY: event.screenY,
+            localX: event.screenX - hit.globalPosition.x,
+            localY: event.screenY - hit.globalPosition.y,
+            shiftKey: event.shiftKey,
+            altKey: event.altKey,
+            ctrlKey: event.ctrlKey,
+        });
+        return !hit.dispatchEvent(synthetic);
+    }
+    handleClick(event) {
+        const rows = this.ensureProjection();
+        const index = this.scrollTop + event.localY;
+        if (index < 0 || index >= rows.length)
+            return;
+        const row = rows[index];
+        if (event.button !== "left")
+            return; // правый клик несёт событие contextmenu
+        if (event.ctrlKey) {
+            this.toggleSelectionAt(index);
+            return;
+        }
+        if (event.shiftKey) {
+            this.cursorIndex = index;
+            this.selectRange(this.anchorIndex, index);
+            this.applyCursor(index);
+            return;
+        }
+        if (this.delegateToRowChild(index, row, event))
+            return;
+        this.setSelectedIndex(index);
+        // Клик по колонке шеврона сворачивает/раскрывает.
+        if (this.hasCollapsibleRows && this.rowHasChildren(row.id)) {
+            const chevronX = row.depth * this.indentSize;
+            if (event.localX >= chevronX && event.localX <= chevronX + 1) {
+                this.toggleCollapsed(row.id);
+            }
+        }
+    }
+    handleDblClick(event) {
+        const rows = this.ensureProjection();
+        const index = this.scrollTop + event.localY;
+        if (index < 0 || index >= rows.length)
+            return;
+        const row = rows[index];
+        if (this.delegateToRowChild(index, row, event))
+            return;
+        if (this.rowHasChildren(row.id)) {
+            this.toggleCollapsed(row.id);
+        }
+        else {
+            this.onActivate?.(row.element);
+        }
+    }
+    handleMouseMove(event) {
+        const rows = this.ensureProjection();
+        const index = this.scrollTop + event.localY;
+        const newHovered = index >= 0 && index < rows.length ? index : null;
+        if (newHovered !== this.hoveredIndex) {
+            this.hoveredIndex = newHovered;
+            this.markDirty();
+        }
+    }
+    handleMouseLeave() {
+        if (this.hoveredIndex !== null) {
+            this.hoveredIndex = null;
+            this.markDirty();
+        }
+    }
+    handleWheel(event) {
+        if (event.wheelDirection === "up") {
+            this.scrollBy(0, -3);
+        }
+        else if (event.wheelDirection === "down") {
+            this.scrollBy(0, 3);
+        }
+    }
+}