@alchemy.run/sigil 0.0.0-alpha.1 → 0.0.0-alpha.10

package/src/dom.ts

@@ -0,0 +1,301 @@
+import { measureText } from "#/measure-text.ts";
+import type { SemanticTextStyle } from "#/semantic-text-style.ts";
+import { squashTextNodes } from "#/squash-text-nodes.ts";
+import { type Styles } from "#/styles.ts";
+import { type AnsiTransformer } from "#/transform-adapter.ts";
+import { wrapText } from "#/wrap-text.ts";
+import { Yoga, type Node as YogaNode } from "#/yoga/index.ts";
+
+type InkNode = {
+  parentNode: DOMElement | undefined;
+  yogaNode?: YogaNode;
+  internal_static?: boolean;
+  style: Styles;
+};
+
+type LayoutListener = () => void;
+
+export type TextName = "#text";
+export type ElementNames = "ink-root" | "ink-box" | "ink-text" | "ink-virtual-text";
+
+export type NodeNames = ElementNames | TextName;
+
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export type DOMElement = {
+  nodeName: ElementNames;
+  attributes: Record<string, DOMNodeAttribute>;
+  childNodes: DOMNode[];
+  internal_ansi?: boolean;
+  internal_transform?: AnsiTransformer;
+  internal_textStyle?: SemanticTextStyle;
+
+  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;
+    };
+  };
+
+  // Internal properties
+  isStaticDirty?: boolean;
+  staticNode?: DOMElement;
+  // Tracks the previous commit's `staticNode` so the reconciler can detect identity changes (mount, unmount, key-driven remount) and reset `fullStaticOutput`.
+  previousStaticNode?: DOMElement;
+  onComputeLayout?: () => void;
+  onRender?: () => void;
+  onImmediateRender?: () => void;
+  onStaticChange?: () => void;
+  internal_layoutListeners?: Set<LayoutListener>;
+} & InkNode;
+
+export type TextNode = {
+  nodeName: TextName;
+  nodeValue: string;
+} & InkNode;
+
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export type DOMNode<T = { nodeName: NodeNames }> = T extends {
+  nodeName: infer U;
+}
+  ? U extends "#text"
+    ? TextNode
+    : DOMElement
+  : never;
+
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export type DOMNodeAttribute = boolean | string | number;
+
+export const createNode = (nodeName: ElementNames): DOMElement => {
+  const node: DOMElement = {
+    nodeName,
+    style: {},
+    attributes: {},
+    childNodes: [],
+    parentNode: undefined,
+    yogaNode: nodeName === "ink-virtual-text" ? undefined : Yoga.Node.create(),
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    internal_accessibility: {},
+  };
+
+  if (nodeName === "ink-text") {
+    node.yogaNode?.setMeasureFunc((width) => measureTextNode(node, width));
+  }
+
+  return node;
+};
+
+export const appendChildNode = (node: DOMElement, childNode: DOMElement): void => {
+  if (childNode.parentNode) {
+    removeChildNode(childNode.parentNode, childNode);
+  }
+
+  childNode.parentNode = node;
+  node.childNodes.push(childNode);
+
+  if (childNode.yogaNode) {
+    node.yogaNode?.insertChild(childNode.yogaNode, node.yogaNode.getChildCount());
+  }
+
+  if (node.nodeName === "ink-text" || node.nodeName === "ink-virtual-text") {
+    markNodeAsDirty(node);
+  }
+};
+
+export const insertBeforeNode = (
+  node: DOMElement,
+  newChildNode: DOMNode,
+  beforeChildNode: DOMNode,
+): void => {
+  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.yogaNode) {
+      node.yogaNode?.insertChild(newChildNode.yogaNode, index);
+    }
+  } else {
+    node.childNodes.push(newChildNode);
+
+    if (newChildNode.yogaNode) {
+      node.yogaNode?.insertChild(newChildNode.yogaNode, node.yogaNode.getChildCount());
+    }
+  }
+
+  if (node.nodeName === "ink-text" || node.nodeName === "ink-virtual-text") {
+    markNodeAsDirty(node);
+  }
+};
+
+export const removeChildNode = (node: DOMElement, removeNode: DOMNode): void => {
+  if (removeNode.yogaNode) {
+    removeNode.parentNode?.yogaNode?.removeChild(removeNode.yogaNode);
+  }
+
+  removeNode.parentNode = undefined;
+
+  const index = node.childNodes.indexOf(removeNode);
+  if (index >= 0) {
+    node.childNodes.splice(index, 1);
+  }
+
+  if (node.nodeName === "ink-text" || node.nodeName === "ink-virtual-text") {
+    markNodeAsDirty(node);
+  }
+};
+
+const nullifyYogaNodes = (node: DOMNode): void => {
+  node.yogaNode = undefined;
+
+  if (node.nodeName !== "#text") {
+    for (const childNode of node.childNodes) {
+      nullifyYogaNodes(childNode);
+    }
+  }
+};
+
+/**
+Detach a removed subtree from the layout engine: drop the measure callback
+and null the `yogaNode` reference on every DOM node within it.
+
+Nulling the references makes every `?.yogaNode` guard in the codebase
+effective for removed nodes, turns lingering access into a safe no-op (see
+QwenLM/qwen-code#6820), and lets the garbage collector reclaim the Yoga
+tree along with its closures.
+*/
+export const detachYogaSubtree = (removeNode: DOMNode): void => {
+  removeNode.yogaNode?.unsetMeasureFunc();
+  nullifyYogaNodes(removeNode);
+};
+
+export const setAttribute = (node: DOMElement, key: string, value: DOMNodeAttribute): void => {
+  if (key === "internal_accessibility") {
+    node.internal_accessibility = value as DOMElement["internal_accessibility"];
+    return;
+  }
+
+  node.attributes[key] = value;
+};
+
+export const setStyle = (node: DOMNode, style?: Styles): void => {
+  // Rendering code assumes style is always an object.
+  node.style = style ?? {};
+};
+
+export const createTextNode = (text: string): TextNode => {
+  const node: TextNode = {
+    nodeName: "#text",
+    nodeValue: text,
+    yogaNode: undefined,
+    parentNode: undefined,
+    style: {},
+  };
+
+  setTextNodeValue(node, text);
+
+  return node;
+};
+
+const measureTextNode = function (node: DOMNode, width: number): { width: number; height: number } {
+  const text = node.nodeName === "#text" ? node.nodeValue : squashTextNodes(node);
+
+  const dimensions = measureText(text);
+
+  // Text fits into container, no need to wrap
+  if (dimensions.width <= width) {
+    return dimensions;
+  }
+
+  // This is happening when <Box> is shrinking child nodes and Yoga asks
+  // if we can fit this text node in a <1px space, so we just tell Yoga "no"
+  if (dimensions.width >= 1 && width > 0 && width < 1) {
+    return dimensions;
+  }
+
+  const textWrap = node.style?.textWrap ?? "wrap";
+
+  // `none` keeps the intrinsic dimensions and overflows the container.
+  if (textWrap === "none") {
+    return dimensions;
+  }
+
+  const wrappedText = wrapText(text, width, textWrap);
+
+  return measureText(wrappedText);
+};
+
+const findClosestYogaNode = (node?: DOMNode): YogaNode | undefined => {
+  if (!node?.parentNode) {
+    return;
+  }
+
+  return node.yogaNode ?? findClosestYogaNode(node.parentNode);
+};
+
+const markNodeAsDirty = (node?: DOMNode): void => {
+  // Mark closest Yoga node as dirty to measure text dimensions again
+  const yogaNode = findClosestYogaNode(node);
+  yogaNode?.markDirty();
+};
+
+export const setTextNodeValue = (node: TextNode, text: string): void => {
+  if (typeof text !== "string") {
+    text = String(text);
+  }
+
+  node.nodeValue = text;
+  markNodeAsDirty(node);
+};
+
+export const addLayoutListener = (rootNode: DOMElement, listener: LayoutListener): (() => void) => {
+  if (rootNode.nodeName !== "ink-root") {
+    return () => {};
+  }
+
+  rootNode.internal_layoutListeners ??= new Set();
+  rootNode.internal_layoutListeners.add(listener);
+
+  return () => {
+    rootNode.internal_layoutListeners?.delete(listener);
+  };
+};
+
+export const emitLayoutListeners = (rootNode: DOMElement): void => {
+  if (rootNode.nodeName !== "ink-root" || !rootNode.internal_layoutListeners) {
+    return;
+  }
+
+  for (const listener of rootNode.internal_layoutListeners) {
+    listener();
+  }
+};

