@tuidom/core 0.1.0

package/dist/dom/overlayLayer.d.ts

@@ -0,0 +1,92 @@
+import { BoxConstraints, Point, Size } from "../common/geometryPromitives.js";
+import { RenderContext, TUIElement } from "./tuiElement.js";
+export interface OverlayLayerItem {
+    element: TUIElement;
+    position: Point;
+    visible: boolean;
+}
+export interface OverlayAnchorPosition {
+    screenX: number;
+    screenY: number;
+    offsetX?: number;
+    offsetY?: number;
+    preferBelow?: boolean;
+}
+/**
+ * Поведение оверлей-сессии по клику мимо неё. Поле обязательное — каждый оверлей
+ * должен явно объявить, что происходит с кликом позади него:
+ * - `close-on-outside` — клик снаружи закрывает сессию (попап доходит до элемента позади как раньше);
+ * - `modal` — клик снаружи блокируется и НЕ доходит до элементов позади (плюс Tab-фокус заперт внутри);
+ * - `passthrough` — клик снаружи проходит насквозь, сессия не закрывается (док-виджеты вроде Find).
+ */
+export type PointerPolicy = "close-on-outside" | "modal" | "passthrough";
+export interface OverlaySessionOptions {
+    visible?: boolean;
+    restoreFocus?: boolean;
+    focusOnOpen?: boolean;
+    closeOnEscape?: boolean;
+    pointerPolicy: PointerPolicy;
+    /** Гасит ли оверлей глобальные кейбинды, пока видим. По умолчанию pointerPolicy !== "passthrough". */
+    capturesKeyboard?: boolean;
+    disposeOnClose?: boolean;
+    onClose?: () => void;
+    /**
+     * Дополнительная принадлежность цели к сессии для close-on-outside: клик по
+     * элементу, за который поручился владелец (вложенные попапы-подменю — они
+     * отдельные item'ы слоя, не потомки), сессию не закрывает.
+     */
+    ownsTarget?: (target: TUIElement) => boolean;
+    /**
+     * Хук перед закрытием по Escape: вернуть false, чтобы слой сессию НЕ закрывал
+     * (владелец обработает Escape сам — например закроет только верхнее подменю).
+     */
+    shouldCloseOnEscape?: () => boolean;
+}
+export interface OverlaySessionHandle {
+    readonly element: TUIElement;
+    readonly isDisposed: boolean;
+    isOpen(): boolean;
+    open(): void;
+    close(): void;
+    setPosition(position: Point): void;
+    setAnchor(anchor: OverlayAnchorPosition): void;
+    dispose(): void;
+}
+export declare class OverlayLayer extends TUIElement {
+    private items;
+    private sessions;
+    addItem(element: TUIElement, position: Point, visible?: boolean): void;
+    removeItem(element: TUIElement): void;
+    setVisible(element: TUIElement, visible: boolean): void;
+    setPosition(element: TUIElement, position: Point): void;
+    createSession(element: TUIElement, position: Point, options: OverlaySessionOptions): OverlaySessionHandle;
+    openPopupSession(element: TUIElement, anchor: OverlayAnchorPosition, options: OverlaySessionOptions): OverlaySessionHandle;
+    computeAnchorPosition(element: TUIElement, anchor: OverlayAnchorPosition): Point;
+    hasVisibleItems(): boolean;
+    /**
+     * Клавиатурный аналог модальности из elementFromPoint: видимая захватывающая сессия
+     * гасит ГЛОБАЛЬНЫЕ кейбинды, чтобы шорткат не увёл фокус на панель за оверлеем.
+     * Собственные клавиши оверлея идут мимо глобального реестра, поэтому не задеваются.
+     */
+    hasKeyboardCapturingOverlay(): boolean;
+    clearAll(): void;
+    getItems(): readonly OverlayLayerItem[];
+    /**
+     * Базовый обратный обход детей (скрытые сессии выпадают через hidden) +
+     * modal-хвост: модальная сессия проглатывает точку, не взятую элементами
+     * над ней, — клик не проваливается под оверлей.
+     */
+    protected hitTestChildren(point: Point): TUIElement | null;
+    /** Слой прозрачен для кликов: мимо попапов точка уходит контенту под ним. */
+    protected hitTestSelf(_point: Point): boolean;
+    private isModalElement;
+    protected performLayout(constraints: BoxConstraints): Size;
+    render(context: RenderContext): void;
+    private openSession;
+    private releaseFocusScope;
+    private closeSession;
+    private disposeSessionByElement;
+    private disposeSession;
+    private attachSessionListeners;
+    private cleanupSessionListeners;
+}

