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

package/src/render-background.ts

@@ -0,0 +1,59 @@
+import { samplePaint } from "#/color/sample.ts";
+import { type DOMNode } from "#/dom.ts";
+import type { Canvas } from "#/screen/canvas.ts";
+import { cellAttributes, createCell } from "#/screen/index.ts";
+
+export const renderBackground = (x: number, y: number, node: DOMNode, output: Canvas): void => {
+  if (node.style.backgroundColor === undefined) {
+    return;
+  }
+
+  const width = node.yogaNode!.getComputedWidth();
+  const height = node.yogaNode!.getComputedHeight();
+
+  // Calculate the actual content area considering borders
+  const leftBorderWidth = node.style.borderStyle && node.style.borderLeft !== false ? 1 : 0;
+  const rightBorderWidth = node.style.borderStyle && node.style.borderRight !== false ? 1 : 0;
+  const topBorderHeight = node.style.borderStyle && node.style.borderTop !== false ? 1 : 0;
+  const bottomBorderHeight = node.style.borderStyle && node.style.borderBottom !== false ? 1 : 0;
+
+  const contentWidth = width - leftBorderWidth - rightBorderWidth;
+  const contentHeight = height - topBorderHeight - bottomBorderHeight;
+
+  if (!(contentWidth > 0 && contentHeight > 0)) {
+    return;
+  }
+
+  const bounds = {
+    x: x + leftBorderWidth,
+    y: y + topBorderHeight,
+    width: contentWidth,
+    height: contentHeight,
+  };
+  const lines = Array.from({ length: contentHeight }, (_unused, row) =>
+    Array.from({ length: contentWidth }, (_empty, column) => {
+      const resetBackground = node.style.backgroundColor === "";
+      const background = resetBackground
+        ? undefined
+        : samplePaint(
+            node.style.backgroundColor!,
+            bounds.x + column,
+            bounds.y + row,
+            bounds,
+            output.paintContext,
+          );
+      return createCell(
+        " ",
+        1,
+        {
+          ...(background ? { background } : {}),
+          underline: "none",
+          attributes: cellAttributes.none,
+        },
+        undefined,
+        resetBackground ? { background: true } : undefined,
+      );
+    }),
+  );
+  output.writeCells(bounds.x, bounds.y, lines);
+};

package/src/render-border.ts

