@termuijs/core 0.1.3 → 0.1.4

package/README.md

@@ -1,6 +1,6 @@
 # @termuijs/core
 
-The rendering engine that sits at the bottom of the TermUI stack. Screen buffers, layout, input parsing, events, and styling. Everything else in the framework builds on this.
+The rendering engine at the bottom of the TermUI stack. Screen buffers, flexbox layout, input parsing, events, styling, string utilities, and capability flags. Everything else in the framework builds on this.
 
 ## Install
 
@@ -10,41 +10,71 @@ npm install @termuijs/core
 
 ## What's in the box
 
-- **Screen** — Double-buffered cell grid. Diffs the previous frame against the new one so only changed cells get written to stdout.
-- **LayoutEngine** — Flexbox-inspired positioning: `flexDirection`, `flexGrow`, `flexShrink`, `alignItems`, `justifyContent`, percentage sizing. All calculated in character cells.
-- **InputParser** — Converts raw stdin bytes into typed `KeyEvent` objects. Handles escape sequences, Ctrl combos, and multi-byte UTF-8.
-- **EventEmitter** — Type-safe `on`, `off`, `once`, `emit`. Events bubble from focused widget up through parents.
-- **FocusManager** — Tab cycling between widgets, focus traps for modals, focus groups for arrow key navigation within a panel.
-- **Style** — Colors (RGB, hex, named), border styles (single, double, rounded, bold), padding, margin.
-- **LayerManager** — Z-indexed overlays. Modals and dropdowns render above the base layer without z-fighting.
-- **App** — The entry point. Mounts your widget tree, starts the render loop, and routes input to the focused widget.
+- **Screen** - Double-buffered cell grid. Diffs the previous frame against the new one so only changed cells get written to stdout.
+- **LayoutEngine** - Flexbox positioning: `flexDirection`, `flexGrow`, `flexShrink`, `alignItems`, `justifyContent`, percentage sizing. All calculated in character cells.
+- **InputParser** - Converts raw stdin bytes into typed `KeyEvent` objects. Handles escape sequences, Ctrl combos, and multi-byte UTF-8.
+- **EventEmitter** - Type-safe `on`, `off`, `once`, `emit`. Events bubble from the focused widget up through parents.
+- **FocusManager** - Tab cycling between widgets, focus traps for modals, focus groups for arrow key navigation.
+- **Style** - Colors (RGB, hex, named), border styles (single, double, rounded, bold), padding, margin.
+- **LayerManager** - Z-indexed overlays. Modals and dropdowns render above the base layer without z-fighting.
+- **App** - Mounts your widget tree, starts the render loop, and routes input to the focused widget.
+- **Timer pool** - Shared tick pool for animations. All intervals share one `setInterval` at 16ms.
+- **caps flags** - Runtime capability detection for unicode, motion, and color support.
+- **String utilities** - `stringWidth`, `truncate`, `wordWrap`, `stripAnsi` for CJK-aware terminal text.
+- **WCAG utilities** - `contrastRatio`, `meetsAA`, `meetsAAA` for accessible color combinations.
 
-## Usage
+## Capability flags
+
+The `caps` object reports what the current terminal environment supports:
 
 ```typescript
-import { App, Screen, Style } from '@termuijs/core'
+import { caps } from '@termuijs/core'
+
+caps.unicode  // false when NO_UNICODE=1 — use ASCII fallbacks
+caps.motion   // false when NO_MOTION=1  — skip animations
+caps.color    // false when NO_COLOR=1   — skip ANSI color codes
+```
 
-const app = new App()
+These are evaluated once at module load. All built-in widgets check them automatically. Use them in your own code to provide ASCII fallbacks:
 
-// Screen is the cell buffer
-const screen = app.screen
-screen.setCell(0, 0, { char: 'H', fg: 'red' })
+```typescript
+import { caps } from '@termuijs/core'
 
-// Start the render loop
-app.start()
+const bullet = caps.unicode ? '●' : '*'
+const bar    = caps.unicode ? '█' : '#'
 ```
 