package/src/env.ts

@@ -0,0 +1,12 @@
+// Every modern CI provider sets CI=1 (or CI=true), so any non-empty value
+export const isInCi = Boolean(process.env.CI);
+
+export const isSigilDev = process.env.SIGIL_DEV === "true";
+
+export const isScreenReader = process.env.SIGIL_SCREEN_READER === "true";
+
+export const isWindows = process.platform === "win32";
+
+export const isMacos = process.platform === "darwin";
+
+export const isTty = (stream: NodeJS.ReadableStream) => "isTTY" in stream && stream.isTTY === true;

package/src/get-max-width.ts

@@ -0,0 +1,11 @@
+import { Yoga, type Node as YogaNode } from "#/yoga/index.ts";
+
+export const getMaxWidth = (yogaNode: YogaNode) => {
+  return (
+    yogaNode.getComputedWidth() -
+    yogaNode.getComputedPadding(Yoga.EDGE_LEFT) -
+    yogaNode.getComputedPadding(Yoga.EDGE_RIGHT) -
+    yogaNode.getComputedBorder(Yoga.EDGE_LEFT) -
+    yogaNode.getComputedBorder(Yoga.EDGE_RIGHT)
+  );
+};

package/src/global.d.ts

@@ -0,0 +1,38 @@
+import { type ReactNode, type Key, type Ref } from "react";
+
+import { type DOMElement } from "#/dom.ts";
+import type { SemanticTextStyle } from "#/semantic-text-style.ts";
+import { type Styles } from "#/styles.ts";
+
+declare module "react" {
+  namespace JSX {
+    // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+    interface IntrinsicElements {
+      "ink-box": Ink.Box;
+      "ink-text": Ink.Text;
+    }
+  }
+}
+
+declare namespace Ink {
+  type Box = {
+    internal_static?: boolean;
+    children?: ReactNode;
+    key?: Key;
+    ref?: Ref<DOMElement>;
+    style?: Omit<Styles, "textWrap">;
+    internal_accessibility?: DOMElement["internal_accessibility"];
+  };
+
+  type Text = {
+    children?: ReactNode;
+    key?: Key;
+    style?: Styles;
+
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    internal_ansi?: boolean;
+    internal_transform?: (children: string, index: number) => string;
+    internal_textStyle?: SemanticTextStyle;
+    internal_accessibility?: DOMElement["internal_accessibility"];
+  };
+}

