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

package/src/components/AppContext.ts

@@ -0,0 +1,111 @@
+import { createContext } from "react";
+
+/**
+A handle returned by `suspendTerminal()` when called without a callback.
+
+Call `resume()` to give terminal ownership back to Ink, or use `await using`
+so the suspension is resumed automatically when it leaves scope.
+*/
+export type TerminalSuspension = {
+  readonly resume: () => Promise<void>;
+  readonly [Symbol.asyncDispose]: () => Promise<void>;
+};
+
+/**
+Temporarily hand the terminal over to a child process (e.g. `$EDITOR`, `less`,
+`fzf`), then restore Ink's terminal state and force a full redraw.
+*/
+export type SuspendTerminal = {
+  (callback: () => void | Promise<void>): Promise<void>;
+  (): Promise<TerminalSuspension>;
+};
+
+export type Props = {
+  /**
+	Exit (unmount) the whole Ink app.
+
+	- `exit()` — resolves `waitUntilExit()` with `undefined`.
+	- `exit(new Error('…'))` — rejects `waitUntilExit()` with the error.
+	- `exit(value)` — resolves `waitUntilExit()` with `value`.
+	*/
+  readonly exit: (errorOrResult?: unknown) => void;
+
+  /**
+	Returns a promise that settles after pending render output is flushed to stdout.
+
+	@example
+	```jsx
+	import {useEffect} from 'react';
+	import {useApp} from 'ink';
+
+	const Example = () => {
+		const {waitUntilRenderFlush} = useApp();
+
+		useEffect(() => {
+			void (async () => {
+				await waitUntilRenderFlush();
+				runNextCommand();
+			})();
+		}, [waitUntilRenderFlush]);
+
+		return …;
+	};
+	```
+	*/
+  readonly waitUntilRenderFlush: () => Promise<void>;
+
+  /**
+	Temporarily release the terminal so a child process can take it over, then
+	restore Ink's terminal state and force a full redraw.
+
+	Use the callback form for the common case — Ink restores the terminal even
+	if the callback throws:
+
+	@example
+	```jsx
+	import {useApp} from 'ink';
+
+	const {suspendTerminal} = useApp();
+
+	await suspendTerminal(async () => {
+		await runEditor();
+	});
+	```
+
+	Or hold a suspension and resume it yourself:
+
+	@example
+	```jsx
+	await using suspension = await suspendTerminal();
+	await runEditor();
+	```
+	*/
+  readonly suspendTerminal: SuspendTerminal;
+};
+
+/**
+`AppContext` is a React context that exposes lifecycle methods for the app.
+*/
+// Keep the default value typed so `useApp()` preserves the public `exit(errorOrResult?)` signature.
+const noopSuspension: TerminalSuspension = {
+  async resume() {},
+  async [Symbol.asyncDispose]() {},
+};
+
+const defaultValue: Props = {
+  exit(_errorOrResult?: unknown) {},
+  async waitUntilRenderFlush() {},
+  suspendTerminal: (async (callback?: () => void | Promise<void>) => {
+    if (callback) {
+      await callback();
+      return;
+    }
+
+    return noopSuspension;
+  }) as SuspendTerminal,
+};
+
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const AppContext = createContext(defaultValue);
+
+AppContext.displayName = "InternalAppContext";

package/src/components/BackgroundContext.ts

@@ -0,0 +1,8 @@
+import { createContext } from "react";
+
+import { type ForegroundColorName } from "../ansi/sgr.ts";
+import { type LiteralUnion } from "../types.ts";
+
+export type BackgroundColor = LiteralUnion<ForegroundColorName, string>;
+
+export const backgroundContext = createContext<BackgroundColor | undefined>(undefined);

package/src/components/Box.tsx