-## Event bubbling
+Set `NO_UNICODE=1 NO_MOTION=1` in CI to test ASCII output without a real terminal.
 
-Key events start at the focused widget and bubble up through its parents. Stop propagation at any level.
+## String utilities
 
 ```typescript
-import { createKeyEvent } from '@termuijs/core'
+import { stringWidth, truncate, wordWrap, stripAnsi } from '@termuijs/core'
+
+stringWidth('你好')                    // 4 (each CJK char = 2 columns)
+truncate('Hello World', 8)            // 'Hello W…'
+wordWrap('The quick brown fox', 10)   // wraps at word boundaries
+stripAnsi('\x1b[32mHello\x1b[0m')    // 'Hello'
+```
+
+## WCAG color utilities
+
+```typescript
+import { contrastRatio, meetsAA, meetsAAA } from '@termuijs/core'
+
+contrastRatio('#ffffff', '#000000')  // 21
+meetsAA('#00ff88', '#0a0a0f')        // true (>= 4.5:1)
+meetsAAA('#ffffff', '#333333')       // false (< 7:1)
+```
+
+## Event bubbling
 
+Key events start at the focused widget and bubble up through its parents.
+
+```typescript
 widget.on('key', (event) => {
     if (event.key === 'enter') {
         event.stopPropagation()
-        // handled here, parents won't see it
     }
 })
 ```
@@ -55,15 +85,25 @@ Widgets clip their children by default. Nothing renders outside a widget's bound
 
 ```typescript
 screen.pushClip({ x: 5, y: 5, width: 20, height: 10 })
-// setCell calls outside this rect are silently discarded
 screen.popClip()
 ```
 
-## Batched rendering
+## Timer pool
+
+Use `timerPoolSubscribe` instead of `setInterval` for animations. All subscribers share one underlying timer, reducing CPU overhead.
 
-State changes are batched via `queueMicrotask`. Multiple `setState` calls in the same tick produce a single render pass, not three.
+```typescript
+import { timerPoolSubscribe } from '@termuijs/core'
+
+const unsub = timerPoolSubscribe(16, () => {
+    // runs every ~16ms (60fps)
+})
+
+// Clean up
+unsub()
+```
 
