tinky 0.1.0

package/lib/components/StdoutContext.js

@@ -0,0 +1,13 @@
+import process from "node:process";
+import { createContext } from "react";
+/**
+ * `StdoutContext` is a React context that exposes the stdout stream where
+ * Tinky renders your app.
+ */
+export const StdoutContext = createContext({
+    stdout: process.stdout,
+    write() {
+        // no-op
+    },
+});
+StdoutContext.displayName = "InternalStdoutContext";

package/lib/components/Text.d.ts

@@ -0,0 +1,84 @@
+import { type ReactNode } from "react";
+import { type ForegroundColorName } from "chalk";
+import { type LiteralUnion } from "type-fest";
+import { type Styles } from "../styles.js";
+/**
+ * Props for the Text component.
+ */
+export interface TextProps {
+    /**
+     * A label for the element for screen readers.
+     */
+    readonly "aria-label"?: string;
+    /**
+     * Hide the element from screen readers.
+     */
+    readonly "aria-hidden"?: boolean;
+    /**
+     * Change text color. Tinky uses Chalk under the hood, so all its functionality
+     * is supported.
+     */
+    readonly color?: LiteralUnion<ForegroundColorName, string>;
+    /**
+     * Same as `color`, but for the background.
+     */
+    readonly backgroundColor?: LiteralUnion<ForegroundColorName, string>;
+    /**
+     * Dim the color (make it less bright).
+     */
+    readonly dimColor?: boolean;
+    /**
+     * Make the text bold.
+     */
+    readonly bold?: boolean;
+    /**
+     * Make the text italic.
+     */
+    readonly italic?: boolean;
+    /**
+     * Make the text underlined.
+     */
+    readonly underline?: boolean;
+    /**
+     * Make the text crossed out with a line.
+     */
+    readonly strikethrough?: boolean;
+    /**
+     * Inverse background and foreground colors.
+     */
+    readonly inverse?: boolean;
+    /**
+     * This property tells Tinky to wrap or truncate text if its width is larger
+     * than the container. If `wrap` is passed (the default), Tinky will wrap text
+     * and split it into multiple lines. If `truncate-*` is passed, Tinky will
+     * truncate text instead, resulting in one line with the rest cut off.
+     */
+    readonly wrap?: Styles["textWrap"];
+    /**
+     * Children of the component.
+     */
+    readonly children?: ReactNode;
+}
+/**
+ * This component can display text and change its style to make it bold,
+ * underlined, italic, or strikethrough.
+ *
+ * @example
+ * ```tsx
+ * import {render, Text} from 'tinky';
+ *
+ * render(<Text color="green">I am green</Text>);
+ * ```
+ *
+ * @example
+ * ```tsx
+ * import {render, Text} from 'tinky';
+ *
+ * render(
+ *   <Text bold backgroundColor="blue">
+ *     I am bold on blue background
+ *   </Text>
+ * );
+ * ```
+ */
+export declare function Text({ color, backgroundColor, dimColor, bold, italic, underline, strikethrough, inverse, wrap, children, "aria-label": ariaLabel, "aria-hidden": ariaHidden, }: TextProps): import("react/jsx-runtime").JSX.Element | null;

package/lib/components/Text.js

@@ -0,0 +1,74 @@
+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";
+/**
+ * This component can display text and change its style to make it bold,
+ * underlined, italic, or strikethrough.
+ *
+ * @example
+ * ```tsx
+ * import {render, Text} from 'tinky';
+ *
+ * render(<Text color="green">I am green</Text>);
+ * ```
+ *
+ * @example
+ * ```tsx
+ * import {render, Text} from 'tinky';
+ *
+ * render(
+ *   <Text bold backgroundColor="blue">
+ *     I am bold on blue background
+ *   </Text>
+ * );
+ * ```
+ */
+export function Text({ color, backgroundColor, dimColor = false, bold = false, italic = false, underline = false, strikethrough = false, inverse = false, wrap = "wrap", children, "aria-label": ariaLabel, "aria-hidden": ariaHidden = false, }) {
+    const { isScreenReaderEnabled } = useContext(AccessibilityContext);
+    const inheritedBackgroundColor = useContext(backgroundContext);
+    const childrenOrAriaLabel = isScreenReaderEnabled && ariaLabel ? ariaLabel : children;
+    if (childrenOrAriaLabel === undefined || childrenOrAriaLabel === null) {
+        return null;
+    }
+    const transform = (children) => {
+        if (dimColor) {
+            children = chalk.dim(children);
+        }
+        if (color) {
+            children = colorize(children, color, "foreground");
+        }
+        // Use explicit backgroundColor if provided, otherwise use inherited from parent Box
+        const effectiveBackgroundColor = backgroundColor ?? inheritedBackgroundColor;
+        if (effectiveBackgroundColor) {
+            children = colorize(children, effectiveBackgroundColor, "background");
+        }
+        if (bold) {
+            children = chalk.bold(children);
+        }
+        if (italic) {
+            children = chalk.italic(children);
+        }
+        if (underline) {
+            children = chalk.underline(children);
+        }
+        if (strikethrough) {
+            children = chalk.strikethrough(children);
+        }
+        if (inverse) {
+            children = chalk.inverse(children);
+        }
+        return children;
+    };
+    if (isScreenReaderEnabled && ariaHidden) {
+        return null;
+    }
+    return (_jsx("tinky-text", { style: {
+            flexGrow: 0,
+            flexShrink: 1,
+            flexDirection: "row",
+            textWrap: wrap,
+        }, internal_transform: transform, children: isScreenReaderEnabled && ariaLabel ? ariaLabel : children }));
+}

