@tuidom/core 0.4.0 → 0.5.1

package/dist/dom/overlayLayer.d.ts

@@ -41,6 +41,13 @@ export interface OverlaySessionOptions {
      * (владелец обработает Escape сам — например закроет только верхнее подменю).
      */
     shouldCloseOnEscape?: () => boolean;
+    /**
+     * Рисовать тень под оверлеем (`TUIElement.shadow`, цвет `widget.shadow`) —
+     * TUI-аналог box-shadow попапов VS Code. Выключено по умолчанию у всех
+     * сессий, включая меню tuidom: включает хост. Не задано — остаётся
+     * `element.shadow` как выставил владелец.
+     */
+    shadow?: boolean;
 }
 export interface OverlaySessionHandle {
     readonly element: TUIElement;

package/dist/dom/overlayLayer.js

@@ -1,4 +1,4 @@
-import { BoxConstraints, Offset, Point, Rect, Size } from "../common/geometryPromitives.js";
+import { BoxConstraints, Point, Size } from "../common/geometryPromitives.js";
 import { RenderContext, TUIElement } from "./tuiElement.js";
 export class OverlayLayer extends TUIElement {
     items = [];
@@ -42,6 +42,8 @@ export class OverlayLayer extends TUIElement {
     createSession(element, position, options) {
         this.disposeSessionByElement(element);
         const initialVisible = options.visible ?? false;
+        if (options.shadow !== undefined)
+            element.shadow = options.shadow;
         this.addItem(element, position, false);
         const session = {
             element,
@@ -201,15 +203,9 @@ export class OverlayLayer extends TUIElement {
                 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);
+            // Клип по границам ребёнка и тень за ним — общий renderChild (Н2):
+            // нарисованное не выходит за layoutSize, хит-зона совпадает с видимым.
+            this.renderChild(context, item.element);
         }
     }
     openSession(session) {

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

@@ -47,9 +47,6 @@ export declare const STYLE_TOKEN_DEFAULTS: {
     "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;
@@ -72,6 +69,7 @@ export declare const STYLE_TOKEN_DEFAULTS: {
     "editorSuggestWidget.selectedForeground": number;
     "editorSuggestWidget.iconForeground": number;
     "editorSuggestWidget.detailForeground": number;
+    "widget.shadow": number;
     "editorWidget.foreground": number;
     "editorWidget.background": number;
     "editorWidget.border": number;

package/dist/dom/styles/styleTokens.js

@@ -1,4 +1,4 @@
-import { DEFAULT_COLOR, packRgb } from "../../common/colorUtils.js";
+import { DEFAULT_COLOR, packRgb, packRgba } from "../../common/colorUtils.js";
 /**
  * Дефолтные значения цветовых токенов tuidom — единственное место, где у
  * виджетов tuidom/ui есть RGB-литералы. Правило: токен, на который ссылается
@@ -53,10 +53,10 @@ export const STYLE_TOKEN_DEFAULTS = {
     "tab.inactiveForeground": packRgb(150, 150, 150),
     "tab.inactiveBackground": packRgb(45, 45, 45),
     "editorGroupHeader.tabsBackground": packRgb(37, 37, 38),
-    // ── Панель ──
-    "panel.background": packRgb(24, 24, 24),
-    "panelTitle.inactiveForeground": packRgb(142, 142, 142),
-    "panel.border": packRgb(43, 43, 43),
+    // ── Панель с заголовком ──
+    // Дефолтов `panel.*` здесь больше нет: виджет нижней панели уехал в vexx
+    // (прикладной — его API оперировал понятиями панели IDE), и токены вместе с
+    // ним, в его реестр цветов.
     "titledPanel.titleForeground": packRgb(130, 130, 130),
     // ── Терминал ──
     "terminal.foreground": DEFAULT_COLOR,
@@ -85,6 +85,10 @@ export const STYLE_TOKEN_DEFAULTS = {
     "editorSuggestWidget.selectedForeground": packRgb(255, 255, 255),
     "editorSuggestWidget.iconForeground": packRgb(130, 170, 255),
     "editorSuggestWidget.detailForeground": packRgb(120, 120, 130),
+    // ── Оверлеи ──
+    // Тень попапа (`TUIElement.shadow`): полупрозрачный чёрный, композитится с
+    // тем, что под ним. Значение — дефолт VS Code для тёмных тем (`#00000059`).
+    "widget.shadow": packRgba(0, 0, 0, 0x59),
     // ── Виджеты редактора (диалоги, find) ──
     "editorWidget.foreground": packRgb(204, 204, 204),
     "editorWidget.background": packRgb(37, 37, 38),

package/dist/dom/tuiApplication.d.ts

@@ -35,8 +35,13 @@ export declare class TuiApplication {
     /**
      * Schedules a deferred render via setImmediate.
      * Batches multiple markDirty() calls into a single frame.
-     * Skips rendering if layout is already clean (e.g. a synchronous
+     * Skips rendering if there is nothing to repaint (e.g. a synchronous
      * renderFrame from handleInput already ran).
+     *
+     * Гейт — {@link TUIElement.needsRepaint}, а не layout-грязь: layout снимает
+     * кто угодно (ленивый фоллбэк `layoutSize` у хит-теста мыши, инспектора,
+     * измеряющего виджета), и гейт по ней ронял уже запланированный кадр
+     * насовсем — экран ретейн-буфер, старые ячейки так и оставались на нём.
      */
     scheduleRender(): void;
     private handleInput;
@@ -50,6 +55,11 @@ export declare class TuiApplication {
      * жгли CPU впустую. Стилевые изменения гейт проходят: markStyleDirty
      * заканчивается markDirty. Синхронность оставлена намеренно: тесты и
      * обработчики читают экран/геометрию сразу после события.
+     *
+     * Гейт — {@link TUIElement.needsRepaint} (см. {@link scheduleRender}): сам
+     * хит-тест мыши читает `layoutSize` и гасит layout-грязь, так что гейт по
+     * ней терял кадр, помеченный ДО этого события (например ответ субпроцесса,
+     * пришедший между press и release одного клика).
      */
     private renderAfterInput;
     private handleResize;

package/dist/dom/tuiApplication.js

@@ -109,8 +109,13 @@ export class TuiApplication {
     /**
      * Schedules a deferred render via setImmediate.
      * Batches multiple markDirty() calls into a single frame.
-     * Skips rendering if layout is already clean (e.g. a synchronous
+     * Skips rendering if there is nothing to repaint (e.g. a synchronous
      * renderFrame from handleInput already ran).
+     *
+     * Гейт — {@link TUIElement.needsRepaint}, а не layout-грязь: layout снимает
+     * кто угодно (ленивый фоллбэк `layoutSize` у хит-теста мыши, инспектора,
+     * измеряющего виджета), и гейт по ней ронял уже запланированный кадр
+     * насовсем — экран ретейн-буфер, старые ячейки так и оставались на нём.
      */
     scheduleRender() {
         if (this.renderScheduled)
@@ -118,7 +123,7 @@ export class TuiApplication {
         this.renderScheduled = true;
         setImmediate(() => {
             this.renderScheduled = false;
-            if (this.root?.isLayoutDirty) {
+            if (this.root?.needsRepaint === true) {
                 this.renderFrame();
             }
         });
@@ -194,9 +199,14 @@ export class TuiApplication {
      * жгли CPU впустую. Стилевые изменения гейт проходят: markStyleDirty
      * заканчивается markDirty. Синхронность оставлена намеренно: тесты и
      * обработчики читают экран/геометрию сразу после события.
+     *
+     * Гейт — {@link TUIElement.needsRepaint} (см. {@link scheduleRender}): сам
+     * хит-тест мыши читает `layoutSize` и гасит layout-грязь, так что гейт по
+     * ней терял кадр, помеченный ДО этого события (например ответ субпроцесса,
+     * пришедший между press и release одного клика).
      */
     renderAfterInput() {
-        if (this.root?.isLayoutDirty) {
+        if (this.root?.needsRepaint === true) {
             this.renderFrame();
         }
     }

package/dist/dom/tuiElement.d.ts

@@ -133,6 +133,23 @@ export declare class TUIElement {
     private hasPaintDirtyDescendant;
     private lastPaintedRect;
     private pendingDetachDamage;
+    /**
+     * Есть ли что отдать следующему кадру в этом поддереве: кто-то просил
+     * перерисовку ({@link markDirty}) или отцепил поддерево, и кадра с тех пор
+     * не было.
+     *
+     * Это — и только это — гейт отложенного кадра (`TuiApplication`
+     * `scheduleRender`) и кадра после ввода. В отличие от
+     * {@link isLayoutDirty}, снимается ТОЛЬКО damage-обходом настоящего кадра
+     * ({@link collectDamage}): layout снимает кто угодно — ленивый фоллбэк
+     * геттера {@link layoutSize} зовут хит-тест мыши
+     * ({@link elementFromPoint}), инспектор и любой виджет, измеряющий соседа.
+     * Пока гейтом была layout-грязь, такой читатель гасил флаг посреди
+     * ожидания, и запланированный кадр не состоялся вовсе — а экран
+     * ретейн-буфер, так что старые ячейки оставались на нём до следующей
+     * несвязанной перерисовки.
+     */
+    get needsRepaint(): boolean;
     protected _parent: TUIElement | null;
     private isRootAnchor;
     private requestRenderCallback;
@@ -184,6 +201,25 @@ export declare class TUIElement {
     get hidden(): boolean;
     set hidden(value: boolean);
     private hiddenValue;
+    /**
+     * Тень оверлея — TUI-аналог `box-shadow` VS Code: колонка справа и строка
+     * снизу от элемента (сдвиг 1×1) затемняются цветом `widget.shadow`
+     * (с альфой, композитится с тем, что уже нарисовано). Рисует не сам
+     * элемент, а его родитель после него ({@link renderChildren},
+     * `OverlayLayer.render`): клип ребёнка не выпускает его за собственный
+     * rect (Н2), а тень лежит снаружи. Damage-обход учитывает её через
+     * {@link paintOutset}. Отдаёт форму оверлею там, где тема рисует рамку
+     * цветом фона (Catppuccin: `menu.border` = фон меню).
+     *
+     * Рисуют её канонические циклы — {@link renderChildren} и
+     * `OverlayLayer.render` (оба через {@link renderChild}). Контейнеры со своим
+     * циклом (`SizedBoxElement`, `ScrollViewport`, строки списка) ребёнка
+     * растягивают на весь свой rect — тени там некуда лечь, она осталась бы за
+     * клипом самого контейнера.
+     */
+    get shadow(): boolean;
+    set shadow(value: boolean);
+    private shadowValue;
     /** Прикрепляет ребёнка в конец списка (снимая с прежнего родителя). */
     protected appendChild(child: TUIElement): void;
     /** Прикрепляет ребёнка на позицию index (снимая с прежнего родителя). */
@@ -363,6 +399,11 @@ export declare class TUIElement {
      * запустило бы lazy-layout с мусорными constraints).
      */
     collectDamage(sink: DamageList, parentOrigin: Point): void;
+    /**
+     * На сколько ячеек вправо и вниз родитель рисует за границей элемента
+     * (тень, см. {@link shadow}). Damage-rect элемента расширяется на столько же.
+     */
+    protected get paintOutset(): number;
     /** Обход детей damage-сбора — seam для контейнеров с нестандартной структурой. */
     protected collectChildrenDamage(sink: DamageList, origin: Point): void;
     /**
@@ -529,6 +570,32 @@ export declare class TUIElement {
      * самый цикл, который раньше был скопирован в десяток контейнеров.
      */
     protected renderChildren(context: RenderContext): void;
+    /**
+     * Отрисовка одного ребёнка в контексте родителя: сдвиг на localPosition,
+     * клип по границам ребёнка, затем его тень (см. {@link shadow}) — уже в
+     * контексте родителя, потому что она лежит за клипом ребёнка. Тень не
+     * зависит от того, попал ли сам ребёнок в клип: damage-rect может задеть
+     * только полосу тени (перерисовался виджет под ней), и тогда ребёнок
+     * пропускается, а тень обязана лечь заново.
+     */
+    protected renderChild(context: RenderContext, child: TUIElement): void;
+    /**
+     * Тень ребёнка (см. {@link shadow}) в контексте РОДИТЕЛЯ: колонка справа
+     * (x = right, строки top+1…bottom) и строка снизу (y = bottom, колонки
+     * left+1…right) — классический сдвиг 1×1. Ячейка затемняется цветом
+     * `widget.shadow` из var-scope ребёнка: bg композитит грид, fg — здесь
+     * (грид кладёт fg с альфой на bg, а не на прежний fg); терминальный
+     * DEFAULT_COLOR у fg не трогаем — смешивать не с чем.
+     *
+     * Широкий глиф (CJK, эмодзи) наполовину не красится: голова тянет цвета в
+     * продолжение (`Grid.updateCell`), поэтому глиф под кромкой тени
+     * затемняется целиком — тень на этой строке шире на колонку. Продолжение
+     * в полосе пропускается: его голова либо сама в полосе (уже покрашена —
+     * иначе двойная тень), либо внутри ребёнка (его глиф у правой кромки).
+     * Единственное исключение — голова в пропущенном нижнем левом углу: такой
+     * глиф красится целиком через голову.
+     */
+    protected paintChildShadow(context: RenderContext, child: TUIElement): void;
     /**
      * Финальный шаблон хит-теста — НЕ переопределять (кастомизация — через
      * {@link hitTestChildren}/{@link hitTestSelf}): скрытое не кликается,

package/dist/dom/tuiElement.js

@@ -200,6 +200,28 @@ export class TUIElement {
     lastPaintedRect = null;
     // Только на корне: rect'ы поддеревьев, отцеплённых с последнего кадра.
     pendingDetachDamage = [];
+    /**
+     * Есть ли что отдать следующему кадру в этом поддереве: кто-то просил
+     * перерисовку ({@link markDirty}) или отцепил поддерево, и кадра с тех пор
+     * не было.
+     *
+     * Это — и только это — гейт отложенного кадра (`TuiApplication`
+     * `scheduleRender`) и кадра после ввода. В отличие от
+     * {@link isLayoutDirty}, снимается ТОЛЬКО damage-обходом настоящего кадра
+     * ({@link collectDamage}): layout снимает кто угодно — ленивый фоллбэк
+     * геттера {@link layoutSize} зовут хит-тест мыши
+     * ({@link elementFromPoint}), инспектор и любой виджет, измеряющий соседа.
+     * Пока гейтом была layout-грязь, такой читатель гасил флаг посреди
+     * ожидания, и запланированный кадр не состоялся вовсе — а экран
+     * ретейн-буфер, так что старые ячейки оставались на нём до следующей
+     * несвязанной перерисовки.
+     */
+    get needsRepaint() {
+        return (this.isPaintDirty ||
+            this.hasPaintDirtyDescendant ||
+            this.isLayoutDirty ||
+            this.pendingDetachDamage.length > 0);
+    }
     _parent = null;
     // Якорь дерева: выставляется setAsRoot() (BodyElement, тестовые корни).
     // Сам root НЕ кэшируется — getRoot() выводит его из цепочки родителей.
@@ -312,6 +334,32 @@ export class TUIElement {
         this.markDirty();
     }
     hiddenValue = false;
+    /**
+     * Тень оверлея — TUI-аналог `box-shadow` VS Code: колонка справа и строка
+     * снизу от элемента (сдвиг 1×1) затемняются цветом `widget.shadow`
+     * (с альфой, композитится с тем, что уже нарисовано). Рисует не сам
+     * элемент, а его родитель после него ({@link renderChildren},
+     * `OverlayLayer.render`): клип ребёнка не выпускает его за собственный
+     * rect (Н2), а тень лежит снаружи. Damage-обход учитывает её через
+     * {@link paintOutset}. Отдаёт форму оверлею там, где тема рисует рамку
+     * цветом фона (Catppuccin: `menu.border` = фон меню).
+     *
+     * Рисуют её канонические циклы — {@link renderChildren} и
+     * `OverlayLayer.render` (оба через {@link renderChild}). Контейнеры со своим
+     * циклом (`SizedBoxElement`, `ScrollViewport`, строки списка) ребёнка
+     * растягивают на весь свой rect — тени там некуда лечь, она осталась бы за
+     * клипом самого контейнера.
+     */
+    get shadow() {
+        return this.shadowValue;
+    }
+    set shadow(value) {
+        if (this.shadowValue === value)
+            return;
+        this.shadowValue = value;
+        this.markDirty();
+    }
+    shadowValue = false;
     /** Прикрепляет ребёнка в конец списка (снимая с прежнего родителя). */
     appendChild(child) {
         this.insertChild(this.childrenList.length, child);
@@ -813,7 +861,11 @@ export class TUIElement {
             this.hasPaintDirtyDescendant = false;
             return;
         }
-        const rect = new Rect(new Point(parentOrigin.x + this.localPosition.dx, parentOrigin.y + this.localPosition.dy), this.allocatedSize);
+        // Rect для damage — с outset'ом: тень родитель рисует за границей
+        // allocatedSize, и её ячейки тоже должны перерисоваться при переезде,
+        // скрытии и paint-dirty.
+        const outset = this.paintOutset;
+        const rect = new Rect(new Point(parentOrigin.x + this.localPosition.dx, parentOrigin.y + this.localPosition.dy), new Size(this.allocatedSize.width + outset, this.allocatedSize.height + outset));
         const old = this.lastPaintedRect;
         // Ещё не рисовался — тоже moved. Optional chain здесь не подходит: после
         // первого `old?.x` тип уже сужен, и остальные `old?.` стали бы лишними.
@@ -839,6 +891,13 @@ export class TUIElement {
         if (descend)
             this.collectChildrenDamage(sink, rect.origin);
     }
+    /**
+     * На сколько ячеек вправо и вниз родитель рисует за границей элемента
+     * (тень, см. {@link shadow}). Damage-rect элемента расширяется на столько же.
+     */
+    get paintOutset() {
+        return this.shadowValue ? 1 : 0;
+    }
     /** Обход детей damage-сбора — seam для контейнеров с нестандартной структурой. */
     collectChildrenDamage(sink, origin) {
         for (const child of this.childrenList)
@@ -1147,16 +1206,75 @@ export class TUIElement {
         for (const child of this.getChildren()) {
             if (child.hidden)
                 continue;
-            const offset = new Offset(child.localPosition.dx, child.localPosition.dy);
-            const clip = new Rect(child.globalPosition, child.layoutSize);
-            const childContext = context.withOffset(offset).withClip(clip);
-            // Пустой клип — ребёнок целиком вне отрисовываемой области: пропуск
-            // всего поддерева, включая side-эффекты его render.
-            if (childContext.clipRect.isEmpty)
-                continue;
-            child.render(childContext);
+            this.renderChild(context, child);
         }
     }
+    /**
+     * Отрисовка одного ребёнка в контексте родителя: сдвиг на localPosition,
+     * клип по границам ребёнка, затем его тень (см. {@link shadow}) — уже в
+     * контексте родителя, потому что она лежит за клипом ребёнка. Тень не
+     * зависит от того, попал ли сам ребёнок в клип: damage-rect может задеть
+     * только полосу тени (перерисовался виджет под ней), и тогда ребёнок
+     * пропускается, а тень обязана лечь заново.
+     */
+    renderChild(context, child) {
+        const offset = new Offset(child.localPosition.dx, child.localPosition.dy);
+        const clip = new Rect(child.globalPosition, child.layoutSize);
+        const childContext = context.withOffset(offset).withClip(clip);
+        // Пустой клип — ребёнок целиком вне отрисовываемой области: пропуск
+        // всего поддерева, включая side-эффекты его render.
+        if (!childContext.clipRect.isEmpty)
+            child.render(childContext);
+        if (child.shadow)
+            this.paintChildShadow(context, child);
+    }
+    /**
+     * Тень ребёнка (см. {@link shadow}) в контексте РОДИТЕЛЯ: колонка справа
+     * (x = right, строки top+1…bottom) и строка снизу (y = bottom, колонки
+     * left+1…right) — классический сдвиг 1×1. Ячейка затемняется цветом
+     * `widget.shadow` из var-scope ребёнка: bg композитит грид, fg — здесь
+     * (грид кладёт fg с альфой на bg, а не на прежний fg); терминальный
+     * DEFAULT_COLOR у fg не трогаем — смешивать не с чем.
+     *
+     * Широкий глиф (CJK, эмодзи) наполовину не красится: голова тянет цвета в
+     * продолжение (`Grid.updateCell`), поэтому глиф под кромкой тени
+     * затемняется целиком — тень на этой строке шире на колонку. Продолжение
+     * в полосе пропускается: его голова либо сама в полосе (уже покрашена —
+     * иначе двойная тень), либо внутри ребёнка (его глиф у правой кромки).
+     * Единственное исключение — голова в пропущенном нижнем левом углу: такой
+     * глиф красится целиком через голову.
+     */
+    paintChildShadow(context, child) {
+        const color = child.styleVar("widget.shadow");
+        if (color === TRANSPARENT_COLOR)
+            return;
+        const left = child.localPosition.dx;
+        const top = child.localPosition.dy;
+        const right = left + child.layoutSize.width;
+        const bottom = top + child.layoutSize.height;
+        const shadeCell = (x, y, cell) => {
+            context.setCell(x, y, { bg: color, fg: cell.fg < 0 ? cell.fg : compositeOver(color, cell.fg) });
+        };
+        const shade = (x, y, wholeGlyph) => {
+            const cell = context.getCell(x, y);
+            if (cell === null)
+                return;
+            if (cell.width !== 0) {
+                shadeCell(x, y, cell);
+                return;
+            }
+            if (!wholeGlyph)
+                return;
+            const head = context.getCell(x - 1, y);
+            if (head === null)
+                return;
+            shadeCell(x - 1, y, head);
+        };
+        for (let y = top + 1; y <= bottom; y++)
+            shade(right, y, false);
+        for (let x = left + 1; x < right; x++)
+            shade(x, bottom, x === left + 1);
+    }
     // ─── Hit-testing ───
     //
     // Правило системы (Н6): рендер и Tab обходят детей ВПЕРЁД, хит-тест — тем

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@tuidom/core",
-    "version": "0.4.0",
+    "version": "0.5.1",
     "type": "module",
     "description": "Experimental terminal UI DOM — core: element tree, flex layout, grid rendering, input parsing. API is unstable.",
     "license": "MIT",