@semos-labs/glyph 0.1.81 → 0.1.82

package/dist/index.d.ts

@@ -185,6 +185,50 @@ interface AppHandle {
     exit(code?: number): void;
 }
 
+type GlyphNodeType = "box" | "text" | "input";
+type GlyphChild = GlyphNode | GlyphTextInstance;
+interface GlyphNode {
+    type: GlyphNodeType;
+    props: Record<string, any>;
+    style: Style;
+    children: GlyphNode[];
+    rawTextChildren: GlyphTextInstance[];
+    /** All children in order (both nodes and raw text) for correct text composition */
+    allChildren: GlyphChild[];
+    parent: GlyphNode | null;
+    yogaNode: Node | null;
+    text: string | null;
+    layout: LayoutRect;
+    focusId: string | null;
+    hidden: boolean;
+}
+interface GlyphTextInstance {
+    type: "raw-text";
+    text: string;
+    parent: GlyphNode | null;
+}
+
+/**
+ * Options for {@link ScrollViewContextValue.scrollTo} and
+ * {@link FocusableHandle.scrollIntoView}.
+ *
+ * @example
+ * ```tsx
+ * ref.current?.scrollIntoView({ block: "center" });
+ * ```
+ * @category Types
+ */
+interface ScrollIntoViewOptions {
+    /**
+     * Where to align the element relative to the viewport.
+     * - `"nearest"` — minimal scroll to make visible (default)
+     * - `"start"` — align element top with viewport top
+     * - `"center"` — center element in viewport
+     * - `"end"` — align element bottom with viewport bottom
+     */
+    block?: "start" | "center" | "end" | "nearest";
+}
+
 /**
  * DOM-like imperative handles for focusable components.
  * Use these with React refs to programmatically control components.
@@ -213,6 +257,25 @@ interface FocusableHandle {
     blur(): void;
     /** Whether this element is currently focused */
     readonly isFocused: boolean;
