tinky 0.1.0 → 1.1.0

package/README.ja-JP.md

@@ -282,6 +282,8 @@ Tinky は複数のカラー形式をサポートしています：
 
 ## 🔧 API リファレンス
 
+完全な API ドキュメントは [API ドキュメント](./docs/api/globals.md) を参照してください。
+
 ### render(element, options?)
 
 React 要素をターミナルにレンダリングします。

package/README.md

@@ -282,6 +282,8 @@ Tinky supports multiple color formats:
 
 ## 🔧 API Reference
 
+For complete API documentation, see the [API Docs](./docs/api/globals.md).
+
 ### render(element, options?)
 
 Render a React element to the terminal.

package/README.zh-CN.md

@@ -282,6 +282,8 @@ Tinky 支持多种颜色格式：
 
 ## 🔧 API 参考
 
+完整的 API 文档请参阅 [API 文档](./docs/api/globals.md)。
+
 ### render(element, options?)
 
 将 React 元素渲染到终端。

package/lib/components/App.js

@@ -2,12 +2,12 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { EventEmitter } from "node:events";
 import process from "node:process";
 import { PureComponent } from "react";
-import cliCursor from "cli-cursor";
-import { AppContext } from "./AppContext.js";
-import { StdinContext } from "./StdinContext.js";
-import { StdoutContext } from "./StdoutContext.js";
-import { StderrContext } from "./StderrContext.js";
-import { FocusContext } from "./FocusContext.js";
+import * as cliCursor from "../utils/cli-cursor.js";
+import { AppContext } from "../contexts/AppContext.js";
+import { StdinContext } from "../contexts/StdinContext.js";
+import { StdoutContext } from "../contexts/StdoutContext.js";
+import { StderrContext } from "../contexts/StderrContext.js";
+import { FocusContext } from "../contexts/FocusContext.js";
 import { ErrorOverview } from "./ErrorOverview.js";
 const tab = "\t";
 const shiftTab = "\u001B[Z";

package/lib/components/Box.d.ts

@@ -1,6 +1,6 @@
 import { type Except } from "type-fest";
-import { type Styles } from "../styles.js";
-import { type DOMElement } from "../dom.js";
+import { type Styles } from "../core/styles.js";
+import { type DOMElement } from "../core/dom.js";
 /**
  * Props for the Box component.
  */

package/lib/components/Box.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { forwardRef, useContext } from "react";
-import { AccessibilityContext } from "./AccessibilityContext.js";
-import { backgroundContext } from "./BackgroundContext.js";
+import { AccessibilityContext } from "../contexts/AccessibilityContext.js";
+import { backgroundContext } from "../contexts/BackgroundContext.js";
 /**
  * `<Box>` is an essential Tinky component to build your layout. It's like
  * `<div style="display: flex">` in the browser.

package/lib/components/Static.d.ts

@@ -1,5 +1,5 @@
 import { type ReactNode } from "react";
-import { type Styles } from "../styles.js";
+import { type Styles } from "../core/styles.js";
 /**
  * Props for the Static component.
  */

package/lib/components/Text.d.ts

@@ -1,7 +1,7 @@
 import { type ReactNode } from "react";
 import { type ForegroundColorName } from "chalk";
 import { type LiteralUnion } from "type-fest";
-import { type Styles } from "../styles.js";
+import { type Styles } from "../core/styles.js";
 /**
  * Props for the Text component.
  */

package/lib/components/Text.js

@@ -1,9 +1,9 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useContext } from "react";
 import chalk from "chalk";