@@ -0,0 +1,167 @@
+import { graphemes } from "#/ansi/graphemes.ts";
+import { stringWidth } from "#/ansi/string-width.ts";
+import type { Paint, PaintContext } from "#/color/paint.ts";
+import { samplePaint } from "#/color/sample.ts";
+import { type DOMNode } from "#/dom.ts";
+import { BOXES } from "#/glyphs.ts";
+import type { Canvas } from "#/screen/canvas.ts";
+import type { Rect } from "#/screen/geometry.ts";
+import { cellAttributes, createCell, type Cell } from "#/screen/index.ts";
+
+const stylePiece = (
+  segment: string,
+  x: number,
+  y: number,
+  bounds: Rect,
+  context: PaintContext,
+  fg?: Paint,
+  bg?: Paint,
+  dim?: boolean,
+): Cell[] => {
+  let column = x;
+  return [...graphemes(segment)].map((grapheme) => {
+    const foreground = fg ? samplePaint(fg, column, y, bounds, context) : undefined;
+    const background = bg ? samplePaint(bg, column, y, bounds, context) : undefined;
+    const width = Math.max(1, stringWidth(grapheme));
+    column += width;
+    return createCell(grapheme, width, {
+      ...(foreground ? { foreground } : {}),
+      ...(background ? { background } : {}),
+      underline: "none",
+      attributes: dim ? cellAttributes.faint : cellAttributes.none,
+    });
+  });
+};
+
+export const renderBorder = (x: number, y: number, node: DOMNode, output: Canvas): void => {
+  if (node.style.borderStyle) {
+    const width = node.yogaNode!.getComputedWidth();
+    const height = node.yogaNode!.getComputedHeight();
+    const bounds = { x, y, width, height };
+    const box =
+      typeof node.style.borderStyle === "string"
+        ? BOXES[node.style.borderStyle]
+        : node.style.borderStyle;
+
+    const topBorderColor = node.style.borderTopColor ?? node.style.borderColor;
+    const bottomBorderColor = node.style.borderBottomColor ?? node.style.borderColor;
+    const leftBorderColor = node.style.borderLeftColor ?? node.style.borderColor;
+    const rightBorderColor = node.style.borderRightColor ?? node.style.borderColor;
+
+    const topBorderBackgroundColor =
+      node.style.borderTopBackgroundColor ?? node.style.borderBackgroundColor;
+    const bottomBorderBackgroundColor =
+      node.style.borderBottomBackgroundColor ?? node.style.borderBackgroundColor;
+    const leftBorderBackgroundColor =
+      node.style.borderLeftBackgroundColor ?? node.style.borderBackgroundColor;
+    const rightBorderBackgroundColor =
+      node.style.borderRightBackgroundColor ?? node.style.borderBackgroundColor;
+
+    const dimTopBorderColor = node.style.borderTopDimColor ?? node.style.borderDimColor;
+
+    const dimBottomBorderColor = node.style.borderBottomDimColor ?? node.style.borderDimColor;
+
+    const dimLeftBorderColor = node.style.borderLeftDimColor ?? node.style.borderDimColor;
+
+    const dimRightBorderColor = node.style.borderRightDimColor ?? node.style.borderDimColor;
+
+    const showTopBorder = node.style.borderTop !== false;
+    const showBottomBorder = node.style.borderBottom !== false;
+    const showLeftBorder = node.style.borderLeft !== false;
+    const showRightBorder = node.style.borderRight !== false;
+
+    const contentWidth = width - (showLeftBorder ? 1 : 0) - (showRightBorder ? 1 : 0);
+
+    const topBorder = showTopBorder
+      ? (showLeftBorder ? box.topLeft : "") +
+        box.top.repeat(contentWidth) +
+        (showRightBorder ? box.topRight : "")
+      : undefined;
+
+    let verticalBorderHeight = height;
+
+    if (showTopBorder) {
+      verticalBorderHeight -= 1;
+    }
+
+    if (showBottomBorder) {
+      verticalBorderHeight -= 1;
+    }
+
+    const offsetY = showTopBorder ? 1 : 0;
+
+    const bottomBorder = showBottomBorder
+      ? (showLeftBorder ? box.bottomLeft : "") +
+        box.bottom.repeat(contentWidth) +
+        (showRightBorder ? box.bottomRight : "")
+      : undefined;
+
+    if (topBorder) {
+      output.writeCells(x, y, [
+        stylePiece(
+          topBorder,
+          x,
+          y,
+          bounds,
+          output.paintContext,
+          topBorderColor,
+          topBorderBackgroundColor,
+          dimTopBorderColor,
+        ),
+      ]);
+    }
+
+    if (showLeftBorder) {
+      output.writeCells(
+        x,
+        y + offsetY,
+        Array.from({ length: verticalBorderHeight }, (_, row) =>
+          stylePiece(
+            box.left,
+            x,
+            y + offsetY + row,
+            bounds,
+            output.paintContext,
+            leftBorderColor,
+            leftBorderBackgroundColor,
+            dimLeftBorderColor,
+          ),
+        ),
+      );
+    }
+
+    if (showRightBorder) {
+      output.writeCells(
+        x + width - 1,
+        y + offsetY,
+        Array.from({ length: verticalBorderHeight }, (_, row) =>
+          stylePiece(
+            box.right,
+            x + width - 1,
+            y + offsetY + row,
+            bounds,
+            output.paintContext,
+            rightBorderColor,
+            rightBorderBackgroundColor,
+            dimRightBorderColor,
+          ),
+        ),
+      );
+    }
+
+    if (bottomBorder) {
+      output.writeCells(x, y + height - 1, [
+        stylePiece(
+          bottomBorder,
+          x,
+          y + height - 1,
+          bounds,
+          output.paintContext,
+          bottomBorderColor,
+          bottomBorderBackgroundColor,
+          dimBottomBorderColor,
+        ),
+      ]);
+    }
+  }
+};

package/src/render-frame.ts