-## API reference
+## Documentation
 
 Full docs at [www.termui.io/docs/core/overview](https://www.termui.io/docs/core/overview).
 

package/dist/index.cjs

@@ -21,9 +21,12 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   App: () => App,
+  BLOCK: () => BLOCK,
   BORDER_CHARS: () => BORDER_CHARS,
+  BOX: () => BOX,
   BRAILLE_DOTS: () => BRAILLE_DOTS,
   BRAILLE_OFFSET: () => BRAILLE_OFFSET,
+  BRAILLE_SPIN: () => BRAILLE_SPIN,
   BarSets: () => BarSets,
   BorderSets: () => BorderSets,
   CTRL_KEYS: () => CTRL_KEYS,
@@ -44,12 +47,14 @@ __export(index_exports, {
   VERTICAL_BAR_SYMBOLS: () => VERTICAL_BAR_SYMBOLS,
   ansi: () => ansi_exports,
   borderSize: () => borderSize,
+  caps: () => caps,
   cellsEqual: () => cellsEqual,
   colorToAnsiBg: () => colorToAnsiBg,
   colorToAnsiFg: () => colorToAnsiFg,
   colorToRgb: () => colorToRgb,
   computeLayout: () => computeLayout,
   containsPoint: () => containsPoint,
+  contrastRatio: () => contrastRatio,
   createKeyEvent: () => createKeyEvent,
   createLayoutNode: () => createLayoutNode,
   createTestScreen: () => createTestScreen,
@@ -70,6 +75,7 @@ __export(index_exports, {
   parseMouseEvent: () => parseMouseEvent,
   percentage: () => percentage,
   ratio: () => ratio,
+  relativeLuminance: () => relativeLuminance,
   renderFallback: () => renderFallback,
   shouldUseFallback: () => shouldUseFallback,
   shrinkRect: () => shrinkRect,
@@ -84,7 +90,10 @@ __export(index_exports, {
   testScreenToString: () => testScreenToString,
   truncate: () => truncate,
   unionRect: () => unionRect,
-  wordWrap: () => wordWrap
+  validateThemeContrast: () => validateThemeContrast,
+  wcagLevel: () => wcagLevel,
+  wordWrap: () => wordWrap,
+  writeClipboard: () => writeClipboard
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -283,6 +292,56 @@ function colorToAnsiBg(color, depth) {
       return "";
   }
 }
+function relativeLuminance(color) {
+  const [r, g, b] = colorToRgb(color);
+  const linearize = (c) => {
+    const sRGB = c / 255;
+    return sRGB <= 0.03928 ? sRGB / 12.92 : Math.pow((sRGB + 0.055) / 1.055, 2.4);
+  };
+  return 0.2126 * linearize(r) + 0.7152 * linearize(g) + 0.0722 * linearize(b);
+}
+function contrastRatio(fg, bg) {
+  const l1 = relativeLuminance(fg);
+  const l2 = relativeLuminance(bg);
+  const lighter = Math.max(l1, l2);
+  const darker = Math.min(l1, l2);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+function wcagLevel(ratio2, large = false) {
+  if (large) {
+    if (ratio2 >= 4.5) return "AAA";
+    if (ratio2 >= 3) return "AA";
+    return "fail";
+  }
+  if (ratio2 >= 7) return "AAA";
+  if (ratio2 >= 4.5) return "AA";
+  if (ratio2 >= 3) return "A";
+  return "fail";
+}
+function validateThemeContrast(theme) {
+  const failures = [];
+  const bg = theme["bg"];
+  if (!bg) return failures;
+  const bgColor = parseColor(bg);
+  const pairs = [
+    ["fg on bg", theme["fg"]],
+    ["primary on bg", theme["primary"]],
+    ["error on bg", theme["error"]],
+    ["success on bg", theme["success"]],
+    ["warning on bg", theme["warning"]],
+    ["muted on bg", theme["muted"]]
+  ];
+  for (const [label, hex] of pairs) {
+    if (!hex) continue;
+    const fgColor = parseColor(hex);
+    const ratio2 = contrastRatio(fgColor, bgColor);
+    const level = wcagLevel(ratio2);
+    if (level !== "AAA" && level !== "AA") {
+      failures.push({ pair: label, ratio: Math.round(ratio2 * 100) / 100, level, required: "AA" });
+    }
+  }
+  return failures;
+}
 
 // src/utils/ansi.ts
 var ansi_exports = {};
@@ -330,7 +389,8 @@ __export(ansi_exports, {
   setTitle: () => setTitle,
   showCursor: () => showCursor,
   strikethrough: () => strikethrough,
-  underline: () => underline
+  underline: () => underline,
+  writeClipboard: () => writeClipboard
 });
 var CSI = "\x1B[";
 var OSC = "\x1B]";
@@ -390,6 +450,10 @@ var resetScrollRegion = `${CSI}r`;
 function setTitle(title) {
   return `${OSC}0;${title}\x07`;
 }
+function writeClipboard(text, stdout = process.stdout) {
+  const encoded = Buffer.from(text, "utf8").toString("base64");
+  stdout.write(`${OSC}52;c;${encoded}\x07`);
+}
 
 // src/terminal/Terminal.ts
 var Terminal = class {
@@ -409,6 +473,8 @@ var Terminal = class {
   _exitHandler = null;
   _sigintHandler = null;
   _sigtermHandler = null;
+  _uncaughtExceptionHandler = null;
+  _unhandledRejectionHandler = null;
   _restored = false;
   constructor(options = {}) {
     this.stdout = options.stdout ?? process.stdout;
@@ -509,6 +575,14 @@ var Terminal = class {
     if (this._exitHandler) process.off("exit", this._exitHandler);
     if (this._sigintHandler) process.off("SIGINT", this._sigintHandler);
     if (this._sigtermHandler) process.off("SIGTERM", this._sigtermHandler);
+    if (this._uncaughtExceptionHandler) {
+      process.off("uncaughtException", this._uncaughtExceptionHandler);
+      this._uncaughtExceptionHandler = null;
+    }
+    if (this._unhandledRejectionHandler) {
+      process.off("unhandledRejection", this._unhandledRejectionHandler);
+      this._unhandledRejectionHandler = null;
+    }
     if (this._resizeHandler) {
       this.stdout.off("resize", this._resizeHandler);
     }
@@ -546,15 +620,26 @@ var Terminal = class {
     process.on("exit", this._exitHandler);
     process.on("SIGINT", this._sigintHandler);
     process.on("SIGTERM", this._sigtermHandler);
+    this._uncaughtExceptionHandler = (err) => {
+      this.restore();
+      process.exit(1);
+    };
+    this._unhandledRejectionHandler = () => {
+      this.restore();
+      process.exit(1);
+    };
+    process.on("uncaughtException", this._uncaughtExceptionHandler);
+    process.on("unhandledRejection", this._unhandledRejectionHandler);
   }
 };
 
 // src/terminal/Screen.ts
+var EMPTY_COLOR = Object.freeze({ type: "none" });
 function emptyCell() {
   return {
     char: " ",
-    fg: { type: "none" },
-    bg: { type: "none" },
+    fg: EMPTY_COLOR,
+    bg: EMPTY_COLOR,
     bold: false,
     italic: false,
     underline: false,
@@ -566,8 +651,8 @@ function emptyCell() {
 }
 function resetCell(cell) {
   cell.char = " ";
-  cell.fg = { type: "none" };
-  cell.bg = { type: "none" };
+  cell.fg = EMPTY_COLOR;
+  cell.bg = EMPTY_COLOR;
   cell.bold = false;
   cell.italic = false;
   cell.underline = false;
@@ -705,6 +790,7 @@ var Screen = class {
    * Clear the back buffer to all empty cells.
    */
   clear() {
+    this._clipStack = [];
     for (let r = 0; r < this._rows; r++) {
       for (let c = 0; c < this._cols; c++) {
         resetCell(this.back[r][c]);
@@ -762,6 +848,7 @@ var Renderer = class {
   _frameTimer = null;
   _renderRequested = false;
   _colorDepth;
+  _onTick = null;
   constructor(terminal, screen, fps = 30) {
     this._terminal = terminal;
     this._screen = screen;
@@ -773,14 +860,16 @@ var Renderer = class {
     this._fps = fps;
     if (this._frameTimer) {
       this.stop();
-      this.start();
+      this.start(this._onTick ?? void 0);
     }
   }
   /** Start the render loop */
-  start() {
+  start(onTick) {
     if (this._frameTimer) return;
+    this._onTick = onTick ?? null;
     const interval = Math.floor(1e3 / this._fps);
     this._frameTimer = setInterval(() => {
+      this._onTick?.();
       if (this._renderRequested) {
         this._renderRequested = false;
         this._flush();
@@ -1046,6 +1135,42 @@ var LayerManager = class {
   }
 };
 
+// src/terminal/env-caps.ts
+var caps = {
+  color: !process.env.NO_COLOR && process.env.TERM !== "dumb",
+  unicode: !process.env.NO_UNICODE && process.env.TERM !== "dumb",
+  motion: !process.env.NO_MOTION && !process.env.CI,
+  ci: !!process.env.CI
+};
+
+// src/terminal/ascii-map.ts
+var BOX = {
+  "\u250C": "+",
+  "\u2510": "+",
+  "\u2514": "+",
+  "\u2518": "+",
+  "\u2500": "-",
+  "\u2502": "|",
+  "\u251C": "+",
+  "\u2524": "+",
+  "\u252C": "+",
+  "\u2534": "+",
+  "\u253C": "+",
+  "\u2550": "=",
+  "\u2551": "|",
+  "\u2554": "+",
+  "\u2557": "+",
+  "\u255A": "+",
+  "\u255D": "+",
+  "\u2560": "+",
+  "\u2563": "+",
+  "\u2566": "+",
+  "\u2569": "+",
+  "\u256C": "+"
+};
+var BRAILLE_SPIN = ["|", "/", "-", "\\"];
+var BLOCK = { full: "#", empty: " ", partial: "-" };
+
 // src/events/types.ts
 function createKeyEvent(base) {
   const event = {
@@ -1401,6 +1526,10 @@ var InputParser = class {
         return;
       }
       if (seq.length < 20) {
+        if (this._escapeTimeout) {
+          clearTimeout(this._escapeTimeout);
+          this._escapeTimeout = null;
+        }
         this._escapeTimeout = setTimeout(() => {
           this._escapeBuffer = "";
           this._escapeTimeout = null;
@@ -1440,6 +1569,10 @@ var InputParser = class {
       this._escapeBuffer = "";
       return;
     }
+    if (this._escapeTimeout) {
+      clearTimeout(this._escapeTimeout);
+      this._escapeTimeout = null;
+    }
     this._escapeTimeout = setTimeout(() => {
       this._escapeBuffer = "";
       this._escapeTimeout = null;
@@ -1568,7 +1701,8 @@ function createLayoutNode(id, style, children = []) {
     id,
     style,
     children,
-    computed: { x: 0, y: 0, width: 0, height: 0 }
+    computed: { x: 0, y: 0, width: 0, height: 0 },
+    _dirty: true
   };
 }
 function computeLayout(root, containerWidth, containerHeight) {
@@ -1590,7 +1724,10 @@ function layoutNode(node, availWidth, availHeight, precomputed = false) {
     node.computed.width = nodeWidth2;
     node.computed.height = nodeHeight2;
   }
-  if (node.children.length === 0) return;
+  if (node.children.length === 0) {
+    node._dirty = false;
+    return;
+  }
   const nodeWidth = node.computed.width;
   const nodeHeight = node.computed.height;
   const innerX = padding.left + border.horizontal / 2;
@@ -1711,6 +1848,7 @@ function layoutNode(node, availWidth, availHeight, precomputed = false) {
     mainOffset += info.mainSize + gap + spaceBetween;
     layoutNode(info.node, info.node.computed.width, info.node.computed.height, true);
   }
+  node._dirty = false;
 }
 function resolveSize(value, available) {
   if (value === void 0) return void 0;
@@ -2321,6 +2459,9 @@ var App = class {
   _options;
   _mounted = false;
   _exitResolve = null;
+  _unsubKey = null;
+  _unsubMouse = null;
+  _widgetById = /* @__PURE__ */ new Map();
   constructor(rootWidget, options = {}) {
     this._rootWidget = rootWidget;
     this._options = {
@@ -2365,10 +2506,11 @@ var App = class {
       this.screen.invalidate();
       this.layers.resize(cols, rows);
       this.events.emit("resize", { cols, rows });
+      this._rootWidget.markDirty?.();
       this.requestRender();
     });
     this.input.start();
-    this.input.onKey((rawEvent) => {
+    this._unsubKey = this.input.onKey((rawEvent) => {
       const event = createKeyEvent({
         ...rawEvent,
         targetId: this.focus.currentId ?? void 0
@@ -2394,10 +2536,10 @@ var App = class {
         this.events.emit("key", event);
       }
     });
-    this.input.onMouse((event) => {
+    this._unsubMouse = this.input.onMouse((event) => {
       this.events.emit("mouse", event);
     });
-    this.renderer.start();
+    this.renderer.start(() => this.requestRender());
     this._rootWidget.mount?.();
     this.events.emit("mount", void 0);
     this.screen.invalidate();
@@ -2414,6 +2556,10 @@ var App = class {
     this._mounted = false;
     this._rootWidget.unmount?.();
     this.events.emit("unmount", void 0);
+    this._unsubKey?.();
+    this._unsubKey = null;
+    this._unsubMouse?.();
+    this._unsubMouse = null;
     this.renderer.stop();
     this.input.stop();
     this.terminal.restore();
@@ -2435,14 +2581,20 @@ var App = class {
   }
   /**
    * Request a re-render on the next frame.
+   * Skips layout + render pass when the root widget reports no dirty state.
    */
   requestRender() {
     if (!this._mounted) return;
+    if (this._rootWidget.isDirty === false) {
+      return;
+    }
     const layoutRoot = this._rootWidget.getLayoutNode();
     computeLayout(layoutRoot, this.terminal.cols, this.terminal.rows);
     this._rootWidget.syncLayout?.();
+    this._buildWidgetMap(this._rootWidget);
     this.screen.clear();
     this._rootWidget.render(this.screen);
+    this._rootWidget.clearDirty?.();
     this.layers.composite(this.screen);
     this.renderer.requestFrame();
   }
@@ -2471,10 +2623,11 @@ var App = class {
   /**
    * Build the bubble chain for keyboard events.
    * Returns an array: [focused widget, parent, grandparent, ..., root]
+   * Uses the cached _widgetById map for O(1) lookup instead of DFS.
    */
   _buildBubbleChain(widgetId) {
     const chain = [];
-    const widget = this._findWidgetById(this._rootWidget, widgetId);
+    const widget = this._widgetById.get(widgetId);
     if (!widget) return chain;
     let current = widget;
     while (current) {
@@ -2486,19 +2639,22 @@ var App = class {
     return chain;
   }
   /**
-   * Find a widget by ID in the widget tree (DFS).
-   * Uses duck-typing to work with any object that has id/children.
+   * Rebuild the widget ID cache by walking the entire widget tree.
+   * Called after syncLayout() so the map stays current.
    */
-  _findWidgetById(root, id) {
-    if (root.id === id) return root;
-    const children = root._children ?? root.children ?? [];
+  _buildWidgetMap(root) {
+    this._widgetById.clear();
+    this._walkWidget(root);
+  }
+  _walkWidget(widget) {
+    if (!widget) return;
+    if (widget.id) this._widgetById.set(widget.id, widget);
+    const children = widget._children ?? widget.children ?? [];
     if (Array.isArray(children)) {
       for (const child of children) {
-        const found = this._findWidgetById(child, id);
-        if (found) return found;
+        this._walkWidget(child);
       }
     }
-    return null;
   }
 };
 
@@ -2665,9 +2821,12 @@ function wordWrap(str, width) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   App,
+  BLOCK,
   BORDER_CHARS,
+  BOX,
   BRAILLE_DOTS,
   BRAILLE_OFFSET,
+  BRAILLE_SPIN,
   BarSets,
   BorderSets,
   CTRL_KEYS,
@@ -2688,12 +2847,14 @@ function wordWrap(str, width) {
   VERTICAL_BAR_SYMBOLS,
   ansi,
   borderSize,
+  caps,
   cellsEqual,
   colorToAnsiBg,
   colorToAnsiFg,
   colorToRgb,
   computeLayout,
   containsPoint,
+  contrastRatio,
   createKeyEvent,
   createLayoutNode,
   createTestScreen,
@@ -2714,6 +2875,7 @@ function wordWrap(str, width) {
   parseMouseEvent,
   percentage,
   ratio,
+  relativeLuminance,
   renderFallback,
   shouldUseFallback,
   shrinkRect,
@@ -2728,6 +2890,9 @@ function wordWrap(str, width) {
   testScreenToString,
   truncate,
   unionRect,
-  wordWrap
+  validateThemeContrast,
+  wcagLevel,
+  wordWrap,
+  writeClipboard
 });
 //# sourceMappingURL=index.cjs.map