package/lib/components/Transform.d.ts

@@ -0,0 +1,41 @@
+import { type ReactNode } from "react";
+/**
+ * Props for the Transform component.
+ */
+export interface TransformProps {
+    /**
+     * Screen-reader-specific text to output. If set, all children will be
+     * ignored.
+     */
+    readonly accessibilityLabel?: string;
+    /**
+     * Function that transforms children output. It accepts children and must
+     * return transformed children as well.
+     */
+    readonly transform: (children: string, index: number) => string;
+    /**
+     * Children to transform.
+     */
+    readonly children?: ReactNode;
+}
+/**
+ * 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
+ * clickable link, or create some text effects. These use cases can't accept
+ * React nodes as input; they expect a string. That's what the <Transform>
+ * component does: it gives you an output string of its child components and
+ * lets you transform it in any way.
+ *
+ * @example
+ * ```tsx
+ * import {render, Transform, Text} from 'tinky';
+ *
+ * render(
+ *   <Transform transform={output => output.toUpperCase()}>
+ *     <Text>Hello World</Text>
+ *   </Transform>
+ * );
+ * // Output: HELLO WORLD
+ * ```
+ */
+export declare function Transform({ children, transform, accessibilityLabel, }: TransformProps): import("react/jsx-runtime").JSX.Element | null;

package/lib/components/Transform.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useContext } from "react";
+import { AccessibilityContext } from "./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
+ * clickable link, or create some text effects. These use cases can't accept
+ * React nodes as input; they expect a string. That's what the <Transform>
+ * component does: it gives you an output string of its child components and
+ * lets you transform it in any way.
+ *
+ * @example
+ * ```tsx
+ * import {render, Transform, Text} from 'tinky';
+ *
+ * render(
+ *   <Transform transform={output => output.toUpperCase()}>
+ *     <Text>Hello World</Text>
+ *   </Transform>
+ * );
+ * // Output: HELLO WORLD
+ * ```
+ */
+export function Transform({ children, transform, accessibilityLabel, }) {
+    const { isScreenReaderEnabled } = useContext(AccessibilityContext);
+    if (children === undefined || children === null) {
+        return null;
+    }
+    return (_jsx("tinky-text", { style: { flexGrow: 0, flexShrink: 1, flexDirection: "row" }, internal_transform: transform, children: isScreenReaderEnabled && accessibilityLabel
+            ? accessibilityLabel
+            : children }));
+}

package/lib/devtools-window-polyfill.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/devtools-window-polyfill.js