+    /**
+     * Scroll the nearest parent {@link ScrollView} to make this element visible.
+     * Behaves like the DOM `Element.scrollIntoView()` method.
+     * No-op if the element is not inside a ScrollView.
+     *
+     * @param options - Alignment options (default: `{ block: "nearest" }`)
+     *
+     * @example
+     * ```tsx
+     * const inputRef = useRef<InputHandle>(null);
+     *
+     * // Minimal scroll — just enough to make it visible
+     * inputRef.current?.scrollIntoView();
+     *
+     * // Center the element in the viewport
+     * inputRef.current?.scrollIntoView({ block: "center" });
+     * ```
+     */
+    scrollIntoView(options?: ScrollIntoViewOptions): void;
 }
 /** Handle for Button */
 interface ButtonHandle extends FocusableHandle {
@@ -280,29 +343,6 @@ interface TextHandle extends FocusableHandle {
  */
 declare function render(element: ReactElement, opts?: RenderOptions): AppHandle;
 
-type GlyphNodeType = "box" | "text" | "input";
-type GlyphChild = GlyphNode | GlyphTextInstance;
-interface GlyphNode {
-    type: GlyphNodeType;
-    props: Record<string, any>;
-    style: Style;
-    children: GlyphNode[];
-    rawTextChildren: GlyphTextInstance[];
-    /** All children in order (both nodes and raw text) for correct text composition */
-    allChildren: GlyphChild[];
-    parent: GlyphNode | null;
-    yogaNode: Node | null;
-    text: string | null;
-    layout: LayoutRect;
-    focusId: string | null;
-    hidden: boolean;
-}
-interface GlyphTextInstance {
-    type: "raw-text";
-    text: string;
-    parent: GlyphNode | null;
-}
-
 /**
  * Props for the {@link Box} component.
  */
@@ -1636,6 +1676,31 @@ interface FocusRegistryValue {
  */
 declare function useFocusRegistry(): FocusRegistryValue | null;
 
+/**
+ * Returns a function that scrolls the nearest parent {@link ScrollView}
+ * to make the referenced node visible.
+ *
+ * This is the non-focusable counterpart to `handle.scrollIntoView()` —
+ * use it with plain `Box` refs or any `GlyphNode`.
+ *
+ * @param nodeRef - React ref pointing to the target node.
+ * @returns A stable callback you can invoke to scroll to the node.
+ *
+ * @example
+ * ```tsx
+ * const boxRef = useRef<GlyphNode>(null);
+ * const scrollIntoView = useScrollIntoView(boxRef);
+ *
+ * // Later, e.g. in an effect or event handler:
+ * scrollIntoView();                       // minimal scroll
+ * scrollIntoView({ block: "center" });    // center in viewport
+ * ```
+ * @category Hooks
+ */
+declare function useScrollIntoView(nodeRef: {
+    current: GlyphNode | null;
+}): (options?: ScrollIntoViewOptions) => void;
+
 /**
  * Input mask utilities for Glyph Input component.
  *
@@ -1769,4 +1834,4 @@ declare function detectTerminalCapabilities(debug?: boolean): TerminalCapabiliti
  */
 declare function supportsInlineImages(): boolean;
 
-export { type AlertOptions, type AnsiStyle, type AppHandle, type BorderStyle, Box, type BoxProps, Button, type ButtonHandle, type ButtonProps, Checkbox, type CheckboxHandle, type CheckboxProps, type Color, type ConfirmOptions, type DialogContextValue, DialogHost, type DialogHostProps, type DimensionValue, type FocusRegistryValue, FocusScope, type FocusScopeProps, type FocusableElement, type FocusableHandle, type HexColor, Image, type ImageHandle, type ImageProps, type ImageState, Input, type InputHandle, type InputProps, type InputType, JumpNav, type JumpNavProps, type Key, Keybind, type KeybindProps, type LayoutRect, List, type ListHandle, type ListItemInfo, type ListProps, type MaskOptions, Menu, type MenuItem, type MenuProps, type NamedColor, Portal, type PortalProps, Progress, type ProgressProps, type RGBColor, Radio, type RadioHandle, type RadioItem, type RadioProps, type RenderOptions, ScrollView, type ScrollViewProps, Select, type SelectHandle, type SelectItem, type SelectProps, Spacer, type SpacerProps, Spinner, type SpinnerProps, type Style, type StyledSegment, type TerminalCapabilities, Text, type TextAlign, type TextHandle, type TextProps, type Toast, ToastHost, type ToastHostProps, type ToastPosition, type ToastVariant, type UseFocusableOptions, type UseFocusableResult, type VisibleRange, type WrapMode, createMask, detectTerminalCapabilities, masks, parseAnsi, render, stripAnsi, supportsInlineImages, useApp, useDialog, useFocus, useFocusRegistry, useFocusable, useInput, useLayout, useToast };
+export { type AlertOptions, type AnsiStyle, type AppHandle, type BorderStyle, Box, type BoxProps, Button, type ButtonHandle, type ButtonProps, Checkbox, type CheckboxHandle, type CheckboxProps, type Color, type ConfirmOptions, type DialogContextValue, DialogHost, type DialogHostProps, type DimensionValue, type FocusRegistryValue, FocusScope, type FocusScopeProps, type FocusableElement, type FocusableHandle, type HexColor, Image, type ImageHandle, type ImageProps, type ImageState, Input, type InputHandle, type InputProps, type InputType, JumpNav, type JumpNavProps, type Key, Keybind, type KeybindProps, type LayoutRect, List, type ListHandle, type ListItemInfo, type ListProps, type MaskOptions, Menu, type MenuItem, type MenuProps, type NamedColor, Portal, type PortalProps, Progress, type ProgressProps, type RGBColor, Radio, type RadioHandle, type RadioItem, type RadioProps, type RenderOptions, type ScrollIntoViewOptions, ScrollView, type ScrollViewProps, Select, type SelectHandle, type SelectItem, type SelectProps, Spacer, type SpacerProps, Spinner, type SpinnerProps, type Style, type StyledSegment, type TerminalCapabilities, Text, type TextAlign, type TextHandle, type TextProps, type Toast, ToastHost, type ToastHostProps, type ToastPosition, type ToastVariant, type UseFocusableOptions, type UseFocusableResult, type VisibleRange, type WrapMode, createMask, detectTerminalCapabilities, masks, parseAnsi, render, stripAnsi, supportsInlineImages, useApp, useDialog, useFocus, useFocusRegistry, useFocusable, useInput, useLayout, useScrollIntoView, useToast };