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

package/src/components/TerminalOscContext.ts

@@ -0,0 +1,25 @@
+import { createContext } from "react";
+
+import type { ClipboardSelection, TerminalProgressState } from "#/ansi/osc.ts";
+
+export type TerminalOsc = {
+  readonly publishProgress: (owner: symbol, state: TerminalProgressState, value?: number) => void;
+  readonly copyToClipboard: (text: string, selection?: ClipboardSelection) => void;
+  readonly publishTitle: (owner: symbol, title?: string) => void;
+  readonly setWorkingDirectory: (directory: URL | string) => void;
+  readonly notify: (title: string) => void;
+  readonly setPointerShape: (shape: string) => void;
+};
+
+const noop = () => {};
+
+export const TerminalOscContext = createContext<TerminalOsc>({
+  publishProgress: noop,
+  copyToClipboard: noop,
+  publishTitle: noop,
+  setWorkingDirectory: noop,
+  notify: noop,
+  setPointerShape: noop,
+});
+
+TerminalOscContext.displayName = "InternalTerminalOscContext";

package/src/components/Text.tsx

@@ -0,0 +1,122 @@
+/** @jsxImportSource react */
+import { useContext, type ReactNode } from "react";
+
+import type { Paint } from "#/color/paint.ts";
+import { accessibilityContext } from "#/components/AccessibilityContext.ts";
+import { cellAttributes } from "#/screen/cell.ts";
+import { parseSemanticColor } from "#/semantic-text-style.ts";
+import { type Styles } from "#/styles.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?: Paint;
+
+  /**
+	Same as `color`, but for the background.
+	*/
+  readonly backgroundColor?: Paint;
+
+  /**
+	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. If `none` is passed, the text is neither wrapped nor truncated — it overflows the container (and the screen's nominal width), which is intended for log lines committed to scrollback (e.g. inside `<Static>`), not for live regions.
+	*/
+  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 childrenOrAriaLabel = isScreenReaderEnabled && ariaLabel ? ariaLabel : children;
+
+  if (childrenOrAriaLabel === undefined || childrenOrAriaLabel === null) {
+    return null;
+  }
+
+  const foreground = typeof color === "object" ? color : parseSemanticColor(color);
+  const background =
+    typeof backgroundColor === "object" ? backgroundColor : parseSemanticColor(backgroundColor);
+  const semanticStyle = {
+    ...(foreground ? { foreground } : {}),
+    ...(background ? { background } : {}),
+    ...(color === "" ? { resetForeground: true } : {}),
+    ...(backgroundColor === "" ? { resetBackground: true } : {}),
+    ...(underline ? { underline: "single" as const } : {}),
+    attributes:
+      (dimColor ? cellAttributes.faint : 0) +
+      (bold ? cellAttributes.bold : 0) +
+      (italic ? cellAttributes.italic : 0) +
+      (strikethrough ? cellAttributes.strikethrough : 0) +
+      (inverse ? cellAttributes.inverse : 0),
+  };
+
+  if (isScreenReaderEnabled && ariaHidden) {
+    return null;
+  }
+
+  return (
+    <ink-text
+      style={{ flexGrow: 0, flexShrink: 1, flexDirection: "row", textWrap: wrap }}
+      internal_textStyle={semanticStyle}
+    >
+      {childrenOrAriaLabel}
+    </ink-text>
+  );
+}

package/src/components/Transform.tsx