@@ -0,0 +1,83 @@
+import type { PaintContext } from "#/color/paint.ts";
+import { type DOMElement } from "#/dom.ts";
+import { paintTree, renderAccessibleText } from "#/paint-tree.ts";
+import { Canvas } from "#/screen/canvas.ts";
+import { type ColorProfile } from "#/screen/index.ts";
+import type { Screen } from "#/screen/screen.ts";
+
+type Result = {
+  screen?: Screen;
+  staticScreen?: Screen;
+  accessibleText?: string;
+  staticAccessibleText?: string;
+};
+
+type RendererOptions = {
+  colorProfile?: ColorProfile;
+  paintContext?: PaintContext;
+};
+
+const renderDimension = (value: number): number =>
+  Number.isFinite(value) ? Math.max(0, Math.ceil(value)) : 0;
+
+export const renderFrame = (
+  node: DOMElement,
+  isScreenReaderEnabled: boolean,
+  options: RendererOptions = {},
+): Result => {
+  if (node.yogaNode) {
+    if (isScreenReaderEnabled) {
+      const output = renderAccessibleText(node, {
+        skipStaticElements: true,
+      });
+
+      let staticOutput = "";
+
+      if (node.staticNode) {
+        staticOutput = renderAccessibleText(node.staticNode, {
+          skipStaticElements: false,
+        });
+      }
+
+      return {
+        accessibleText: output,
+        staticAccessibleText: staticOutput,
+      };
+    }
+
+    const output = new Canvas({
+      width: renderDimension(node.yogaNode.getComputedWidth()),
+      height: renderDimension(node.yogaNode.getComputedHeight()),
+      colorProfile: options.colorProfile,
+      paintContext: options.paintContext,
+    });
+
+    paintTree(node, output, {
+      skipStaticElements: true,
+    });
+
+    let staticOutput;
+
+    if (node.staticNode?.yogaNode) {
+      staticOutput = new Canvas({
+        width: renderDimension(node.staticNode.yogaNode.getComputedWidth()),
+        height: renderDimension(node.staticNode.yogaNode.getComputedHeight()),
+        colorProfile: options.colorProfile,
+        paintContext: options.paintContext,
+      });
+
+      paintTree(node.staticNode, staticOutput, {
+        skipStaticElements: false,
+      });
+    }
+
+    return {
+      screen: output.finish(),
+      ...(staticOutput ? { staticScreen: staticOutput.finish() } : {}),
+    };
+  }
+
+  return {
+    accessibleText: "",
+  };
+};

package/src/render-to-string.ts

