tinky 1.7.0 → 1.8.0

package/lib/components/Text.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useContext } from "react";
+import { useContext, useCallback } from "react";
 import { applyTextStyles, } from "../utils/apply-text-styles.js";
 import { AccessibilityContext } from "../contexts/AccessibilityContext.js";
 import { backgroundContext } from "../contexts/BackgroundContext.js";
@@ -41,7 +41,7 @@ export function Text({ color, backgroundColor, dimColor = false, bold = false, i
     if (childrenOrAriaLabel === undefined || childrenOrAriaLabel === null) {
         return null;
     }
-    const transform = (children) => {
+    const transform = useCallback((children) => {
         return applyTextStyles(children, {
             color,
             backgroundColor: effectiveBackgroundColor,
@@ -52,7 +52,16 @@ export function Text({ color, backgroundColor, dimColor = false, bold = false, i
             strikethrough,
             inverse,
         });
-    };
+    }, [
+        color,
+        effectiveBackgroundColor,
+        dimColor,
+        bold,
+        italic,
+        underline,
+        strikethrough,
+        inverse,
+    ]);
     if (isScreenReaderEnabled && ariaHidden) {
         return null;
     }

package/lib/core/dom.d.ts

@@ -1,6 +1,7 @@
 import { type Styles } from "./styles.js";
 import { type OutputTransformer } from "./render-node-to-output.js";
 import { TaffyNode } from "./taffy-node.js";
+import { type SizeObserver } from "./size-observer.js";
 /**
  * Interface representing a node in the Tinky tree.
  */
@@ -74,6 +75,8 @@ export type DOMElement = {
     onRender?: () => void;
     /** Callback to trigger an immediate render. */
     onImmediateRender?: () => void;
+    /** Set of resize observers attached to this element. */
+    resizeObservers?: Set<SizeObserver>;
 } & TinkyNode;
 /**
  * Interface representing a text node in Tinky.

package/lib/core/reconciler.js

@@ -5,6 +5,7 @@ import { createContext } from "react";
 import { createTextNode, appendChildNode, insertBeforeNode, removeChildNode, setStyle, setTextNodeValue, createNode, setAttribute, } from "./dom.js";
 import { applyStyles } from "./styles.js";
 import { process } from "../utils/node-adapter.js";
+import { removeSizeObserversInSubtree } from "./size-observer.js";
 // We need to conditionally perform devtools connection to avoid
 // accidentally breaking other third-party code.
 if (process?.env?.["DEV"] === "true") {
@@ -204,6 +205,7 @@ export const reconciler = createReconciler({
     insertInContainerBefore: insertBeforeNode,
     removeChildFromContainer(node, removeNode) {
         removeChildNode(node, removeNode);
+        removeSizeObserversInSubtree(removeNode);
         cleanupTaffyNode(removeNode.taffyNode);
     },
     commitUpdate(node, _type, oldProps, newProps) {
@@ -241,6 +243,7 @@ export const reconciler = createReconciler({
     },
     removeChild(node, removeNode) {
         removeChildNode(node, removeNode);
+        removeSizeObserversInSubtree(removeNode);
         cleanupTaffyNode(removeNode.taffyNode);
     },
     setCurrentUpdatePriority(newPriority) {

package/lib/core/size-observer.d.ts

@@ -0,0 +1,60 @@
+import { type DOMElement, type DOMNode } from "./dom.js";
+import { type Dimension } from "../utils/dimension.js";
+/**
+ * Interface for elements returned by the SizeObserver callback.
+ */
+export interface SizeObserverEntry {
+    target: DOMElement;
+    dimension: Dimension;
+}
+/**
+ * Callback type for resize observers.
+ */
+export type SizeObserverCallback = (entries: SizeObserverEntry[], observer: SizeObserver) => void;
+/**
+ * Global registry mapping DOMElements to their registered SizeObservers.
+ */
+export declare const resizeObserverRegistry: Map<DOMElement, Set<SizeObserver>>;
+/**
+ * Implements a SizeObserver API similar to the HTML specification.
+ * It allows observing changes to the computed dimensions of Tinky DOM elements.
+ */
+export declare class SizeObserver {
+    private callback;
+    /**
+     * Creates a new SizeObserver.
+     *
+     * @param callback - The function to call when observed elements resize.
+     */
+    constructor(callback: SizeObserverCallback);
+    /**
+     * Starts observing the specified element.
+     *
+     * @param target - The element to observe.
+     */
+    observe(target: DOMElement): void;
+    /**
+     * Stops observing the specified element.
+     *
+     * @param target - The element to stop observing.
+     */
+    unobserve(target: DOMElement): void;
+    /**
+     * Stops observing all elements.
+     */
+    disconnect(): void;
+    /** @internal */
+    _invokeCallback(entries: SizeObserverEntry[]): void;
+}
+/**
+ * Removes all resize observers from a node and its descendants.
+ * Called during mutation cleanup to prevent stale observer entries.
+ *
+ * @param node - Root of the removed subtree.
+ */
+export declare const removeSizeObserversInSubtree: (node: DOMNode) => void;
+/**
+ * Notifies all registered resize observers of their current dimensions.
+ * Called by the Tinky instance after each layout computation pass.
+ */
+export declare const notifySizeObservers: () => void;

package/lib/core/size-observer.js

@@ -0,0 +1,133 @@
+/**
+ * Global registry mapping DOMElements to their registered SizeObservers.
+ */
+export const resizeObserverRegistry = new Map();
+/**
+ * Implements a SizeObserver API similar to the HTML specification.
+ * It allows observing changes to the computed dimensions of Tinky DOM elements.
+ */
+export class SizeObserver {
+    callback;
+    /**
+     * Creates a new SizeObserver.
+     *
+     * @param callback - The function to call when observed elements resize.
+     */
+    constructor(callback) {
+        this.callback = callback;
+    }
+    /**
+     * Starts observing the specified element.
+     *
+     * @param target - The element to observe.
+     */
+    observe(target) {
+        if (!target.resizeObservers) {
+            target.resizeObservers = new Set();
+        }
+        target.resizeObservers.add(this);
+        let observers = resizeObserverRegistry.get(target);
+        if (!observers) {
+            observers = new Set();
+            resizeObserverRegistry.set(target, observers);
+        }
+        observers.add(this);
+    }
+    /**
+     * Stops observing the specified element.
+     *
+     * @param target - The element to stop observing.
+     */
+    unobserve(target) {
+        target.resizeObservers?.delete(this);
+        if (target.resizeObservers?.size === 0) {
+            target.resizeObservers = undefined;
+        }
+        const observers = resizeObserverRegistry.get(target);
+        if (observers) {
+            observers.delete(this);
+            if (observers.size === 0) {
+                resizeObserverRegistry.delete(target);
+            }
+        }
+    }
+    /**
+     * Stops observing all elements.
+     */
+    disconnect() {
+        for (const [target, observers] of resizeObserverRegistry.entries()) {
+            if (observers.has(this)) {
+                this.unobserve(target);
+            }
+        }
+    }
+    /** @internal */
+    _invokeCallback(entries) {
+        this.callback(entries, this);
+    }
+}
+/**
+ * Removes all resize observers from a node and its descendants.
+ * Called during mutation cleanup to prevent stale observer entries.
+ *
+ * @param node - Root of the removed subtree.
+ */
+export const removeSizeObserversInSubtree = (node) => {
+    if (node.nodeName === "#text") {
+        return;
+    }
+    if (node.resizeObservers) {
+        // Collect all observers to avoid disconnecting while iterating
+        const observers = Array.from(node.resizeObservers);
+        for (const observer of observers) {
+            observer.unobserve(node);
+        }
+        node.resizeObservers = undefined;
+    }
+    // Not strictly necessary here since unobserve handles it,
+    // but good for completeness in case it fell through
+    resizeObserverRegistry.delete(node);
+    for (const childNode of node.childNodes) {
+        removeSizeObserversInSubtree(childNode);
+    }
+};
+/**
+ * Notifies all registered resize observers of their current dimensions.
+ * Called by the Tinky instance after each layout computation pass.
+ */
+export const notifySizeObservers = () => {
+    const entriesByObserver = new Map();
+    for (const [node, observers] of resizeObserverRegistry.entries()) {
+        if (!node.taffyNode) {
+            continue;
+        }
+        let layout;
+        try {
+            layout = node.taffyNode.tree.getLayout(node.taffyNode.id);
+        }
+        catch {
+            // Node was removed from the tree before passive effect cleanup ran.
+            const nodeObservers = Array.from(observers);
+            for (const observer of nodeObservers) {
+                observer.unobserve(node);
+            }
+            continue;
+        }
+        const dimension = {
+            width: layout?.width ?? 0,
+            height: layout?.height ?? 0,
+        };
+        const entry = { target: node, dimension };
+        for (const observer of observers) {
+            let entries = entriesByObserver.get(observer);
+            if (!entries) {
+                entries = [];
+                entriesByObserver.set(observer, entries);
+            }
+            entries.push(entry);
+        }
+    }
+    for (const [observer, entries] of entriesByObserver.entries()) {
+        observer._invokeCallback(entries);
+    }
+};

package/lib/core/tinky.js

@@ -19,6 +19,7 @@ import { App } from "../components/App.js";
 import { AccessibilityContext } from "../contexts/AccessibilityContext.js";
 import { CellBuffer, StyleRegistry } from "./cell-buffer.js";
 import { normalizeIncrementalRendering, } from "./incremental-rendering.js";
+import { notifySizeObservers } from "./size-observer.js";
 const noop = () => {
     // no-op
 };
@@ -222,6 +223,8 @@ export class Tinky {
             }
             return context.measureFunc(availableSpace.width);
         });
+        // Notify all registered resize observers of their current dimensions.
+        notifySizeObservers();
     };
     /**
      * Performs the render operation.

package/lib/hooks/use-size-observer.d.ts

@@ -0,0 +1,44 @@
+import { type DOMElement } from "../core/dom.js";
+/**
+ * Options for the `useSizeObserver` hook.
+ */
+export interface SizeObserverOptions {
+    /**
+     * Enable or disable the size observer.
+     *
+     * @defaultValue true
+     */
+    isActive?: boolean;
+}
+/**
+ * Hook that observes the computed layout dimensions of a `<Box>` element
+ * and triggers a re-render whenever its size changes.
+ *
+ * The observer is registered in a global resize observer registry that is
+ * invoked by the Tinky core after each layout computation pass. This means
+ * size changes are detected regardless of which component caused the
+ * re-render — including sibling updates and terminal resize events.
+ *
+ * Multiple observers can be attached to the same element.
+ *
+ * This is similar to HTML's `SizeObserver` API.
+ *
+ * @example
+ * ```tsx
+ * import { Box, Text, useSizeObserver } from 'tinky';
+ *
+ * function MyComponent() {
+ *   const [ref, width, height] = useSizeObserver();
+ *
+ *   return (
+ *     <Box ref={ref} width="50%" height={10}>
+ *       <Text>Size: {width}x{height}</Text>
+ *     </Box>
+ *   );
+ * }
+ * ```
+ *
+ * @param options - Configuration options.
+ * @returns A tuple containing `[refCallback, width, height]`. Attach `refCallback` to a `<Box>` element.
+ */
+export declare const useSizeObserver: (options?: SizeObserverOptions) => [(node: DOMElement | null) => void, number, number];

package/lib/hooks/use-size-observer.js

@@ -0,0 +1,70 @@
+import { useCallback, useRef, useState } from "react";
+import { measureElement } from "../utils/measure-element.js";
+import { SizeObserver } from "../core/size-observer.js";
+import { reconciler } from "../core/reconciler.js";
+/**
+ * Hook that observes the computed layout dimensions of a `<Box>` element
+ * and triggers a re-render whenever its size changes.
+ *
+ * The observer is registered in a global resize observer registry that is
+ * invoked by the Tinky core after each layout computation pass. This means
+ * size changes are detected regardless of which component caused the
+ * re-render — including sibling updates and terminal resize events.
+ *
+ * Multiple observers can be attached to the same element.
+ *
+ * This is similar to HTML's `SizeObserver` API.
+ *
+ * @example
+ * ```tsx
+ * import { Box, Text, useSizeObserver } from 'tinky';
+ *
+ * function MyComponent() {
+ *   const [ref, width, height] = useSizeObserver();
+ *
+ *   return (
+ *     <Box ref={ref} width="50%" height={10}>
+ *       <Text>Size: {width}x{height}</Text>
+ *     </Box>
+ *   );
+ * }
+ * ```
+ *
+ * @param options - Configuration options.
+ * @returns A tuple containing `[refCallback, width, height]`. Attach `refCallback` to a `<Box>` element.
+ */
+export const useSizeObserver = (options = {}) => {
+    const [size, setSize] = useState({ width: 0, height: 0 });
+    const observerRef = useRef(null);
+    const prevSize = useRef({ width: 0, height: 0 });
+    const { isActive = true } = options;
+    const callbackRef = useCallback((node) => {
+        // Cleanup previous observer
+        if (observerRef.current) {
+            observerRef.current.disconnect();
+            observerRef.current = null;
+        }
+        // If active and node is attached, start observing
+        if (isActive && node) {
+            const callback = (entries) => {
+                if (entries.length === 0)
+                    return;
+                const { dimension } = entries[0];
+                if (dimension.width !== prevSize.current.width ||
+                    dimension.height !== prevSize.current.height) {
+                    prevSize.current = { ...dimension };
+                    reconciler.batchedUpdates(() => {
+                        setSize({ ...dimension });
+                    }, null);
+                }
+            };
+            const observer = new SizeObserver(callback);
+            // Read initial dimensions
+            const initial = measureElement(node);
+            callback([{ target: node, dimension: initial }]);
+            observer.observe(node);
+            observerRef.current = observer;
+        }
+    }, [isActive]);
+    return [callbackRef, size.width, size.height];
+};

package/lib/index.d.ts

@@ -21,6 +21,7 @@ export { useFocus, type FocusOptions, type FocusState, } from "./hooks/use-focus
 export { useFocusManager, type FocusManager, } from "./hooks/use-focus-manager.js";
 export { useIsScreenReaderEnabled } from "./hooks/use-is-screen-reader-enabled.js";
 export { measureElement } from "./utils/measure-element.js";
+export { useSizeObserver, type SizeObserverOptions, } from "./hooks/use-size-observer.js";
 export { type Dimension } from "./utils/dimension.js";
 export { type ForegroundColorName } from "./utils/colorize.js";
 export { applyTextStyles, type TextStyles } from "./utils/apply-text-styles.js";

package/lib/index.js

@@ -19,6 +19,7 @@ export { useFocus, } from "./hooks/use-focus.js";
 export { useFocusManager, } from "./hooks/use-focus-manager.js";
 export { useIsScreenReaderEnabled } from "./hooks/use-is-screen-reader-enabled.js";
 export { measureElement } from "./utils/measure-element.js";
+export { useSizeObserver, } from "./hooks/use-size-observer.js";
 export { applyTextStyles } from "./utils/apply-text-styles.js";
 export { boxStyles } from "./core/box-styles.js";
 export { EventEmitter } from "./utils/event-emitter.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tinky",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "React for CLIs, re-imagined with the Taffy engine",
   "keywords": [
     "react",