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

package/src/components/Text.tsx

@@ -0,0 +1,144 @@
+import { useContext, type ReactNode } from "react";
+
+import { chalk, type ForegroundColorName } from "../ansi/chalk.ts";
+import { colorize } from "../colorize.ts";
+import { type Styles } from "../styles.ts";
+import { type LiteralUnion } from "../types.ts";
+import { accessibilityContext } from "./AccessibilityContext.ts";
+import { backgroundContext } from "./BackgroundContext.ts";
+
+export type Props = {
+  /**
+	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. Ink 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 Ink to wrap or truncate text if its width is larger than the container. If `wrap` is passed (the default), Ink will wrap text and split it into multiple lines. If `hard` is passed, Ink will fill each line to the full column width, breaking words as necessary. If `truncate-*` is passed, Ink will truncate text instead, resulting in one line of text with the rest cut off.
+	*/
+  readonly wrap?: Styles["textWrap"];
+
+  readonly children?: ReactNode;
+};
+
+/**
+This component can display text and change its style to make it bold, underlined, italic, or strikethrough.
+*/
+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,
+}: Props) {
+  const { isScreenReaderEnabled } = useContext(accessibilityContext);
+  const inheritedBackgroundColor = useContext(backgroundContext);
+  const childrenOrAriaLabel = isScreenReaderEnabled && ariaLabel ? ariaLabel : children;
+
+  if (childrenOrAriaLabel === undefined || childrenOrAriaLabel === null) {
+    return null;
+  }
+
+  const transform = (text: string): string => {
+    if (dimColor) {
+      text = chalk.dim(text);
+    }
+
+    if (color) {
+      text = colorize(text, color, "foreground");
+    }
+
+    // Use explicit backgroundColor if provided, otherwise use inherited from parent Box
+    const effectiveBackgroundColor = backgroundColor ?? inheritedBackgroundColor;
+    if (effectiveBackgroundColor) {
+      text = colorize(text, effectiveBackgroundColor, "background");
+    }
+
+    if (bold) {
+      text = chalk.bold(text);
+    }
+
+    if (italic) {
+      text = chalk.italic(text);
+    }
+
+    if (underline) {
+      text = chalk.underline(text);
+    }
+
+    if (strikethrough) {
+      text = chalk.strikethrough(text);
+    }
+
+    if (inverse) {
+      text = chalk.inverse(text);
+    }
+
+    return text;
+  };
+
+  if (isScreenReaderEnabled && ariaHidden) {
+    return null;
+  }
+
+  return (
+    <ink-text
+      style={{ flexGrow: 0, flexShrink: 1, flexDirection: "row", textWrap: wrap }}
+      internal_transform={transform}
+    >
+      {childrenOrAriaLabel}
+    </ink-text>
+  );
+}

package/src/components/Transform.tsx