-import { colorize } from "../colorize.js";
-import { AccessibilityContext } from "./AccessibilityContext.js";
-import { backgroundContext } from "./BackgroundContext.js";
+import { colorize } from "../utils/colorize.js";
+import { AccessibilityContext } from "../contexts/AccessibilityContext.js";
+import { backgroundContext } from "../contexts/BackgroundContext.js";
 /**
  * This component can display text and change its style to make it bold,
  * underlined, italic, or strikethrough.

package/lib/components/Transform.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useContext } from "react";
-import { AccessibilityContext } from "./AccessibilityContext.js";
+import { AccessibilityContext } from "../contexts/AccessibilityContext.js";
 /**
  * Transform a string representation of React components before they're written
  * to output. For example, you might want to apply a gradient to text, add a

package/lib/contexts/AccessibilityContext.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Value type for the AccessibilityContext.
+ */
+export interface AccessibilityContextValue {
+    /**
+     * Whether the screen reader is enabled.
+     *
+     * @defaultValue false
+     */
+    readonly isScreenReaderEnabled: boolean;
+}
+/**
+ * Context to manage accessibility settings, specifically screen reader.
+ *
+ * @example
+ * ```tsx
+ * import { useIsScreenReaderEnabled } from 'tinky';
+ *
+ * const Component = () => {
+ *   const isScreenReaderEnabled = useIsScreenReaderEnabled();
+ *
+ *   if (isScreenReaderEnabled) {
+ *     return <Text>Screen reader friendly output</Text>;
+ *   }
+ *
+ *   return <Text>Regular output</Text>;
+ * };
+ * ```
+ */
+export declare const AccessibilityContext: import("react").Context<AccessibilityContextValue>;

package/lib/contexts/AccessibilityContext.js

@@ -0,0 +1,25 @@
+import { createContext } from "react";
+/**
+ * Context to manage accessibility settings, specifically screen reader.
+ *
+ * @example
+ * ```tsx
+ * import { useIsScreenReaderEnabled } from 'tinky';
+ *
+ * const Component = () => {
+ *   const isScreenReaderEnabled = useIsScreenReaderEnabled();
+ *
+ *   if (isScreenReaderEnabled) {
+ *     return <Text>Screen reader friendly output</Text>;
+ *   }
+ *
+ *   return <Text>Regular output</Text>;
+ * };
+ * ```
+ */
+export const AccessibilityContext = createContext({
+    /**
+     * Whether the screen reader is enabled.
+     */
+    isScreenReaderEnabled: false,
+});

package/lib/contexts/BackgroundContext.d.ts

@@ -0,0 +1,25 @@
+import { type LiteralUnion } from "type-fest";
+import { type ForegroundColorName } from "ansi-styles";
+/**
+ * Union type for background colors.
+ *
+ * Accepts any named color from `ansi-styles`, hex colors, RGB colors,
+ * or ANSI 256 color codes.
+ *
+ * @example
+ * ```tsx
+ * backgroundColor="red"                    // Named color
+ * backgroundColor="#ff6600"                // Hex color
+ * backgroundColor="rgb(255, 102, 0)"       // RGB color
+ * backgroundColor="ansi256:208"            // ANSI 256 color
+ * ```
+ */
+export type BackgroundColor = LiteralUnion<ForegroundColorName, string>;
+/**
+ * Context to pass the background color down the component tree.
+ *
+ * Allows nested components to inherit the background color from parents.
+ *
+ * @defaultValue undefined
+ */
+export declare const backgroundContext: import("react").Context<BackgroundColor | undefined>;

package/lib/{components → contexts}/BackgroundContext.js

@@ -1,5 +1,9 @@
 import { createContext } from "react";
 /**
  * Context to pass the background color down the component tree.
+ *
+ * Allows nested components to inherit the background color from parents.
+ *
+ * @defaultValue undefined
  */
 export const backgroundContext = createContext(undefined);

package/lib/{components → contexts}/FocusContext.d.ts

@@ -8,20 +8,29 @@ export interface FocusProps {
     readonly activeId?: string;
     /**
      * Register a new focusable component.
+     *
+     * @param id - Unique identifier for the focusable component.
+     * @param options.autoFocus - Auto-focus the component when registered.
      */
     readonly add: (id: string, options: {
         autoFocus: boolean;
     }) => void;
     /**
      * Unregister a focusable component.
+     *
+     * @param id - Unique identifier of the component to unregister.
      */
     readonly remove: (id: string) => void;
     /**
-     * Mark a component as active.
+     * Mark a component as active (focused).
+     *
+     * @param id - Unique identifier of the component to activate.
      */
     readonly activate: (id: string) => void;
     /**
-     * Mark a component as inactive.
+     * Mark a component as inactive (unfocused).
+     *
+     * @param id - Unique identifier of the component to deactivate.
      */
     readonly deactivate: (id: string) => void;
     /**
@@ -42,6 +51,8 @@ export interface FocusProps {
     readonly focusPrevious: () => void;
     /**
      * Focus a specific component by ID.
+     *
+     * @param id - Unique identifier of the component to focus.
      */
     readonly focus: (id: string) => void;
 }