@@ -0,0 +1,70 @@
+import ws from "ws";
+const customGlobal = global;
+// Polyfill WebSocket for React DevTools backend communication.
+// Node.js does not have a native WebSocket implementation, so we use 'ws'.
+customGlobal.WebSocket ||= ws;
+// Polyfill 'window' and 'self' to point to the global object.
+// React DevTools expects a browser-like environment where these exist.
+customGlobal.window ||= global;
+customGlobal.self ||= global;
+// Configure filters to hide internal Tinky components from the React DevTools
+// component tree.
+// This keeps the DevTools view clean, showing only the user's components.
+customGlobal.window.__REACT_DEVTOOLS_COMPONENT_FILTERS__ = [
+    {
+        // ComponentFilterElementType
+        type: 1,
+        // ElementTypeHostComponent: Hide host components (e.g. text nodes rendered
+        // by Tinky)
+        value: 7,
+        isEnabled: true,
+    },
+    {
+        // ComponentFilterDisplayName
+        type: 2,
+        // Hide the internal wrapper component 'InternalApp'
+        value: "InternalApp",
+        isEnabled: true,
+        isValid: true,
+    },
+    {
+        // ComponentFilterDisplayName
+        type: 2,
+        // Hide the internal AppContext provider
+        value: "InternalAppContext",
+        isEnabled: true,
+        isValid: true,
+    },
+    {
+        // ComponentFilterDisplayName
+        type: 2,
+        // Hide the internal StdoutContext provider
+        value: "InternalStdoutContext",
+        isEnabled: true,
+        isValid: true,
+    },
+    {
+        // ComponentFilterDisplayName
+        type: 2,
+        // Hide the internal StderrContext provider
+        value: "InternalStderrContext",
+        isEnabled: true,
+        isValid: true,
+    },
+    {
+        // ComponentFilterDisplayName
+        type: 2,
+        // Hide the internal StdinContext provider
+        value: "InternalStdinContext",
+        isEnabled: true,
+        isValid: true,
+    },
+    {
+        // ComponentFilterDisplayName
+        type: 2,
+        // Hide the internal FocusContext provider
+        value: "InternalFocusContext",
+        isEnabled: true,
+        isValid: true,
+    },
+];

package/lib/devtools.d.ts

@@ -0,0 +1 @@
+import "./devtools-window-polyfill.js";

package/lib/devtools.js

@@ -0,0 +1,8 @@
+import "./devtools-window-polyfill.js";
+import devtools from "react-devtools-core";
+/**
+ * Initializes React DevTools for Tinky functionality.
+ * This sets up the WebSocket connection required for the standalone DevTools.
+ */
+devtools.initialize();
+devtools.connectToDevTools();

package/lib/dom.d.ts

@@ -0,0 +1,130 @@
+import { type Styles } from "./styles.js";
+import { type OutputTransformer } from "./render-node-to-output.js";
+import { TaffyNode } from "./taffy-node.js";
+/**
+ * Interface representing a node in the Tinky tree.
+ */
+interface TinkyNode {
+    parentNode: DOMElement | undefined;
+    taffyNode?: TaffyNode;
+    internal_static?: boolean;
+    style: Styles;
+}
+/**
+ * Type representing a text node name.
+ */
+export type TextName = "#text";
+/**
+ * Type representing element names in the Tinky DOM.
+ */
+export type ElementNames = "tinky-root" | "tinky-box" | "tinky-text" | "tinky-virtual-text";
+/**
+ * Union type of all possible node names.
+ */
+export type NodeNames = ElementNames | TextName;
+/**
+ * Interface representing a DOM element in Tinky.
+ */
+export type DOMElement = {
+    nodeName: ElementNames;
+    attributes: Record<string, DOMNodeAttribute>;
+    childNodes: DOMNode[];
+    internal_transform?: OutputTransformer;
+    internal_accessibility?: {
+        role?: "button" | "checkbox" | "combobox" | "list" | "listbox" | "listitem" | "menu" | "menuitem" | "option" | "progressbar" | "radio" | "radiogroup" | "tab" | "tablist" | "table" | "textbox" | "timer" | "toolbar";
+        state?: {
+            busy?: boolean;
+            checked?: boolean;
+            disabled?: boolean;
+            expanded?: boolean;
+            multiline?: boolean;
+            multiselectable?: boolean;
+            readonly?: boolean;
+            required?: boolean;
+            selected?: boolean;
+        };
+    };
+    isStaticDirty?: boolean;
+    staticNode?: DOMElement;
+    onComputeLayout?: () => void;
+    onRender?: () => void;
+    onImmediateRender?: () => void;
+} & TinkyNode;
+/**
+ * Interface representing a text node in Tinky.
+ */
+export type TextNode = {
+    nodeName: TextName;
+    nodeValue: string;
+} & TinkyNode;
+/**
+ * Union type representing either a DOM element or a text node.
+ */
+export type DOMNode<T = {
+    nodeName: NodeNames;
+}> = T extends {
+    nodeName: infer U;
+} ? U extends "#text" ? TextNode : DOMElement : never;
+/**
+ * Type representing possible types for DOM node attributes.
+ */
+export type DOMNodeAttribute = boolean | string | number;
+/**
+ * Creates a new DOM element.
+ *
+ * @param nodeName - The name of the node to create.
+ * @returns The created DOM element.
+ */
+export declare const createNode: (nodeName: ElementNames) => DOMElement;
+/**
+ * Appends a child node to a parent node.
+ *
+ * @param node - The parent node.
+ * @param childNode - The child node to append.
+ */
+export declare const appendChildNode: (node: DOMElement, childNode: DOMElement) => void;
+/**
+ * Inserts a new child node before a reference node.
+ *
+ * @param node - The parent node.
+ * @param newChildNode - The new child node to insert.
+ * @param beforeChildNode - The reference node before which to insert the new node.
+ */
+export declare const insertBeforeNode: (node: DOMElement, newChildNode: DOMNode, beforeChildNode: DOMNode) => void;
+/**
+ * Removes a child node from a parent node.
+ *
+ * @param node - The parent node.
+ * @param removeNode - The child node to remove.
+ */
+export declare const removeChildNode: (node: DOMElement, removeNode: DOMNode) => void;
+/**
+ * Sets an attribute on a DOM element.
+ *
+ * @param node - The DOM element.
+ * @param key - The attribute key.
+ * @param value - The attribute value.
+ */
+export declare const setAttribute: (node: DOMElement, key: string, value: DOMNodeAttribute) => void;
+/**
+ * Sets the style of a DOM node.
+ *
+ * @param node - The DOM node.
+ * @param style - The style object.
+ */
+export declare const setStyle: (node: DOMNode, style: Styles) => void;
+/**
+ * Creates a text node.
+ *
+ * @param text - The text content.
+ * @returns The created text node.
+ */
+export declare const createTextNode: (text: string) => TextNode;
+/**
+ * Sets the value of a text node.
+ *
+ * @param node - The text node.
+ * @param text - The new text value.
+ */
+export declare const setTextNodeValue: (node: TextNode, text: string) => void;
+export {};

