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

package/src/hooks/use-paste.ts

@@ -0,0 +1,78 @@
+import { useEffect, useEffectEvent } from "react";
+
+import { useStdinContext } from "#/hooks/use-stdin.ts";
+import { reconciler } from "#/reconciler.ts";
+
+type Options = {
+  /**
+	Enable or disable the paste handler. Useful when multiple components use `usePaste` and only one should be active at a time.
+
+	@default true
+	*/
+  isActive?: boolean;
+};
+
+/**
+A React hook that calls `handler` whenever the user pastes text in the terminal. Bracketed paste mode (`\x1b[?2004h`) is automatically enabled while the hook is active, so pasted text arrives as a single string rather than being misinterpreted as individual key presses.
+
+`usePaste` and `useInput` can be used together in the same component. They operate on separate event channels, so paste content is never forwarded to `useInput` handlers when `usePaste` is active.
+
+```
+import {useInput, usePaste} from 'ink';
+
+const MyInput = () => {
+	useInput((input, key) => {
+		// Only receives typed characters and key events, not pasted text.
+		if (key.return) {
+			// Submit
+		}
+	});
+
+	usePaste((text) => {
+		// Receives the full pasted string, including newlines.
+		console.log('Pasted:', text);
+	});
+
+	return …
+};
+```
+*/
+export const usePaste = (handler: (text: string) => void, options: Options = {}): void => {
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  const { setRawMode, setBracketedPasteMode, internal_eventEmitter } = useStdinContext();
+
+  useEffect(() => {
+    if (options.isActive === false) {
+      return;
+    }
+
+    setRawMode(true);
+    setBracketedPasteMode(true);
+
+    return () => {
+      setRawMode(false);
+      setBracketedPasteMode(false);
+    };
+  }, [options.isActive, setRawMode, setBracketedPasteMode]);
+
+  const handlePaste = useEffectEvent((text: string) => {
+    // Use discreteUpdates to assign DiscreteEventPriority to state
+    // updates triggered by paste, matching the priority of useInput.
+    // @ts-expect-error Types require 5 arguments (fn, a, b, c, d) but only fn is needed at runtime.
+    reconciler.discreteUpdates(() => {
+      handler(text);
+    });
+  });
+
+  useEffect(() => {
+    if (options.isActive === false) {
+      return;
+    }
+
+    internal_eventEmitter.on("paste", handlePaste);
+
+    return () => {
+      internal_eventEmitter.removeListener("paste", handlePaste);
+    };
+  }, [options.isActive, internal_eventEmitter]);
+};

package/src/hooks/use-stderr.ts

@@ -0,0 +1,8 @@
+import { useContext } from "react";
+
+import { StderrContext } from "#/components/StderrContext.ts";
+
+/**
+A React hook that returns the stderr stream.
+*/
+export const useStderr = () => useContext(StderrContext);

package/src/hooks/use-stdin.ts

@@ -0,0 +1,10 @@
+import { useContext } from "react";
+
+import { StdinContext, type PublicProps, type Props } from "#/components/StdinContext.ts";
+
+/**
+A React hook that returns the stdin stream and stdin-related utilities.
+*/
+export const useStdin = (): PublicProps => useContext(StdinContext);
+
+export const useStdinContext = (): Props => useContext(StdinContext);

package/src/hooks/use-stdout.ts

@@ -0,0 +1,8 @@
+import { useContext } from "react";
+
+import { StdoutContext } from "#/components/StdoutContext.ts";
+
+/**
+A React hook that returns the stdout stream where Ink renders your app.
+*/
+export const useStdout = () => useContext(StdoutContext);

package/src/hooks/use-terminal-osc.ts

