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

package/src/hooks/use-box-metrics.ts

@@ -0,0 +1,134 @@
+import { type RefObject, useState, useEffect, useCallback, useMemo } from "react";
+
+import { type DOMElement, addLayoutListener } from "#/dom.ts";
+
+// Yoga's `right`/`bottom` are omitted: always `0` for flow layout and unintuitive for absolute positioning.
+/**
+Metrics of a box element.
+
+All positions are relative to the element's parent.
+*/
+export type BoxMetrics = {
+  /**
+	Element width.
+	*/
+  readonly width: number;
+
+  /**
+	Element height.
+	*/
+  readonly height: number;
+
+  /**
+	Distance from the left edge of the parent.
+	*/
+  readonly left: number;
+
+  /**
+	Distance from the top edge of the parent.
+	*/
+  readonly top: number;
+};
+
+export type UseBoxMetricsResult = BoxMetrics & {
+  /**
+	Whether the currently tracked element has been measured in the latest layout pass.
+	*/
+  readonly hasMeasured: boolean;
+};
+
+const emptyMetrics: BoxMetrics = {
+  width: 0,
+  height: 0,
+  left: 0,
+  top: 0,
+};
+
+// eslint-disable-next-line @typescript-eslint/no-restricted-types
+const findRootNode = (node: DOMElement | null): DOMElement | undefined => {
+  if (!node) {
+    return;
+  }
+
+  if (!node.parentNode) {
+    return node.nodeName === "ink-root" ? node : undefined;
+  }
+
+  return findRootNode(node.parentNode);
+};
+
+/**
+A React hook that returns the current layout metrics for a tracked box element.
+It updates when layout changes (for example terminal resize, sibling/content changes, or position changes).
+
+The hook returns `{width: 0, height: 0, left: 0, top: 0}` until the first layout pass completes. It also returns zeros when the tracked ref is detached.
+
+Use `hasMeasured` to detect when the currently tracked element has been measured.
+
+@example
+```tsx
+import {useRef} from 'react';
+import {Box, Text, useBoxMetrics} from 'ink';
+
+const Example = () => {
+	const ref = useRef(null);
+	const {width, height, left, top, hasMeasured} = useBoxMetrics(ref);
+	return (
+		<Box ref={ref}>
+			<Text>
+				{hasMeasured ? `${width}x${height} at ${left},${top}` : 'Measuring...'}
+			</Text>
+		</Box>
+	);
+};
+```
+*/
+export const useBoxMetrics = (
+  /* eslint-disable-next-line @typescript-eslint/no-restricted-types --
+		Creating a ref object with an initial null, especially when the ref object
+		will be passed to a DOM node's ref attribute, is common in React. */
+  ref: RefObject<DOMElement | null>,
+): UseBoxMetricsResult => {
+  const [metrics, setMetrics] = useState(emptyMetrics);
+  const [hasMeasured, setHasMeasured] = useState(false);
+
+  const updateMetrics = useCallback(() => {
+    const layout = ref.current?.yogaNode?.getComputedLayout() ?? emptyMetrics;
+
+    setMetrics((previousMetrics) => {
+      const hasChanged =
+        previousMetrics.width !== layout.width ||
+        previousMetrics.height !== layout.height ||
+        previousMetrics.left !== layout.left ||
+        previousMetrics.top !== layout.top;
+
+      return hasChanged ? layout : previousMetrics;
+    });
+
+    setHasMeasured(Boolean(ref.current));
+  }, [ref]);
+
+  // Runs after every render of this component.
+  // This keeps metrics fresh when local state/props in this subtree change.
+  useEffect(updateMetrics);
+
+  // Subscribe to root layout commits so memoized components still receive
+  // sibling-driven position/size updates, even when they skip re-rendering.
+  useEffect(() => {
+    const rootNode = findRootNode(ref.current);
+
+    if (!rootNode) {
+      return;
+    }
+
+    return addLayoutListener(rootNode, updateMetrics);
+  });
+
+  return useMemo(
+    () => ({
+      ...metrics,
+      hasMeasured,
+    }),
+    [metrics, hasMeasured],
+  );
+};