@@ -0,0 +1,116 @@
+import { forwardRef, useContext, type PropsWithChildren } 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";
+
+export type Props = Except<Styles, "textWrap"> & {
+  /**
+	A label for the element for screen readers.
+	*/
+  readonly "aria-label"?: string;
+
+  /**
+	Hide the element from screen readers.
+	*/
+  readonly "aria-hidden"?: boolean;
+
+  /**
+	The role of the element.
+	*/
+  readonly "aria-role"?:
+    | "button"
+    | "checkbox"
+    | "combobox"
+    | "list"
+    | "listbox"
+    | "listitem"
+    | "menu"
+    | "menuitem"
+    | "option"
+    | "progressbar"
+    | "radio"
+    | "radiogroup"
+    | "tab"
+    | "tablist"
+    | "table"
+    | "textbox"
+    | "timer"
+    | "toolbar";
+
+  /**
+	The state of the element.
+	*/
+  readonly "aria-state"?: {
+    readonly busy?: boolean;
+    readonly checked?: boolean;
+    readonly disabled?: boolean;
+    readonly expanded?: boolean;
+    readonly multiline?: boolean;
+    readonly multiselectable?: boolean;
+    readonly readonly?: boolean;
+    readonly required?: boolean;
+    readonly selected?: boolean;
+  };
+};
+
+/**
+`<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;
+    }
+
+    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";

package/src/components/CursorContext.ts

@@ -0,0 +1,19 @@
+import { createContext } from "react";
+
+import { type CursorPosition } from "../log-update.ts";
+
+export type Props = {
+  /**
+	Set the cursor position relative to the Ink output.
+
+	Pass `undefined` to hide the cursor.
+	*/
+  readonly setCursorPosition: (position: CursorPosition | undefined) => void;
+};
+
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const CursorContext = createContext<Props>({
+  setCursorPosition() {},
+});
+
+CursorContext.displayName = "InternalCursorContext";

package/src/components/ErrorBoundary.tsx

@@ -0,0 +1,38 @@
+import { PureComponent, type ReactNode } from "react";
+
+import { ErrorOverview } from "./ErrorOverview.tsx";
+
+type Props = {
+  readonly children: ReactNode;
+  readonly onError: (error: Error) => void;
+};
+
+type State = {
+  readonly error?: Error;
+};
+
+// Error boundary must be a class component since getDerivedStateFromError
+// and componentDidCatch are not available as hooks
+export class ErrorBoundary extends PureComponent<Props, State> {
+  static displayName = "InternalErrorBoundary";
+
+  static getDerivedStateFromError(error: Error) {
+    return { error };
+  }
+
+  override state: State = {
+    error: undefined,
+  };
+
+  override componentDidCatch(error: Error): void {
+    this.props.onError(error);
+  }
+
+  override render(): ReactNode {
+    if (this.state.error) {
+      return <ErrorOverview error={this.state.error} />;
+    }
+
+    return this.props.children;
+  }
+}

package/src/components/ErrorOverview.tsx

@@ -0,0 +1,133 @@
+import * as fs 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";
+
+// Error's source file is reported as file:///home/user/file.js
+// This function removes the file://[cwd] part
+const cleanupPath = (path: string | undefined): string | undefined => {
+  return path?.replace(`file://${cwd()}/`, "");
+};
+
+type Props = {
+  readonly error: Error;
+};
+
+export function ErrorOverview({ error }: Props) {
+  const stack = error.stack ? error.stack.split("\n").slice(1) : undefined;
+  const origin = stack ? parseStackLine(stack[0]!) : undefined;
+  const filePath = cleanupPath(origin?.file);
+  let excerpt: CodeExcerpt[] | undefined;
+  let lineWidth = 0;
+  const stackLineCounts = new Map<string, number>();
+
+  if (filePath && origin?.line && fs.existsSync(filePath)) {
+    const sourceCode = fs.readFileSync(filePath, "utf8");
+    excerpt = codeExcerpt(sourceCode, origin.line);
+
+    if (excerpt) {
+      for (const { line } of excerpt) {
+        lineWidth = Math.max(lineWidth, String(line).length);
+      }
+    }
+  }
+
+  return (
+    <Box flexDirection="column" padding={1}>
+      <Box>
+        <Text backgroundColor="red" color="white">
+          {" "}
+          ERROR{" "}
+        </Text>
+
+        <Text> {error.message}</Text>
+      </Box>
+
+      {origin && filePath ? (
+        <Box marginTop={1}>
+          <Text dimColor>
+            {filePath}:{origin.line}:{origin.column}
+          </Text>
+        </Box>
+      ) : null}
+
+      {origin && excerpt ? (
+        <Box marginTop={1} flexDirection="column">
+          {excerpt.map(({ line, value }) => (
+            <Box key={line}>
+              <Box width={lineWidth + 1}>
+                <Text
+                  dimColor={line !== origin.line}
+                  backgroundColor={line === origin.line ? "red" : undefined}
+                  color={line === origin.line ? "white" : undefined}
+                  aria-label={line === origin.line ? `Line ${line}, error` : `Line ${line}`}
+                >
+                  {String(line).padStart(lineWidth, " ")}:
+                </Text>
+              </Box>
+
+              <Text
+                key={line}
+                backgroundColor={line === origin.line ? "red" : undefined}
+                color={line === origin.line ? "white" : undefined}
+              >
+                {" " + value}
+              </Text>
+            </Box>
+          ))}
+        </Box>
+      ) : null}
+
+      {error.stack ? (
+        <Box marginTop={1} flexDirection="column">
+          {error.stack
+            .split("\n")
+            .slice(1)
+            .map((line) => {
+              const parsedLine = parseStackLine(line);
+              const lineCount = stackLineCounts.get(line) ?? 0;
+              stackLineCounts.set(line, lineCount + 1);
+              const key = `${line}-${lineCount}`;
+
+              // If the line from the stack cannot be parsed, or parsed into an incomplete
+              // frame without source location data (for example, "at native"), we print
+              // out the unparsed line.
+              if (!parsedLine?.file || !parsedLine.line || !parsedLine.column) {
+                return (
+                  <Box key={key}>
+                    <Text dimColor>- </Text>
+                    <Text dimColor bold>
+                      {line}
+                      \t{" "}
+                    </Text>
+                  </Box>
+                );
+              }
+
+              return (
+                <Box key={key}>
+                  <Text dimColor>- </Text>
+                  <Text dimColor bold>
+                    {parsedLine.function}
+                  </Text>
+                  <Text
+                    dimColor
+                    color="gray"
+                    aria-label={`at ${
+                      cleanupPath(parsedLine.file) ?? ""
+                    } line ${parsedLine.line} column ${parsedLine.column}`}
+                  >
+                    {" "}
+                    ({cleanupPath(parsedLine.file) ?? ""}:{parsedLine.line}:{parsedLine.column})
+                  </Text>
+                </Box>
+              );
+            })}
+        </Box>
+      ) : null}
+    </Box>
+  );
+}

