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

package/src/global.d.ts

@@ -0,0 +1,36 @@
+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";
+
+declare module "react" {
+  namespace JSX {
+    // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+    interface IntrinsicElements {
+      "ink-box": Ink.Box;
+      "ink-text": Ink.Text;
+    }
+  }
+}
+
+declare namespace Ink {
+  type Box = {
+    internal_static?: boolean;
+    children?: ReactNode;
+    key?: Key;
+    ref?: Ref<DOMElement>;
+    style?: Except<Styles, "textWrap">;
+    internal_accessibility?: DOMElement["internal_accessibility"];
+  };
+
+  type Text = {
+    children?: ReactNode;
+    key?: Key;
+    style?: Styles;
+
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    internal_transform?: (children: string, index: number) => string;
+    internal_accessibility?: DOMElement["internal_accessibility"];
+  };
+}

package/src/hooks/use-animation.ts

@@ -0,0 +1,142 @@
+import { useState, useLayoutEffect, useRef, useCallback, useContext } from "react";
+
+import { animationContext as AnimationContext } from "../components/AnimationContext.ts";
+
+const defaultAnimationInterval = 100;
+const maximumTimerInterval = 2_147_483_647;
+const zeroAnimState = { frame: 0, time: 0, delta: 0 };
+
+type Options = {
+  /**
+	Time between ticks in milliseconds.
+
+	@default 100
+	*/
+  readonly interval?: number;
+
+  /**
+	Whether the animation is running. When set to `false`, the animation stops. When toggled back to `true`, all values reset to `0`.
+
+	@default true
+	*/
+  readonly isActive?: boolean;
+};
+
+export type AnimationResult = {
+  /**
+	Discrete counter that increments by 1 each interval. Useful for indexed sequences like spinner frames.
+	*/
+  readonly frame: number;
+
+  /**
+	Total elapsed time in milliseconds since the animation started or was last reset. Useful for continuous math-based animations like sine waves: `Math.sin(time / 1000 * Math.PI * 2)`.
+	*/
+  readonly time: number;
+
+  /**
+	Time in milliseconds since the previous rendered tick. Accounts for throttled renders. Useful for physics-based or velocity-driven motion: `position += speed * delta`.
+	*/
+  readonly delta: number;
+
+  /**
+	Resets `frame`, `time`, and `delta` to `0` and restarts timing from the current moment. Useful for one-shot animations triggered by events.
+	*/
+  readonly reset: () => void;
+};
+
+/**
+A React hook that drives animations. Returns a frame counter, elapsed time, frame delta, and a reset function. All animations share a single timer internally, so multiple animated components consolidate into one render cycle.
+
+@example
+```
+import {Text, useAnimation} from 'ink';
+
+const Spinner = () => {
+	const {frame} = useAnimation({interval: 80});
+	const characters = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+
+	return <Text>{characters[frame % characters.length]}</Text>;
+};
+```
+*/
+export function useAnimation(options?: Options): AnimationResult {
+  const { interval = defaultAnimationInterval, isActive = true } = options ?? {};
+  const safeInterval = normalizeAnimationInterval(interval);
+  const { subscribe, renderThrottleMs } = useContext(AnimationContext);
+  const [resetKey, setResetKey] = useState(0);
+  const [animState, setAnimState] = useState(zeroAnimState);
+  const nextRenderTimeRef = useRef(0);
+  const lastRenderTimeRef = useRef(0);
+  const previousOptionsRef = useRef({ isActive, safeInterval, resetKey });
+  const previousOptions = previousOptionsRef.current;
+  const shouldReset =
+    isActive &&
+    (safeInterval !== previousOptions.safeInterval ||
+      !previousOptions.isActive ||
+      resetKey !== previousOptions.resetKey);
+
+  const reset = useCallback(() => {
+    setResetKey((k) => k + 1);
+  }, []);
+
+  useLayoutEffect(() => {
+    if (!isActive) {
+      return;
+    }
+
+    // Reset to zero immediately so any render that occurs between this
+    // effect commit and the first tick shows zeros, not stale values.
+    // On initial mount this is a no-op: Object.is bails out because the
+    // state was initialized with the same zeroAnimState reference.
+    setAnimState(zeroAnimState);
+
+    let startTime = 0;
+
+    const { startTime: subscriberStartTime, unsubscribe } = subscribe((currentTime) => {
+      const isThrottled = renderThrottleMs > 0 && currentTime < nextRenderTimeRef.current;
+
+      if (isThrottled) {
+        // Coalesce intermediate ticks while Ink is inside the current
+        // render-throttle window; the next allowed render will jump
+        // straight to the latest elapsed values.
+        return;
+      }
+
+      const elapsed = currentTime - startTime;
+      const nextDelta = currentTime - lastRenderTimeRef.current;
+
+      lastRenderTimeRef.current = currentTime;
+      nextRenderTimeRef.current = currentTime + renderThrottleMs;
+      setAnimState({
+        frame: Math.floor(elapsed / safeInterval),
+        time: elapsed,
+        delta: nextDelta,
+      });
+    }, safeInterval);
+    // Use the scheduler's start time instead of sampling our own clock so the
+    // first delivered tick cannot start one frame late.
+    startTime = subscriberStartTime;
+    lastRenderTimeRef.current = subscriberStartTime;
+    nextRenderTimeRef.current = startTime + renderThrottleMs;
+
+    return unsubscribe;
+  }, [safeInterval, isActive, subscribe, renderThrottleMs, resetKey]);
+
+  useLayoutEffect(() => {
+    previousOptionsRef.current = { isActive, safeInterval, resetKey };
+  }, [isActive, safeInterval, resetKey]);
+
+  if (shouldReset) {
+    return { ...zeroAnimState, reset };
+  }
+
+  return { ...animState, reset };
+}
+
+function normalizeAnimationInterval(interval: number): number {
+  if (!Number.isFinite(interval)) {
+    return defaultAnimationInterval;
+  }
+
+  return Math.min(maximumTimerInterval, Math.max(1, interval));
+}

package/src/hooks/use-app.ts

@@ -0,0 +1,8 @@
+import { useContext } from "react";
+
+import { AppContext } from "../components/AppContext.ts";
+
+/**
+A React hook that returns app lifecycle methods like `exit()` and `waitUntilRenderFlush()`.
+*/
+export const useApp = () => useContext(AppContext);

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

@@ -0,0 +1,33 @@
+import { useContext, useRef, useCallback, useInsertionEffect } from "react";
+
+import { CursorContext } from "../components/CursorContext.ts";
+import { type CursorPosition } from "../log-update.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 log-update only during commit phase.
+  // 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,83 @@
+import { useEffect, useContext, useMemo } from "react";
+
+import { FocusContext } from "../components/FocusContext.ts";
+import { useStdin } from "./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 id = useMemo(() => {
+    return customId ?? Math.random().toString().slice(2, 7);
+  }, [customId]);
+
+  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,
+  };
+};