package/src/hooks/use-capabilities.ts

@@ -0,0 +1,73 @@
+import { useEffect, useEffectEvent, useSyncExternalStore } from "react";
+
+import { type Capabilities } from "#/capabilities/detect.ts";
+import { getCapabilities } from "#/capabilities/store.ts";
+import { useStdinContext } from "#/hooks/use-stdin.ts";
+import { useStdout } from "#/hooks/use-stdout.ts";
+
+/**
+Returns everything knowable about the terminal: size, identity, platform,
+color depth, theme, and feature support.
+
+A thin wrapper over the framework-free capabilities store (`getCapabilities`):
+environment-derived facts are available immediately; facts only the terminal
+itself can answer fill in after a lazy one-time query, and re-mounting
+consumers refreshes the dynamic facts (theme colors, pixel geometry).
+Re-renders on terminal resize and whenever query answers arrive.
+*/
+export const useCapabilities = (): Capabilities => {
+  const { stdout } = useStdout();
+  const { stdin } = useStdinContext();
+  const store = getCapabilities(stdin, stdout);
+
+  const capabilities = useSyncExternalStore(store.subscribe, () => store.current);
+
+  useEffect(() => {
+    void store.query();
+  }, [store]);
+
+  return capabilities;
+};
+
+/**
+Calls `onChange` whenever the terminal changes: resizes (including in-band
+pixel geometry), color scheme switches, window focus, and query answers
+arriving. The React wrapper over `capabilities.subscribe()` for side effects —
+for rendering, use `useCapabilities` instead.
+
+The callback always sees the latest render's closure and changing it does not
+resubscribe. Both the new and previous snapshot are passed, so handlers can
+react to the specific change:
+
+```tsx
+useCapabilitiesChange((next, previous) => {
+  if (next.theme.appearance !== previous.theme.appearance) {
+    // re-theme
+  }
+});
+```
+*/
+export const useCapabilitiesChange = (
+  onChange: (capabilities: Capabilities, previous: Capabilities) => void,
+): void => {
+  const { stdout } = useStdout();
+  const { stdin } = useStdinContext();
+  const store = getCapabilities(stdin, stdout);
+
+  const handleChange = useEffectEvent(onChange);
+
+  useEffect(() => {
+    let previous = store.current;
+    const unsubscribe = store.subscribe((next) => {
+      const before = previous;
+      previous = next;
+      handleChange(next, before);
+    });
+
+    // Make sure the terminal has been asked — push report modes only turn
+    // on once the query has revealed support for them.
+    void store.query();
+
+    return unsubscribe;
+  }, [store]);
+};

package/src/hooks/use-cursor.ts

@@ -0,0 +1,33 @@
+import { useContext, useRef, useCallback, useInsertionEffect } from "react";
+
+import { CursorContext } from "#/components/CursorContext.ts";
+import { type CursorPosition } from "#/cursor-position.ts";
+
+/**
+A React hook that returns methods to control the terminal cursor position.
+
+Setting a cursor position makes the cursor visible at the specified coordinates (relative to the Ink output origin). This is useful for IME (Input Method Editor) support, where the composing character is displayed at the cursor location.
+
+Pass `undefined` to hide the cursor.
+*/
+export const useCursor = () => {
+  const context = useContext(CursorContext);
+  const positionRef = useRef<CursorPosition | undefined>(undefined);
+
+  const setCursorPosition = useCallback((position: CursorPosition | undefined) => {
+    positionRef.current = position;
+  }, []);
+
+  // Propagate cursor position to the terminal presenter only during commit.
+  // useInsertionEffect runs before resetAfterCommit (which triggers onRender),
+  // and does NOT run for abandoned concurrent renders (e.g. suspended components).
+  // This prevents cursor state from leaking across render boundaries.
+  useInsertionEffect(() => {
+    context.setCursorPosition(positionRef.current);
+    return () => {
+      context.setCursorPosition(undefined);
+    };
+  });
+
+  return { setCursorPosition };
+};

package/src/hooks/use-focus-manager.ts

