giggles 0.6.0 → 0.6.2

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-QV7GQTKO.js → chunk-TWXBZE5C.js}

@@ -36,8 +36,13 @@ function useKeybindings(focus, bindings, options) {
 }
 
 // src/core/input/useKeybindingRegistry.ts
+import { useSyncExternalStore } from "react";
 function useKeybindingRegistry(focus) {
   const store = useStore();
+  useSyncExternalStore(
+    (cb) => store.subscribe(cb),
+    () => store.getVersion()
+  );
   const all = store.getAllBindings().filter((b) => b.name != null);
   const branchPath = store.getActiveBranchPath();
   const branchSet = new Set(branchPath);
@@ -47,15 +52,24 @@ function useKeybindingRegistry(focus) {
     const trapIndex = branchPath.indexOf(trapNodeId);
     return trapIndex >= 0 ? new Set(branchPath.slice(0, trapIndex + 1)) : null;
   })();
-  const available = all.filter((b) => {
-    return (withinTrapSet ?? branchSet).has(b.nodeId);
-  });
+  const availableSet = withinTrapSet ?? branchSet;
+  const seenKeys = /* @__PURE__ */ new Set();
+  const available = [];
+  for (const nodeId of branchPath) {
+    if (!availableSet.has(nodeId)) continue;
+    for (const b of all) {
+      if (b.nodeId === nodeId && !seenKeys.has(b.key)) {
+        seenKeys.add(b.key);
+        available.push(b);
+      }
+    }
+  }
   const local = focus ? all.filter((b) => b.nodeId === focus.id) : [];
   return { all, available, local };
 }
 
 // src/core/focus/useFocusNode.ts
-import { useContext as useContext2, useEffect as useEffect2, useId as useId2, useMemo, useSyncExternalStore } from "react";
+import { useContext as useContext2, useEffect as useEffect2, useId as useId2, useMemo, useSyncExternalStore as useSyncExternalStore2 } from "react";
 function useFocusNode(options) {
   var _a;
   const id = useId2();
@@ -69,7 +83,7 @@ function useFocusNode(options) {
       store.unregisterNode(id);
     };
   }, [id, parentId, store]);
-  const hasFocus = useSyncExternalStore(subscribe, () => store.isFocused(id));
+  const hasFocus = useSyncExternalStore2(subscribe, () => store.isFocused(id));
   return { id, hasFocus };
 }
 
@@ -106,7 +120,7 @@ function InputRouter({ children }) {
 }
 
 // src/core/focus/useFocusScope.ts
-import { useCallback, useContext as useContext3, useEffect as useEffect4, useId as useId3, useMemo as useMemo2, useSyncExternalStore as useSyncExternalStore2 } from "react";
+import { useCallback, useContext as useContext3, useEffect as useEffect4, useId as useId3, useMemo as useMemo2, useSyncExternalStore as useSyncExternalStore3 } from "react";
 function useFocusScope(options) {
   var _a;
   const id = useId3();
@@ -121,8 +135,8 @@ function useFocusScope(options) {
       store.unregisterNode(id);
     };
   }, [id, parentId, store]);
-  const hasFocus = useSyncExternalStore2(subscribe, () => store.isFocused(id));
-  const isPassive = useSyncExternalStore2(subscribe, () => store.isPassive(id));
+  const hasFocus = useSyncExternalStore3(subscribe, () => store.isFocused(id));
+  const isPassive = useSyncExternalStore3(subscribe, () => store.isPassive(id));
   const next = useCallback(() => store.navigateSibling("next", true, id), [store, id]);
   const prev = useCallback(() => store.navigateSibling("prev", true, id), [store, id]);
   const nextShallow = useCallback(() => store.navigateSibling("next", true, id, true), [store, id]);
@@ -136,12 +150,25 @@ function useFocusScope(options) {
       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 };
 }
 
 // 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 });
 }
 
@@ -177,7 +204,9 @@ 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
   // Keybindings register synchronously during render; nodes register in useEffect.
   // A keybinding may exist for a node that has not yet appeared in the node tree —
@@ -191,10 +220,14 @@ var FocusStore = class {
     return () => this.listeners.delete(listener);
   }
   notify() {
+    this.version++;
     for (const listener of this.listeners) {
       listener();
     }
   }
+  getVersion() {
+    return this.version;
+  }
   // ---------------------------------------------------------------------------
   // Registration
   // ---------------------------------------------------------------------------
@@ -377,6 +410,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,8 +41,6 @@ type FocusScopeHandle = {
     id: string;
     hasFocus: boolean;
     isPassive: boolean;
-};
-type FocusScopeHelpers = {
     next: () => void;
     prev: () => void;
     nextShallow: () => void;
@@ -50,6 +48,7 @@ type FocusScopeHelpers = {
     escape: () => void;
     drillIn: () => void;
 };
+type FocusScopeHelpers = Pick<FocusScopeHandle, 'next' | 'prev' | 'nextShallow' | 'prevShallow' | 'escape' | 'drillIn'>;
 type FocusScopeOptions = {
     parent?: FocusScopeHandle;
     keybindings?: Keybindings | ((helpers: FocusScopeHelpers) => Keybindings);

package/dist/index.js

@@ -14,7 +14,7 @@ import {
   useKeybindingRegistry,
   useKeybindings,
   useStore
-} from "./chunk-QV7GQTKO.js";
+} from "./chunk-TWXBZE5C.js";
 import {
   ThemeProvider,
   useTheme

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.js

@@ -4,7 +4,7 @@ import {
   useFocusNode,
   useKeybindingRegistry,
   useKeybindings
-} from "../chunk-QV7GQTKO.js";
+} from "../chunk-TWXBZE5C.js";
 import {
   CodeBlock
 } from "../chunk-SKSDNDQF.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "giggles",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -40,7 +40,8 @@
   "scripts": {
     "build": "tsup",
     "build:watch": "nodemon --watch src --ext ts,tsx --exec tsup",
-    "play": "tsx --watch",
+    "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"
   },