@@ -0,0 +1,59 @@
+import { useCallback, useContext, useEffect, useRef } from "react";
+
+import type { ClipboardSelection, TerminalProgressState } from "#/ansi/osc.ts";
+import { TerminalOscContext } from "#/components/TerminalOscContext.ts";
+
+export type ProgressOptions = {
+  readonly state: TerminalProgressState;
+  readonly value?: number;
+};
+
+export const useProgress = ({ state, value }: ProgressOptions): void => {
+  const terminal = useContext(TerminalOscContext);
+  const owner = useRef<symbol>(undefined);
+  owner.current ??= Symbol("terminal-progress");
+
+  useEffect(() => {
+    terminal.publishProgress(owner.current!, state, value);
+  }, [state, terminal, value]);
+
+  useEffect(() => {
+    return () => {
+      terminal.publishProgress(owner.current!, "inactive");
+    };
+  }, [terminal]);
+};
+
+export const useClipboard = (): ((text: string, selection?: ClipboardSelection) => void) => {
+  const terminal = useContext(TerminalOscContext);
+  return useCallback((text, selection) => terminal.copyToClipboard(text, selection), [terminal]);
+};
+
+export const useTitle = (title?: string): void => {
+  const terminal = useContext(TerminalOscContext);
+  const owner = useRef<symbol>(undefined);
+  owner.current ??= Symbol("terminal-title");
+  useEffect(() => {
+    terminal.publishTitle(owner.current!, title);
+  }, [terminal, title]);
+  useEffect(() => () => terminal.publishTitle(owner.current!, undefined), [terminal]);
+};
+
+export const useWorkingDirectory = (directory: URL | string): void => {
+  const terminal = useContext(TerminalOscContext);
+  useEffect(() => {
+    terminal.setWorkingDirectory(directory);
+  }, [directory, terminal]);
+};
+
+export const useNotification = (): ((title: string) => void) => {
+  const terminal = useContext(TerminalOscContext);
+  return useCallback((title) => terminal.notify(title), [terminal]);
+};
+
+export const usePointerShape = (shape: string): void => {
+  const terminal = useContext(TerminalOscContext);
+  useEffect(() => {
+    terminal.setPointerShape(shape);
+  }, [shape, terminal]);
+};

package/src/hooks/use-virtual-scroll.ts

@@ -0,0 +1,84 @@
+import { useCallback, useEffect, useState } from "react";
+
+import {
+  virtualScrollWindow,
+  type VirtualScrollOptions,
+  type VirtualScrollWindow,
+} from "#/virtual-scroll.ts";
+
+export type UseVirtualScrollOptions = Omit<VirtualScrollOptions, "scrollTop">;
+
+export type UseVirtualScrollResult = VirtualScrollWindow & {
+  /**
+	Scroll so the viewport starts `top` rows from the top of the list.
+	*/
+  readonly scrollTo: (top: number) => void;
+
+  /**
+	Scroll by `delta` rows; negative values scroll up.
+	*/
+  readonly scrollBy: (delta: number) => void;
+};
+
+/**
+A React hook that owns the scroll position of a windowed list and returns which
+items to render for it. The position is clamped to the scrollable range and,
+while `focusedIndex` is set, moved as little as necessary to keep that item
+fully visible. Render the items in `[start, end)` inside an `overflowY="hidden"`
+box of `viewportHeight` rows, shifted up by `offset` rows.
+
+`<VirtualList>` wraps this hook; use it directly to draw your own chrome such
+as overflow markers or a scrollbar around the window.
+
+@example
+```tsx
+import { Box, Text, useVirtualScroll } from "@alchemy.run/sigil";
+
+const Example = ({ lines, cursor }: { lines: string[]; cursor: number }) => {
+	const { start, end, offset, hiddenAbove, hiddenBelow } = useVirtualScroll({
+		count: lines.length,
+		itemHeight: () => 1,
+		viewportHeight: 10,
+		focusedIndex: cursor,
+	});
+
+	return (
+		<Box flexDirection="column">
+			<Text dimColor>{hiddenAbove > 0 ? `↑ ${hiddenAbove} more` : ""}</Text>
+			<Box flexDirection="column" height={10} overflowY="hidden">
+				<Box flexDirection="column" flexShrink={0} marginTop={offset}>
+					{lines.slice(start, end).map((line, index) => (
+						<Text key={start + index} inverse={start + index === cursor}>
+							{line}
+						</Text>
+					))}
+				</Box>
+			</Box>
+			<Text dimColor>{hiddenBelow > 0 ? `↓ ${hiddenBelow} more` : ""}</Text>
+		</Box>
+	);
+};
+```
+*/
+export const useVirtualScroll = (options: UseVirtualScrollOptions): UseVirtualScrollResult => {
+  const [position, setPosition] = useState(0);
+  const window = virtualScrollWindow({ ...options, scrollTop: position });
+
+  // Persist clamping and follow-focus corrections so the next scroll starts
+  // from where the viewport actually is, not from the stale request.
+  useEffect(() => {
+    if (window.scrollTop !== position) {
+      setPosition(window.scrollTop);
+    }
+  }, [window.scrollTop, position]);
+
+  const scrollTo = useCallback((top: number) => {
+    setPosition(top);
+  }, []);
+
+  const scrollBy = useCallback((delta: number) => {
+    setPosition((current) => current + delta);
+  }, []);
+
+  return { ...window, scrollTo, scrollBy };
+};