@@ -0,0 +1,146 @@
+import type { ReactNode } from "react";
+import { LegacyRoot } from "react-reconciler/constants.js";
+
+import { detectColorLevel } from "#/capabilities/detect.ts";
+import { createNode, type DOMElement } from "#/dom.ts";
+import { reconciler } from "#/reconciler.ts";
+import { renderFrame } from "#/render-frame.ts";
+import { colorProfileFromLevel, type ColorProfile } from "#/screen/index.ts";
+import { serializeScreen } from "#/screen/serialize.ts";
+import { Yoga } from "#/yoga/index.ts";
+
+export type RenderToStringOptions = {
+  /**
+	Width of the virtual terminal in columns.
+
+	@default 80
+	*/
+  columns?: number;
+
+  /**
+	Color profile used for deterministic serialization. By default this retains
+	the process color level for Ink compatibility.
+	*/
+  colorProfile?: ColorProfile;
+};
+
+/**
+Render a React element to a string synchronously. Unlike `render()`, this function does not write to stdout, does not set up any terminal event listeners, and returns the rendered output as a string.
+
+Useful for generating documentation, writing output to files, testing, or any scenario where you need the rendered output as a string without starting a persistent terminal application.
+
+**Notes:**
+
+- Terminal-specific hooks (`useInput`, `useStdin`, `useStdout`, `useStderr`, `useApp`, `useFocus`, `useFocusManager`) return default no-op values since there is no terminal session. They will not throw, but they will not function as in a live terminal.
+- `useEffect` callbacks will execute during rendering (due to synchronous rendering mode), but state updates they trigger will not affect the returned output, which reflects the initial render.
+- `useLayoutEffect` callbacks fire synchronously during commit, so state updates they trigger **will** be reflected in the output.
+- The `<Static>` component is supported — its output is prepended to the dynamic output.
+- If a component throws during rendering, the error is propagated to the caller after cleanup.
+
+@example
+```
+import {renderToString, Text, Box} from 'ink';
+
+const output = renderToString(
+	<Box padding={1}>
+		<Text color="green">Hello World</Text>
+	</Box>,
+	{columns: 40}
+);
+
+console.log(output);
+```
+*/
+export const renderToString = (node: ReactNode, options?: RenderToStringOptions): string => {
+  const columns = options?.columns ?? 80;
+  const colorProfile = options?.colorProfile ?? colorProfileFromLevel(detectColorLevel());
+
+  // Create a standalone root node — no stdout, stdin, or terminal bindings
+  const rootNode: DOMElement = createNode("ink-root");
+
+  // Capture static output from intermediate renders.
+  // The <Static> component uses useLayoutEffect to clear its children after
+  // the first commit. The reconciler's resetAfterCommit calls onImmediateRender
+  // when static content is dirty (and returns early, skipping the normal
+  // onRender callback), giving us a chance to capture it before it's cleared
+  // by the subsequent re-render.
+  let capturedStaticOutput = "";
+
+  rootNode.onComputeLayout = () => {
+    rootNode.yogaNode!.setWidth(columns);
+    rootNode.yogaNode!.calculateLayout(undefined, undefined, Yoga.DIRECTION_LTR);
+  };
+
+  rootNode.onImmediateRender = () => {
+    const { staticScreen } = renderFrame(rootNode, false, { colorProfile });
+    const staticOutput = staticScreen
+      ? `${serializeScreen(staticScreen, { colorProfile, styles: colorProfile !== "none" })}\n`
+      : "";
+    if (staticOutput && staticOutput !== "\n") {
+      capturedStaticOutput += staticOutput;
+    }
+  };
+
+  // Capture the first uncaught error so we can re-throw it after cleanup.
+  // React's reconciler catches component errors internally and reports them
+  // via onUncaughtError rather than letting them propagate. For a synchronous
+  // utility like renderToString, callers expect errors to throw.
+  let uncaughtError: unknown;
+
+  // Create a reconciler container in legacy (synchronous) mode.
+  // The four trailing callbacks are: onUncaughtError, onCaughtError,
+  // onRecoverableError, and onHostTransitionComplete.
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+  const container = reconciler.createContainer(
+    rootNode,
+    LegacyRoot,
+    null,
+    false,
+    null,
+    "render-to-string",
+    (error: unknown) => {
+      uncaughtError ??= error;
+    },
+    () => {},
+    () => {},
+    () => {},
+  );
+
+  // Synchronously render the React tree into the container
+  reconciler.updateContainerSync(node, container, null, () => {});
+  reconciler.flushSyncWork();
+
+  // Yoga layout has already been calculated by onComputeLayout during commit.
+  // Render the DOM tree to a string — this captures the dynamic (non-static) output.
+  const { screen } = renderFrame(rootNode, false, { colorProfile });
+  const output = screen
+    ? serializeScreen(screen, { colorProfile, styles: colorProfile !== "none" })
+    : "";
+
+  // Tear down: unmount the tree so the reconciler cleans up child nodes
+  // and runs effect cleanup functions. The reconciler detaches removed
+  // subtrees (removeChildFromContainer → detachYogaSubtree); the garbage
+  // collector reclaims the Yoga nodes.
+  reconciler.updateContainerSync(null, container, null, () => {});
+  reconciler.flushSyncWork();
+
+  // Re-throw after full cleanup so callers see the original error.
+  if (uncaughtError !== undefined) {
+    throw uncaughtError instanceof Error
+      ? uncaughtError
+      : // eslint-disable-next-line @typescript-eslint/no-base-to-string
+        new Error(String(uncaughtError));
+  }
+
+  // Static terminal output ends with a newline so dynamic output starts on a
+  // fresh line. Strip it here so renderToString returns clean output.
+  const normalizedStaticOutput = capturedStaticOutput.endsWith("\n")
+    ? capturedStaticOutput.slice(0, -1)
+    : capturedStaticOutput;
+
+  if (normalizedStaticOutput && output) {
+    return normalizedStaticOutput + "\n" + output;
+  }
+
+  return normalizedStaticOutput || output;
+};