package/lib/dom.js

@@ -0,0 +1,209 @@
+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 { TaffyNode } from "./taffy-node.js";
+/**
+ * Creates a new DOM element.
+ *
+ * @param nodeName - The name of the node to create.
+ * @returns The created DOM element.
+ */
+export const createNode = (nodeName) => {
+    const node = {
+        nodeName,
+        style: {},
+        attributes: {},
+        childNodes: [],
+        parentNode: undefined,
+        taffyNode: nodeName === "tinky-virtual-text" ? undefined : new TaffyNode(nodeName),
+        internal_accessibility: {},
+    };
+    if (nodeName === "tinky-text" && node.taffyNode) {
+        node.taffyNode.measureFunc = measureTextNode.bind(null, node);
+    }
+    return node;
+};
+/**
+ * Appends a child node to a parent node.
+ *
+ * @param node - The parent node.
+ * @param childNode - The child node to append.
+ */
+export const appendChildNode = (node, childNode) => {
+    if (childNode.parentNode) {
+        removeChildNode(childNode.parentNode, childNode);
+    }
+    childNode.parentNode = node;
+    node.childNodes.push(childNode);
+    if (childNode.taffyNode) {
+        node.taffyNode?.tree.addChild(node.taffyNode.id, childNode.taffyNode.id);
+    }
+    if (node.nodeName === "tinky-text" ||
+        node.nodeName === "tinky-virtual-text") {
+        markNodeAsDirty(node);
+    }
+};
+/**
+ * Inserts a new child node before a reference node.
+ *
+ * @param node - The parent node.
+ * @param newChildNode - The new child node to insert.
+ * @param beforeChildNode - The reference node before which to insert the new node.
+ */
+export const insertBeforeNode = (node, newChildNode, beforeChildNode) => {
+    if (newChildNode.parentNode) {
+        removeChildNode(newChildNode.parentNode, newChildNode);
+    }
+    newChildNode.parentNode = node;
+    const index = node.childNodes.indexOf(beforeChildNode);
+    if (index >= 0) {
+        node.childNodes.splice(index, 0, newChildNode);
+        if (newChildNode.taffyNode) {
+            node.taffyNode?.tree.insertChildAtIndex(node.taffyNode.id, index, newChildNode.taffyNode.id);
+        }
+        return;
+    }
+    node.childNodes.push(newChildNode);
+    if (newChildNode.taffyNode) {
+        node.taffyNode?.tree.addChild(node.taffyNode.id, newChildNode.taffyNode.id);
+    }
+    if (node.nodeName === "tinky-text" ||
+        node.nodeName === "tinky-virtual-text") {
+        markNodeAsDirty(node);
+    }
+};
+/**
+ * Removes a child node from a parent node.
+ *
+ * @param node - The parent node.
+ * @param removeNode - The child node to remove.
+ */
+export const removeChildNode = (node, removeNode) => {
+    if (removeNode.taffyNode) {
+        removeNode.parentNode?.taffyNode?.tree.removeChild(removeNode.parentNode.taffyNode.id, removeNode.taffyNode.id);
+    }
+    removeNode.parentNode = undefined;
+    const index = node.childNodes.indexOf(removeNode);
+    if (index >= 0) {
+        node.childNodes.splice(index, 1);
+    }
+    if (node.nodeName === "tinky-text" ||
+        node.nodeName === "tinky-virtual-text") {
+        markNodeAsDirty(node);
+    }
+};
+/**
+ * Sets an attribute on a DOM element.
+ *
+ * @param node - The DOM element.
+ * @param key - The attribute key.
+ * @param value - The attribute value.
+ */
+export const setAttribute = (node, key, value) => {
+    if (key === "internal_accessibility") {
+        node.internal_accessibility = value;
+        return;
+    }
+    node.attributes[key] = value;
+};
+/**
+ * Sets the style of a DOM node.
+ *
+ * @param node - The DOM node.
+ * @param style - The style object.
+ */
+export const setStyle = (node, style) => {
+    node.style = style;
+};
+/**
+ * Creates a text node.
+ *
+ * @param text - The text content.
+ * @returns The created text node.
+ */
+export const createTextNode = (text) => {
+    const node = {
+        nodeName: "#text",
+        nodeValue: text,
+        taffyNode: undefined,
+        parentNode: undefined,
+        style: {},
+    };
+    setTextNodeValue(node, text);
+    return node;
+};
+/**
+ * Measures the dimensions of a text node.
+ *
+ * @param node - The text node to measure.
+ * @param width - The available width constraint.
+ * @returns The measured width and height.
+ */
+const measureTextNode = function (node, width) {
+    const text = node.nodeName === "#text" ? node.nodeValue : squashTextNodes(node);
+    // For minContent mode, compute the minimum possible width for the text.
+    // This is the width of the widest character (e.g., emojis are typically 2
+    // columns, ASCII chars are 1).
+    if (width === "min-content") {
+        const chars = [...text];
+        const maxCharWidth = Math.max(...chars.map((c) => stringWidth(c)), 1);
+        const textWrap = node.style?.textWrap ?? "wrap";
+        const wrappedText = wrapText(text, maxCharWidth, textWrap);
+        return measureText(wrappedText);
+    }
+    const dimensions = measureText(text);
+    // For maxContent mode, return the natural text dimensions without wrapping
+    if (width === "max-content") {
+        return dimensions;
+    }
+    // For definite mode with width constraint:
+    // Text fits into container, no need to wrap
+    if (dimensions.width <= width) {
+        return dimensions;
+    }
+    // This is happening when <Box> is shrinking child nodes and layout engine
+    // asks if we can fit this text node in a <1px space, so we just tell it "no"
+    if (dimensions.width >= 1 && width > 0 && width < 1) {
+        return dimensions;
+    }
+    const textWrap = node.style?.textWrap ?? "wrap";
+    const wrappedText = wrapText(text, width, textWrap);
+    return measureText(wrappedText);
+};
+/**
+ * Finds the closest Taffy node for a given DOM node.
+ * Traverses up the DOM tree until a node with a Taffy node is found.
+ *
+ * @param node - The DOM node to start searching from.
+ * @returns The closest Taffy node or undefined if not found.
+ */
+const findClosestTaffyNode = (node) => {
+    if (!node?.parentNode) {
+        return undefined;
+    }
+    return node.taffyNode ?? findClosestTaffyNode(node.parentNode);
+};
+/**
+ * Marks a node as dirty, triggering a re-measure of its layout.
+ *
+ * @param node - The DOM node to mark as dirty.
+ */
+const markNodeAsDirty = (node) => {
+    // Mark closest Taffy node as dirty to measure text dimensions again
+    const taffyNode = findClosestTaffyNode(node);
+    taffyNode?.tree.markDirty(taffyNode.id);
+};
+/**
+ * Sets the value of a text node.
+ *
+ * @param node - The text node.
+ * @param text - The new text value.
+ */
+export const setTextNodeValue = (node, text) => {
+    if (typeof text !== "string") {
+        text = String(text);
+    }
+    node.nodeValue = text;
+    markNodeAsDirty(node);
+};

package/lib/get-max-width.d.ts

@@ -0,0 +1,9 @@
+import { type Layout } from "taffy-layout";
+/**
+ * Calculates the maximum available width for content within a Taffy layout.
+ * It subtracts padding and borders from the total width of the element.
+ *
+ * @param layout - The Taffy layout object with width, padding, and border info.
+ * @returns The maximum width available for content.
+ */
+export declare const getMaxWidth: (layout: Layout) => number;