package/dist/dom/overlayLayer.js

@@ -0,0 +1,343 @@
+import { BoxConstraints, Offset, Point, Rect, Size } from "../common/geometryPromitives.js";
+import { RenderContext, TUIElement } from "./tuiElement.js";
+export class OverlayLayer extends TUIElement {
+    items = [];
+    sessions = new Map();
+    addItem(element, position, visible = false) {
+        this.appendChild(element);
+        element.hidden = !visible;
+        this.items.push({ element, position, visible });
+        this.markDirty();
+    }
+    removeItem(element) {
+        const session = this.sessions.get(element);
+        if (session && !session.isDisposed) {
+            this.disposeSession(session);
+            return;
+        }
+        const index = this.items.findIndex((item) => item.element === element);
+        if (index !== -1) {
+            this.removeChild(this.items[index].element);
+            this.items.splice(index, 1);
+            this.markDirty();
+        }
+    }
+    setVisible(element, visible) {
+        const item = this.items.find((item) => item.element === element);
+        if (item) {
+            item.visible = visible;
+            // hidden зеркалит видимость item'а: базовые обходы (Tab, hit-test)
+            // пропускают закрытые сессии сами, без override'ов.
+            item.element.hidden = !visible;
+            this.markDirty();
+        }
+    }
+    setPosition(element, position) {
+        const item = this.items.find((item) => item.element === element);
+        if (item) {
+            item.position = position;
+            this.markDirty();
+        }
+    }
+    createSession(element, position, options) {
+        this.disposeSessionByElement(element);
+        const initialVisible = options.visible ?? false;
+        this.addItem(element, position, false);
+        const session = {
+            element,
+            options: {
+                restoreFocus: options.restoreFocus ?? false,
+                focusOnOpen: options.focusOnOpen ?? false,
+                closeOnEscape: options.closeOnEscape ?? false,
+                pointerPolicy: options.pointerPolicy,
+                capturesKeyboard: options.capturesKeyboard ?? options.pointerPolicy !== "passthrough",
+                disposeOnClose: options.disposeOnClose ?? false,
+            },
+            visible: false,
+            isDisposed: false,
+            savedFocus: null,
+            focusScopePushed: false,
+            rootEscapeHandler: null,
+            rootOutsideHandler: null,
+            onClose: options.onClose ?? null,
+            ownsTarget: options.ownsTarget ?? null,
+            shouldCloseOnEscape: options.shouldCloseOnEscape ?? null,
+        };
+        this.sessions.set(element, session);
+        if (initialVisible) {
+            this.openSession(session);
+        }
+        const handle = {
+            element,
+            get isDisposed() {
+                return session.isDisposed;
+            },
+            isOpen: () => {
+                return !session.isDisposed && session.visible;
+            },
+            open: () => {
+                if (session.isDisposed)
+                    return;
+                this.openSession(session);
+            },
+            close: () => {
+                if (session.isDisposed)
+                    return;
+                this.closeSession(session);
+            },
+            setPosition: (nextPosition) => {
+                if (session.isDisposed)
+                    return;
+                this.setPosition(session.element, nextPosition);
+            },
+            setAnchor: (anchor) => {
+                if (session.isDisposed)
+                    return;
+                this.setPosition(session.element, this.computeAnchorPosition(session.element, anchor));
+            },
+            dispose: () => {
+                if (session.isDisposed)
+                    return;
+                this.disposeSession(session);
+            },
+        };
+        return handle;
+    }
+    openPopupSession(element, anchor, options) {
+        const position = this.computeAnchorPosition(element, anchor);
+        return this.createSession(element, position, options);
+    }
+    computeAnchorPosition(element, anchor) {
+        const menuW = element.getMaxIntrinsicWidth(0);
+        const menuH = element.getMaxIntrinsicHeight(menuW);
+        const screenW = this.layoutSize.width;
+        const screenH = this.layoutSize.height;
+        const offsetX = anchor.offsetX ?? 0;
+        const offsetY = anchor.offsetY ?? 0;
+        const preferBelow = anchor.preferBelow ?? true;
+        let px = anchor.screenX + offsetX;
+        let py = preferBelow ? anchor.screenY + 1 + offsetY : anchor.screenY + offsetY;
+        if (px + menuW > screenW) {
+            px = Math.max(0, screenW - menuW);
+        }
+        if (py + menuH > screenH) {
+            py = Math.max(0, anchor.screenY - menuH);
+        }
+        px = Math.max(0, px);
+        py = Math.max(0, py);
+        return new Point(px, py);
+    }
+    hasVisibleItems() {
+        return this.items.some((item) => item.visible);
+    }
+    /**
+     * Клавиатурный аналог модальности из elementFromPoint: видимая захватывающая сессия
+     * гасит ГЛОБАЛЬНЫЕ кейбинды, чтобы шорткат не увёл фокус на панель за оверлеем.
+     * Собственные клавиши оверлея идут мимо глобального реестра, поэтому не задеваются.
+     */
+    hasKeyboardCapturingOverlay() {
+        for (const session of this.sessions.values()) {
+            if (session.visible && session.options.capturesKeyboard)
+                return true;
+        }
+        return false;
+    }
+    clearAll() {
+        for (const session of this.sessions.values()) {
+            this.cleanupSessionListeners(session);
+            this.releaseFocusScope(session);
+            session.isDisposed = true;
+        }
+        this.sessions.clear();
+        for (const item of this.items) {
+            this.removeChild(item.element);
+        }
+        this.items = [];
+        this.markDirty();
+    }
+    getItems() {
+        return this.items;
+    }
+    /**
+     * Базовый обратный обход детей (скрытые сессии выпадают через hidden) +
+     * modal-хвост: модальная сессия проглатывает точку, не взятую элементами
+     * над ней, — клик не проваливается под оверлей.
+     */
+    hitTestChildren(point) {
+        const children = this.getChildren();
+        for (let i = children.length - 1; i >= 0; i--) {
+            const child = children[i];
+            const hit = child.elementFromPoint(point);
+            if (hit)
+                return hit;
+            if (this.isModalElement(child))
+                return child;
+        }
+        return null;
+    }
+    /** Слой прозрачен для кликов: мимо попапов точка уходит контенту под ним. */
+    hitTestSelf(_point) {
+        return false;
+    }
+    isModalElement(element) {
+        const session = this.sessions.get(element);
+        return session?.visible === true && session.options.pointerPolicy === "modal";
+    }
+    performLayout(constraints) {
+        const layerSize = super.performLayout(constraints);
+        for (const item of this.items) {
+            if (!item.visible)
+                continue;
+            // Constrain child so it doesn't overflow beyond the layer bounds
+            const availableWidth = Math.max(0, layerSize.width - item.position.x);
+            const availableHeight = Math.max(0, layerSize.height - item.position.y);
+            this.layoutChild(item.element, item.position.x, item.position.y, BoxConstraints.loose(new Size(availableWidth, availableHeight)));
+        }
+        return layerSize;
+    }
+    render(context) {
+        for (const item of this.items) {
+            if (!item.visible)
+                continue;
+            // Позиция — из localPosition (её выставил layoutChild), не из
+            // item.position: после layout авторитетна геометрия элемента (Н5).
+            // Клип по границам ребёнка — инвариант отрисовки (Н2): нарисованное
+            // не выходит за layoutSize, хит-зона совпадает с видимым.
+            const child = item.element;
+            const childOffset = new Offset(child.localPosition.dx, child.localPosition.dy);
+            const clip = new Rect(child.globalPosition, child.layoutSize);
+            const childContext = context.withOffset(childOffset).withClip(clip);
+            if (childContext.clipRect.isEmpty)
+                continue;
+            child.render(childContext);
+        }
+    }
+    openSession(session) {
+        if (session.visible || session.isDisposed)
+            return;
+        const root = this.getRoot();
+        const focusManager = root?.focusManager ?? null;
+        if (session.options.restoreFocus) {
+            session.savedFocus = focusManager?.activeElement ?? null;
+        }
+        session.visible = true;
+        this.setVisible(session.element, true);
+        this.attachSessionListeners(session);
+        if (focusManager && session.options.pointerPolicy === "modal" && !session.focusScopePushed) {
+            focusManager.pushFocusScope(session.element);
+            session.focusScopePushed = true;
+        }
+        if (session.options.focusOnOpen) {
+            session.element.focus();
+        }
+    }
+    releaseFocusScope(session) {
+        if (!session.focusScopePushed)
+            return;
+        const focusManager = this.getRoot()?.focusManager ?? null;
+        focusManager?.popFocusScope(session.element);
+        session.focusScopePushed = false;
+    }
+    closeSession(session) {
+        if (!session.visible || session.isDisposed)
+            return;
+        const root = this.getRoot();
+        const focusManager = root?.focusManager ?? null;
+        session.visible = false;
+        this.setVisible(session.element, false);
+        this.cleanupSessionListeners(session);
+        this.releaseFocusScope(session);
+        if (session.options.restoreFocus && session.savedFocus) {
+            focusManager?.setFocus(session.savedFocus);
+            session.savedFocus = null;
+        }
+        session.onClose?.();
+        if (session.options.disposeOnClose) {
+            this.disposeSession(session);
+        }
+    }
+    disposeSessionByElement(element) {
+        const session = this.sessions.get(element);
+        if (!session)
+            return;
+        this.disposeSession(session);
+    }
+    disposeSession(session) {
+        /* v8 ignore start -- defensive: a disposed session is removed from the map and clearAll sets isDisposed directly, so disposeSession is never re-entered for the same session */
+        if (session.isDisposed)
+            return;
+        /* v8 ignore stop */
+        if (session.visible) {
+            session.visible = false;
+            this.setVisible(session.element, false);
+            this.releaseFocusScope(session);
+        }
+        this.cleanupSessionListeners(session);
+        const index = this.items.findIndex((item) => item.element === session.element);
+        /* v8 ignore start -- defensive: createSession always adds the element to items, so a live session's element is always found here */
+        if (index >= 0) {
+            this.removeChild(this.items[index].element);
+            this.items.splice(index, 1);
+        }
+        /* v8 ignore stop */
+        session.isDisposed = true;
+        session.savedFocus = null;
+        this.sessions.delete(session.element);
+        this.markDirty();
+    }
+    attachSessionListeners(session) {
+        const root = this.getRoot();
+        if (!root)
+            return;
+        if (session.options.closeOnEscape && !session.rootEscapeHandler) {
+            session.rootEscapeHandler = (event) => {
+                /* v8 ignore start -- defensive: the handler is registered only for "keydown", so a non-keydown event never reaches it */
+                if (event.type !== "keydown")
+                    return;
+                /* v8 ignore stop */
+                const keyEvent = event;
+                if (keyEvent.key !== "Escape" || event.defaultPrevented)
+                    return;
+                // Владелец может перехватить Escape (закрыть только подменю).
+                if (session.shouldCloseOnEscape && !session.shouldCloseOnEscape())
+                    return;
+                this.closeSession(session);
+            };
+            root.addEventListener("keydown", session.rootEscapeHandler, { capture: true });
+        }
+        if (session.options.pointerPolicy === "close-on-outside" && !session.rootOutsideHandler) {
+            session.rootOutsideHandler = (event) => {
+                /* v8 ignore start -- defensive: the handler is registered only for "mousedown", so a non-mousedown event never reaches it */
+                if (event.type !== "mousedown")
+                    return;
+                /* v8 ignore stop */
+                if (event.target && isInsideElement(event.target, session.element))
+                    return;
+                if (event.target && session.ownsTarget?.(event.target) === true)
+                    return;
+                this.closeSession(session);
+            };
+            root.addEventListener("mousedown", session.rootOutsideHandler, { capture: true });
+        }
+    }
+    cleanupSessionListeners(session) {
+        const root = this.getRoot();
+        if (root && session.rootEscapeHandler) {
+            root.removeEventListener("keydown", session.rootEscapeHandler, { capture: true });
+        }
+        if (root && session.rootOutsideHandler) {
+            root.removeEventListener("mousedown", session.rootOutsideHandler, { capture: true });
+        }
+        session.rootEscapeHandler = null;
+        session.rootOutsideHandler = null;
+    }
+}
+function isInsideElement(element, ancestor) {
+    let current = element;
+    while (current !== null) {
+        if (current === ancestor)
+            return true;
+        current = current.getParent();
+    }
+    return false;
+}

