giggles 0.4.0 → 0.5.1

package/README.md

@@ -12,9 +12,9 @@ inspired by the [charmbracelet](https://github.com/charmbracelet) ecosystem, it
 
 ## features
 
-- no `useInput` hooks scattered across your app — focus, input routing, and keyboard navigation are handled for you
+- each component owns its keys — a text input inside a list inside a panel all work independently, with unhandled keys naturally passing up to the right parent. no global input handler, no coordination code
 - navigate between views with a simple API; the previously focused component is restored when you return
-- a full set of hooks and components — `useFocus`, `useFocusNode`, `FocusGroup`, `FocusTrap`, `useNavigation`, and more — for building any interaction pattern without reimplementing the plumbing
+- a full set of hooks and components — `useFocusScope`, `useFocusNode`, `FocusTrap`, `useNavigation`, and more — for building any interaction pattern without reimplementing the plumbing
 - built-in keybinding registry so your app can always show users what keys do what, in the current context — context-aware and accessible via a hook
 - a component library covering most TUI use cases, from text inputs and autocomplete to virtual lists for large datasets — with sensible defaults and render props for full customization
 - render markdown in the terminal, with full formatting and syntax-highlighted code block and diff support

package/dist/{chunk-R5I4YOOP.js → chunk-C77VBSPK.js}

@@ -4,6 +4,7 @@ import { jsx } from "react/jsx-runtime";
 var defaultTheme = {
   accentColor: "#6B9FD4",
   borderColor: "#5C5C5C",
+  borderStyle: "round",
   selectedColor: "#8FBF7F",
   hintColor: "#8A8A8A",
   hintDimColor: "#5C5C5C",

package/dist/chunk-LXNKSYJT.js

@@ -0,0 +1,540 @@
+// src/core/GigglesError.ts
+var GigglesError = class extends Error {
+  constructor(message) {
+    super(`[giggles] ${message}`);
+    this.name = "GigglesError";
+  }
+};
+
+// src/core/input/useKeybindings.tsx
+import { useEffect, useId, useRef } from "react";
+
+// src/core/focus/StoreContext.ts
+import { createContext, useContext } from "react";
+var StoreContext = createContext(null);
+var ScopeIdContext = createContext(null);
+function useStore() {
+  const store = useContext(StoreContext);
+  if (!store) {
+    throw new GigglesError("useStore must be used within a GigglesProvider");
+  }
+  return store;
+}
+
+// src/core/input/useKeybindings.tsx
+function useKeybindings(focus, bindings, options) {
+  const store = useStore();
+  const registrationId = useId();
+  const nodeIdRef = useRef(focus.id);
+  nodeIdRef.current = focus.id;
+  store.registerKeybindings(nodeIdRef.current, registrationId, bindings, options);
+  useEffect(() => {
+    return () => {
+      store.unregisterKeybindings(nodeIdRef.current, registrationId);
+    };
+  }, [registrationId, store]);
+}
+
+// src/core/input/useKeybindingRegistry.ts
+function useKeybindingRegistry(focus) {
+  const store = useStore();
+  const all = store.getAllBindings().filter((b) => b.name != null);
+  const branchPath = store.getActiveBranchPath();
+  const branchSet = new Set(branchPath);
+  const trapNodeId = store.getTrapNodeId();
+  const withinTrapSet = (() => {
+    if (!trapNodeId) return null;
+    const trapIndex = branchPath.indexOf(trapNodeId);
+    return trapIndex >= 0 ? new Set(branchPath.slice(0, trapIndex + 1)) : null;
+  })();
+  const available = all.filter((b) => {
+    if (b.when === "mounted") return withinTrapSet ? withinTrapSet.has(b.nodeId) : true;
+    return (withinTrapSet ?? branchSet).has(b.nodeId);
+  });
+  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";
+function useFocusNode(options) {
+  var _a;
+  const id = useId2();
+  const store = useStore();
+  const contextParentId = useContext2(ScopeIdContext);
+  const parentId = ((_a = options == null ? void 0 : options.parent) == null ? void 0 : _a.id) ?? contextParentId;
+  const subscribe = useMemo(() => store.subscribe.bind(store), [store]);
+  useEffect2(() => {
+    store.registerNode(id, parentId);
+    return () => {
+      store.unregisterNode(id);
+    };
+  }, [id, parentId, store]);
+  const hasFocus = useSyncExternalStore(subscribe, () => store.isFocused(id));
+  return { id, hasFocus };
+}
+
+// src/core/input/FocusTrap.tsx
+import { useEffect as useEffect3, useRef as useRef2 } from "react";
+import { jsx } from "react/jsx-runtime";
+function FocusTrap({ children }) {
+  const { id } = useFocusNode();
+  const store = useStore();
+  const previousFocusRef = useRef2(store.getFocusedId());
+  useEffect3(() => {
+    const previousFocus = previousFocusRef.current;
+    store.setTrap(id);
+    store.focusFirstChild(id);
+    return () => {
+      store.clearTrap(id);
+      if (previousFocus) {
+        store.focusNode(previousFocus);
+      }
+    };
+  }, [id]);
+  return /* @__PURE__ */ jsx(ScopeIdContext.Provider, { value: id, children });
+}
+
+// src/core/input/InputRouter.tsx
+import { useInput } from "ink";
+import { Fragment, jsx as jsx2 } from "react/jsx-runtime";
+function InputRouter({ children }) {
+  const store = useStore();
+  useInput((input, key) => {
+    store.dispatch(input, key);
+  });
+  return /* @__PURE__ */ jsx2(Fragment, { 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";
+function useFocusScope(options) {
+  var _a;
+  const id = useId3();
+  const keybindingRegistrationId = useId3();
+  const store = useStore();
+  const contextParentId = useContext3(ScopeIdContext);
+  const parentId = ((_a = options == null ? void 0 : options.parent) == null ? void 0 : _a.id) ?? contextParentId;
+  const subscribe = useMemo2(() => store.subscribe.bind(store), [store]);
+  useEffect4(() => {
+    store.registerNode(id, parentId);
+    return () => {
+      store.unregisterNode(id);
+    };
+  }, [id, parentId, store]);
+  const hasFocus = useSyncExternalStore2(subscribe, () => store.isFocused(id));
+  const isPassive = useSyncExternalStore2(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]);
+  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) ?? {};
+  store.registerKeybindings(id, keybindingRegistrationId, resolvedBindings);
+  useEffect4(() => {
+    return () => {
+      store.unregisterKeybindings(id, keybindingRegistrationId);
+    };
+  }, [id, keybindingRegistrationId, store]);
+  return { id, hasFocus, isPassive };
+}
+
+// src/core/focus/FocusScope.tsx
+import { jsx as jsx3 } from "react/jsx-runtime";
+function FocusScope({ handle, children }) {
+  return /* @__PURE__ */ jsx3(ScopeIdContext.Provider, { value: handle.id, children });
+}
+
+// src/core/input/normalizeKey.ts
+function normalizeKey(input, key) {
+  if (input === "\x1B[I" || input === "\x1B[O") return "";
+  if (key.downArrow) return "down";
+  if (key.upArrow) return "up";
+  if (key.leftArrow) return "left";
+  if (key.rightArrow) return "right";
+  if (key.return) return "enter";
+  if (key.escape) return "escape";
+  if (key.tab && key.shift) return "shift+tab";
+  if (key.tab) return "tab";
+  if (input === "\x1B[3~") return "delete";
+  if (key.backspace || key.delete) return "backspace";
+  if (key.pageUp) return "pageup";
+  if (key.pageDown) return "pagedown";
+  if (key.home) return "home";
+  if (key.end) return "end";
+  if (key.ctrl && input.length === 1) {
+    return `ctrl+${input}`;
+  }
+  return input;
+}
+
+// src/core/focus/FocusStore.ts
+var FocusStore = class {
+  nodes = /* @__PURE__ */ new Map();
+  // Persistent parent record — never deleted from, used for ancestor-walk during unregistration
+  parentMap = /* @__PURE__ */ new Map();
+  focusedId = null;
+  passiveSet = /* @__PURE__ */ new Set();
+  pendingFocusFirstChild = /* @__PURE__ */ new Set();
+  trapNodeId = null;
+  listeners = /* @__PURE__ */ new Set();
+  // 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 —
+  // this is safe because dispatch only walks nodes in the active branch path.
+  keybindings = /* @__PURE__ */ new Map();
+  // ---------------------------------------------------------------------------
+  // Subscription
+  // ---------------------------------------------------------------------------
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  notify() {
+    for (const listener of this.listeners) {
+      listener();
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Registration
+  // ---------------------------------------------------------------------------
+  registerNode(id, parentId) {
+    const node = { id, parentId, childrenIds: [] };
+    this.nodes.set(id, node);
+    this.parentMap.set(id, parentId);
+    if (parentId) {
+      const parent = this.nodes.get(parentId);
+      if (parent && !parent.childrenIds.includes(id)) {
+        const wasEmpty = parent.childrenIds.length === 0;
+        parent.childrenIds.push(id);
+        if (wasEmpty && this.pendingFocusFirstChild.has(parentId)) {
+          this.pendingFocusFirstChild.delete(parentId);
+          this.focusNode(id);
+        }
+      }
+    }
+    for (const [existingId, existingNode] of this.nodes) {
+      if (existingNode.parentId === id && !node.childrenIds.includes(existingId)) {
+        node.childrenIds.push(existingId);
+      }
+    }
+    if (this.nodes.size === 1) {
+      this.focusNode(id);
+    }
+    this.notify();
+  }
+  unregisterNode(id) {
+    const node = this.nodes.get(id);
+    if (!node) return;
+    if (node.parentId) {
+      const parent = this.nodes.get(node.parentId);
+      if (parent) {
+        parent.childrenIds = parent.childrenIds.filter((c) => c !== id);
+      }
+    }
+    this.nodes.delete(id);
+    this.passiveSet.delete(id);
+    this.pendingFocusFirstChild.delete(id);
+    if (this.focusedId === id) {
+      let candidate = node.parentId;
+      while (candidate !== null) {
+        if (this.nodes.has(candidate)) {
+          this.focusNode(candidate);
+          return;
+        }
+        candidate = this.parentMap.get(candidate) ?? null;
+      }
+      this.focusedId = null;
+    }
+    this.notify();
+  }
+  // ---------------------------------------------------------------------------
+  // Focus
+  // ---------------------------------------------------------------------------
+  focusNode(id) {
+    if (!this.nodes.has(id)) return;
+    const oldFocusedId = this.focusedId;
+    if (oldFocusedId === id) return;
+    this.focusedId = id;
+    for (const passiveId of this.passiveSet) {
+      const wasAncestor = this.isAncestorOf(passiveId, oldFocusedId);
+      const isAncestor = this.isAncestorOf(passiveId, id);
+      if (wasAncestor && !isAncestor) {
+        this.passiveSet.delete(passiveId);
+      }
+      if (isAncestor && id !== passiveId) {
+        this.passiveSet.delete(passiveId);
+      }
+    }
+    this.notify();
+  }
+  focusFirstChild(parentId) {
+    const parent = this.nodes.get(parentId);
+    if (parent && parent.childrenIds.length > 0) {
+      let target = parent.childrenIds[0];
+      let targetNode = this.nodes.get(target);
+      while (targetNode && targetNode.childrenIds.length > 0) {
+        target = targetNode.childrenIds[0];
+        targetNode = this.nodes.get(target);
+      }
+      this.focusNode(target);
+    } else {
+      this.pendingFocusFirstChild.add(parentId);
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Navigation
+  // ---------------------------------------------------------------------------
+  navigateSibling(direction, wrap = true, groupId, shallow = false) {
+    var _a;
+    if (!this.focusedId) return;
+    let currentChildId;
+    let siblings;
+    if (groupId) {
+      const group = this.nodes.get(groupId);
+      if (!group || group.childrenIds.length === 0) return;
+      siblings = group.childrenIds;
+      let cursor = this.focusedId;
+      while (cursor) {
+        const node = this.nodes.get(cursor);
+        if ((node == null ? void 0 : node.parentId) === groupId) {
+          currentChildId = cursor;
+          break;
+        }
+        cursor = (node == null ? void 0 : node.parentId) ?? null;
+      }
+      if (!currentChildId) {
+        const targetId2 = direction === "next" ? siblings[0] : siblings[siblings.length - 1];
+        if (!shallow && ((_a = this.nodes.get(targetId2)) == null ? void 0 : _a.childrenIds.length)) {
+          this.focusFirstChild(targetId2);
+        } else {
+          this.focusNode(targetId2);
+        }
+        return;
+      }
+    } else {
+      const currentNode = this.nodes.get(this.focusedId);
+      if (!(currentNode == null ? void 0 : currentNode.parentId)) return;
+      const parent = this.nodes.get(currentNode.parentId);
+      if (!parent || parent.childrenIds.length === 0) return;
+      siblings = parent.childrenIds;
+      currentChildId = this.focusedId;
+    }
+    const currentIndex = siblings.indexOf(currentChildId);
+    if (currentIndex === -1) return;
+    let nextIndex;
+    if (wrap) {
+      nextIndex = direction === "next" ? (currentIndex + 1) % siblings.length : (currentIndex - 1 + siblings.length) % siblings.length;
+    } else {
+      nextIndex = direction === "next" ? Math.min(currentIndex + 1, siblings.length - 1) : Math.max(currentIndex - 1, 0);
+    }
+    const targetId = siblings[nextIndex];
+    const target = this.nodes.get(targetId);
+    if (!shallow && target && target.childrenIds.length > 0) {
+      this.focusFirstChild(targetId);
+    } else {
+      this.focusNode(targetId);
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Passive scopes
+  // ---------------------------------------------------------------------------
+  makePassive(id) {
+    if (!this.nodes.has(id)) return;
+    this.passiveSet.add(id);
+    this.focusNode(id);
+  }
+  isPassive(id) {
+    return this.passiveSet.has(id);
+  }
+  // ---------------------------------------------------------------------------
+  // Queries
+  // ---------------------------------------------------------------------------
+  isFocused(id) {
+    if (!this.focusedId) return false;
+    let cursor = this.focusedId;
+    while (cursor) {
+      if (cursor === id) return true;
+      const node = this.nodes.get(cursor);
+      cursor = (node == null ? void 0 : node.parentId) ?? null;
+    }
+    return false;
+  }
+  getFocusedId() {
+    return this.focusedId;
+  }
+  getActiveBranchPath() {
+    if (!this.focusedId) return [];
+    const path = [];
+    let cursor = this.focusedId;
+    while (cursor) {
+      path.push(cursor);
+      const node = this.nodes.get(cursor);
+      cursor = (node == null ? void 0 : node.parentId) ?? null;
+    }
+    return path;
+  }
+  // ---------------------------------------------------------------------------
+  // Trap
+  // ---------------------------------------------------------------------------
+  setTrap(nodeId) {
+    this.trapNodeId = nodeId;
+  }
+  clearTrap(nodeId) {
+    if (this.trapNodeId === nodeId) {
+      this.trapNodeId = null;
+    }
+  }
+  getTrapNodeId() {
+    return this.trapNodeId;
+  }
+  // ---------------------------------------------------------------------------
+  // Keybinding registry
+  // ---------------------------------------------------------------------------
+  registerKeybindings(nodeId, registrationId, bindings, options) {
+    const entries = Object.entries(bindings).filter((entry) => entry[1] != null).map(([key, def]) => {
+      if (typeof def === "function") {
+        return [key, { handler: def }];
+      }
+      return [key, { handler: def.action, name: def.name, when: def.when }];
+    });
+    const registration = {
+      bindings: new Map(entries),
+      capture: (options == null ? void 0 : options.capture) ?? false,
+      onKeypress: options == null ? void 0 : options.onKeypress,
+      passthrough: (options == null ? void 0 : options.passthrough) ? new Set(options.passthrough) : void 0,
+      layer: options == null ? void 0 : options.layer
+    };
+    if (!this.keybindings.has(nodeId)) {
+      this.keybindings.set(nodeId, /* @__PURE__ */ new Map());
+    }
+    this.keybindings.get(nodeId).set(registrationId, registration);
+  }
+  unregisterKeybindings(nodeId, registrationId) {
+    const nodeRegistrations = this.keybindings.get(nodeId);
+    if (nodeRegistrations) {
+      nodeRegistrations.delete(registrationId);
+      if (nodeRegistrations.size === 0) {
+        this.keybindings.delete(nodeId);
+      }
+    }
+  }
+  getNodeBindings(nodeId) {
+    const nodeRegistrations = this.keybindings.get(nodeId);
+    if (!nodeRegistrations || nodeRegistrations.size === 0) return void 0;
+    const mergedBindings = /* @__PURE__ */ new Map();
+    let finalCapture = false;
+    let finalOnKeypress;
+    let finalPassthrough;
+    let finalLayer;
+    for (const registration of nodeRegistrations.values()) {
+      const isCaptureRegistration = registration.onKeypress !== void 0;
+      const shouldIncludeBindings = !isCaptureRegistration || registration.capture;
+      if (shouldIncludeBindings) {
+        for (const [key, entry] of registration.bindings) {
+          mergedBindings.set(key, entry);
+        }
+      }
+      if (registration.capture) {
+        finalCapture = true;
+        finalOnKeypress = registration.onKeypress;
+        finalPassthrough = registration.passthrough;
+      }
+      if (registration.layer) {
+        finalLayer = registration.layer;
+      }
+    }
+    return {
+      bindings: mergedBindings,
+      capture: finalCapture,
+      onKeypress: finalOnKeypress,
+      passthrough: finalPassthrough,
+      layer: finalLayer
+    };
+  }
+  getAllBindings() {
+    const all = [];
+    for (const [nodeId, nodeRegistrations] of this.keybindings) {
+      for (const registration of nodeRegistrations.values()) {
+        for (const [key, entry] of registration.bindings) {
+          all.push({
+            nodeId,
+            key,
+            handler: entry.handler,
+            name: entry.name,
+            when: entry.when,
+            layer: registration.layer
+          });
+        }
+      }
+    }
+    return all;
+  }
+  // ---------------------------------------------------------------------------
+  // Input dispatch
+  // ---------------------------------------------------------------------------
+  // Bridge target for InputRouter. Walks the active branch path with passive-scope
+  // skipping, capture mode, and trap boundary — the full dispatch algorithm.
+  dispatch(input, key) {
+    var _a;
+    const keyName = normalizeKey(input, key);
+    if (!keyName) return;
+    const path = this.getActiveBranchPath();
+    const trapNodeId = this.trapNodeId;
+    for (const nodeId of path) {
+      if (this.passiveSet.has(nodeId)) continue;
+      const nodeBindings = this.getNodeBindings(nodeId);
+      if (nodeBindings) {
+        if (nodeBindings.capture && nodeBindings.onKeypress) {
+          if (!((_a = nodeBindings.passthrough) == null ? void 0 : _a.has(keyName))) {
+            nodeBindings.onKeypress(input, key);
+            return;
+          }
+        }
+        const entry = nodeBindings.bindings.get(keyName);
+        if (entry && entry.when !== "mounted") {
+          entry.handler(input, key);
+          return;
+        }
+      }
+      if (nodeId === trapNodeId) {
+        return;
+      }
+    }
+    for (const binding of this.getAllBindings()) {
+      if (binding.key === keyName && binding.when === "mounted") {
+        binding.handler(input, key);
+        return;
+      }
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+  // Is `ancestor` an ancestor of `descendant`? (or equal)
+  isAncestorOf(ancestor, descendant) {
+    let cursor = descendant;
+    while (cursor) {
+      if (cursor === ancestor) return true;
+      const node = this.nodes.get(cursor);
+      cursor = (node == null ? void 0 : node.parentId) ?? null;
+    }
+    return false;
+  }
+};
+
+export {
+  GigglesError,
+  FocusStore,
+  StoreContext,
+  ScopeIdContext,
+  useStore,
+  InputRouter,
+  useKeybindings,
+  useKeybindingRegistry,
+  useFocusNode,
+  FocusTrap,
+  useFocusScope,
+  FocusScope
+};

package/dist/{chunk-DFB7V4OK.js → chunk-SKSDNDQF.js}

@@ -1,6 +1,6 @@
 import {
   useTheme
-} from "./chunk-R5I4YOOP.js";
+} from "./chunk-C77VBSPK.js";
 
 // src/ui/CodeBlock.tsx
 import { Box, Text } from "ink";
@@ -27,7 +27,7 @@ function CodeBlock({ children, language, tokenColors, ...boxProps }) {
   const colors = { ...defaultTokenColors, ...tokenColors };
   const grammar = language ? Prism.languages[language] : void 0;
   const content = grammar ? renderTokens(Prism.tokenize(children, grammar), colors) : /* @__PURE__ */ jsx(Text, { children });
-  return /* @__PURE__ */ jsx(Box, { paddingX: 1, borderStyle: "round", borderColor: theme.borderColor, ...boxProps, children: /* @__PURE__ */ jsx(Text, { children: content }) });
+  return /* @__PURE__ */ jsx(Box, { paddingX: 1, borderStyle: theme.borderStyle, borderColor: theme.borderColor, ...boxProps, children: /* @__PURE__ */ jsx(Text, { children: content }) });
 }
 function renderTokens(tokens, colors) {
   return tokens.map((token, idx) => {

package/dist/chunk-WNGBTD67.js

@@ -0,0 +1,25 @@
+// src/terminal/hooks/useTerminalSize.ts
+import { useEffect, useState } from "react";
+function useTerminalSize() {
+  const [size, setSize] = useState({
+    rows: process.stdout.rows,
+    columns: process.stdout.columns
+  });
+  useEffect(() => {
+    const handleResize = () => {
+      setSize({
+        rows: process.stdout.rows,
+        columns: process.stdout.columns
+      });
+    };
+    process.stdout.on("resize", handleResize);
+    return () => {
+      process.stdout.off("resize", handleResize);
+    };
+  }, []);
+  return size;
+}
+
+export {
+  useTerminalSize
+};