package/src/glyphs.ts

@@ -0,0 +1,99 @@
+// Derived from `cli-boxes` (MIT, Sindre Sorhus).
+export const BOXES = {
+  single: {
+    topLeft: "┌",
+    top: "─",
+    topRight: "┐",
+    right: "│",
+    bottomRight: "┘",
+    bottom: "─",
+    bottomLeft: "└",
+    left: "│",
+  },
+  double: {
+    topLeft: "╔",
+    top: "═",
+    topRight: "╗",
+    right: "║",
+    bottomRight: "╝",
+    bottom: "═",
+    bottomLeft: "╚",
+    left: "║",
+  },
+  round: {
+    topLeft: "╭",
+    top: "─",
+    topRight: "╮",
+    right: "│",
+    bottomRight: "╯",
+    bottom: "─",
+    bottomLeft: "╰",
+    left: "│",
+  },
+  bold: {
+    topLeft: "┏",
+    top: "━",
+    topRight: "┓",
+    right: "┃",
+    bottomRight: "┛",
+    bottom: "━",
+    bottomLeft: "┗",
+    left: "┃",
+  },
+  singleDouble: {
+    topLeft: "╓",
+    top: "─",
+    topRight: "╖",
+    right: "║",
+    bottomRight: "╜",
+    bottom: "─",
+    bottomLeft: "╙",
+    left: "║",
+  },
+  doubleSingle: {
+    topLeft: "╒",
+    top: "═",
+    topRight: "╕",
+    right: "│",
+    bottomRight: "╛",
+    bottom: "═",
+    bottomLeft: "╘",
+    left: "│",
+  },
+  classic: {
+    topLeft: "+",
+    top: "-",
+    topRight: "+",
+    right: "|",
+    bottomRight: "+",
+    bottom: "-",
+    bottomLeft: "+",
+    left: "|",
+  },
+  arrow: {
+    topLeft: "↘",
+    top: "↓",
+    topRight: "↙",
+    right: "←",
+    bottomRight: "↖",
+    bottom: "↑",
+    bottomLeft: "↗",
+    left: "→",
+  },
+} as const;
+
+export type BoxStyle = keyof typeof BOXES;
+
+/**
+The set of glyphs making up a box border, for custom `borderStyle` objects.
+*/
+export type BoxGlyphs = {
+  readonly topLeft: string;
+  readonly top: string;
+  readonly topRight: string;
+  readonly right: string;
+  readonly bottomRight: string;
+  readonly bottom: string;
+  readonly bottomLeft: string;
+  readonly left: string;
+};

package/src/hooks/use-animation.ts