package/src/hooks/use-window-size.ts

@@ -0,0 +1,37 @@
+import { useMemo, useSyncExternalStore } from "react";
+
+import { getCapabilities } from "#/capabilities/store.ts";
+import { useStdinContext } from "#/hooks/use-stdin.ts";
+import { useStdout } from "#/hooks/use-stdout.ts";
+
+/**
+Dimensions of the terminal window.
+*/
+export type WindowSize = {
+  /**
+	Number of columns (horizontal character cells).
+	*/
+  readonly columns: number;
+
+  /**
+	Number of rows (vertical character cells).
+	*/
+  readonly rows: number;
+};
+
+/**
+A React hook that returns the current terminal window dimensions and re-renders the component whenever the terminal is resized.
+
+Reads the capabilities store, so on terminals that send in-band size reports
+(mode 2048) the dimensions are the emulator's own, arriving after it has
+rewrapped its screen; elsewhere they are the stream's `columns`/`rows`.
+Subscribing to dimensions does not initiate capability queries. In-band reports
+are used when another consumer has explicitly enabled capability discovery.
+*/
+export const useWindowSize = (): WindowSize => {
+  const { stdin } = useStdinContext();
+  const { stdout } = useStdout();
+  const store = getCapabilities(stdin, stdout);
+  const { size } = useSyncExternalStore(store.subscribe, () => store.current);
+  return useMemo(() => ({ columns: size.columns, rows: size.rows }), [size.columns, size.rows]);
+};

package/src/index.ts