@@ -0,0 +1,62 @@
+import { useContext } from "react";
+
+import { FocusContext, type Props } from "#/components/FocusContext.ts";
+
+type Output = {
+  /**
+	Enable focus management for all components.
+	*/
+  enableFocus: Props["enableFocus"];
+
+  /**
+	Disable focus management for all components. The currently active component (if there's one) will lose its focus.
+	*/
+  disableFocus: Props["disableFocus"];
+
+  /**
+	Switch focus to the next focusable component. If there's no active component right now, focus will be given to the first focusable component. If the active component is the last in the list of focusable components, focus will be switched to the first focusable component.
+	*/
+  focusNext: Props["focusNext"];
+
+  /**
+	Switch focus to the previous focusable component. If there's no active component right now, focus will be given to the first focusable component. If the active component is the first in the list of focusable components, focus will be switched to the last focusable component.
+	*/
+  focusPrevious: Props["focusPrevious"];
+
+  /**
+	Switch focus to the element with provided `id`. If there's no element with that `id`, focus is not changed.
+	*/
+  focus: Props["focus"];
+
+  /**
+	The ID of the currently focused component, or `undefined` if no component is focused.
+
+	@example
+	```tsx
+	import {Text, useFocusManager} from 'ink';
+
+	const Example = () => {
+		const {activeId} = useFocusManager();
+
+		return <Text>Focused: {activeId ?? 'none'}</Text>;
+	};
+	```
+	*/
+  activeId: Props["activeId"];
+};
+
+/**
+A React hook that returns methods to enable or disable focus management for all components or manually switch focus to the next or previous components.
+*/
+export const useFocusManager = (): Output => {
+  const focusContext = useContext(FocusContext);
+
+  return {
+    enableFocus: focusContext.enableFocus,
+    disableFocus: focusContext.disableFocus,
+    focusNext: focusContext.focusNext,
+    focusPrevious: focusContext.focusPrevious,
+    focus: focusContext.focus,
+    activeId: focusContext.activeId,
+  };
+};

package/src/hooks/use-focus.ts

@@ -0,0 +1,82 @@
+import { useEffect, useContext, useId } from "react";
+
+import { FocusContext } from "#/components/FocusContext.ts";
+import { useStdin } from "#/hooks/use-stdin.ts";
+
+type Input = {
+  /**
+	Enable or disable this component's focus, while still maintaining its position in the list of focusable components.
+	*/
+  isActive?: boolean;
+
+  /**
+	Auto-focus this component if there's no active (focused) component right now.
+	*/
+  autoFocus?: boolean;
+
+  /**
+	Assign an ID to this component, so it can be programmatically focused with `focus(id)`.
+	*/
+  id?: string;
+};
+
+type Output = {
+  /**
+	Determines whether this component is focused.
+	*/
+  isFocused: boolean;
+
+  /**
+	Allows focusing a specific element with the provided `id`.
+	*/
+  focus: (id: string) => void;
+};
+
+/**
+A React hook that returns focus state and focus controls for the current component.
+A component that uses the `useFocus` hook becomes "focusable" to Ink, so when the user presses <kbd>Tab</kbd>, Ink will switch focus to this component. If there are multiple components that execute the `useFocus` hook, focus will be given to them in the order in which these components are rendered.
+*/
+export const useFocus = ({
+  isActive = true,
+  autoFocus = false,
+  id: customId,
+}: Input = {}): Output => {
+  const { isRawModeSupported, setRawMode } = useStdin();
+  const { activeId, add, remove, activate, deactivate, focus } = useContext(FocusContext);
+
+  const autoId = useId();
+  const id = customId ?? autoId;
+
+  useEffect(() => {
+    add(id, { autoFocus });
+
+    return () => {
+      remove(id);
+    };
+  }, [id, autoFocus, add, remove]);
+
+  useEffect(() => {
+    if (isActive) {
+      activate(id);
+    } else {
+      deactivate(id);
+    }
+  }, [isActive, id, activate, deactivate]);
+
+  useEffect(() => {
+    if (!isRawModeSupported || !isActive) {
+      return;
+    }
+
+    setRawMode(true);
+
+    return () => {
+      setRawMode(false);
+    };
+  }, [isActive, isRawModeSupported, setRawMode]);
+
+  return {
+    isFocused: Boolean(id) && activeId === id,
+    focus,
+  };
+};