package/dist/dom/styles/index.d.ts

@@ -0,0 +1,4 @@
+export type { AnyStyleToken, StyleToken } from "./styleTokens.js";
+export { ROOT_VAR_SCOPE, STYLE_TOKEN_DEFAULTS } from "./styleTokens.js";
+export type { ResolvedTUIStyle, StyleColor, StyleResolutionContext, StyleState, StyleStateSelector, StyleStateVariant, StyleVarScope, TUIStyle, } from "./tuiStyle.js";
+export { extendVarScope, INHERITED_BG, INHERITED_FG, mergeStyleVariants, resolveStyle, resolveStyleColor, ROOT_RESOLVED_STYLE, ROOT_STYLE_CONTEXT, styleEquals, } from "./tuiStyle.js";

package/dist/dom/styles/index.js

@@ -0,0 +1,2 @@
+export { ROOT_VAR_SCOPE, STYLE_TOKEN_DEFAULTS } from "./styleTokens.js";
+export { extendVarScope, INHERITED_BG, INHERITED_FG, mergeStyleVariants, resolveStyle, resolveStyleColor, ROOT_RESOLVED_STYLE, ROOT_STYLE_CONTEXT, styleEquals, } from "./tuiStyle.js";

package/dist/dom/styles/styleTokens.d.ts

