@alchemy.run/sigil 0.0.0-alpha.8 → 0.1.0-alpha.1

package/dist/index.d.ts

@@ -8,10 +8,10 @@ import { n as Text, r as Styles, t as Props$8 } from "./Text-DV9CuzAT.js";
 import { i as Node } from "./index-DDVME65c.js";
 import { t as CursorPosition } from "./cursor-position-D2LAkRG0.js";
 import { Writable } from "node:stream";
-import { PropsWithChildren, ReactNode, Ref, RefObject } from "react";
 import { EventEmitter } from "node:events";
+import { Key as Key$1, PropsWithChildren, ReactNode, Ref, RefObject } from "react";
 //#region src/kitty-keyboard.d.ts
-declare const kittyFlags: {
+export declare const kittyFlags: {
   readonly disambiguateEscapeCodes: 1;
   readonly reportEventTypes: 2;
   readonly reportAlternateKeys: 4;
@@ -19,7 +19,7 @@ declare const kittyFlags: {
   readonly reportAssociatedText: 16;
 };
 type KittyFlagName = keyof typeof kittyFlags;
-declare const kittyModifiers: {
+export declare const kittyModifiers: {
   readonly shift: 1;
   readonly alt: 2;
   readonly ctrl: 4;
@@ -263,7 +263,7 @@ type Instance = {
 /**
 Mount a component and render the output.
 */
-declare const render: (node: ReactNode, options?: Writable | RenderOptions) => Instance;
+export declare const render: (node: ReactNode, options?: Writable | RenderOptions) => Instance;
 //#endregion
 //#region src/render-to-string.d.ts
 type RenderToStringOptions = {
@@ -306,7 +306,7 @@ const output = renderToString(
 console.log(output);
 ```
 */
-declare const renderToString: (node: ReactNode, options?: RenderToStringOptions) => string;
+export declare const renderToString: (node: ReactNode, options?: RenderToStringOptions) => string;
 //#endregion
 //#region src/semantic-text-style.d.ts
 type SemanticTextStyle = {
@@ -405,7 +405,7 @@ type Props$2 = Omit<Styles, "textWrap"> & {
 /**
 `<Box>` is an essential Ink component to build your layout. It's like `<div style="display: flex">` in the browser.
 */
-declare function Box({ children, ref, backgroundColor, "aria-label": ariaLabel, "aria-hidden": ariaHidden, "aria-role": role, "aria-state": ariaState, ...style }: PropsWithChildren<Props$2> & {
+export declare function Box({ children, ref, backgroundColor, "aria-label": ariaLabel, "aria-hidden": ariaHidden, "aria-role": role, "aria-state": ariaState, ...style }: PropsWithChildren<Props$2> & {
   readonly ref?: Ref<DOMElement>;
 }): import("react").JSX.Element | null;
 //#endregion
@@ -421,7 +421,7 @@ type Props = {
  * Renders explicitly trusted ANSI-styled output as structured terminal cells.
  * Ordinary `Text` continues to strip terminal control sequences.
  */
-declare function AnsiText({ children, wrap, "aria-label": ariaLabel, "aria-hidden": ariaHidden }: Props): import("react").JSX.Element | null;
+export declare function AnsiText({ children, wrap, "aria-label": ariaLabel, "aria-hidden": ariaHidden }: Props): import("react").JSX.Element | null;
 //#endregion
 //#region src/components/AppContext.d.ts
 /**
@@ -565,7 +565,7 @@ It's preferred to use `<Static>` for use cases like these when you can't know or
 
 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.
 */
-declare function Static<T>(props: Props$5<T>): import("react").JSX.Element;
+export declare function Static<T>(props: Props$5<T>): import("react").JSX.Element;
 //#endregion
 //#region src/components/Transform.d.ts
 type Props$9 = {
@@ -582,7 +582,7 @@ type Props$9 = {
 /**
 Transform a string representation of React components before they're written to output. For example, you might want to apply a gradient to text, add a clickable link, or create some text effects. These use cases can't accept React nodes as input; they expect a string. That's what the <Transform> component does: it gives you an output string of its child components and lets you transform it in any way.
 */
-declare function Transform({ children, transform, accessibilityLabel }: Props$9): import("react").JSX.Element | null;
+export declare function Transform({ children, transform, accessibilityLabel }: Props$9): import("react").JSX.Element | null;
 //#endregion
 //#region src/components/Hyperlink.d.ts
 type Props$3 = Omit<Props$8, "children"> & {
@@ -609,7 +609,7 @@ back to `text (url)`.
 <Hyperlink url="https://example.com">Documentation</Hyperlink>
 ```
 */
-declare function Hyperlink({ url, fallback, children, ...textProps }: Props$3): import("react").JSX.Element;
+export declare function Hyperlink({ url, fallback, children, ...textProps }: Props$3): import("react").JSX.Element;
 //#endregion
 //#region src/components/Newline.d.ts
 /** @jsxImportSource react */
@@ -624,7 +624,7 @@ type Props$4 = {
 /**
 Adds one or more newline (`\n`) characters. Must be used within `<Text>` components.
 */
-declare function Newline({ count }: Props$4): import("react").JSX.Element;
+export declare function Newline({ count }: Props$4): import("react").JSX.Element;
 //#endregion
 //#region src/components/Spacer.d.ts
 /**
@@ -632,7 +632,49 @@ 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.
 */
-declare function Spacer(): import("react").JSX.Element;
+export declare function Spacer(): import("react").JSX.Element;
+//#endregion
+//#region src/components/VirtualList.d.ts
+type Props$10<Item> = {
+  /**
+      Items to window over.
+      */
+  readonly items: ReadonlyArray<Item>;
+  /**
+      Height of an item in rows. It must match what `renderItem` produces for it:
+      the window is computed from these numbers, never from the rendered output.
+      */
+  readonly itemHeight: (item: Item, index: number) => number;
+  /**
+      Render one item. Only items intersecting the viewport are rendered.
+      */
+  readonly renderItem: (item: Item, index: number) => ReactNode;
+  /**
+      React key for an item. Defaults to its index.
+      */
+  readonly getKey?: (item: Item, index: number) => Key$1;
+  /**
+      Item to keep fully visible. When it changes, the list scrolls as little as
+      necessary to show it.
+      */
+  readonly focusedIndex?: number;
+  /**
+      Viewport height in rows. When omitted the list takes the height of its
+      content and shrinks to whatever space its container leaves: bound an
+      ancestor (`height` or `maxHeight`) and give the siblings that must keep
+      their size `flexShrink={0}`.
+      */
+  readonly height?: number;
+};
+/**
+A vertically windowed list: only the items intersecting the viewport are
+rendered, inside a clipped box that scrolls by whole rows. Items may have
+different heights, and the item at the top edge may be partially visible.
+
+Until the first layout pass has measured the viewport, every item is rendered
+inside the clipped box so the first frame already looks right.
+*/
+export declare function VirtualList<Item>({ items, itemHeight, renderItem, getKey, focusedIndex, height }: Props$10<Item>): import("react").JSX.Element;
 //#endregion
 //#region src/hooks/use-capabilities.d.ts
 /**
@@ -645,7 +687,7 @@ 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.
 */
-declare const useCapabilities: () => Capabilities;
+export declare const useCapabilities: () => Capabilities;
 /**
 Calls `onChange` whenever the terminal changes: resizes (including in-band
 pixel geometry), color scheme switches, window focus, and query answers
@@ -664,7 +706,7 @@ useCapabilitiesChange((next, previous) => {
 });
 ```
 */
-declare const useCapabilitiesChange: (onChange: (capabilities: Capabilities, previous: Capabilities) => void) => void;
+export declare const useCapabilitiesChange: (onChange: (capabilities: Capabilities, previous: Capabilities) => void) => void;
 //#endregion
 //#region src/hooks/use-input.d.ts
 /**
@@ -797,7 +839,7 @@ const UserInput = () => {
 };
 ```
 */
-declare const useInput: (inputHandler: Handler, options?: Options$2) => void;
+export declare const useInput: (inputHandler: Handler, options?: Options$2) => void;
 //#endregion
 //#region src/hooks/use-paste.d.ts
 type Options$1 = {
@@ -833,31 +875,31 @@ const MyInput = () => {
 };
 ```
 */
-declare const usePaste: (handler: (text: string) => void, options?: Options$1) => void;
+export declare const usePaste: (handler: (text: string) => void, options?: Options$1) => void;
 //#endregion
 //#region src/hooks/use-app.d.ts
 /**
 A React hook that returns app lifecycle methods like `exit()` and `waitUntilRenderFlush()`.
 */
-declare const useApp: () => Props$1;
+export declare const useApp: () => Props$1;
 //#endregion
 //#region src/hooks/use-stdin.d.ts
 /**
 A React hook that returns the stdin stream and stdin-related utilities.
 */
-declare const useStdin: () => PublicProps;
+export declare const useStdin: () => PublicProps;
 //#endregion
 //#region src/hooks/use-stdout.d.ts
 /**
 A React hook that returns the stdout stream where Ink renders your app.
 */
-declare const useStdout: () => Props$7;
+export declare const useStdout: () => Props$7;
 //#endregion
 //#region src/hooks/use-stderr.d.ts
 /**
 A React hook that returns the stderr stream.
 */
-declare const useStderr: () => Props$6;
+export declare const useStderr: () => Props$6;
 //#endregion
 //#region src/hooks/use-focus.d.ts
 type Input = {
@@ -888,10 +930,10 @@ type Output$2 = {
 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.
 */
-declare const useFocus: ({ isActive, autoFocus, id: customId }?: Input) => Output$2;
+export declare const useFocus: ({ isActive, autoFocus, id: customId }?: Input) => Output$2;
 //#endregion
 //#region src/components/FocusContext.d.ts
-type Props$10 = {
+type Props$11 = {
   readonly activeId?: string;
   readonly add: (id: string, options: {
     autoFocus: boolean;
@@ -911,23 +953,23 @@ type Output$1 = {
   /**
       Enable focus management for all components.
       */
-  enableFocus: Props$10["enableFocus"];
+  enableFocus: Props$11["enableFocus"];
   /**
       Disable focus management for all components. The currently active component (if there's one) will lose its focus.
       */
-  disableFocus: Props$10["disableFocus"];
+  disableFocus: Props$11["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$10["focusNext"];
+  focusNext: Props$11["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$10["focusPrevious"];
+  focusPrevious: Props$11["focusPrevious"];
   /**
       Switch focus to the element with provided `id`. If there's no element with that `id`, focus is not changed.
       */
-  focus: Props$10["focus"];
+  focus: Props$11["focus"];
   /**
       The ID of the currently focused component, or `undefined` if no component is focused.
   
@@ -942,19 +984,19 @@ type Output$1 = {
       };
       ```
       */
-  activeId: Props$10["activeId"];
+  activeId: Props$11["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.
 */
-declare const useFocusManager: () => Output$1;
+export declare const useFocusManager: () => Output$1;
 //#endregion
 //#region src/hooks/use-is-screen-reader-enabled.d.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.
 */
-declare const useIsScreenReaderEnabled: () => boolean;
+export declare const useIsScreenReaderEnabled: () => boolean;
 //#endregion
 //#region src/hooks/use-cursor.d.ts
 /**
@@ -964,7 +1006,7 @@ Setting a cursor position makes the cursor visible at the specified coordinates
 
 Pass `undefined` to hide the cursor.
 */
-declare const useCursor: () => {
+export declare const useCursor: () => {
   setCursorPosition: (position: CursorPosition | undefined) => void;
 };
 //#endregion
@@ -1016,19 +1058,19 @@ const Spinner = () => {
 };
 ```
 */
-declare function useAnimation(options?: Options): AnimationResult;
+export declare function useAnimation(options?: Options): AnimationResult;
 //#endregion
 //#region src/hooks/use-terminal-osc.d.ts
 type ProgressOptions = {
   readonly state: TerminalProgressState;
   readonly value?: number;
 };
-declare const useProgress: ({ state, value }: ProgressOptions) => void;
-declare const useClipboard: () => ((text: string, selection?: ClipboardSelection) => void);
-declare const useTitle: (title?: string) => void;
-declare const useWorkingDirectory: (directory: URL | string) => void;
-declare const useNotification: () => ((title: string) => void);
-declare const usePointerShape: (shape: string) => void;
+export declare const useProgress: ({ state, value }: ProgressOptions) => void;
+export declare const useClipboard: () => ((text: string, selection?: ClipboardSelection) => void);
+export declare const useTitle: (title?: string) => void;
+export declare const useWorkingDirectory: (directory: URL | string) => void;
+export declare const useNotification: () => ((title: string) => void);
+export declare const usePointerShape: (shape: string) => void;
 //#endregion
 //#region src/hooks/use-window-size.d.ts
 /**
@@ -1050,8 +1092,10 @@ A React hook that returns the current terminal window dimensions and re-renders
 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.
 */
-declare const useWindowSize: () => WindowSize;
+export declare const useWindowSize: () => WindowSize;
 //#endregion
 //#region src/hooks/use-box-metrics.d.ts
 /**
@@ -1109,7 +1153,130 @@ const Example = () => {
 };
 ```
 */
-declare const useBoxMetrics: (ref: RefObject<DOMElement | null>) => UseBoxMetricsResult;
+export declare const useBoxMetrics: (ref: RefObject<DOMElement | null>) => UseBoxMetricsResult;
+//#endregion
+//#region src/virtual-scroll.d.ts
+/**
+Windowing math shared by `useVirtualScroll` and `<VirtualList>`.
+
+Items are stacked vertically and measured in terminal rows. The viewport shows
+`viewportHeight` rows of that stack starting `scrollTop` rows from the top.
+*/
+type VirtualScrollOptions = {
+  /**
+      Number of items in the list.
+      */
+  readonly count: number;
+  /**
+      Height of the item at `index` in rows. It must match what the item renders:
+      the window is computed from these numbers, never from the rendered output.
+      */
+  readonly itemHeight: (index: number) => number;
+  /**
+      Rows available to show items.
+      */
+  readonly viewportHeight: number;
+  /**
+      Requested distance of the viewport from the top of the list in rows. It is
+      clamped to the scrollable range and then moved as little as necessary to keep
+      `focusedIndex` fully visible.
+      */
+  readonly scrollTop: number;
+  /**
+      Item that must stay fully visible. An item taller than the viewport is aligned
+      to the top. Out-of-range values are ignored.
+      */
+  readonly focusedIndex?: number;
+};
+type VirtualScrollWindow = {
+  /**
+      Index of the first item that intersects the viewport.
+      */
+  readonly start: number;
+  /**
+      Index after the last item that intersects the viewport.
+      */
+  readonly end: number;
+  /**
+      Effective distance of the viewport from the top of the list in rows.
+      */
+  readonly scrollTop: number;
+  /**
+      Largest `scrollTop` that still fills the viewport.
+      */
+  readonly maxScrollTop: number;
+  /**
+      Height of every item combined in rows.
+      */
+  readonly totalHeight: number;
+  /**
+      Position of the `start` item relative to the top of the viewport. Zero or
+      negative: a negative value means the item is partially scrolled out above.
+      */
+  readonly offset: number;
+  /**
+      Rows scrolled out above the viewport.
+      */
+  readonly hiddenAbove: number;
+  /**
+      Rows left below the viewport.
+      */
+  readonly hiddenBelow: number;
+};
+//#endregion
+//#region src/hooks/use-virtual-scroll.d.ts
+type UseVirtualScrollOptions = Omit<VirtualScrollOptions, "scrollTop">;
+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 declare const useVirtualScroll: (options: UseVirtualScrollOptions) => UseVirtualScrollResult;
 //#endregion
 //#region src/measure-element.d.ts
 type Output = {
@@ -1138,6 +1305,6 @@ Returns an object with `x`, `y`, `width`, and `height` properties.
 
 Note: `measureElement()` returns `{x: 0, y: 0, width: 0, height: 0}` when called during render (before layout is calculated). Call it from post-render code, such as `useEffect`, `useLayoutEffect`, input handlers, or timer callbacks. When content changes, pass the relevant dependency to your effect so it re-measures after each update.
 */
-declare const measureElement: (node: DOMElement) => Output;
+export declare const measureElement: (node: DOMElement) => Output;
 //#endregion
-export { type AnimationResult, AnsiText, type Props as AnsiTextProps, type Props$1 as AppProps, Box, type BoxMetrics, type Props$2 as BoxProps, type Capabilities, type CapabilitiesStore, type CapturedOutputSource, type ColorInfo, type ColorSupport, type ColorSupportLevel, type CursorPosition, type DOMElement, type Output as ElementMetrics, Hyperlink, type Props$3 as HyperlinkProps, type Instance, type Key, type KittyFlagName, type KittyKeyboardOptions, type Multiplexer, Newline, type Props$4 as NewlineProps, type PixelGeometry, type PixelSize, type ProgressOptions, type RenderOptions, type RenderToStringOptions, type RgbColor, Spacer, Static, type Props$5 as StaticProps, type Props$6 as StderrProps, type PublicProps as StdinProps, type Props$7 as StdoutProps, type SuspendTerminal, type TerminalAppearance, type TerminalIdentity, type TerminalQueryOptions, type TerminalQueryResult, type TerminalSuspension, Text, type Props$8 as TextProps, Transform, type Props$9 as TransformProps, type UseBoxMetricsResult, type WindowSize, applyTerminalQuery, capabilities, createSupportsColor, detectCapabilities, detectColorLevel, detectHyperlinkSupport, detectTerminal, detectUnicodeSupport, getCapabilities, getTerminalQuery, kittyFlags, kittyModifiers, measureElement, queryTerminal, refreshTerminalQuery, render, renderToString, useAnimation, useApp, useBoxMetrics, useCapabilities, useCapabilitiesChange, useClipboard, useCursor, useFocus, useFocusManager, useInput, useIsScreenReaderEnabled, useNotification, usePaste, usePointerShape, useProgress, useStderr, useStdin, useStdout, useTitle, useWindowSize, useWorkingDirectory };
+export { type AnimationResult, type Props as AnsiTextProps, type Props$1 as AppProps, type BoxMetrics, type Props$2 as BoxProps, type Capabilities, type CapabilitiesStore, type CapturedOutputSource, type ColorInfo, type ColorSupport, type ColorSupportLevel, type CursorPosition, type DOMElement, type Output as ElementMetrics, type Props$3 as HyperlinkProps, type Instance, type Key, type KittyFlagName, type KittyKeyboardOptions, type Multiplexer, type Props$4 as NewlineProps, type PixelGeometry, type PixelSize, type ProgressOptions, type RenderOptions, type RenderToStringOptions, type RgbColor, type Props$5 as StaticProps, type Props$6 as StderrProps, type PublicProps as StdinProps, type Props$7 as StdoutProps, type SuspendTerminal, type TerminalAppearance, type TerminalIdentity, type TerminalQueryOptions, type TerminalQueryResult, type TerminalSuspension, Text, type Props$8 as TextProps, type Props$9 as TransformProps, type UseBoxMetricsResult, type UseVirtualScrollOptions, type UseVirtualScrollResult, type Props$10 as VirtualListProps, type VirtualScrollWindow, type WindowSize, applyTerminalQuery, capabilities, createSupportsColor, detectCapabilities, detectColorLevel, detectHyperlinkSupport, detectTerminal, detectUnicodeSupport, getCapabilities, getTerminalQuery, queryTerminal, refreshTerminalQuery };