package/src/hooks/use-input.ts

@@ -0,0 +1,267 @@
+import { useEffect, useEffectEvent } from "react";
+
+import { ESC } from "#/ansi/escapes.ts";
+import { useStdinContext } from "#/hooks/use-stdin.ts";
+import { parseKeypress, nonAlphanumericKeys } from "#/parse-keypress.ts";
+import { reconciler } from "#/reconciler.ts";
+
+/**
+Handy information about a key that was pressed.
+*/
+export type Key = {
+  /**
+	Up arrow key was pressed.
+	*/
+  upArrow: boolean;
+
+  /**
+	Down arrow key was pressed.
+	*/
+  downArrow: boolean;
+
+  /**
+	Left arrow key was pressed.
+	*/
+  leftArrow: boolean;
+
+  /**
+	Right arrow key was pressed.
+	*/
+  rightArrow: boolean;
+
+  /**
+	Page Down key was pressed.
+	*/
+  pageDown: boolean;
+
+  /**
+	Page Up key was pressed.
+	*/
+  pageUp: boolean;
+
+  /**
+	Home key was pressed.
+	*/
+  home: boolean;
+
+  /**
+	End key was pressed.
+	*/
+  end: boolean;
+
+  /**
+	Return (Enter) key was pressed.
+	*/
+  return: boolean;
+
+  /**
+	Escape key was pressed.
+	*/
+  escape: boolean;
+
+  /**
+	Ctrl key was pressed.
+	*/
+  ctrl: boolean;
+
+  /**
+	Shift key was pressed.
+	*/
+  shift: boolean;
+
+  /**
+	Tab key was pressed.
+	*/
+  tab: boolean;
+
+  /**
+	Backspace key was pressed.
+	*/
+  backspace: boolean;
+
+  /**
+	Delete key was pressed.
+	*/
+  delete: boolean;
+
+  /**
+	[Meta key](https://en.wikipedia.org/wiki/Meta_key) was pressed.
+	*/
+  meta: boolean;
+
+  /**
+	Super key (Cmd on Mac, Win on Windows) was pressed.
+
+	Only available with kitty keyboard protocol.
+	*/
+  super: boolean;
+
+  /**
+	Hyper key was pressed.
+
+	Only available with kitty keyboard protocol.
+	*/
+  hyper: boolean;
+
+  /**
+	Caps Lock is active.
+
+	Only available with kitty keyboard protocol.
+	*/
+  capsLock: boolean;
+
+  /**
+	Num Lock is active.
+
+	Only available with kitty keyboard protocol.
+	*/
+  numLock: boolean;
+
+  /**
+	Event type for key events.
+
+	Only available with kitty keyboard protocol.
+	*/
+  eventType?: "press" | "repeat" | "release";
+};
+
+type Handler = (input: string, key: Key) => void;
+
+type Options = {
+  /**
+	Enable or disable capturing of user input. Useful when there are multiple `useInput` hooks used at once to avoid handling the same input several times.
+
+	@default true
+	*/
+  isActive?: boolean;
+};
+
+/**
+A React hook that returns `void` and handles user input.
+It's a more convenient alternative to using `StdinContext` and listening for `data` events. The callback you pass to `useInput` is called for each character when the user enters any input. However, if the user pastes text and it's more than one character, the callback will be called only once, and the whole string will be passed as `input`.
+
+```
+import {useInput} from 'ink';
+
+const UserInput = () => {
+  useInput((input, key) => {
+    if (input === 'q') {
+      // Exit program
+    }
+
+    if (key.leftArrow) {
+      // Left arrow key pressed
+    }
+  });
+
+  return …
+};
+```
+*/
+export const useInput = (inputHandler: Handler, options: Options = {}) => {
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  const { setRawMode, internal_exitOnCtrlC, internal_eventEmitter } = useStdinContext();
+
+  useEffect(() => {
+    if (options.isActive === false) {
+      return;
+    }
+
+    setRawMode(true);
+
+    return () => {
+      setRawMode(false);
+    };
+  }, [options.isActive, setRawMode]);
+
+  const handleData = useEffectEvent((data: string) => {
+    const keypress = parseKeypress(data);
+
+    const key: Key = {
+      upArrow: keypress.name === "up",
+      downArrow: keypress.name === "down",
+      leftArrow: keypress.name === "left",
+      rightArrow: keypress.name === "right",
+      pageDown: keypress.name === "pagedown",
+      pageUp: keypress.name === "pageup",
+      home: keypress.name === "home",
+      end: keypress.name === "end",
+      return: keypress.name === "return",
+      escape: keypress.name === "escape",
+      ctrl: keypress.ctrl,
+      shift: keypress.shift,
+      tab: keypress.name === "tab",
+      backspace: keypress.name === "backspace",
+      delete: keypress.name === "delete",
+      meta: keypress.meta,
+      // Kitty keyboard protocol modifiers
+      super: keypress.super ?? false,
+      hyper: keypress.hyper ?? false,
+      capsLock: keypress.capsLock ?? false,
+      numLock: keypress.numLock ?? false,
+      eventType: keypress.eventType,
+    };
+
+    let input: string;
+    if (keypress.isKittyProtocol) {
+      // Use text-as-codepoints field for printable keys (needed when
+      // reportAllKeysAsEscapeCodes flag is enabled), suppress non-printable
+      if (keypress.isPrintable) {
+        input = keypress.text ?? keypress.name;
+      } else if (keypress.ctrl && keypress.name.length === 1) {
+        // Ctrl+letter via codepoint 1-26 form: not printable text, but
+        // the letter name must flow through so handlers (e.g. exitOnCtrlC
+        // checking `input === 'c' && key.ctrl`) still work.
+        input = keypress.name;
+      } else {
+        input = "";
+      }
+    } else if (keypress.ctrl) {
+      // Keypress.name is guaranteed non-undefined by parseKeypress,
+      // but guard defensively since a TypeError here would crash the
+      // entire Ink app (see https://github.com/vadimdemedes/ink/issues/901).
+      input = keypress.name ?? "";
+    } else {
+      input = keypress.sequence;
+    }
+
+    if (!keypress.isKittyProtocol && nonAlphanumericKeys.includes(keypress.name)) {
+      input = "";
+    }
+
+    // Strip escape prefix from broken/incomplete sequences that
+    // parseKeypress did not fully resolve (e.g. a flushed "\u001B[").
+    if (input.startsWith(ESC)) {
+      input = input.slice(1);
+    }
+
+    if (input.length === 1 && /[A-Z]/.test(input)) {
+      key.shift = true;
+    }
+
+    // If app is supposed to exit on Ctrl+C, skip input listeners.
+    if (input === "c" && key.ctrl && internal_exitOnCtrlC) {
+      return;
+    }
+
+    // Use discreteUpdates to assign DiscreteEventPriority to state
+    // updates from keyboard input, ensuring they are processed at the
+    // highest priority in concurrent mode.
+    // @ts-expect-error Types require 5 arguments (fn, a, b, c, d) but only fn is needed at runtime.
+    reconciler.discreteUpdates(() => {
+      inputHandler(input, key);
+    });
+  });
+
+  useEffect(() => {
+    if (options.isActive === false) {
+      return;
+    }
+
+    internal_eventEmitter.on("input", handleData);
+
+    return () => {
+      internal_eventEmitter.removeListener("input", handleData);
+    };
+  }, [options.isActive, internal_eventEmitter]);
+};

package/src/hooks/use-is-screen-reader-enabled.ts

@@ -0,0 +1,12 @@
+import { useContext } from "react";
+
+import { accessibilityContext } from "#/components/AccessibilityContext.ts";
+
+/**
+A React hook that returns whether a screen reader is enabled.
+This is useful when you want to render different output for screen readers.
+*/
+export const useIsScreenReaderEnabled = (): boolean => {
+  const { isScreenReaderEnabled } = useContext(accessibilityContext);
+  return isScreenReaderEnabled;
+};