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

package/src/hooks/use-input.ts

@@ -0,0 +1,267 @@
+import { useEffect, useEffectEvent } from "react";
+
+import { ESC } from "../ansi/escapes.ts";
+import { parseKeypress, nonAlphanumericKeys } from "../parse-keypress.ts";
+import { reconciler } from "../reconciler.ts";
+import { useStdinContext } from "./use-stdin.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;
+};

package/src/hooks/use-paste.ts

@@ -0,0 +1,78 @@
+import { useEffect, useEffectEvent } from "react";
+
+import { reconciler } from "../reconciler.ts";
+import { useStdinContext } from "./use-stdin.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-window-size.ts

@@ -0,0 +1,41 @@
+import { useState, useEffect } from "react";
+
+import { getWindowSize } from "../utils.ts";
+import { useStdout } from "./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.
+*/
+export const useWindowSize = (): WindowSize => {
+  const { stdout } = useStdout();
+  const [size, setSize] = useState<WindowSize>(() => getWindowSize(stdout));
+
+  useEffect(() => {
+    const onResize = () => {
+      setSize(getWindowSize(stdout));
+    };
+
+    stdout.on("resize", onResize);
+
+    return () => {
+      stdout.off("resize", onResize);
+    };
+  }, [stdout]);
+
+  return size;
+};

package/src/indent-string.ts

@@ -0,0 +1,16 @@
+// Derived from `indent-string` (MIT, Sindre Sorhus), reduced to the surface Ink uses.
+export const indentString = (
+  string: string,
+  count = 1,
+  options: { indent?: string; includeEmptyLines?: boolean } = {},
+): string => {
+  const { indent = " ", includeEmptyLines = false } = options;
+
+  if (count === 0) {
+    return string;
+  }
+
+  const regex = includeEmptyLines ? /^/gm : /^(?!\s*$)/gm;
+
+  return string.replace(regex, indent.repeat(count));
+};

package/src/index.ts

@@ -0,0 +1,44 @@
+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 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 NewlineProps } from "./components/Newline.tsx";
+export { Newline } from "./components/Newline.tsx";
+export { Spacer } from "./components/Spacer.tsx";
+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 { 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 { CursorPosition } from "./log-update.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";