package/lib/{dom.d.ts → core/dom.d.ts}

@@ -4,10 +4,14 @@ import { TaffyNode } from "./taffy-node.js";
 /**
  * Interface representing a node in the Tinky tree.
  */
-interface TinkyNode {
+export interface TinkyNode {
+    /** Parent DOM element in the tree. */
     parentNode: DOMElement | undefined;
+    /** Taffy layout node for computing dimensions. */
     taffyNode?: TaffyNode;
+    /** Whether this node is inside a Static component. */
     internal_static?: boolean;
+    /** Styles applied to this node. */
     style: Styles;
 }
 /**
@@ -26,35 +30,58 @@ export type NodeNames = ElementNames | TextName;
  * Interface representing a DOM element in Tinky.
  */
 export type DOMElement = {
+    /** Name of the element type. */
     nodeName: ElementNames;
+    /** Key-value pairs of element attributes. */
     attributes: Record<string, DOMNodeAttribute>;
+    /** Array of child nodes. */
     childNodes: DOMNode[];
+    /** Function to transform the output of this element. */
     internal_transform?: OutputTransformer;
+    /** Accessibility attributes for screen readers. */
     internal_accessibility?: {
+        /** ARIA role for the element. */
         role?: "button" | "checkbox" | "combobox" | "list" | "listbox" | "listitem" | "menu" | "menuitem" | "option" | "progressbar" | "radio" | "radiogroup" | "tab" | "tablist" | "table" | "textbox" | "timer" | "toolbar";
+        /** ARIA state values for the element. */
         state?: {
+            /** Whether the element is busy. */
             busy?: boolean;
+            /** Whether the element is checked. */
             checked?: boolean;
+            /** Whether the element is disabled. */
             disabled?: boolean;
+            /** Whether the element is expanded. */
             expanded?: boolean;
+            /** Whether the element accepts multiline input. */
             multiline?: boolean;
+            /** Whether multiple items can be selected. */
             multiselectable?: boolean;
+            /** Whether the element is read-only. */
             readonly?: boolean;
+            /** Whether the element is required. */
             required?: boolean;
+            /** Whether the element is selected. */
             selected?: boolean;
         };
     };
+    /** Whether static nodes need to be re-rendered. */
     isStaticDirty?: boolean;
+    /** Reference to the Static component node. */
     staticNode?: DOMElement;
+    /** Callback to compute layout before rendering. */
     onComputeLayout?: () => void;
+    /** Callback to trigger a render. */
     onRender?: () => void;
+    /** Callback to trigger an immediate render. */
     onImmediateRender?: () => void;
 } & TinkyNode;
 /**
  * Interface representing a text node in Tinky.
  */
 export type TextNode = {
+    /** Text node identifier. */
     nodeName: TextName;
+    /** Text content of the node. */
     nodeValue: string;
 } & TinkyNode;
 /**
@@ -127,4 +154,3 @@ export declare const createTextNode: (text: string) => TextNode;
  * @param text - The new text value.
  */
 export declare const setTextNodeValue: (node: TextNode, text: string) => void;
-export {};

package/lib/{dom.js → core/dom.js}

@@ -1,7 +1,7 @@
 import stringWidth from "string-width";
-import { measureText } from "./measure-text.js";
-import { wrapText } from "./wrap-text.js";
-import { squashTextNodes } from "./squash-text-nodes.js";
+import { measureText } from "../utils/measure-text.js";
+import { wrapText } from "../utils/wrap-text.js";
+import { squashTextNodes } from "../utils/squash-text-nodes.js";
 import { TaffyNode } from "./taffy-node.js";
 /**
  * Creates a new DOM element.

package/lib/{log-update.js → core/log-update.js}

@@ -1,5 +1,5 @@
 import ansiEscapes from "ansi-escapes";
-import cliCursor from "cli-cursor";
+import * as cliCursor from "../utils/cli-cursor.js";
 /**
  * Creates a standard LogUpdate instance.
  * Re-renders the entire previous output on each update.

package/lib/{output.d.ts → core/output.d.ts}

@@ -1,24 +1,16 @@
 import { type OutputTransformer } from "./render-node-to-output.js";
-/**
- * Options for creating an Output instance.
- */
-interface Options {
-    /**
-     * Width of the output area.
-     */
-    width: number;
-    /**
-     * Height of the output area.
-     */
-    height: number;
-}
+import { type Dimension } from "../utils/dimension.js";
 /**
  * Represents a clipping rectangle.
  */
 interface Clip {
+    /** Left boundary (undefined for no limit). */
     x1: number | undefined;
+    /** Right boundary (undefined for no limit). */
     x2: number | undefined;
+    /** Top boundary (undefined for no limit). */
     y1: number | undefined;
+    /** Bottom boundary (undefined for no limit). */
     y2: number | undefined;
 }
 /**
@@ -36,9 +28,9 @@ export declare class Output {
     /**
      * Creates a new Output instance.
      *
-     * @param options - Configuration options containing width and height.
+     * @param dimension - Dimensions containing width and height.
      */
-    constructor(options: Options);
+    constructor(dimension: Dimension);
     /**
      * Writes text to the output at a specified position.
      *

package/lib/{output.js → core/output.js}

@@ -17,10 +17,10 @@ export class Output {
     /**
      * Creates a new Output instance.
      *
-     * @param options - Configuration options containing width and height.
+     * @param dimension - Dimensions containing width and height.
      */
-    constructor(options) {
-        const { width, height } = options;
+    constructor(dimension) {
+        const { width, height } = dimension;
         this.width = width;
         this.height = height;
     }

package/lib/{reconciler.js → core/reconciler.js}

@@ -4,7 +4,7 @@ import { DefaultEventPriority, NoEventPriority, } from "react-reconciler/constan
 import { Display } from "taffy-layout";
 import { createContext } from "react";
 import { createTextNode, appendChildNode, insertBeforeNode, removeChildNode, setStyle, setTextNodeValue, createNode, setAttribute, } from "./dom.js";
-import { styles } from "./styles.js";
+import { applyStyles } from "./styles.js";
 // We need to conditionally perform devtools connection to avoid
 // accidentally breaking other third-party code.
 if (process.env["DEV"] === "true") {
@@ -54,10 +54,19 @@ const diff = (before, after) => {
     }
     return isChanged ? changed : undefined;
 };
+/**
+ * Cleans up a Taffy node by freeing its resources.
+ *
+ * @param node - The Taffy node to cleanup.
+ */
 const cleanupTaffyNode = (node) => {
     node?.free();
 };
 let currentUpdatePriority = NoEventPriority;
+/**
+ * Reference to the current root DOM element during rendering.
+ * Used to track static node state across renders.
+ */
 let currentRootNode;
 /**
  * React reconciler implementation for Tinky.
@@ -113,7 +122,7 @@ export const reconciler = createReconciler({
             if (key === "style") {
                 setStyle(node, value);
                 if (node.taffyNode) {
-                    styles(node.taffyNode, value);
+                    applyStyles(node.taffyNode, value);
                 }
                 continue;
             }
@@ -224,7 +233,7 @@ export const reconciler = createReconciler({
             }
         }
         if (style && node.taffyNode) {
-            styles(node.taffyNode, style);
+            applyStyles(node.taffyNode, style);
         }
     },
     commitTextUpdate(node, _oldText, newText) {

package/lib/{render-border.js → core/render-border.js}

@@ -1,6 +1,6 @@
 import cliBoxes from "cli-boxes";
 import chalk from "chalk";
-import { colorize } from "./colorize.js";
+import { colorize } from "../utils/colorize.js";
 /**
  * Renders the border for a DOM node.
  * Calculates border dimensions and draws border characters with specified

package/lib/{render-node-to-output.js → core/render-node-to-output.js}

@@ -1,11 +1,11 @@
 import widestLine from "widest-line";
 import indentString from "indent-string";
 import { Display } from "taffy-layout";
-import { wrapText } from "./wrap-text.js";
-import { getMaxWidth } from "./get-max-width.js";
-import { squashTextNodes } from "./squash-text-nodes.js";
+import { wrapText } from "../utils/wrap-text.js";
+import { getMaxWidth } from "../utils/get-max-width.js";
+import { squashTextNodes } from "../utils/squash-text-nodes.js";
 import { renderBorder } from "./render-border.js";
-import { renderBackground } from "./render-background.js";
+import { renderBackground } from "../utils/render-background.js";
 /**
  * Applies padding to text based on the layout of the first text node.
  *

package/lib/{render.d.ts → core/render.d.ts}

@@ -23,7 +23,8 @@ export interface RenderOptions {
      */
     stderr?: NodeJS.WriteStream;
     /**
-     * If true, each update will be rendered as separate output, without replacing.
+     * If true, each update will be rendered as separate output, without
+     * replacing.
      *
      * @defaultValue false
      */
@@ -63,7 +64,8 @@ export interface RenderOptions {
     maxFps?: number;
     /**
      * Enable incremental rendering mode which only updates changed lines instead
-     * of redrawing the entire output. Reduces flickering and improves performance.
+     * of redrawing the entire output. Reduces flickering and improves
+     * performance.
      *
      * @defaultValue false
      */

package/lib/{styles.d.ts → core/styles.d.ts}

@@ -399,4 +399,4 @@ export interface Styles {
      */
     readonly gridTemplateAreas?: GridTemplateArea[];
 }
-export declare const styles: (node: TaffyNode, style?: Styles) => void;
+export declare const applyStyles: (node: TaffyNode, style?: Styles) => void;

package/lib/{styles.js → core/styles.js}

@@ -617,7 +617,7 @@ const applyGridStyles = (taffyStyle, style) => {
         }
     }
 };
-export const styles = (node, style = {}) => {
+export const applyStyles = (node, style = {}) => {
     const taffyStyle = node.tree.getStyle(node.id);
     applyPositionStyles(taffyStyle, style);
     applyMarginStyles(taffyStyle, style);

package/lib/{taffy-node.d.ts → core/taffy-node.d.ts}

@@ -35,5 +35,10 @@ export declare class TaffyNode {
      * Necessary to prevent memory leaks as Taffy nodes aren't GC'd automatically.
      */
     free(): void;
+    /**
+     * Recursively removes a node and all its descendants from the Taffy tree.
+     *
+     * @param id - The ID of the node to remove.
+     */
     private freeRecursive;
 }

package/lib/{taffy-node.js → core/taffy-node.js}

@@ -51,6 +51,11 @@ export class TaffyNode {
         }
         this.tree.remove(this.id);
     }
+    /**
+     * Recursively removes a node and all its descendants from the Taffy tree.
+     *
+     * @param id - The ID of the node to remove.
+     */
     freeRecursive(id) {
         for (const childId of this.tree.children(id)) {
             this.freeRecursive(childId);

package/lib/{tinky.d.ts → core/tinky.d.ts}

@@ -68,19 +68,33 @@ export interface Options {
  * lifecycle, and terminal output.
  */
 export declare class Tinky {
+    /** Configuration options for this instance. */
     private readonly options;
+    /** Log update instance for output. */
     private readonly log;
+    /** Throttled log update instance for output. */
     private readonly throttledLog;
+    /** Whether screen reader support is enabled. */
     private readonly isScreenReaderEnabled;
+    /** Whether the app has been unmounted. */
     private isUnmounted;
+    /** Last output string that was rendered. */
     private lastOutput;
+    /** Height of the last output in lines. */
     private lastOutputHeight;
+    /** Width of the terminal at last render. */
     private lastTerminalWidth;
+    /** React reconciler container. */
     private readonly container;
+    /** Root DOM element for the React tree. */
     private readonly rootNode;
+    /** Full static output for debug mode. */
     private fullStaticOutput;
+    /** Promise that resolves when the app exits. */
     private exitPromise?;
+    /** Function to restore console after patching. */
     private restoreConsole?;
+    /** Function to unsubscribe from resize events. */
     private readonly unsubscribeResize?;
     /**
      * Creates an instance of Tinky.
@@ -99,9 +113,13 @@ export declare class Tinky {
      * Clears the screen when width decreases to prevent overlapping re-renders.
      */
     resized: () => void;
+    /** Resolves the exit promise when the app unmounts. */
     resolveExitPromise: () => void;
+    /** Rejects the exit promise with an error. */
     rejectExitPromise: (reason?: Error) => void;
+    /** Unsubscribes from the exit event. */
     unsubscribeExit: () => void;
+    /** Error that occurred during rendering, if any. */
     renderError: Error | null;
     /**
      * Calculates the layout of the UI (TaffyLayout).