@@ -0,0 +1,114 @@
+import type { StyleVarScope } from "./tuiStyle.js";
+/**
+ * Дефолтные значения цветовых токенов tuidom — единственное место, где у
+ * виджетов tuidom/ui есть RGB-литералы. Правило: токен, на который ссылается
+ * виджет, ОБЯЗАН иметь строку здесь — иначе резолв без хостовой таблицы
+ * (тесты, stories, standalone-использование) упадёт fail-fast'ом.
+ *
+ * Имена — в конвенции color id VS Code ("list.activeSelectionBackground"),
+ * чтобы хост перекрывал дефолты ключами своей темы без функций-мостов;
+ * tuidom-специфика без темного эквивалента — под собственным именем
+ * ("menu.shortcutForeground", "quickPick.*", "titledPanel.*", "menuBar.*").
+ * Значения — только конкретные числа (packed RGB | DEFAULT_COLOR); сентинелы
+ * INHERITED_* в таблицах запрещены (проверяется в setStyleVars).
+ *
+ * Дефолты сохраняют исторический вид unthemed-палитр, которые сюда переехали
+ * (Н3): под управлением хоста всё перекрывается активной темой.
+ */
+export declare const STYLE_TOKEN_DEFAULTS: {
+    "button.foreground": number;
+    "button.background": number;
+    "button.hoverBackground": number;
+    "button.secondaryForeground": number;
+    "button.secondaryBackground": number;
+    "button.secondaryHoverBackground": number;
+    "menu.foreground": number;
+    "menu.background": number;
+    "menu.selectionForeground": number;
+    "menu.selectionBackground": number;
+    "menu.border": number;
+    "menu.separatorBackground": number;
+    "menu.shortcutForeground": number;
+    "menuBar.foreground": number;
+    "menuBar.background": number;
+    "menubar.selectionForeground": number;
+    "menubar.selectionBackground": number;
+    "list.activeSelectionBackground": number;
+    "list.activeSelectionForeground": number;
+    "list.inactiveSelectionBackground": number;
+    "list.inactiveSelectionForeground": number;
+    "list.hoverBackground": number;
+    "list.deemphasizedForeground": number;
+    "list.highlightForeground": number;
+    "scrollbarSlider.background": number;
+    "scrollbar.background": number;
+    "tab.activeForeground": number;
+    "tab.activeBackground": number;
+    "tab.inactiveForeground": number;
+    "tab.inactiveBackground": number;
+    "editorGroupHeader.tabsBackground": number;
+    "panel.background": number;
+    "panelTitle.inactiveForeground": number;
+    "panel.border": number;
+    "titledPanel.titleForeground": number;
+    "terminal.foreground": number;
+    "terminal.background": number;
+    "dropdown.foreground": number;
+    "dropdown.background": number;
+    "dropdown.border": number;
+    "dropdown.listBackground": number;
+    "input.foreground": number;
+    "input.background": number;
+    "input.placeholderForeground": number;
+    "input.border": number;
+    "input.selectionBackground": number;
+    focusBorder: number;
+    "sash.hoverBorder": number;
+    "quickInput.foreground": number;
+    "quickInput.background": number;
+    "quickPick.border": number;
+    "quickPick.badgeForeground": number;
+    "quickPick.shortcutForeground": number;
+    "quickPick.hintForeground": number;
+    "quickPick.titleForeground": number;
+    "quickPick.promptForeground": number;
+    descriptionForeground: number;
+    "editorSuggestWidget.border": number;
+    "editorSuggestWidget.background": number;
+    "editorSuggestWidget.foreground": number;
+    "editorSuggestWidget.selectedBackground": number;
+    "editorSuggestWidget.selectedForeground": number;
+    "editorSuggestWidget.iconForeground": number;
+    "editorSuggestWidget.detailForeground": number;
+    "editorWidget.foreground": number;
+    "editorWidget.background": number;
+    "editorWidget.border": number;
+    "textLink.foreground": number;
+    "editorLineNumber.foreground": number;
+    "editorLineNumber.activeForeground": number;
+    "editor.wordHighlightBackground": number;
+    "editorGutter.foldingControlForeground": number;
+    "editorIndentGuide.background1": number;
+    "editorIndentGuide.activeBackground1": number;
+    "editorError.foreground": number;
+    "editorWarning.foreground": number;
+    "editorInfo.foreground": number;
+    "editorHint.foreground": number;
+    "diffEditor.insertedLineBackground": number;
+    "diffEditor.removedLineBackground": number;
+    "diffEditor.unchangedRegionForeground": number;
+};
+/** Литеральный union имён токенов tuidom — автокомплит и проверка внутри tuidom/ui. */
+export type StyleToken = keyof typeof STYLE_TOKEN_DEFAULTS;
+/**
+ * Публичный тип имени токена: автокомплит по дефолтам сохраняется, но хост
+ * может ссылаться на произвольные ключи своей темы — опечатки в них ловит
+ * рантайм-fail-fast резолва (в первом же кадре), не компилятор.
+ */
+export type AnyStyleToken = StyleToken | (string & {});
+/**
+ * Дно прототипной цепочки var-scope'ов: замороженные дефолты с null-прототипом
+ * (лукап по цепочке не должен находить ключи Object.prototype). Пользовательские
+ * таблицы (setStyleVars) ложатся ПОВЕРХ через Object.create.
+ */
+export declare const ROOT_VAR_SCOPE: StyleVarScope;