@@ -0,0 +1,37 @@
+import { useContext, type ReactNode } from "react";
+
+import { accessibilityContext } from "./AccessibilityContext.ts";
+
+export type Props = {
+  /**
+	Screen-reader-specific text to output. If this is set, all children will be ignored.
+	*/
+  readonly accessibilityLabel?: string;
+
+  /**
+	Function that transforms children output. It accepts children and must return transformed children as well. Note that when children use `<Text>` styling props (e.g. `color`, `bold`), the string will contain ANSI escape codes.
+	*/
+  readonly transform: (children: string, index: number) => string;
+
+  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.
+*/
+export function Transform({ children, transform, accessibilityLabel }: Props) {
+  const { isScreenReaderEnabled } = useContext(accessibilityContext);
+
+  if (children === undefined || children === null) {
+    return null;
+  }
+
+  return (
+    <ink-text
+      style={{ flexGrow: 0, flexShrink: 1, flexDirection: "row" }}
+      internal_transform={transform}
+    >
+      {isScreenReaderEnabled && accessibilityLabel ? accessibilityLabel : children}
+    </ink-text>
+  );
+}

package/src/cursor-position.ts

@@ -0,0 +1,103 @@
+import { ansiEscapes } from "./ansi/escapes.ts";
+
+export type CursorPosition = {
+  x: number;
+  y: number;
+};
+
+export const showCursorEscape = ansiEscapes.cursorShow;
+export const hideCursorEscape = ansiEscapes.cursorHide;
+
+/**
+Compare two cursor positions. Returns true if they differ.
+*/
+export const cursorPositionChanged = (
+  a: CursorPosition | undefined,
+  b: CursorPosition | undefined,
+): boolean => a?.x !== b?.x || a?.y !== b?.y;
+
+/**
+Build escape sequence to move cursor from the bottom of the output to the target position and show it.
+
+`bottomLine` is the row the renderer left the cursor on, counted from the top of the output.
+That is always `lines.length - 1` for `lines = str.split('\n')`, whether or not the output ends
+with a newline:
+
+- With a trailing newline, `split` yields one extra empty element and the renderer stops just
+  past the last visible line — which is `lines.length - 1`.
+- Without one, there is no extra element and the renderer deliberately stops on the last visible
+  line instead of moving past it — which is also `lines.length - 1`.
+
+This is the same row basis `buildReturnToBottom` measures from, so the two stay in step.
+*/
+export const buildCursorSuffix = (
+  bottomLine: number,
+  cursorPosition: CursorPosition | undefined,
+): string => {
+  if (!cursorPosition) {
+    return "";
+  }
+
+  const moveUp = bottomLine - cursorPosition.y;
+  return (
+    (moveUp > 0 ? ansiEscapes.cursorUp(moveUp) : "") +
+    ansiEscapes.cursorTo(cursorPosition.x) +
+    showCursorEscape
+  );
+};
+
+/**
+Build escape sequence to move cursor from previousCursorPosition back to the bottom of output.
+This must be done before eraseLines or any operation that assumes cursor is at the bottom.
+*/
+export const buildReturnToBottom = (
+  previousLineCount: number,
+  previousCursorPosition: CursorPosition | undefined,
+): string => {
+  if (!previousCursorPosition) {
+    return "";
+  }
+
+  // PreviousLineCount is the raw `split('\n')` length, so `previousLineCount - 1`
+  // is the row the cursor was left on regardless of a trailing newline — the same
+  // basis `buildCursorSuffix` takes as its `bottomLine`.
+  const down = previousLineCount - 1 - previousCursorPosition.y;
+  return (down > 0 ? ansiEscapes.cursorDown(down) : "") + ansiEscapes.cursorTo(0);
+};
+
+export type CursorOnlyInput = {
+  cursorWasShown: boolean;
+  previousLineCount: number;
+  previousCursorPosition: CursorPosition | undefined;
+  cursorPosition: CursorPosition | undefined;
+};
+
+/**
+Build the escape sequence for cursor-only updates (output unchanged, cursor moved).
+Hides cursor if it was previously shown, returns to bottom, then repositions.
+
+`buildReturnToBottom` has just placed the cursor on row `previousLineCount - 1`, so the
+suffix measures from there rather than recomputing the row from the output.
+*/
+export const buildCursorOnlySequence = (input: CursorOnlyInput): string => {
+  const hidePrefix = input.cursorWasShown ? hideCursorEscape : "";
+  const returnToBottom = buildReturnToBottom(input.previousLineCount, input.previousCursorPosition);
+  const cursorSuffix = buildCursorSuffix(input.previousLineCount - 1, input.cursorPosition);
+  return hidePrefix + returnToBottom + cursorSuffix;
+};
+
+/**
+Build the prefix that hides cursor and returns to bottom before erasing or rewriting.
+Returns empty string if cursor was not shown.
+*/
+export const buildReturnToBottomPrefix = (
+  cursorWasShown: boolean,
+  previousLineCount: number,
+  previousCursorPosition: CursorPosition | undefined,
+): string => {
+  if (!cursorWasShown) {
+    return "";
+  }
+
+  return hideCursorEscape + buildReturnToBottom(previousLineCount, previousCursorPosition);
+};

package/src/devtools-window-polyfill.ts

@@ -0,0 +1,73 @@
+// Ignoring missing types error to avoid adding another dependency for this hack to work
+import ws from "ws";
+
+// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+const customGlobal = globalThis as any;
+
+// These things must exist before importing `react-devtools-core`
+// Using ||= intentionally to set falsy values, not just null/undefined
+
+// eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
+customGlobal.WebSocket ||= ws;
+
+// eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
+customGlobal.window ||= globalThis;
+
+// eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
+customGlobal.self ||= globalThis;
+
+// Filter out Ink's internal components from devtools for a cleaner view.
+// Also, ince `react-devtools-shared` package isn't published on npm, we can't
+// use its types, that's why there are hard-coded values in `type` fields below.
+// See https://github.com/facebook/react/blob/edf6eac8a181860fd8a2d076a43806f1237495a1/packages/react-devtools-shared/src/types.js#L24
+customGlobal.window.__REACT_DEVTOOLS_COMPONENT_FILTERS__ = [
+  {
+    // ComponentFilterElementType
+    type: 1,
+    // ElementTypeHostComponent
+    value: 7,
+    isEnabled: true,
+  },
+  {
+    // ComponentFilterDisplayName
+    type: 2,
+    value: "InternalApp",
+    isEnabled: true,
+    isValid: true,
+  },
+  {
+    // ComponentFilterDisplayName
+    type: 2,
+    value: "InternalAppContext",
+    isEnabled: true,
+    isValid: true,
+  },
+  {
+    // ComponentFilterDisplayName
+    type: 2,
+    value: "InternalStdoutContext",
+    isEnabled: true,
+    isValid: true,
+  },
+  {
+    // ComponentFilterDisplayName
+    type: 2,
+    value: "InternalStderrContext",
+    isEnabled: true,
+    isValid: true,
+  },
+  {
+    // ComponentFilterDisplayName
+    type: 2,
+    value: "InternalStdinContext",
+    isEnabled: true,
+    isValid: true,
+  },
+  {
+    // ComponentFilterDisplayName
+    type: 2,
+    value: "InternalFocusContext",
+    isEnabled: true,
+    isValid: true,
+  },
+];

package/src/devtools.ts

@@ -0,0 +1,43 @@
+/* eslint-disable import-x/order */
+
+// eslint-disable-next-line import-x/no-unassigned-import
+import "./devtools-window-polyfill.ts";
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-expect-error
+import devtools from "react-devtools-core";
+import WebSocket from "ws";
+
+const isDevToolsReachable = async (): Promise<boolean> =>
+  new Promise((resolve) => {
+    const socket = new WebSocket("ws://localhost:8097");
+
+    const timeout = setTimeout(() => {
+      socket.terminate();
+      resolve(false);
+    }, 2000);
+    // Don't let the timeout keep the process alive on its own
+    timeout.unref();
+
+    socket.on("open", () => {
+      clearTimeout(timeout);
+      socket.terminate();
+      resolve(true);
+    });
+
+    socket.on("error", () => {
+      clearTimeout(timeout);
+      socket.terminate();
+      resolve(false);
+    });
+  });
+
+if (await isDevToolsReachable()) {
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+  (devtools as any).initialize();
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+  (devtools as any).connectToDevTools();
+} else {
+  console.warn(
+    "SIGIL_DEV is set to true, but the React DevTools server is not running. Start it with:\n\n$ npx react-devtools\n",
+  );
+}

package/src/dom.ts

@@ -0,0 +1,292 @@
+import { measureText } from "./measure-text.ts";
+import { type OutputTransformer } from "./render-node-to-output.ts";
+import { squashTextNodes } from "./squash-text-nodes.ts";
+import { type Styles } from "./styles.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_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;
+    };
+  };
+
+  // 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(measureTextNode.bind(null, node));
+  }
+
+  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";
+  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/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)
+  );
+};