giggles 0.0.3 → 0.1.0

package/README.md

@@ -0,0 +1 @@
+wip -- see [giggles.zzzzion.com](https://giggles.zzzzion.com)!

package/dist/index.d.ts

@@ -1,2 +1,204 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as React$1 from 'react';
+import React__default from 'react';
+import { Key } from 'ink';
+export { Key } from 'ink';
 
-export {  }
+type GigglesProviderProps = {
+    children: React__default.ReactNode;
+};
+/**
+ * Root provider for Giggles applications. Combines focus and input systems.
+ *
+ * Wraps your app in the necessary context providers and sets up the input router.
+ * All Giggles apps must be wrapped in this provider.
+ *
+ * @example
+ * ```tsx
+ * import { render } from 'ink';
+ * import { GigglesProvider } from 'giggles';
+ * import { App } from './App';
+ *
+ * render(
+ *   <GigglesProvider>
+ *     <App />
+ *   </GigglesProvider>
+ * );
+ * ```
+ */
+declare function GigglesProvider({ children }: GigglesProviderProps): react_jsx_runtime.JSX.Element;
+
+type FocusGroupProps = {
+    children: React__default.ReactNode;
+    direction?: 'vertical' | 'horizontal';
+    value?: string;
+    wrap?: boolean;
+    navigable?: boolean;
+};
+declare function FocusGroup({ children, direction, value, wrap, navigable }: FocusGroupProps): react_jsx_runtime.JSX.Element;
+
+declare const useFocus: () => {
+    id: string;
+    focused: boolean;
+    focus: () => void;
+};
+
+declare function useFocusState<T extends string>(initial: T): readonly [T, React$1.Dispatch<React$1.SetStateAction<T>>];
+
+/**
+ * Handler function for a key binding.
+ *
+ * If a binding exists for a key, the handler will be called and the input will stop bubbling.
+ * Unhandled keys (those without bindings) automatically bubble up to parent components.
+ *
+ * For conditional handling, either:
+ * - Register bindings conditionally based on component state, or
+ * - Use internal logic within the handler to decide whether to perform an action
+ *
+ * @param input - The character string for the key pressed (e.g., 'j', 'q')
+ * @param key - Ink's Key object with boolean properties (downArrow, return, escape, etc.)
+ *
+ * @example
+ * ```tsx
+ * useKeybindings(focus, {
+ *   j: () => moveDown(),
+ *   k: () => moveUp(),
+ *   return: () => selectItem()
+ * });
+ * ```
+ */
+type KeyHandler = (input: string, key: Key) => void;
+type SpecialKey = 'up' | 'down' | 'left' | 'right' | 'enter' | 'escape' | 'tab' | 'backspace' | 'delete' | 'pageup' | 'pagedown' | 'home' | 'end';
+type KeyName = SpecialKey | (string & {});
+/**
+ * Map of key names to handler functions.
+ *
+ * Keys are strings that match either:
+ * - Special keys (autocompleted): 'enter', 'escape', 'up', 'down', etc.
+ * - Character keys: 'j', 'k', 'a', '?', etc.
+ * - Modified keys: 'ctrl+c', 'ctrl+q', etc.
+ *
+ * @example
+ * ```tsx
+ * const bindings: Keybindings = {
+ *   j: () => moveDown(),
+ *   k: () => moveUp(),
+ *   enter: () => selectItem(),
+ *   'ctrl+q': () => quit()
+ * };
+ * ```
+ */
+type Keybindings = Partial<Record<KeyName, KeyHandler>>;
+/**
+ * Options for configuring keybinding behavior.
+ */
+type KeybindingOptions = {
+    /**
+     * Enable capture mode. When true, explicit bindings are checked first,
+     * then all remaining keystrokes go to `onKeypress`. Nothing bubbles.
+     *
+     * Used for text inputs and components that need to receive all keystrokes.
+     */
+    capture?: boolean;
+    /**
+     * Handler for keystrokes in capture mode that don't match explicit bindings.
+     *
+     * Only called when `capture` is true.
+     */
+    onKeypress?: (input: string, key: Key) => void;
+    /**
+     * Optional layer identifier for organizing keybindings.
+     *
+     * Can be used for debugging or building tooling that inspects keybindings.
+     * Has no effect on input routing behavior.
+     */
+    layer?: string;
+};
+
+/**
+ * Registers keybindings that only fire when this component is focused.
+ *
+ * Solves Ink's global `useInput` problem by routing keypresses through the focus tree.
+ * Only the focused component receives input. Unhandled keys bubble up to parent components.
+ *
+ * @param focus - The focus handle from `useFocus()`. Ties bindings to this component's focus node.
+ * @param bindings - Map of key names to handler functions. Handlers only fire when focused.
+ * @param options - Optional configuration for capture mode, keypress handlers, and layers.
+ *
+ * @example
+ * ```tsx
+ * function FileList() {
+ *   const focus = useFocus();
+ *
+ *   useKeybindings(focus, {
+ *     j: () => moveDown(),
+ *     k: () => moveUp(),
+ *     enter: () => openFile()
+ *   });
+ *
+ *   return <List focused={focus.focused} items={files} />;
+ * }
+ * ```
+ *
+ * @example Capture mode for text input
+ * ```tsx
+ * function TextInput() {
+ *   const focus = useFocus();
+ *   const [value, setValue] = useState('');
+ *
+ *   useKeybindings(
+ *     focus,
+ *     {
+ *       escape: () => blur(),
+ *       enter: () => submit(value)
+ *     },
+ *     {
+ *       capture: true,
+ *       onKeypress: (key) => setValue(v => v + key)
+ *     }
+ *   );
+ *
+ *   return <Text>{value}</Text>;
+ * }
+ * ```
+ */
+declare function useKeybindings(focus: {
+    id: string;
+}, bindings: Keybindings, options?: KeybindingOptions): void;
+
+type FocusTrapProps = {
+    children: React.ReactNode;
+};
+/**
+ * Stops input bubbling at a boundary. Used for modals and dialogs.
+ *
+ * When a key is pressed, it bubbles up the focus tree until handled.
+ * FocusTrap creates a barrier - if nothing inside the trap handles the key,
+ * it stops at the trap boundary instead of bubbling to parent components.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const [showModal, setShowModal] = useState(false);
+ *
+ *   useKeybindings(focus, {
+ *     '?': () => setShowModal(true),
+ *     q: () => exit()
+ *   });
+ *
+ *   return (
+ *     <Screen>
+ *       <MainContent />
+ *       {showModal && (
+ *         <FocusTrap>
+ *           <HelpModal onClose={() => setShowModal(false)} />
+ *         </FocusTrap>
+ *       )}
+ *     </Screen>
+ *   );
+ * }
+ * ```
+ */
+declare function FocusTrap({ children }: FocusTrapProps): react_jsx_runtime.JSX.Element;
+
+export { FocusGroup, FocusTrap, GigglesProvider, type KeyHandler, type KeybindingOptions, type Keybindings, useFocus, useFocusState, useKeybindings };

package/dist/index.js

@@ -0,0 +1,391 @@
+// src/core/focus/FocusContext.tsx
+import { createContext, useCallback, useContext, useRef, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+var FocusContext = createContext(null);
+var FocusProvider = ({ children }) => {
+  const nodesRef = useRef(/* @__PURE__ */ new Map());
+  const [focusedId, setFocusedId] = useState(null);
+  const [activeBranchNodes, setActiveBranchNodes] = useState(/* @__PURE__ */ new Set());
+  const [activeBranchPath, setActiveBranchPath] = useState([]);
+  const focusNode = useCallback((id) => {
+    const nodes = nodesRef.current;
+    if (!nodes.has(id)) return;
+    setFocusedId((current) => {
+      if (current === id) return current;
+      const pathSet = /* @__PURE__ */ new Set();
+      const pathArray = [];
+      let currentNode = id;
+      while (currentNode) {
+        pathSet.add(currentNode);
+        pathArray.push(currentNode);
+        const node = nodes.get(currentNode);
+        currentNode = (node == null ? void 0 : node.parentId) ?? null;
+      }
+      setActiveBranchNodes(pathSet);
+      setActiveBranchPath(pathArray);
+      return id;
+    });
+  }, []);
+  const registerNode = useCallback(
+    (id, parentId) => {
+      const nodes = nodesRef.current;
+      const node = {
+        id,
+        parentId,
+        childrenIds: []
+      };
+      nodes.set(id, node);
+      if (parentId) {
+        const parent = nodes.get(parentId);
+        if (parent && !parent.childrenIds.includes(id)) {
+          parent.childrenIds.push(id);
+        }
+      }
+      nodes.forEach((existingNode) => {
+        if (existingNode.parentId === id && !node.childrenIds.includes(existingNode.id)) {
+          node.childrenIds.push(existingNode.id);
+        }
+      });
+      if (nodes.size === 1) {
+        focusNode(id);
+      }
+    },
+    [focusNode]
+  );
+  const unregisterNode = useCallback((id) => {
+    const nodes = nodesRef.current;
+    const node = nodes.get(id);
+    if (!node) return;
+    if (node.parentId) {
+      const parent = nodes.get(node.parentId);
+      if (parent) {
+        parent.childrenIds = parent.childrenIds.filter((childId) => childId !== id);
+      }
+    }
+    nodes.delete(id);
+    setFocusedId((current) => {
+      if (current !== id) return current;
+      if (node.parentId) {
+        const pathSet = /* @__PURE__ */ new Set();
+        const pathArray = [];
+        let currentNode = node.parentId;
+        while (currentNode) {
+          pathSet.add(currentNode);
+          pathArray.push(currentNode);
+          const n = nodes.get(currentNode);
+          currentNode = (n == null ? void 0 : n.parentId) ?? null;
+        }
+        setActiveBranchNodes(pathSet);
+        setActiveBranchPath(pathArray);
+        return node.parentId;
+      }
+      setActiveBranchNodes(/* @__PURE__ */ new Set());
+      setActiveBranchPath([]);
+      return null;
+    });
+  }, []);
+  const isFocused = useCallback(
+    (id) => {
+      return id === focusedId;
+    },
+    [focusedId]
+  );
+  const getFocusedId = useCallback(() => {
+    return focusedId;
+  }, [focusedId]);
+  const isInActiveBranch = useCallback(
+    (id) => {
+      return activeBranchNodes.has(id);
+    },
+    [activeBranchNodes]
+  );
+  const getActiveBranchPath = useCallback(() => {
+    return activeBranchPath;
+  }, [activeBranchPath]);
+  const navigateSibling = useCallback(
+    (direction, wrap = true) => {
+      const currentId = focusedId;
+      if (!currentId) return;
+      const nodes = nodesRef.current;
+      const currentNode = nodes.get(currentId);
+      if (!(currentNode == null ? void 0 : currentNode.parentId)) return;
+      const parent = nodes.get(currentNode.parentId);
+      if (!parent || parent.childrenIds.length === 0) return;
+      const siblings = parent.childrenIds;
+      const currentIndex = siblings.indexOf(currentId);
+      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);
+      }
+      focusNode(siblings[nextIndex]);
+    },
+    [focusedId, focusNode]
+  );
+  return /* @__PURE__ */ jsx(
+    FocusContext.Provider,
+    {
+      value: {
+        registerNode,
+        unregisterNode,
+        focusNode,
+        isFocused,
+        getFocusedId,
+        isInActiveBranch,
+        getActiveBranchPath,
+        navigateSibling
+      },
+      children
+    }
+  );
+};
+var FocusNodeContext = createContext(null);
+var useFocusContext = () => {
+  const context = useContext(FocusContext);
+  if (!context) {
+    throw new Error("useFocusContext must be used within a FocusProvider");
+  }
+  return context;
+};
+
+// src/core/focus/FocusGroup.tsx
+import { useCallback as useCallback3, useEffect as useEffect4, useMemo, useRef as useRef3 } from "react";
+
+// src/core/input/InputContext.tsx
+import { createContext as createContext2, useCallback as useCallback2, useContext as useContext2, useRef as useRef2 } from "react";
+import { jsx as jsx2 } from "react/jsx-runtime";
+var InputContext = createContext2(null);
+var InputProvider = ({ children }) => {
+  const bindingsRef = useRef2(/* @__PURE__ */ new Map());
+  const trapNodeIdRef = useRef2(null);
+  const registerKeybindings = useCallback2((nodeId, bindings, options) => {
+    const registration = {
+      bindings: new Map(Object.entries(bindings).filter((entry) => entry[1] != null)),
+      capture: (options == null ? void 0 : options.capture) ?? false,
+      onKeypress: options == null ? void 0 : options.onKeypress,
+      layer: options == null ? void 0 : options.layer
+    };
+    bindingsRef.current.set(nodeId, registration);
+  }, []);
+  const unregisterKeybindings = useCallback2((nodeId) => {
+    bindingsRef.current.delete(nodeId);
+  }, []);
+  const getNodeBindings = useCallback2((nodeId) => {
+    return bindingsRef.current.get(nodeId);
+  }, []);
+  const setTrap = useCallback2((nodeId) => {
+    trapNodeIdRef.current = nodeId;
+  }, []);
+  const clearTrap = useCallback2((nodeId) => {
+    if (trapNodeIdRef.current === nodeId) {
+      trapNodeIdRef.current = null;
+    }
+  }, []);
+  const getTrapNodeId = useCallback2(() => {
+    return trapNodeIdRef.current;
+  }, []);
+  const getAllBindings = useCallback2(() => {
+    const allBindings = [];
+    bindingsRef.current.forEach((nodeBindings, nodeId) => {
+      nodeBindings.bindings.forEach((handler, key) => {
+        allBindings.push({
+          nodeId,
+          key,
+          handler,
+          layer: nodeBindings.layer
+        });
+      });
+    });
+    return allBindings;
+  }, []);
+  return /* @__PURE__ */ jsx2(
+    InputContext.Provider,
+    {
+      value: {
+        registerKeybindings,
+        unregisterKeybindings,
+        getNodeBindings,
+        setTrap,
+        clearTrap,
+        getTrapNodeId,
+        getAllBindings
+      },
+      children
+    }
+  );
+};
+function useInputContext() {
+  const context = useContext2(InputContext);
+  if (!context) {
+    throw new Error("useInputContext must be used within an InputProvider");
+  }
+  return context;
+}
+
+// src/core/input/InputRouter.tsx
+import { useInput } from "ink";
+
+// src/core/input/normalizeKey.ts
+function normalizeKey(input, key) {
+  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) return "tab";
+  if (key.backspace) return "backspace";
+  if (key.delete) return "delete";
+  if (key.pageUp) return "pageup";
+  if (key.pageDown) return "pagedown";
+  if (key.home) return "home";
+  if (key.end) return "end";
+  return input;
+}
+
+// src/core/input/InputRouter.tsx
+import { Fragment, jsx as jsx3 } from "react/jsx-runtime";
+function InputRouter({ children }) {
+  const { getFocusedId, getActiveBranchPath } = useFocusContext();
+  const { getNodeBindings, getTrapNodeId } = useInputContext();
+  useInput((input, key) => {
+    const focusedId = getFocusedId();
+    if (!focusedId) return;
+    const path = getActiveBranchPath();
+    const trapNodeId = getTrapNodeId();
+    const keyName = normalizeKey(input, key);
+    for (const nodeId of path) {
+      const nodeBindings = getNodeBindings(nodeId);
+      if (!nodeBindings) continue;
+      const handler = nodeBindings.bindings.get(keyName);
+      if (handler) {
+        handler(input, key);
+        return;
+      }
+      if (nodeBindings.capture && nodeBindings.onKeypress) {
+        nodeBindings.onKeypress(input, key);
+        return;
+      }
+      if (nodeId === trapNodeId) {
+        return;
+      }
+    }
+  });
+  return /* @__PURE__ */ jsx3(Fragment, { children });
+}
+
+// src/core/input/useKeybindings.tsx
+import { useEffect } from "react";
+function useKeybindings(focus, bindings, options) {
+  const { registerKeybindings, unregisterKeybindings } = useInputContext();
+  registerKeybindings(focus.id, bindings, options);
+  useEffect(() => {
+    return () => unregisterKeybindings(focus.id);
+  }, [focus.id, unregisterKeybindings]);
+}
+
+// src/core/input/FocusTrap.tsx
+import { useEffect as useEffect2 } from "react";
+import { Fragment as Fragment2, jsx as jsx4 } from "react/jsx-runtime";
+function FocusTrap({ children }) {
+  const { id } = useFocus();
+  const { setTrap, clearTrap } = useInputContext();
+  useEffect2(() => {
+    setTrap(id);
+    return () => clearTrap(id);
+  }, [id, setTrap, clearTrap]);
+  return /* @__PURE__ */ jsx4(Fragment2, { children });
+}
+
+// src/core/focus/FocusBindContext.tsx
+import { createContext as createContext3, useContext as useContext3 } from "react";
+var FocusBindContext = createContext3(null);
+
+// src/core/focus/useFocus.ts
+import { useContext as useContext4, useEffect as useEffect3, useId } from "react";
+var useFocus = () => {
+  const nodeId = useId();
+  const parentId = useContext4(FocusNodeContext);
+  const { focusNode, registerNode, unregisterNode, isFocused } = useFocusContext();
+  useEffect3(() => {
+    registerNode(nodeId, parentId);
+    return () => {
+      unregisterNode(nodeId);
+    };
+  }, [nodeId, parentId, registerNode, unregisterNode]);
+  return {
+    id: nodeId,
+    focused: isFocused(nodeId),
+    focus: () => focusNode(nodeId)
+  };
+};
+
+// src/core/focus/FocusGroup.tsx
+import { jsx as jsx5 } from "react/jsx-runtime";
+function FocusGroup({
+  children,
+  direction = "vertical",
+  value,
+  wrap = true,
+  navigable = true
+}) {
+  const { id } = useFocus();
+  const { focusNode, navigateSibling } = useFocusContext();
+  const bindMapRef = useRef3(/* @__PURE__ */ new Map());
+  const register = useCallback3((logicalId, nodeId) => {
+    bindMapRef.current.set(logicalId, nodeId);
+  }, []);
+  const unregister = useCallback3((logicalId) => {
+    bindMapRef.current.delete(logicalId);
+  }, []);
+  useEffect4(() => {
+    if (value) {
+      const nodeId = bindMapRef.current.get(value);
+      if (nodeId) {
+        focusNode(nodeId);
+      }
+    }
+  }, [value, focusNode]);
+  const bindContextValue = value ? { register, unregister } : null;
+  const navigationKeys = useMemo(() => {
+    if (!navigable) return {};
+    const next = () => navigateSibling("next", wrap);
+    const prev = () => navigateSibling("prev", wrap);
+    return direction === "vertical" ? {
+      j: next,
+      k: prev,
+      down: next,
+      up: prev
+    } : {
+      l: next,
+      h: prev,
+      right: next,
+      left: prev
+    };
+  }, [navigable, direction, wrap, navigateSibling]);
+  useKeybindings({ id }, navigationKeys);
+  return /* @__PURE__ */ jsx5(FocusNodeContext.Provider, { value: id, children: /* @__PURE__ */ jsx5(FocusBindContext.Provider, { value: bindContextValue, children }) });
+}
+
+// src/core/focus/useFocusState.ts
+import { useState as useState2 } from "react";
+function useFocusState(initial) {
+  const [focused, setFocused] = useState2(initial);
+  return [focused, setFocused];
+}
+
+// src/core/GigglesProvider.tsx
+import { jsx as jsx6 } from "react/jsx-runtime";
+function GigglesProvider({ children }) {
+  return /* @__PURE__ */ jsx6(FocusProvider, { children: /* @__PURE__ */ jsx6(InputProvider, { children: /* @__PURE__ */ jsx6(InputRouter, { children }) }) });
+}
+export {
+  FocusGroup,
+  FocusTrap,
+  GigglesProvider,
+  useFocus,
+  useFocusState,
+  useKeybindings
+};

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "giggles",
-  "version": "0.0.3",
+  "version": "0.1.0",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/zion-off/bento.git"
+    "url": "git+https://github.com/zion-off/giggles.git"
   },
   "type": "module",
   "main": "dist/index.js",
@@ -31,13 +31,13 @@
     "ink": "^6.0.0",
     "react": "^18.0.0 || ^19.0.0"
   },
-  "dependencies": {},
   "devDependencies": {
     "@trivago/prettier-plugin-sort-imports": "^4.3.0",
     "@types/node": "^22.0.0",
     "@types/react": "^19.2.13",
     "eslint": "^9.0.0",
     "eslint-plugin-react": "^7.32.2",
+    "eslint-plugin-react-hooks": "^7.0.1",
     "ink": "^6.6.0",
     "nodemon": "^3.1.11",
     "prettier": "^2.8.7",