package/src/components/FocusContext.ts

@@ -0,0 +1,30 @@
+import { createContext } from "react";
+
+export type Props = {
+  readonly activeId?: string;
+  readonly add: (id: string, options: { autoFocus: boolean }) => void;
+  readonly remove: (id: string) => void;
+  readonly activate: (id: string) => void;
+  readonly deactivate: (id: string) => void;
+  readonly enableFocus: () => void;
+  readonly disableFocus: () => void;
+  readonly focusNext: () => void;
+  readonly focusPrevious: () => void;
+  readonly focus: (id: string) => void;
+};
+
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const FocusContext = createContext<Props>({
+  activeId: undefined,
+  add() {},
+  remove() {},
+  activate() {},
+  deactivate() {},
+  enableFocus() {},
+  disableFocus() {},
+  focusNext() {},
+  focusPrevious() {},
+  focus() {},
+});
+
+FocusContext.displayName = "InternalFocusContext";

package/src/components/Newline.tsx

@@ -0,0 +1,15 @@
+export type Props = {
+  /**
+	Number of newlines to insert.
+
+	@default 1
+	*/
+  readonly count?: number;
+};
+
+/**
+Adds one or more newline (`\n`) characters. Must be used within `<Text>` components.
+*/
+export function Newline({ count = 1 }: Props) {
+  return <ink-text>{"\n".repeat(count)}</ink-text>;
+}

package/src/components/Spacer.tsx

@@ -0,0 +1,10 @@
+import { Box } from "./Box.tsx";
+
+/**
+A flexible space that expands along the major axis of its containing layout.
+
+It's useful as a shortcut for filling all the available space between elements.
+*/
+export function Spacer() {
+  return <Box flexGrow={1} />;
+}

package/src/components/Static.tsx

@@ -0,0 +1,59 @@
+import { useMemo, useState, useLayoutEffect, type ReactNode } from "react";
+
+import { type Styles } from "../styles.ts";
+
+export type Props<T> = {
+  /**
+	Array of items of any type to render using the function you pass as a component child.
+	*/
+  readonly items: T[];
+
+  /**
+	Styles to apply to a container of child elements. See <Box> for supported properties.
+	*/
+  readonly style?: Styles;
+
+  /**
+	Function that is called to render every item in the `items` array. The first argument is the item itself, and the second argument is the index of that item in the `items` array. Note that a `key` must be assigned to the root component.
+	*/
+  readonly children: (item: T, index: number) => ReactNode;
+};
+
+/**
+`<Static>` component permanently renders its output above everything else. It's useful for displaying activity like completed tasks or logs—things that don't change after they're rendered (hence the name "Static").
+
+It's preferred to use `<Static>` for use cases like these when you can't know or control the number of items that need to be rendered.
+
+For example, [Tap](https://github.com/tapjs/node-tap) uses `<Static>` to display a list of completed tests. [Gatsby](https://github.com/gatsbyjs/gatsby) uses it to display a list of generated pages while still displaying a live progress bar.
+*/
+export function Static<T>(props: Props<T>) {
+  const { items, children: render, style: customStyle } = props;
+  const [index, setIndex] = useState(0);
+
+  const itemsToRender: T[] = useMemo(() => {
+    return items.slice(index);
+  }, [items, index]);
+
+  useLayoutEffect(() => {
+    setIndex(items.length);
+  }, [items.length]);
+
+  const children = itemsToRender.map((item, itemIndex): ReactNode => {
+    return render(item, index + itemIndex);
+  });
+
+  const style: Styles = useMemo(
+    () => ({
+      position: "absolute",
+      flexDirection: "column",
+      ...customStyle,
+    }),
+    [customStyle],
+  );
+
+  return (
+    <ink-box internal_static style={style}>
+      {children}
+    </ink-box>
+  );
+}

