giggles 0.6.1 → 0.7.0

package/README.md

@@ -4,7 +4,7 @@
 
 # giggles
 
-![giggles](https://github.com/user-attachments/assets/c5c7ef05-232f-4180-8b85-0160fb0f083a)
+<img src="https://github.com/user-attachments/assets/c5c7ef05-232f-4180-8b85-0160fb0f083a" width="700" alt="giggles">
 
 giggles is a batteries-included react framework for building terminal apps. built on ink, it handles focus, input routing, screen navigation, and theming out of the box so you can skip the plumbing and build.
 
@@ -30,3 +30,83 @@ npx create-giggles-app
 ```
 
 see [giggles.zzzzion.com](https://giggles.zzzzion.com) for API documentation and live demos.
+
+## giggles/ui
+
+### [select](https://giggles.zzzzion.com/ui/select)
+
+<img src="https://github.com/user-attachments/assets/8ce13f75-7a7b-4123-a973-f2992193bf84" width="500" alt="select">
+
+### [multi select](https://giggles.zzzzion.com/ui/multi-select)
+
+<img src="https://github.com/user-attachments/assets/24f5d625-6e46-4cb1-8d22-42d40eb48f56" width="500" alt="multi-select">
+
+### [markdown](https://giggles.zzzzion.com/ui/markdown)
+
+<img src="https://github.com/user-attachments/assets/1cdb6e84-c714-470a-8cf0-b6abf68b78a9" width="500" alt="markdown">
+
+### [text input](https://giggles.zzzzion.com/ui/text-input)
+
+<img src="https://github.com/user-attachments/assets/b56056ca-97e2-4dc2-a1eb-2ee3f4d559e7" width="500" alt="text-input">
+
+### [viewport](https://giggles.zzzzion.com/ui/viewport)
+
+<img src="https://github.com/user-attachments/assets/56c6cb6b-b2a7-4803-bed4-c6c6c34042c3" width="500" alt="viewport">
+
+### [code block](https://giggles.zzzzion.com/ui/codeblock)
+
+<img src="https://github.com/user-attachments/assets/283dbd7e-326c-4acb-b8c0-d3608722952b" width="500" alt="codeblock">
+
+### [confirm](https://giggles.zzzzion.com/ui/confirm)
+
+<img src="https://github.com/user-attachments/assets/b887da72-bf02-4084-b846-8b90cc3c3487" width="500" alt="confirm">
+
+### [spinner](https://giggles.zzzzion.com/ui/spinner)
+
+<img src="https://github.com/user-attachments/assets/71aef7f8-e53b-4876-864f-b9b1a5100c5d" width="500" alt="spinner">
+
+### [modal](https://giggles.zzzzion.com/ui/modal)
+
+<img src="https://github.com/user-attachments/assets/7415c554-927e-4b5c-91d7-7e3b1f4ea0ca" width="500" alt="modal">
+
+### [paginator](https://giggles.zzzzion.com/ui/paginator)
+
+<img src="https://github.com/user-attachments/assets/b0780f46-848e-4881-822a-86d7db02d212" width="500" alt="paginator">
+
+### [autocomplete](https://giggles.zzzzion.com/ui/autocomplete)
+
+<img src="https://github.com/user-attachments/assets/aa76dd7a-5357-4969-a979-95975b5ec578" width="500" alt="autocomplete">
+
+### [command palette](https://giggles.zzzzion.com/ui/command-palette)
+
+<img src="https://github.com/user-attachments/assets/30886cb5-986f-4477-85c1-61cba4b499aa" width="500" alt="command-palette">
+
+### [virtual list](https://giggles.zzzzion.com/ui/virtual-list)
+
+<img src="https://github.com/user-attachments/assets/d3ef1d92-813c-4546-8d60-2c38745ddbbc" width="500" alt="virtual-list">
+
+### [badge](https://giggles.zzzzion.com/ui/badge)
+
+<img src="https://github.com/user-attachments/assets/b144c3f5-8b3b-4236-abf2-fc239d23f0c6" width="500" alt="badge">
+
+### [panel](https://giggles.zzzzion.com/ui/panel)
+
+<img src="https://github.com/user-attachments/assets/9831d73a-baa9-410a-b933-e0dfd9433604" width="500" alt="panel">
+
+## giggles/terminal
+
+### [useShellOut](https://giggles.zzzzion.com/terminal#useshellout)
+
+suspend the UI, hand off the terminal to an external program like `vim` or `less`, and resume cleanly when it exits
+
+### [useSpawn](https://giggles.zzzzion.com/terminal#usespawn)
+
+spawn a child process and stream its stdout/stderr output into your UI — with support for colored output via a pty
+
+### [useTerminalSize](https://giggles.zzzzion.com/terminal#useterminalsize)
+
+reactively track the terminal's current dimensions (rows and columns), updating on resize
+
+### [useTerminalFocus](https://giggles.zzzzion.com/terminal#useterminalfocus)
+
+detect when the terminal window gains or loses focus

package/dist/{chunk-A7BRQXWE.js → chunk-74PBSWEK.js}

@@ -76,13 +76,14 @@ function useFocusNode(options) {
   const store = useStore();
   const contextParentId = useContext2(ScopeIdContext);
   const parentId = ((_a = options == null ? void 0 : options.parent) == null ? void 0 : _a.id) ?? contextParentId;
+  const focusKey = options == null ? void 0 : options.focusKey;
   const subscribe = useMemo(() => store.subscribe.bind(store), [store]);
   useEffect2(() => {
-    store.registerNode(id, parentId);
+    store.registerNode(id, parentId, focusKey);
     return () => {
       store.unregisterNode(id);
     };
-  }, [id, parentId, store]);
+  }, [id, parentId, focusKey, store]);
   const hasFocus = useSyncExternalStore2(subscribe, () => store.isFocused(id));
   return { id, hasFocus };
 }
@@ -128,13 +129,14 @@ function useFocusScope(options) {
   const store = useStore();
   const contextParentId = useContext3(ScopeIdContext);
   const parentId = ((_a = options == null ? void 0 : options.parent) == null ? void 0 : _a.id) ?? contextParentId;
+  const focusKey = options == null ? void 0 : options.focusKey;
   const subscribe = useMemo2(() => store.subscribe.bind(store), [store]);
   useEffect4(() => {
-    store.registerNode(id, parentId);
+    store.registerNode(id, parentId, focusKey);
     return () => {
       store.unregisterNode(id);
     };
-  }, [id, parentId, store]);
+  }, [id, parentId, focusKey, store]);
   const hasFocus = useSyncExternalStore3(subscribe, () => store.isFocused(id));
   const isPassive = useSyncExternalStore3(subscribe, () => store.isPassive(id));
   const next = useCallback(() => store.navigateSibling("next", true, id), [store, id]);
@@ -143,19 +145,46 @@ function useFocusScope(options) {
   const prevShallow = useCallback(() => store.navigateSibling("prev", true, id, true), [store, id]);
   const escape = useCallback(() => store.makePassive(id), [store, id]);
   const drillIn = useCallback(() => store.focusFirstChild(id), [store, id]);
-  const resolvedBindings = typeof (options == null ? void 0 : options.keybindings) === "function" ? options.keybindings({ next, prev, nextShallow, prevShallow, escape, drillIn }) : (options == null ? void 0 : options.keybindings) ?? {};
+  const focusChild = useCallback((key) => store.focusChildByKey(id, key, false), [store, id]);
+  const focusChildShallow = useCallback((key) => store.focusChildByKey(id, key, true), [store, id]);
+  const resolvedBindings = typeof (options == null ? void 0 : options.keybindings) === "function" ? options.keybindings({ next, prev, nextShallow, prevShallow, escape, drillIn, focusChild, focusChildShallow }) : (options == null ? void 0 : options.keybindings) ?? {};
   store.registerKeybindings(id, keybindingRegistrationId, resolvedBindings);
   useEffect4(() => {
     return () => {
       store.unregisterKeybindings(id, keybindingRegistrationId);
     };
   }, [id, keybindingRegistrationId, store]);
-  return { id, hasFocus, isPassive };
+  useEffect4(() => {
+    if (!store.hasFocusScopeComponent(id)) {
+      throw new GigglesError(
+        "useFocusScope() was called but no <FocusScope handle={scope}> was rendered. Every useFocusScope() call requires a corresponding <FocusScope> in the render output \u2014 without it, child components register under the wrong parent scope and keyboard navigation silently breaks."
+      );
+    }
+  }, [id, store]);
+  return {
+    id,
+    hasFocus,
+    isPassive,
+    next,
+    prev,
+    nextShallow,
+    prevShallow,
+    escape,
+    drillIn,
+    focusChild,
+    focusChildShallow
+  };
 }
 
 // src/core/focus/FocusScope.tsx
+import { useEffect as useEffect5 } from "react";
 import { jsx as jsx3 } from "react/jsx-runtime";
 function FocusScope({ handle, children }) {
+  const store = useStore();
+  useEffect5(() => {
+    store.registerFocusScopeComponent(handle.id);
+    return () => store.unregisterFocusScopeComponent(handle.id);
+  }, [handle.id, store]);
   return /* @__PURE__ */ jsx3(ScopeIdContext.Provider, { value: handle.id, children });
 }
 
@@ -191,6 +220,7 @@ var FocusStore = class {
   passiveSet = /* @__PURE__ */ new Set();
   pendingFocusFirstChild = /* @__PURE__ */ new Set();
   trapNodeId = null;
+  renderedScopes = /* @__PURE__ */ new Set();
   listeners = /* @__PURE__ */ new Set();
   version = 0;
   // nodeId → registrationId → BindingRegistration
@@ -198,6 +228,8 @@ var FocusStore = class {
   // A keybinding may exist for a node that has not yet appeared in the node tree —
   // this is safe because dispatch only walks nodes in the active branch path.
   keybindings = /* @__PURE__ */ new Map();
+  // parentId → focusKey → childId
+  keyIndex = /* @__PURE__ */ new Map();
   // ---------------------------------------------------------------------------
   // Subscription
   // ---------------------------------------------------------------------------
@@ -217,7 +249,7 @@ var FocusStore = class {
   // ---------------------------------------------------------------------------
   // Registration
   // ---------------------------------------------------------------------------
-  registerNode(id, parentId) {
+  registerNode(id, parentId, focusKey) {
     const node = { id, parentId, childrenIds: [] };
     this.nodes.set(id, node);
     this.parentMap.set(id, parentId);
@@ -237,6 +269,12 @@ var FocusStore = class {
         node.childrenIds.push(existingId);
       }
     }
+    if (focusKey && parentId) {
+      if (!this.keyIndex.has(parentId)) {
+        this.keyIndex.set(parentId, /* @__PURE__ */ new Map());
+      }
+      this.keyIndex.get(parentId).set(focusKey, id);
+    }
     if (this.nodes.size === 1) {
       this.focusNode(id);
     }
@@ -254,6 +292,21 @@ var FocusStore = class {
     this.nodes.delete(id);
     this.passiveSet.delete(id);
     this.pendingFocusFirstChild.delete(id);
+    if (node.parentId) {
+      const parentKeys = this.keyIndex.get(node.parentId);
+      if (parentKeys) {
+        for (const [key, childId] of parentKeys) {
+          if (childId === id) {
+            parentKeys.delete(key);
+            break;
+          }
+        }
+        if (parentKeys.size === 0) {
+          this.keyIndex.delete(node.parentId);
+        }
+      }
+    }
+    this.keyIndex.delete(id);
     if (this.focusedId === id) {
       let candidate = node.parentId;
       while (candidate !== null) {
@@ -301,6 +354,21 @@ var FocusStore = class {
       this.pendingFocusFirstChild.add(parentId);
     }
   }
+  focusChildByKey(parentId, key, shallow) {
+    var _a;
+    const childId = (_a = this.keyIndex.get(parentId)) == null ? void 0 : _a.get(key);
+    if (!childId || !this.nodes.has(childId)) return;
+    if (shallow) {
+      this.focusNode(childId);
+    } else {
+      const child = this.nodes.get(childId);
+      if (child.childrenIds.length > 0) {
+        this.focusFirstChild(childId);
+      } else {
+        this.focusNode(childId);
+      }
+    }
+  }
   // ---------------------------------------------------------------------------
   // Navigation
   // ---------------------------------------------------------------------------
@@ -396,6 +464,15 @@ var FocusStore = class {
   // ---------------------------------------------------------------------------
   // Trap
   // ---------------------------------------------------------------------------
+  registerFocusScopeComponent(id) {
+    this.renderedScopes.add(id);
+  }
+  unregisterFocusScopeComponent(id) {
+    this.renderedScopes.delete(id);
+  }
+  hasFocusScopeComponent(id) {
+    return this.renderedScopes.has(id);
+  }
   setTrap(nodeId) {
     this.trapNodeId = nodeId;
   }

package/dist/index.d.ts

@@ -41,17 +41,19 @@ type FocusScopeHandle = {
     id: string;
     hasFocus: boolean;
     isPassive: boolean;
-};
-type FocusScopeHelpers = {
     next: () => void;
     prev: () => void;
     nextShallow: () => void;
     prevShallow: () => void;
     escape: () => void;
     drillIn: () => void;
+    focusChild: (key: string) => void;
+    focusChildShallow: (key: string) => void;
 };
+type FocusScopeHelpers = Pick<FocusScopeHandle, 'next' | 'prev' | 'nextShallow' | 'prevShallow' | 'escape' | 'drillIn' | 'focusChild' | 'focusChildShallow'>;
 type FocusScopeOptions = {
     parent?: FocusScopeHandle;
+    focusKey?: string;
     keybindings?: Keybindings | ((helpers: FocusScopeHelpers) => Keybindings);
 };
 declare function useFocusScope(options?: FocusScopeOptions): FocusScopeHandle;
@@ -68,6 +70,7 @@ type FocusNodeHandle = {
 };
 type FocusNodeOptions = {
     parent?: FocusScopeHandle;
+    focusKey?: string;
 };
 declare function useFocusNode(options?: FocusNodeOptions): FocusNodeHandle;
 

package/dist/index.js

@@ -1,3 +1,6 @@
+import {
+  useTerminalSize
+} from "./chunk-WNGBTD67.js";
 import {
   FocusScope,
   FocusStore,
@@ -11,14 +14,11 @@ import {
   useKeybindingRegistry,
   useKeybindings,
   useStore
-} from "./chunk-A7BRQXWE.js";
+} from "./chunk-74PBSWEK.js";
 import {
   ThemeProvider,
   useTheme
 } from "./chunk-C77VBSPK.js";
-import {
-  useTerminalSize
-} from "./chunk-WNGBTD67.js";
 
 // src/core/GigglesProvider.tsx
 import { useRef } from "react";

package/dist/terminal/index.d.ts

@@ -4,6 +4,11 @@ type TerminalSize = {
     rows: number;
     columns: number;
 };
+type ShellOutHandle = {
+    run: (command: string) => Promise<{
+        exitCode: number;
+    }>;
+};
 type SpawnOptions = SpawnOptionsWithoutStdio & {
     /**
      * Inject FORCE_COLOR=1 and TERM=xterm-256color into the child process
@@ -28,12 +33,8 @@ declare function useTerminalSize(): TerminalSize;
 
 declare function useTerminalFocus(callback: (focused: boolean) => void): void;
 
-declare function useShellOut(): {
-    run: (command: string) => Promise<{
-        exitCode: number;
-    }>;
-};
+declare function useShellOut(): ShellOutHandle;
 
 declare function useSpawn(): SpawnHandle;
 
-export { type SpawnHandle, type SpawnOptions, type SpawnOutputLine, type TerminalSize, useShellOut, useSpawn, useTerminalFocus, useTerminalSize };
+export { type ShellOutHandle, type SpawnHandle, type SpawnOptions, type SpawnOutputLine, type TerminalSize, useShellOut, useSpawn, useTerminalFocus, useTerminalSize };

package/dist/ui/index.d.ts

@@ -31,8 +31,9 @@ type TextInputProps = {
     onSubmit?: (value: string) => void;
     placeholder?: string;
     render?: (props: TextInputRenderProps) => React$1.ReactNode;
+    focusKey?: string;
 };
-declare function TextInput({ label, value, onChange, onSubmit, placeholder, render }: TextInputProps): react_jsx_runtime.JSX.Element;
+declare function TextInput({ label, value, onChange, onSubmit, placeholder, render, focusKey }: TextInputProps): react_jsx_runtime.JSX.Element;
 
 type PaginatorStyle = 'dots' | 'arrows' | 'scrollbar' | 'counter' | 'none';
 type PaginatorProps = {
@@ -70,8 +71,9 @@ type SelectProps<T> = {
     paginatorStyle?: PaginatorStyle;
     wrap?: boolean;
     render?: (props: SelectRenderProps<T>) => React$1.ReactNode;
+    focusKey?: string;
 };
-declare function Select<T>({ options, value, onChange, onSubmit, onHighlight, label, immediate, direction, gap, maxVisible, paginatorStyle, wrap, render }: SelectProps<T>): react_jsx_runtime.JSX.Element;
+declare function Select<T>({ options, value, onChange, onSubmit, onHighlight, label, immediate, direction, gap, maxVisible, paginatorStyle, wrap, render, focusKey }: SelectProps<T>): react_jsx_runtime.JSX.Element;
 
 type MultiSelectRenderProps<T> = {
     option: SelectOption<T>;
@@ -92,15 +94,17 @@ type MultiSelectProps<T> = {
     paginatorStyle?: PaginatorStyle;
     wrap?: boolean;
     render?: (props: MultiSelectRenderProps<T>) => React$1.ReactNode;
+    focusKey?: string;
 };
-declare function MultiSelect<T>({ options, value, onChange, onSubmit, onHighlight, label, direction, gap, maxVisible, paginatorStyle, wrap, render }: MultiSelectProps<T>): react_jsx_runtime.JSX.Element;
+declare function MultiSelect<T>({ options, value, onChange, onSubmit, onHighlight, label, direction, gap, maxVisible, paginatorStyle, wrap, render, focusKey }: MultiSelectProps<T>): react_jsx_runtime.JSX.Element;
 
 type ConfirmProps = {
     message: string;
     defaultValue?: boolean;
     onSubmit: (value: boolean) => void;
+    focusKey?: string;
 };
-declare function Confirm({ message, defaultValue, onSubmit }: ConfirmProps): react_jsx_runtime.JSX.Element;
+declare function Confirm({ message, defaultValue, onSubmit, focusKey }: ConfirmProps): react_jsx_runtime.JSX.Element;
 
 type AutocompleteRenderProps<T> = {
     option: SelectOption<T>;
@@ -122,8 +126,9 @@ type AutocompleteProps<T> = {
     paginatorStyle?: PaginatorStyle;
     wrap?: boolean;
     render?: (props: AutocompleteRenderProps<T>) => React$1.ReactNode;
+    focusKey?: string;
 };
-declare function Autocomplete<T>({ options, value, onChange, onSubmit, onHighlight, label, placeholder, filter, gap, maxVisible, paginatorStyle, wrap, render }: AutocompleteProps<T>): react_jsx_runtime.JSX.Element;
+declare function Autocomplete<T>({ options, value, onChange, onSubmit, onHighlight, label, placeholder, filter, gap, maxVisible, paginatorStyle, wrap, render, focusKey }: AutocompleteProps<T>): react_jsx_runtime.JSX.Element;
 
 type VirtualListRenderProps<T> = {
     item: T;
@@ -160,6 +165,7 @@ declare const Viewport: React$1.ForwardRefExoticComponent<Omit<BoxProps, "flexDi
     height: number;
     keybindings?: boolean;
     footer?: React$1.ReactNode;
+    focusKey?: string;
 } & React$1.RefAttributes<ViewportRef>>;
 
 type ModalProps = Omit<BoxProps, 'children'> & {

package/dist/ui/index.js

@@ -4,7 +4,7 @@ import {
   useFocusNode,
   useKeybindingRegistry,
   useKeybindings
-} from "../chunk-A7BRQXWE.js";
+} from "../chunk-74PBSWEK.js";
 import {
   CodeBlock
 } from "../chunk-SKSDNDQF.js";
@@ -136,8 +136,8 @@ function CommandPalette({ onClose, interactive = true, render }) {
 import { useReducer, useRef } from "react";
 import { Text as Text2 } from "ink";
 import { Fragment as Fragment2, jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
-function TextInput({ label, value, onChange, onSubmit, placeholder, render }) {
-  const focus = useFocusNode();
+function TextInput({ label, value, onChange, onSubmit, placeholder, render, focusKey }) {
+  const focus = useFocusNode({ focusKey });
   const cursorRef = useRef(value.length);
   const [, forceRender] = useReducer((c) => c + 1, 0);
   const cursor = Math.min(cursorRef.current, value.length);
@@ -351,7 +351,8 @@ function Select({
   maxVisible,
   paginatorStyle,
   wrap = true,
-  render
+  render,
+  focusKey
 }) {
   const seen = /* @__PURE__ */ new Set();
   for (const opt of options) {
@@ -361,7 +362,7 @@ function Select({
     }
     seen.add(key);
   }
-  const focus = useFocusNode();
+  const focus = useFocusNode({ focusKey });
   const theme = useTheme();
   const [highlightIndex, setHighlightIndex] = useState3(0);
   const safeIndex = options.length === 0 ? -1 : Math.min(highlightIndex, options.length - 1);
@@ -438,7 +439,8 @@ function MultiSelect({
   maxVisible,
   paginatorStyle,
   wrap = true,
-  render
+  render,
+  focusKey
 }) {
   const seen = /* @__PURE__ */ new Set();
   for (const opt of options) {
@@ -448,7 +450,7 @@ function MultiSelect({
     }
     seen.add(key);
   }
-  const focus = useFocusNode();
+  const focus = useFocusNode({ focusKey });
   const theme = useTheme();
   const [highlightIndex, setHighlightIndex] = useState4(0);
   const [internalSelected, setInternalSelected] = useState4([]);
@@ -515,8 +517,8 @@ function MultiSelect({
 // src/ui/Confirm.tsx
 import { Text as Text6 } from "ink";
 import { jsxs as jsxs7 } from "react/jsx-runtime";
-function Confirm({ message, defaultValue = true, onSubmit }) {
-  const focus = useFocusNode();
+function Confirm({ message, defaultValue = true, onSubmit, focusKey }) {
+  const focus = useFocusNode({ focusKey });
   useKeybindings(focus, {
     y: () => onSubmit(true),
     n: () => onSubmit(false),
@@ -558,7 +560,8 @@ function Autocomplete({
   maxVisible,
   paginatorStyle,
   wrap = true,
-  render
+  render,
+  focusKey
 }) {
   const seen = /* @__PURE__ */ new Set();
   for (const opt of options) {
@@ -568,7 +571,7 @@ function Autocomplete({
     }
     seen.add(key);
   }
-  const focus = useFocusNode();
+  const focus = useFocusNode({ focusKey });
   const theme = useTheme();
   const [query, setQuery] = useState5("");
   const [highlightIndex, setHighlightIndex] = useState5(0);
@@ -718,8 +721,8 @@ function MeasurableItem({
   }, [index, onMeasure, children]);
   return /* @__PURE__ */ jsx8(Box7, { ref, flexShrink: 0, width: "100%", flexDirection: "column", children });
 }
-var Viewport = forwardRef(function Viewport2({ children, height, keybindings: enableKeybindings = true, footer, ...boxProps }, ref) {
-  const focus = useFocusNode();
+var Viewport = forwardRef(function Viewport2({ children, height, keybindings: enableKeybindings = true, footer, focusKey, ...boxProps }, ref) {
+  const focus = useFocusNode({ focusKey });
   const [scrollOffset, setScrollOffset] = useState6(0);
   const contentHeightRef = useRef4(0);
   const itemHeightsRef = useRef4({});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "giggles",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -40,10 +40,10 @@
   "scripts": {
     "build": "tsup",
     "build:watch": "nodemon --watch src --ext ts,tsx --exec tsup",
-    "play": "tsx --watch",
-    "record": "vhs",
+    "play": "f() { tsx --watch playground/examples/$1.tsx; }; f",
+    "record": "f() { vhs playground/tapes/$1.tape; }; f",
     "dev:docs": "pnpm build && concurrently --kill-others \"pnpm build:watch\" \"pnpm --filter documentation dev\"",
-    "lint": "prettier --write . && eslint . --fix"
+    "lint": "prettier --write --loglevel warn . && eslint . --fix --quiet"
   },
   "files": [
     "dist"