@tuidom/core 0.4.0 → 0.5.0

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

@@ -72,6 +72,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-литералы. Правило: токен, на который ссылается
@@ -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/tuiElement.d.ts

@@ -184,6 +184,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 +382,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 +553,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

@@ -312,6 +312,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 +839,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 +869,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 +1184,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.0",
     "type": "module",
     "description": "Experimental terminal UI DOM — core: element tree, flex layout, grid rendering, input parsing. API is unstable.",
     "license": "MIT",