@@ -0,0 +1,38 @@
+/** @jsxImportSource react */
+import { useContext, type ReactNode } from "react";
+
+import { accessibilityContext } from "#/components/AccessibilityContext.ts";
+
+export type Props = {
+  /**
+	Screen-reader-specific text to output. If this is set, all children will be ignored.
+	*/
+  readonly accessibilityLabel?: string;
+
+  /**
+	Compatibility function that transforms the ANSI serialization of this subtree.
+	*/
+  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/components/VirtualList.tsx

@@ -0,0 +1,128 @@
+/** @jsxImportSource react */
+import { useEffect, useLayoutEffect, useRef, useState, type Key, type ReactNode } from "react";
+
+import { Box } from "#/components/Box.tsx";
+import { addLayoutListener, type DOMElement } from "#/dom.ts";
+import { useVirtualScroll } from "#/hooks/use-virtual-scroll.ts";
+
+export type Props<Item> = {
+  /**
+	Items to window over.
+	*/
+  readonly items: ReadonlyArray<Item>;
+
+  /**
+	Height of an item in rows. It must match what `renderItem` produces for it:
+	the window is computed from these numbers, never from the rendered output.
+	*/
+  readonly itemHeight: (item: Item, index: number) => number;
+
+  /**
+	Render one item. Only items intersecting the viewport are rendered.
+	*/
+  readonly renderItem: (item: Item, index: number) => ReactNode;
+
+  /**
+	React key for an item. Defaults to its index.
+	*/
+  readonly getKey?: (item: Item, index: number) => Key;
+
+  /**
+	Item to keep fully visible. When it changes, the list scrolls as little as
+	necessary to show it.
+	*/
+  readonly focusedIndex?: number;
+
+  /**
+	Viewport height in rows. When omitted the list takes the height of its
+	content and shrinks to whatever space its container leaves: bound an
+	ancestor (`height` or `maxHeight`) and give the siblings that must keep
+	their size `flexShrink={0}`.
+	*/
+  readonly height?: number;
+};
+
+const rootOf = (node: DOMElement | null): DOMElement | undefined => {
+  let current = node;
+  while (current?.parentNode) {
+    current = current.parentNode;
+  }
+  return current?.nodeName === "ink-root" ? current : undefined;
+};
+
+/**
+A vertically windowed list: only the items intersecting the viewport are
+rendered, inside a clipped box that scrolls by whole rows. Items may have
+different heights, and the item at the top edge may be partially visible.
+
+Until the first layout pass has measured the viewport, every item is rendered
+inside the clipped box so the first frame already looks right.
+*/
+export function VirtualList<Item>({
+  items,
+  itemHeight,
+  renderItem,
+  getKey,
+  focusedIndex,
+  height,
+}: Props<Item>) {
+  const ref = useRef<DOMElement>(null);
+  const [measured, setMeasured] = useState<number>();
+
+  const measure = () => {
+    const next = ref.current?.yogaNode?.getComputedHeight();
+    if (next !== undefined) {
+      setMeasured((previous) => (previous === next ? previous : next));
+    }
+  };
+
+  // Yoga has laid out the tree by the time layout effects run, so the height
+  // this box ended up with is readable synchronously after every commit.
+  useLayoutEffect(() => {
+    if (height === undefined) measure();
+  });
+
+  // Sibling-driven changes (a resize, chrome growing) re-layout without
+  // re-rendering this component; follow the root's layout commits for those.
+  useEffect(() => {
+    if (height !== undefined) return;
+    const root = rootOf(ref.current);
+    return root ? addLayoutListener(root, measure) : undefined;
+  });
+
+  const viewportHeight = height ?? measured;
+  const windowed = viewportHeight !== undefined;
+  const window = useVirtualScroll({
+    count: items.length,
+    itemHeight: (index) => itemHeight(items[index]!, index),
+    viewportHeight: viewportHeight ?? 0,
+    // Following the focus against an unmeasured (zero-row) viewport would pin
+    // the item to the top; wait for the real height so it moves minimally.
+    focusedIndex: windowed ? focusedIndex : undefined,
+  });
+  const start = windowed ? window.start : 0;
+  const end = windowed ? window.end : items.length;
+  const offset = windowed ? window.offset : 0;
+
+  return (
+    <Box
+      ref={ref}
+      flexDirection="column"
+      overflowY="hidden"
+      {...(height === undefined
+        ? { height: window.totalHeight, minHeight: 0, flexShrink: 1 }
+        : { height, flexShrink: 0 })}
+    >
+      <Box flexDirection="column" flexShrink={0} marginTop={offset}>
+        {items.slice(start, end).map((item, sliceIndex) => {
+          const index = start + sliceIndex;
+          return (
+            <Box key={getKey ? getKey(item, index) : index} flexDirection="column" flexShrink={0}>
+              {renderItem(item, index)}
+            </Box>
+          );
+        })}
+      </Box>
+    </Box>
+  );
+}

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.ts

@@ -0,0 +1,103 @@
+import { setTimeout } from "node:timers";
+
+// Node 22.4+ ships a stable browser-compatible WebSocket client, so no `ws`
+// dependency is needed. react-devtools-core resolves the constructor via the
+// `window`/`ws` globals defined here.
+Object.defineProperties(globalThis, {
+  ws: { value: WebSocket },
+  window: { value: globalThis },
+  self: { value: globalThis },
+});
+
+// Filter out Ink's internal components from devtools for a cleaner view.
+// Also, since `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
+Object.defineProperty(globalThis, "__REACT_DEVTOOLS_COMPONENT_FILTERS__", {
+  value: [
+    {
+      // 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,
+    },
+  ],
+});
+
+const isDevToolsReachable = () =>
+  new Promise<boolean>((resolve) => {
+    const socket = new WebSocket("ws://localhost:8097");
+
+    const settle = (reachable: boolean) => {
+      clearTimeout(timeout);
+      socket.close();
+      resolve(reachable);
+    };
+
+    const timeout = setTimeout(() => {
+      settle(false);
+    }, 2000);
+    // Don't let the timeout keep the process alive on its own
+    timeout.unref();
+
+    socket.addEventListener("open", () => {
+      settle(true);
+    });
+    socket.addEventListener("error", () => {
+      settle(false);
+    });
+  });
+
+if (await isDevToolsReachable()) {
+  // @ts-expect-error: react-devtools-core is not typed
+  const devtools = await import("react-devtools-core");
+  devtools.initialize();
+  devtools.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",
+  );
+}