package/src/components/StderrContext.ts

@@ -0,0 +1,26 @@
+import process from "node:process";
+
+import { createContext } from "react";
+
+export type Props = {
+  /**
+	Stderr stream passed to `render()` in `options.stderr` or `process.stderr` by default.
+	*/
+  readonly stderr: NodeJS.WritableStream;
+
+  /**
+	Write any string to stderr while preserving Ink's output. It's useful when you want to display external information outside of Ink's rendering and ensure there's no conflict between the two. It's similar to `<Static>`, except it can't accept components; it only works with strings.
+	*/
+  readonly write: (data: string) => void;
+};
+
+/**
+`StderrContext` is a React context that exposes the stderr stream.
+*/
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const StderrContext = createContext<Props>({
+  stderr: process.stderr,
+  write() {},
+});
+
+StderrContext.displayName = "InternalStderrContext";

package/src/components/StdinContext.ts

@@ -0,0 +1,49 @@
+import { EventEmitter } from "node:events";
+import process from "node:process";
+
+import { createContext } from "react";
+
+export type PublicProps = {
+  /**
+	The stdin stream passed to `render()` in `options.stdin`, or `process.stdin` by default. Useful if your app needs to handle user input.
+	*/
+  readonly stdin: NodeJS.ReadableStream;
+
+  /**
+	Ink exposes this function via own `<StdinContext>` to be able to handle Ctrl+C, that's why you should use Ink's `setRawMode` instead of `process.stdin.setRawMode`. If the `stdin` stream passed to Ink does not support setRawMode, this function does nothing.
+	*/
+  readonly setRawMode: (value: boolean) => void;
+
+  /**
+	A boolean flag determining if the current `stdin` supports `setRawMode`. A component using `setRawMode` might want to use `isRawModeSupported` to nicely fall back in environments where raw mode is not supported.
+	*/
+  readonly isRawModeSupported: boolean;
+};
+
+export type Props = PublicProps & {
+  /**
+	Enable or disable bracketed paste mode on the terminal. When enabled, pasted text is wrapped in escape sequences that allow it to be distinguished from typed input.
+	*/
+  readonly setBracketedPasteMode: (value: boolean) => void;
+
+  readonly internal_exitOnCtrlC: boolean;
+
+  readonly internal_eventEmitter: EventEmitter;
+};
+
+/**
+`StdinContext` is a React context that exposes the input stream.
+*/
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const StdinContext = createContext<Props>({
+  stdin: process.stdin,
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  internal_eventEmitter: new EventEmitter(),
+  setRawMode() {},
+  setBracketedPasteMode() {},
+  isRawModeSupported: false,
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  internal_exitOnCtrlC: true,
+});
+
+StdinContext.displayName = "InternalStdinContext";

package/src/components/StdoutContext.ts

@@ -0,0 +1,28 @@
+import process from "node:process";
+
+import { createContext } from "react";
+
+import type { OutputStream } from "../stream.ts";
+
+export type Props = {
+  /**
+	Stdout stream passed to `render()` in `options.stdout` or `process.stdout` by default.
+	*/
+  readonly stdout: OutputStream;
+
+  /**
+	Write any string to stdout while preserving Ink's output. It's useful when you want to display external information outside of Ink's rendering and ensure there's no conflict between the two. It's similar to `<Static>`, except it can't accept components; it only works with strings.
+	*/
+  readonly write: (data: string) => void;
+};
+
+/**
+`StdoutContext` is a React context that exposes the stdout stream where Ink renders your app.
+*/
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const StdoutContext = createContext<Props>({
+  stdout: process.stdout,
+  write() {},
+});
+
+StdoutContext.displayName = "InternalStdoutContext";