@@ -0,0 +1,142 @@
+import { useState, useLayoutEffect, useRef, useCallback, useContext } from "react";
+
+import { animationContext as AnimationContext } from "#/components/AnimationContext.ts";
+
+const defaultAnimationInterval = 100;
+const maximumTimerInterval = 2_147_483_647;
+const zeroAnimState = { frame: 0, time: 0, delta: 0 };
+
+type Options = {
+  /**
+	Time between ticks in milliseconds.
+
+	@default 100
+	*/
+  readonly interval?: number;
+
+  /**
+	Whether the animation is running. When set to `false`, the animation stops. When toggled back to `true`, all values reset to `0`.
+
+	@default true
+	*/
+  readonly isActive?: boolean;
+};
+
+export type AnimationResult = {
+  /**
+	Discrete counter that increments by 1 each interval. Useful for indexed sequences like spinner frames.
+	*/
+  readonly frame: number;
+
+  /**
+	Total elapsed time in milliseconds since the animation started or was last reset. Useful for continuous math-based animations like sine waves: `Math.sin(time / 1000 * Math.PI * 2)`.
+	*/
+  readonly time: number;
+
+  /**
+	Time in milliseconds since the previous rendered tick. Accounts for throttled renders. Useful for physics-based or velocity-driven motion: `position += speed * delta`.
+	*/
+  readonly delta: number;
+
+  /**
+	Resets `frame`, `time`, and `delta` to `0` and restarts timing from the current moment. Useful for one-shot animations triggered by events.
+	*/
+  readonly reset: () => void;
+};
+
+/**
+A React hook that drives animations. Returns a frame counter, elapsed time, frame delta, and a reset function. All animations share a single timer internally, so multiple animated components consolidate into one render cycle.
+
+@example
+```
+import {Text, useAnimation} from 'ink';
+
+const Spinner = () => {
+	const {frame} = useAnimation({interval: 80});
+	const characters = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+
+	return <Text>{characters[frame % characters.length]}</Text>;
+};
+```
+*/
+export function useAnimation(options?: Options): AnimationResult {
+  const { interval = defaultAnimationInterval, isActive = true } = options ?? {};
+  const safeInterval = normalizeAnimationInterval(interval);
+  const { subscribe, renderThrottleMs } = useContext(AnimationContext);
+  const [resetKey, setResetKey] = useState(0);
+  const [animState, setAnimState] = useState(zeroAnimState);
+  const nextRenderTimeRef = useRef(0);
+  const lastRenderTimeRef = useRef(0);
+  const previousOptionsRef = useRef({ isActive, safeInterval, resetKey });
+  const previousOptions = previousOptionsRef.current;
+  const shouldReset =
+    isActive &&
+    (safeInterval !== previousOptions.safeInterval ||
+      !previousOptions.isActive ||
+      resetKey !== previousOptions.resetKey);
+
+  const reset = useCallback(() => {
+    setResetKey((k) => k + 1);
+  }, []);
+
+  useLayoutEffect(() => {
+    if (!isActive) {
+      return;
+    }
+
+    // Reset to zero immediately so any render that occurs between this
+    // effect commit and the first tick shows zeros, not stale values.
+    // On initial mount this is a no-op: Object.is bails out because the
+    // state was initialized with the same zeroAnimState reference.
+    setAnimState(zeroAnimState);
+
+    let startTime = 0;
+
+    const { startTime: subscriberStartTime, unsubscribe } = subscribe((currentTime) => {
+      const isThrottled = renderThrottleMs > 0 && currentTime < nextRenderTimeRef.current;
+
+      if (isThrottled) {
+        // Coalesce intermediate ticks while Ink is inside the current
+        // render-throttle window; the next allowed render will jump
+        // straight to the latest elapsed values.
+        return;
+      }
+
+      const elapsed = currentTime - startTime;
+      const nextDelta = currentTime - lastRenderTimeRef.current;
+
+      lastRenderTimeRef.current = currentTime;
+      nextRenderTimeRef.current = currentTime + renderThrottleMs;
+      setAnimState({
+        frame: Math.floor(elapsed / safeInterval),
+        time: elapsed,
+        delta: nextDelta,
+      });
+    }, safeInterval);
+    // Use the scheduler's start time instead of sampling our own clock so the
+    // first delivered tick cannot start one frame late.
+    startTime = subscriberStartTime;
+    lastRenderTimeRef.current = subscriberStartTime;
+    nextRenderTimeRef.current = startTime + renderThrottleMs;
+
+    return unsubscribe;
+  }, [safeInterval, isActive, subscribe, renderThrottleMs, resetKey]);
+
+  useLayoutEffect(() => {
+    previousOptionsRef.current = { isActive, safeInterval, resetKey };
+  }, [isActive, safeInterval, resetKey]);
+
+  if (shouldReset) {
+    return { ...zeroAnimState, reset };
+  }
+
+  return { ...animState, reset };
+}
+
+function normalizeAnimationInterval(interval: number): number {
+  if (!Number.isFinite(interval)) {
+    return defaultAnimationInterval;
+  }
+
+  return Math.min(maximumTimerInterval, Math.max(1, interval));
+}

package/src/hooks/use-app.ts

@@ -0,0 +1,8 @@
+import { useContext } from "react";
+
+import { AppContext } from "#/components/AppContext.ts";
+
+/**
+A React hook that returns app lifecycle methods like `exit()` and `waitUntilRenderFlush()`.
+*/
+export const useApp = () => useContext(AppContext);