@alchemy.run/sigil 0.0.0-alpha.3 → 0.0.0-alpha.5

package/src/components/Box.tsx

@@ -1,13 +1,11 @@
 /** @jsxImportSource react */
-import { forwardRef, useContext, type PropsWithChildren } from "react";
+import { useContext, type PropsWithChildren, type Ref } from "react";
 
-import { type DOMElement } from "../dom.ts";
-import { type Styles } from "../styles.ts";
-import { type Except } from "../types.ts";
-import { accessibilityContext } from "./AccessibilityContext.ts";
-import { backgroundContext } from "./BackgroundContext.ts";
+import { accessibilityContext } from "#/components/AccessibilityContext.ts";
+import { type DOMElement } from "#/dom.ts";
+import { type Styles } from "#/styles.ts";
 
-export type Props = Except<Styles, "textWrap"> & {
+export type Props = Omit<Styles, "textWrap"> & {
   /**
 	A label for the element for screen readers.
 	*/
@@ -60,58 +58,43 @@ export type Props = Except<Styles, "textWrap"> & {
 /**
 `<Box>` is an essential Ink component to build your layout. It's like `<div style="display: flex">` in the browser.
 */
-export const Box = forwardRef<DOMElement, PropsWithChildren<Props>>(
-  (
-    {
-      children,
-      backgroundColor,
-      "aria-label": ariaLabel,
-      "aria-hidden": ariaHidden,
-      "aria-role": role,
-      "aria-state": ariaState,
-      ...style
-    },
-    ref,
-  ) => {
-    const { isScreenReaderEnabled } = useContext(accessibilityContext);
-    const label = ariaLabel ? <ink-text>{ariaLabel}</ink-text> : undefined;
-    if (isScreenReaderEnabled && ariaHidden) {
-      return null;
-    }
+export function Box({
+  children,
+  ref,
+  backgroundColor,
+  "aria-label": ariaLabel,
+  "aria-hidden": ariaHidden,
+  "aria-role": role,
+  "aria-state": ariaState,
+  ...style
+}: PropsWithChildren<Props> & { readonly ref?: Ref<DOMElement> }) {
+  const { isScreenReaderEnabled } = useContext(accessibilityContext);
+  const label = ariaLabel ? <ink-text>{ariaLabel}</ink-text> : undefined;
+  if (isScreenReaderEnabled && ariaHidden) {
+    return null;
+  }
 
-    const boxElement = (
-      <ink-box
-        ref={ref}
-        style={{
-          flexWrap: "nowrap",
-          flexDirection: "row",
-          flexGrow: 0,
-          flexShrink: 1,
-          ...style,
-          backgroundColor,
-          overflowX: style.overflowX ?? style.overflow ?? "visible",
-          overflowY: style.overflowY ?? style.overflow ?? "visible",
-        }}
-        internal_accessibility={{
-          role,
-          state: ariaState,
-        }}
-      >
-        {isScreenReaderEnabled && label ? label : children}
-      </ink-box>
-    );
+  const boxElement = (
+    <ink-box
+      ref={ref}
+      style={{
+        flexWrap: "nowrap",
+        flexDirection: "row",
+        flexGrow: 0,
+        flexShrink: 1,
+        ...style,
+        backgroundColor,
+        overflowX: style.overflowX ?? style.overflow ?? "visible",
+        overflowY: style.overflowY ?? style.overflow ?? "visible",
+      }}
+      internal_accessibility={{
+        role,
+        state: ariaState,
+      }}
+    >
+      {isScreenReaderEnabled && label ? label : children}
+    </ink-box>
+  );
 
-    // If this Box has a background color, provide it to children via context
-    if (backgroundColor) {
-      return (
-        <backgroundContext.Provider value={backgroundColor}>
-          {boxElement}
-        </backgroundContext.Provider>
-      );
-    }
-
-    return boxElement;
-  },
-);
-
-Box.displayName = "Box";
+  return boxElement;
+}

package/src/components/CursorContext.ts

@@ -1,6 +1,6 @@
 import { createContext } from "react";
 
-import { type CursorPosition } from "../log-update.ts";
+import { type CursorPosition } from "#/cursor-position.ts";
 
 export type Props = {
   /**

package/src/components/ErrorBoundary.tsx

@@ -1,7 +1,7 @@
 /** @jsxImportSource react */
 import { PureComponent, type ReactNode } from "react";
 
-import { ErrorOverview } from "./ErrorOverview.tsx";
+import { ErrorOverview } from "#/components/ErrorOverview.tsx";
 
 type Props = {
   readonly children: ReactNode;

package/src/components/ErrorOverview.tsx

@@ -1,11 +1,12 @@
 /** @jsxImportSource react */
-import * as fs from "node:fs";
+
+import { existsSync, readFileSync } from "node:fs";
 import { cwd } from "node:process";
 
-import { codeExcerpt, type CodeExcerpt } from "../code-excerpt.ts";
-import { parseStackLine } from "../parse-stack-line.ts";
-import { Box } from "./Box.tsx";
-import { Text } from "./Text.tsx";
+import { codeExcerpt, type CodeExcerpt } from "#/code-excerpt.ts";
+import { Box } from "#/components/Box.tsx";
+import { Text } from "#/components/Text.tsx";
+import { parseStackLine } from "#/parse-stack-line.ts";
 
 // Error's source file is reported as file:///home/user/file.js
 // This function removes the file://[cwd] part
@@ -25,8 +26,8 @@ export function ErrorOverview({ error }: Props) {
   let lineWidth = 0;
   const stackLineCounts = new Map<string, number>();
 
-  if (filePath && origin?.line && fs.existsSync(filePath)) {
-    const sourceCode = fs.readFileSync(filePath, "utf8");
+  if (filePath && origin?.line && existsSync(filePath)) {
+    const sourceCode = readFileSync(filePath, "utf8");
     excerpt = codeExcerpt(sourceCode, origin.line);
 
     if (excerpt) {

package/src/components/Hyperlink.tsx

@@ -0,0 +1,56 @@
+/** @jsxImportSource react */
+import { type ReactNode } from "react";
+
+import { link } from "#/ansi/escapes.ts";
+import { detectHyperlinkSupport } from "#/capabilities/detect.ts";
+import { Text, type Props as TextProps } from "#/components/Text.tsx";
+import { Transform } from "#/components/Transform.tsx";
+import { useStdout } from "#/hooks/use-stdout.ts";
+
+export type Props = Omit<TextProps, "children"> & {
+  /**
+	The URL the hyperlink points to.
+	*/
+  readonly url: string;
+
+  /**
+	When the terminal does not support OSC 8 hyperlinks, append the URL in
+	parentheses after the text so it stays reachable. Set to `false` to render
+	the text alone.
+
+	@default true
+	*/
+  readonly fallback?: boolean;
+
+  readonly children?: ReactNode;
+};
+
+/**
+A clickable OSC 8 hyperlink — the counterpart to the router's `<Link>`, which
+navigates between screens. On terminals without hyperlink support it falls
+back to `text (url)`.
+
+```tsx
+<Hyperlink url="https://example.com">Documentation</Hyperlink>
+```
+*/
+export function Hyperlink({ url, fallback = true, children, ...textProps }: Props) {
+  const { stdout } = useStdout();
+
+  if (!detectHyperlinkSupport(stdout)) {
+    return (
+      <Text {...textProps}>
+        {children}
+        {fallback ? <Text dimColor> ({url})</Text> : null}
+      </Text>
+    );
+  }
+
+  // OSC 8 sequences are zero-width, so wrapping after layout is safe. The
+  // transform runs per output line, giving every line its own complete pair.
+  return (
+    <Transform transform={(text) => link(text, url)}>
+      <Text {...textProps}>{children}</Text>
+    </Transform>
+  );
+}

package/src/components/Spacer.tsx

@@ -1,5 +1,5 @@
 /** @jsxImportSource react */
-import { Box } from "./Box.tsx";
+import { Box } from "#/components/Box.tsx";
 
 /**
 A flexible space that expands along the major axis of its containing layout.

package/src/components/Static.tsx

@@ -1,7 +1,7 @@
 /** @jsxImportSource react */
 import { useMemo, useState, useLayoutEffect, type ReactNode } from "react";
 
-import { type Styles } from "../styles.ts";
+import { type Styles } from "#/styles.ts";
 
 export type Props<T> = {
   /**

package/src/components/StderrContext.ts

@@ -1,5 +1,3 @@
-import process from "node:process";
-
 import { createContext } from "react";
 
 export type Props = {

package/src/components/StdinContext.ts

@@ -1,5 +1,4 @@
 import { EventEmitter } from "node:events";
-import process from "node:process";
 
 import { createContext } from "react";
 

package/src/components/StdoutContext.ts

@@ -1,8 +1,6 @@
-import process from "node:process";
-
 import { createContext } from "react";
 
-import type { OutputStream } from "../stream.ts";
+import type { OutputStream } from "#/stream.ts";
 
 export type Props = {
   /**

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

@@ -1,12 +1,11 @@
 /** @jsxImportSource react */
 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";
+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 = {
   /**
@@ -22,12 +21,12 @@ export type Props = {
   /**
 	Change text color. Ink uses Chalk under the hood, so all its functionality is supported.
 	*/
-  readonly color?: LiteralUnion<ForegroundColorName, string>;
+  readonly color?: Paint;
 
   /**
 	Same as `color`, but for the background.
 	*/
-  readonly backgroundColor?: LiteralUnion<ForegroundColorName, string>;
+  readonly backgroundColor?: Paint;
 
   /**
 	Dim the color (make it less bright).
@@ -85,49 +84,27 @@ export function Text({
   "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;
+  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) {
@@ -137,7 +114,7 @@ export function Text({
   return (
     <ink-text
       style={{ flexGrow: 0, flexShrink: 1, flexDirection: "row", textWrap: wrap }}
-      internal_transform={transform}
+      internal_textStyle={semanticStyle}
     >
       {childrenOrAriaLabel}
     </ink-text>

package/src/components/Transform.tsx

@@ -1,7 +1,7 @@
 /** @jsxImportSource react */
 import { useContext, type ReactNode } from "react";
 
-import { accessibilityContext } from "./AccessibilityContext.ts";
+import { accessibilityContext } from "#/components/AccessibilityContext.ts";
 
 export type Props = {
   /**
@@ -10,7 +10,7 @@ export type Props = {
   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.
+	Compatibility function that transforms the ANSI serialization of this subtree.
 	*/
   readonly transform: (children: string, index: number) => string;
 

package/src/cursor-position.ts

@@ -1,4 +1,4 @@
-import { ansiEscapes } from "./ansi/escapes.ts";
+import { ansiEscapes } from "#/ansi/escapes.ts";
 
 export type CursorPosition = {
   x: number;

package/src/devtools.ts

@@ -1,41 +1,101 @@
-/* eslint-disable import-x/order */
+import { setTimeout } from "node:timers";
 
-// 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";
+// 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 },
+});
 
-const isDevToolsReachable = async (): Promise<boolean> =>
-  new Promise((resolve) => {
+// 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(() => {
-      socket.terminate();
-      resolve(false);
+      settle(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.addEventListener("open", () => {
+      settle(true);
     });
-
-    socket.on("error", () => {
-      clearTimeout(timeout);
-      socket.terminate();
-      resolve(false);
+    socket.addEventListener("error", () => {
+      settle(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();
+  // @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",

package/src/dom.ts

@@ -1,9 +1,10 @@
-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";
+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;
@@ -24,7 +25,9 @@ export type DOMElement = {
   nodeName: ElementNames;
   attributes: Record<string, DOMNodeAttribute>;
   childNodes: DOMNode[];
-  internal_transform?: OutputTransformer;
+  internal_ansi?: boolean;
+  internal_transform?: AnsiTransformer;
+  internal_textStyle?: SemanticTextStyle;
 
   internal_accessibility?: {
     role?:
@@ -101,7 +104,7 @@ export const createNode = (nodeName: ElementNames): DOMElement => {
   };
 
   if (nodeName === "ink-text") {
-    node.yogaNode?.setMeasureFunc(measureTextNode.bind(null, node));
+    node.yogaNode?.setMeasureFunc((width) => measureTextNode(node, width));
   }
 
   return node;

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

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

package/src/global.d.ts

@@ -1,8 +1,8 @@
 import { type ReactNode, type Key, type Ref } from "react";
 
-import { type DOMElement } from "./dom.ts";
-import { type Styles } from "./styles.ts";
-import { type Except } from "./types.ts";
+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 {
@@ -20,7 +20,7 @@ declare namespace Ink {
     children?: ReactNode;
     key?: Key;
     ref?: Ref<DOMElement>;
-    style?: Except<Styles, "textWrap">;
+    style?: Omit<Styles, "textWrap">;
     internal_accessibility?: DOMElement["internal_accessibility"];
   };
 
@@ -30,7 +30,9 @@ declare namespace Ink {
     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"];
   };
 }