@@ -0,0 +1,96 @@
+export type { RenderOptions, Instance } from "#/render.ts";
+export type { CapturedOutputSource } from "#/ink.tsx";
+export { render } from "#/render.ts";
+export type { RenderToStringOptions } from "#/render-to-string.ts";
+export { renderToString } from "#/render-to-string.ts";
+export type { Props as BoxProps } from "#/components/Box.tsx";
+export { Box } from "#/components/Box.tsx";
+export type { Props as TextProps } from "#/components/Text.tsx";
+export { Text } from "#/components/Text.tsx";
+export type { Props as AnsiTextProps } from "#/components/AnsiText.tsx";
+export { AnsiText } from "#/components/AnsiText.tsx";
+export type { Props as AppProps } from "#/components/AppContext.ts";
+export type { PublicProps as StdinProps } from "#/components/StdinContext.ts";
+export type { Props as StdoutProps } from "#/components/StdoutContext.ts";
+export type { Props as StderrProps } from "#/components/StderrContext.ts";
+export type { Props as StaticProps } from "#/components/Static.tsx";
+export { Static } from "#/components/Static.tsx";
+export type { Props as TransformProps } from "#/components/Transform.tsx";
+export { Transform } from "#/components/Transform.tsx";
+export type { Props as HyperlinkProps } from "#/components/Hyperlink.tsx";
+export { Hyperlink } from "#/components/Hyperlink.tsx";
+export type { Props as NewlineProps } from "#/components/Newline.tsx";
+export { Newline } from "#/components/Newline.tsx";
+export { Spacer } from "#/components/Spacer.tsx";
+export type { Props as VirtualListProps } from "#/components/VirtualList.tsx";
+export { VirtualList } from "#/components/VirtualList.tsx";
+// Keep the Ink-compatible root surface fixed. New terminal-core APIs live on
+// their focused subpaths rather than leaking through this entry point.
+export type {
+  Capabilities,
+  ColorInfo,
+  ColorSupport,
+  ColorSupportLevel,
+  Multiplexer,
+  PixelGeometry,
+  RgbColor,
+  TerminalAppearance,
+  TerminalIdentity,
+} from "#/capabilities/detect.ts";
+export {
+  createSupportsColor,
+  detectCapabilities,
+  detectColorLevel,
+  detectHyperlinkSupport,
+  detectTerminal,
+  detectUnicodeSupport,
+} from "#/capabilities/detect.ts";
+export type { PixelSize, TerminalQueryOptions, TerminalQueryResult } from "#/capabilities/query.ts";
+export {
+  applyTerminalQuery,
+  getTerminalQuery,
+  queryTerminal,
+  refreshTerminalQuery,
+} from "#/capabilities/query.ts";
+export type { CapabilitiesStore } from "#/capabilities/store.ts";
+export { capabilities, getCapabilities } from "#/capabilities/store.ts";
+export { useCapabilities, useCapabilitiesChange } from "#/hooks/use-capabilities.ts";
+export type { Key } from "#/hooks/use-input.ts";
+export { useInput } from "#/hooks/use-input.ts";
+export { usePaste } from "#/hooks/use-paste.ts";
+export type { SuspendTerminal, TerminalSuspension } from "#/components/AppContext.ts";
+export { useApp } from "#/hooks/use-app.ts";
+export { useStdin } from "#/hooks/use-stdin.ts";
+export { useStdout } from "#/hooks/use-stdout.ts";
+export { useStderr } from "#/hooks/use-stderr.ts";
+export { useFocus } from "#/hooks/use-focus.ts";
+export { useFocusManager } from "#/hooks/use-focus-manager.ts";
+export { useIsScreenReaderEnabled } from "#/hooks/use-is-screen-reader-enabled.ts";
+export { useCursor } from "#/hooks/use-cursor.ts";
+export type { AnimationResult } from "#/hooks/use-animation.ts";
+export { useAnimation } from "#/hooks/use-animation.ts";
+export type { ProgressOptions } from "#/hooks/use-terminal-osc.ts";
+export {
+  useClipboard,
+  useNotification,
+  usePointerShape,
+  useProgress,
+  useTitle,
+  useWorkingDirectory,
+} from "#/hooks/use-terminal-osc.ts";
+export type { WindowSize } from "#/hooks/use-window-size.ts";
+export { useWindowSize } from "#/hooks/use-window-size.ts";
+export type { BoxMetrics, UseBoxMetricsResult } from "#/hooks/use-box-metrics.ts";
+export { useBoxMetrics } from "#/hooks/use-box-metrics.ts";
+export type { VirtualScrollWindow } from "#/virtual-scroll.ts";
+export type {
+  UseVirtualScrollOptions,
+  UseVirtualScrollResult,
+} from "#/hooks/use-virtual-scroll.ts";
+export { useVirtualScroll } from "#/hooks/use-virtual-scroll.ts";
+export type { CursorPosition } from "#/cursor-position.ts";
+export { measureElement } from "#/measure-element.ts";
+export type { ElementMetrics } from "#/measure-element.ts";
+export type { DOMElement } from "#/dom.ts";
+export { kittyFlags, kittyModifiers } from "#/kitty-keyboard.ts";
+export type { KittyKeyboardOptions, KittyFlagName } from "#/kitty-keyboard.ts";