@silo-code/sdk 0.6.0

package/dist/use-focus-group.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-focus-group.d.ts","sourceRoot":"","sources":["../src/use-focus-group.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,OAAO,CAAC;AAEf;;;;;;;;;;GAUG;AACH,MAAM,MAAM,qBAAqB,GAAG,UAAU,GAAG,YAAY,GAAG,MAAM,CAAC;AAEvE;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,2EAA2E;IAC3E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;IACzC,kCAAkC;IAClC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,IAAI,CAAC;CACvD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,IAAI,CAAC;CACjC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IACtC,SAAS,EAAE,CAAC,CAAC,EAAE,aAAa,KAAK,IAAI,CAAC;IACtC,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,aAAa,EAAE,CAAC,CAAC,EAAE,YAAY,KAAK,IAAI,CAAC;IACzC,8EAA8E;IAC9E,iBAAiB,EAAE,EAAE,CAAC;IACtB;;;OAGG;IACH,oBAAoB,CAAC,EAAE,EAAE,CAAC;CAC3B;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,qCAAqC;IACrC,cAAc,EAAE,wBAAwB,CAAC;IACzC,8BAA8B;IAC9B,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,mBAAmB,CAAC;IACrD,+EAA+E;IAC/E,WAAW,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACpC;AAsBD;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,uBAAuB;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,qFAAqF;IACrF,GAAG,EAAE,MAAM,CAAC;IACZ,6BAA6B;IAC7B,WAAW,EAAE,qBAAqB,CAAC;IACnC,mCAAmC;IACnC,IAAI,EAAE,OAAO,CAAC;IACd,sDAAsD;IACtD,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;CACzC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,GAAG,IAAI,CA6B7E;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,OAAO,CAAC;CACnB,GAAG,OAAO,CAEV;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,iBAAiB,GAAG,UAAU,CAiHpE"}

package/dist/use-focus-group.js

@@ -0,0 +1,236 @@
+import { useCallback, useEffect, useRef, useState, } from "react";
+const clamp = (n, max) => Math.max(0, Math.min(n, max));
+/** First navigable index at or after scanning the whole list, or `null`. */
+function firstNavigable(count, isNavigable) {
+    for (let i = 0; i < count; i++)
+        if (isNavigable(i))
+            return i;
+    return null;
+}
+/** Last navigable index, or `null`. */
+function lastNavigable(count, isNavigable) {
+    for (let i = count - 1; i >= 0; i--)
+        if (isNavigable(i))
+            return i;
+    return null;
+}
+/**
+ * The index a navigation key moves focus to within a focus group, or `null` when
+ * the key isn't a navigation key for this orientation, the list is empty, or no
+ * other navigable item exists. Steps over non-navigable items; wraps at the ends
+ * when `wrap`, otherwise stops (returns `null`). `Home`/`End` jump to the
+ * first/last navigable index regardless of orientation.
+ *
+ * This is the pure roving-index core that {@link useFocusGroup} runs internally.
+ * Reach for it directly only when you **can't** use the hook — e.g. a widget that
+ * drives keys from a document-level listener and a state-driven highlight rather
+ * than DOM focus (Silo's menus work this way). For an ordinary list/toolbar,
+ * prefer {@link useFocusGroup}, which calls this for you.
+ *
+ * @example
+ * ```ts
+ * const next = focusGroupNextIndex({
+ *   current: activeIndex, count: items.length, key: e.key,
+ *   orientation: "vertical", wrap: true,
+ *   isNavigable: (i) => !items[i].disabled,
+ * });
+ * if (next !== null) setActiveIndex(next);
+ * ```
+ *
+ * @category Consumer Services
+ * @public
+ */
+export function focusGroupNextIndex(params) {
+    const { current, count, key, orientation, wrap, isNavigable } = params;
+    if (count <= 0)
+        return null;
+    if (key === "Home")
+        return firstNavigable(count, isNavigable);
+    if (key === "End")
+        return lastNavigable(count, isNavigable);
+    const vertical = orientation === "vertical" || orientation === "grid";
+    const horizontal = orientation === "horizontal" || orientation === "grid";
+    let dir = 0;
+    if ((vertical && key === "ArrowDown") || (horizontal && key === "ArrowRight"))
+        dir = 1;
+    else if ((vertical && key === "ArrowUp") ||
+        (horizontal && key === "ArrowLeft"))
+        dir = -1;
+    if (dir === 0)
+        return null;
+    let i = current;
+    for (let n = 0; n < count; n++) {
+        i += dir;
+        if (i < 0 || i >= count) {
+            if (!wrap)
+                return null;
+            i = (i + count) % count;
+        }
+        if (i === current)
+            return null; // came all the way around — nothing else navigable
+        if (isNavigable(i))
+            return i;
+    }
+    return null;
+}
+/**
+ * Whether a keydown should open an item's context menu — the dedicated
+ * ContextMenu (Menu/Application) key, or `Shift`+`F10` for keyboards without it.
+ *
+ * @internal
+ */
+export function isContextMenuKey(e) {
+    return e.key === "ContextMenu" || (e.shiftKey && e.key === "F10");
+}
+/**
+ * Headless keyboard navigation for a **focus group** — a set of peer items that
+ * share a single tab stop and move with the arrow keys (a list, listbox, menu,
+ * toolbar, tablist, radio group, or flat grid). It owns, once and correctly, the
+ * mechanics every such widget needs:
+ *
+ * - a single-tab-stop `tabIndex` (one item tabbable, the rest `-1`), so the group
+ *   is one Tab stop and the host's "focus the first tabbable" entry lands on
+ *   {@link FocusGroupOptions.start | start};
+ * - Arrow / Home / End movement (per
+ *   {@link FocusGroupOptions.orientation | orientation}, wrapping or stopping per
+ *   {@link FocusGroupOptions.wrap | wrap}, skipping non-navigable items);
+ * - `Enter`/`Space` → {@link FocusGroupOptions.onActivate | onActivate}, the
+ *   context-menu key / `Shift`+`F10` → {@link FocusGroupOptions.onMenu | onMenu};
+ * - a **WebKit-safe, keyboard-only focus ring**: it flags the active item with a
+ *   `data-focus-visible` attribute (state-driven, because WebKit won't repaint
+ *   `:focus` for the programmatic focus the host's region cycle performs), and
+ *   the host ships the ring CSS keyed on that attribute — so every group's ring
+ *   is identical and correct without the author touching it.
+ *
+ * You keep the markup and semantics (`role`, `aria-*`, `onClick`, styling); the
+ * hook supplies behavior. Spread {@link FocusGroup.containerProps | containerProps}
+ * on the wrapper and {@link FocusGroup.getItemProps | getItemProps(i)} on each
+ * item. The index is clamped when {@link FocusGroupOptions.count | count} changes,
+ * so live-filtering a list is safe.
+ *
+ * @example
+ * ```tsx
+ * const group = useFocusGroup({
+ *   count: items.length,
+ *   start: activeIndex,
+ *   onActivate: (i) => select(items[i].id),
+ *   onMenu: (i, anchor) => showMenu(items[i], anchor),
+ * });
+ * return (
+ *   <ul {...group.containerProps}>
+ *     {items.map((it, i) => (
+ *       <li key={it.id} {...group.getItemProps(i)}>{it.label}</li>
+ *     ))}
+ *   </ul>
+ * );
+ * ```
+ *
+ * @category Consumer Services
+ * @public
+ */
+export function useFocusGroup(options) {
+    const { count, start = 0, orientation = "vertical", wrap = true, isNavigable = () => true, onActivate, onMenu, } = options;
+    const [activeIndex, setActiveIndex] = useState(0);
+    // Focus is somewhere inside the group (drives re-parking on the active row).
+    const [focused, setFocused] = useState(false);
+    // Focus arrived/moved via the keyboard (drives the ring), à la `:focus-visible`.
+    const [visible, setVisible] = useState(false);
+    // The most recent focus was preceded by a pointer-down on an item — so it's a
+    // mouse focus and must NOT show the ring. Read+reset on the following onFocus.
+    const pointerOrigin = useRef(false);
+    const itemEls = useRef(new Map());
+    // Read latest options in stable handlers without re-creating them each render.
+    const opts = useRef({
+        count,
+        orientation,
+        wrap,
+        isNavigable,
+        onActivate,
+        onMenu,
+    });
+    opts.current = { count, orientation, wrap, isNavigable, onActivate, onMenu };
+    // Park the active index on `start` (clamped, and nudged to a navigable item)
+    // whenever the group isn't focused, so the host's entry lands there; while
+    // focused, just keep the index in range as items come and go.
+    useEffect(() => {
+        setActiveIndex((i) => {
+            if (count <= 0)
+                return 0;
+            if (focused)
+                return Math.min(i, count - 1);
+            const at = clamp(start, count - 1);
+            return isNavigable(at) ? at : (firstNavigable(count, isNavigable) ?? at);
+            // isNavigable identity changes per render; `start`/`count`/`focused` are the
+            // real inputs — re-running on isNavigable alone would thrash focus.
+            // eslint-disable-next-line react-hooks/exhaustive-deps
+        });
+    }, [start, focused, count]);
+    const focusItem = useCallback((index) => {
+        itemEls.current.get(index)?.focus();
+    }, []);
+    const containerProps = {
+        onBlur: (e) => {
+            // Drop focus state only when focus leaves the whole group (not when it
+            // moves between two items).
+            if (!e.currentTarget.contains(e.relatedTarget)) {
+                setFocused(false);
+                setVisible(false);
+            }
+        },
+    };
+    const getItemProps = (index) => ({
+        tabIndex: index === activeIndex ? 0 : -1,
+        ref: (el) => {
+            if (el)
+                itemEls.current.set(index, el);
+            else
+                itemEls.current.delete(index);
+        },
+        onPointerDown: () => {
+            pointerOrigin.current = true;
+        },
+        onFocus: () => {
+            setFocused(true);
+            setActiveIndex(index);
+            // Keyboard/programmatic focus shows the ring; a pointer-driven focus doesn't.
+            setVisible(!pointerOrigin.current);
+            pointerOrigin.current = false;
+        },
+        onKeyDown: (e) => {
+            const o = opts.current;
+            if (e.key === "Enter" || e.key === " ") {
+                if (!o.onActivate)
+                    return;
+                e.preventDefault();
+                setVisible(true);
+                o.onActivate(index);
+                return;
+            }
+            if (isContextMenuKey(e)) {
+                if (!o.onMenu)
+                    return;
+                e.preventDefault();
+                setVisible(true);
+                o.onMenu(index, e.currentTarget);
+                return;
+            }
+            const next = focusGroupNextIndex({
+                current: index,
+                count: o.count,
+                key: e.key,
+                orientation: o.orientation,
+                wrap: o.wrap,
+                isNavigable: o.isNavigable,
+            });
+            if (next === null)
+                return;
+            e.preventDefault();
+            setVisible(true);
+            focusItem(next);
+        },
+        "data-focus-item": "",
+        ...(visible && index === activeIndex ? { "data-focus-visible": "" } : {}),
+    });
+    return { containerProps, getItemProps, activeIndex, focusItem };
+}
+//# sourceMappingURL=use-focus-group.js.map

package/dist/use-focus-group.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-focus-group.js","sourceRoot":"","sources":["../src/use-focus-group.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,SAAS,EACT,MAAM,EACN,QAAQ,GAIT,MAAM,OAAO,CAAC;AAuGf,MAAM,KAAK,GAAG,CAAC,CAAS,EAAE,GAAW,EAAU,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;AAEhF,4EAA4E;AAC5E,SAAS,cAAc,CACrB,KAAa,EACb,WAAmC;IAEnC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE;QAAE,IAAI,WAAW,CAAC,CAAC,CAAC;YAAE,OAAO,CAAC,CAAC;IAC7D,OAAO,IAAI,CAAC;AACd,CAAC;AAED,uCAAuC;AACvC,SAAS,aAAa,CACpB,KAAa,EACb,WAAmC;IAEnC,KAAK,IAAI,CAAC,GAAG,KAAK,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE;QAAE,IAAI,WAAW,CAAC,CAAC,CAAC;YAAE,OAAO,CAAC,CAAC;IAClE,OAAO,IAAI,CAAC;AACd,CAAC;AAuBD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAA0B;IAC5D,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,MAAM,CAAC;IACvE,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5B,IAAI,GAAG,KAAK,MAAM;QAAE,OAAO,cAAc,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;IAC9D,IAAI,GAAG,KAAK,KAAK;QAAE,OAAO,aAAa,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;IAE5D,MAAM,QAAQ,GAAG,WAAW,KAAK,UAAU,IAAI,WAAW,KAAK,MAAM,CAAC;IACtE,MAAM,UAAU,GAAG,WAAW,KAAK,YAAY,IAAI,WAAW,KAAK,MAAM,CAAC;IAC1E,IAAI,GAAG,GAAe,CAAC,CAAC;IACxB,IAAI,CAAC,QAAQ,IAAI,GAAG,KAAK,WAAW,CAAC,IAAI,CAAC,UAAU,IAAI,GAAG,KAAK,YAAY,CAAC;QAC3E,GAAG,GAAG,CAAC,CAAC;SACL,IACH,CAAC,QAAQ,IAAI,GAAG,KAAK,SAAS,CAAC;QAC/B,CAAC,UAAU,IAAI,GAAG,KAAK,WAAW,CAAC;QAEnC,GAAG,GAAG,CAAC,CAAC,CAAC;IACX,IAAI,GAAG,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAE3B,IAAI,CAAC,GAAG,OAAO,CAAC;IAChB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;QAC/B,CAAC,IAAI,GAAG,CAAC;QACT,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,EAAE,CAAC;YACxB,IAAI,CAAC,IAAI;gBAAE,OAAO,IAAI,CAAC;YACvB,CAAC,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,GAAG,KAAK,CAAC;QAC1B,CAAC;QACD,IAAI,CAAC,KAAK,OAAO;YAAE,OAAO,IAAI,CAAC,CAAC,mDAAmD;QACnF,IAAI,WAAW,CAAC,CAAC,CAAC;YAAE,OAAO,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,CAGhC;IACC,OAAO,CAAC,CAAC,GAAG,KAAK,aAAa,IAAI,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,GAAG,KAAK,KAAK,CAAC,CAAC;AACpE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,MAAM,UAAU,aAAa,CAAC,OAA0B;IACtD,MAAM,EACJ,KAAK,EACL,KAAK,GAAG,CAAC,EACT,WAAW,GAAG,UAAU,EACxB,IAAI,GAAG,IAAI,EACX,WAAW,GAAG,GAAG,EAAE,CAAC,IAAI,EACxB,UAAU,EACV,MAAM,GACP,GAAG,OAAO,CAAC;IAEZ,MAAM,CAAC,WAAW,EAAE,cAAc,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IAClD,6EAA6E;IAC7E,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC9C,iFAAiF;IACjF,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAE9C,8EAA8E;IAC9E,+EAA+E;IAC/E,MAAM,aAAa,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IACpC,MAAM,OAAO,GAAG,MAAM,CAA2B,IAAI,GAAG,EAAE,CAAC,CAAC;IAE5D,+EAA+E;IAC/E,MAAM,IAAI,GAAG,MAAM,CAAC;QAClB,KAAK;QACL,WAAW;QACX,IAAI;QACJ,WAAW;QACX,UAAU;QACV,MAAM;KACP,CAAC,CAAC;IACH,IAAI,CAAC,OAAO,GAAG,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;IAE7E,6EAA6E;IAC7E,2EAA2E;IAC3E,8DAA8D;IAC9D,SAAS,CAAC,GAAG,EAAE;QACb,cAAc,CAAC,CAAC,CAAC,EAAE,EAAE;YACnB,IAAI,KAAK,IAAI,CAAC;gBAAE,OAAO,CAAC,CAAC;YACzB,IAAI,OAAO;gBAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;YAC3C,MAAM,EAAE,GAAG,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;YACnC,OAAO,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,KAAK,EAAE,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC;YACzE,6EAA6E;YAC7E,oEAAoE;YACpE,uDAAuD;QACzD,CAAC,CAAC,CAAC;IACL,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;IAE5B,MAAM,SAAS,GAAG,WAAW,CAAC,CAAC,KAAa,EAAE,EAAE;QAC9C,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,CAAC;IACtC,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,MAAM,cAAc,GAA6B;QAC/C,MAAM,EAAE,CAAC,CAAa,EAAE,EAAE;YACxB,uEAAuE;YACvE,4BAA4B;YAC5B,IAAI,CAAC,CAAC,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC,aAA4B,CAAC,EAAE,CAAC;gBAC9D,UAAU,CAAC,KAAK,CAAC,CAAC;gBAClB,UAAU,CAAC,KAAK,CAAC,CAAC;YACpB,CAAC;QACH,CAAC;KACF,CAAC;IAEF,MAAM,YAAY,GAAG,CAAC,KAAa,EAAuB,EAAE,CAAC,CAAC;QAC5D,QAAQ,EAAE,KAAK,KAAK,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACxC,GAAG,EAAE,CAAC,EAAsB,EAAE,EAAE;YAC9B,IAAI,EAAE;gBAAE,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;;gBAClC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACrC,CAAC;QACD,aAAa,EAAE,GAAG,EAAE;YAClB,aAAa,CAAC,OAAO,GAAG,IAAI,CAAC;QAC/B,CAAC;QACD,OAAO,EAAE,GAAG,EAAE;YACZ,UAAU,CAAC,IAAI,CAAC,CAAC;YACjB,cAAc,CAAC,KAAK,CAAC,CAAC;YACtB,8EAA8E;YAC9E,UAAU,CAAC,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;YACnC,aAAa,CAAC,OAAO,GAAG,KAAK,CAAC;QAChC,CAAC;QACD,SAAS,EAAE,CAAC,CAAgB,EAAE,EAAE;YAC9B,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC;YACvB,IAAI,CAAC,CAAC,GAAG,KAAK,OAAO,IAAI,CAAC,CAAC,GAAG,KAAK,GAAG,EAAE,CAAC;gBACvC,IAAI,CAAC,CAAC,CAAC,UAAU;oBAAE,OAAO;gBAC1B,CAAC,CAAC,cAAc,EAAE,CAAC;gBACnB,UAAU,CAAC,IAAI,CAAC,CAAC;gBACjB,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;gBACpB,OAAO;YACT,CAAC;YACD,IAAI,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC;gBACxB,IAAI,CAAC,CAAC,CAAC,MAAM;oBAAE,OAAO;gBACtB,CAAC,CAAC,cAAc,EAAE,CAAC;gBACnB,UAAU,CAAC,IAAI,CAAC,CAAC;gBACjB,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,aAA4B,CAAC,CAAC;gBAChD,OAAO;YACT,CAAC;YACD,MAAM,IAAI,GAAG,mBAAmB,CAAC;gBAC/B,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,GAAG,EAAE,CAAC,CAAC,GAAG;gBACV,WAAW,EAAE,CAAC,CAAC,WAAW;gBAC1B,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,WAAW,EAAE,CAAC,CAAC,WAAW;aAC3B,CAAC,CAAC;YACH,IAAI,IAAI,KAAK,IAAI;gBAAE,OAAO;YAC1B,CAAC,CAAC,cAAc,EAAE,CAAC;YACnB,UAAU,CAAC,IAAI,CAAC,CAAC;YACjB,SAAS,CAAC,IAAI,CAAC,CAAC;QAClB,CAAC;QACD,iBAAiB,EAAE,EAAE;QACrB,GAAG,CAAC,OAAO,IAAI,KAAK,KAAK,WAAW,CAAC,CAAC,CAAC,EAAE,oBAAoB,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC1E,CAAC,CAAC;IAEH,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC;AAClE,CAAC"}

package/dist/use-service-state.d.ts

@@ -0,0 +1,36 @@
+import type { Disposable } from "./types";
+/**
+ * The minimal reactive contract every stateful `ctx` service satisfies: a
+ * `getState` returning a stable, frozen value and a `subscribe` that fires
+ * on change. This is exactly what React's `useSyncExternalStore` needs — and
+ * the only shape {@link useServiceState} requires.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface ReactiveService<T> {
+    getState(): T;
+    subscribe(listener: (s: T) => void): Disposable;
+}
+/**
+ * Subscribe a React component to a `ctx` service's reactive state. Returns the
+ * service's current state and re-renders when it changes — the one blessed
+ * way to read service state in an extension. Use it for every domain
+ * ({@link ExtensionContext.workspaces | workspaces},
+ * {@link ExtensionContext.layout | layout},
+ * {@link ExtensionContext.theme | theme}, …) rather than re-implementing the
+ * `useSyncExternalStore` boilerplate per call site.
+ *
+ * @example
+ * ```tsx
+ * function Panel({ ctx }: { ctx: ExtensionContext }) {
+ *   const ws = useServiceState(ctx.workspaces);
+ *   return <span>{ws.open.length} open workspaces</span>;
+ * }
+ * ```
+ *
+ * @category Consumer Services
+ * @public
+ */
+export declare function useServiceState<T>(service: ReactiveService<T>): T;
+//# sourceMappingURL=use-service-state.d.ts.map

package/dist/use-service-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-service-state.d.ts","sourceRoot":"","sources":["../src/use-service-state.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,QAAQ,IAAI,CAAC,CAAC;IACd,SAAS,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,IAAI,GAAG,UAAU,CAAC;CACjD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,CAAC,CAKjE"}

package/dist/use-service-state.js

@@ -0,0 +1,25 @@
+import { useCallback, useSyncExternalStore } from "react";
+/**
+ * Subscribe a React component to a `ctx` service's reactive state. Returns the
+ * service's current state and re-renders when it changes — the one blessed
+ * way to read service state in an extension. Use it for every domain
+ * ({@link ExtensionContext.workspaces | workspaces},
+ * {@link ExtensionContext.layout | layout},
+ * {@link ExtensionContext.theme | theme}, …) rather than re-implementing the
+ * `useSyncExternalStore` boilerplate per call site.
+ *
+ * @example
+ * ```tsx
+ * function Panel({ ctx }: { ctx: ExtensionContext }) {
+ *   const ws = useServiceState(ctx.workspaces);
+ *   return <span>{ws.open.length} open workspaces</span>;
+ * }
+ * ```
+ *
+ * @category Consumer Services
+ * @public
+ */
+export function useServiceState(service) {
+    return useSyncExternalStore(useCallback((cb) => service.subscribe(cb).dispose, [service]), service.getState);
+}
+//# sourceMappingURL=use-service-state.js.map

package/dist/use-service-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-service-state.js","sourceRoot":"","sources":["../src/use-service-state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAC;AAiB1D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,eAAe,CAAI,OAA2B;IAC5D,OAAO,oBAAoB,CACzB,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,CAAC,EAC7D,OAAO,CAAC,QAAQ,CACjB,CAAC;AACJ,CAAC"}

package/dist/workspace-service.d.ts

@@ -0,0 +1,72 @@
+import type { Disposable } from "./types";
+import type { Workspace } from "./domain-types";
+export type { Workspace, TerminalRecord } from "./domain-types";
+/**
+ * An immutable, frozen view of workspace state, returned by
+ * {@link WorkspaceService.getState} and delivered to subscribers — read
+ * access without a Valtio dependency.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface WorkspaceState {
+    /** All workspaces, in user-defined order. */
+    all: readonly Workspace[];
+    /** Workspaces where closedAt is null/undefined, in user-defined order. */
+    open: readonly Workspace[];
+    /** Workspaces where closedAt is set, sorted by closedAt descending. */
+    closed: readonly Workspace[];
+    activeId: string | null;
+    /** True once the persisted state has been loaded into the store. */
+    hydrated: boolean;
+}
+/**
+ * Input for {@link WorkspaceService.create}.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface CreateWorkspaceInput {
+    /** Absolute path of the workspace's primary folder. */
+    folder: string;
+    /** Display name for the workspace. */
+    name: string;
+}
+/**
+ * Consumer API for workspace state, exposed as {@link ExtensionContext.workspaces}.
+ * Read via {@link WorkspaceService.getState | getState} /
+ * {@link WorkspaceService.subscribe | subscribe}; drive via the create/rename/
+ * close methods. Opening editor tabs lives on {@link ExtensionContext.editors},
+ * not here.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface WorkspaceService {
+    /** Current frozen view of workspace state. */
+    getState(): WorkspaceState;
+    subscribe(listener: (s: WorkspaceState) => void): Disposable;
+    /**
+     * The workspace with this id, or `undefined`. A one-shot lookup for event
+     * handlers; for reactive reads use {@link useServiceState} over the state.
+     */
+    get(id: string): Workspace | undefined;
+    /** Show a folder picker and create a workspace from the chosen folder. */
+    createFromFolderPicker(): Promise<Workspace | null>;
+    create(input: CreateWorkspaceInput): Workspace;
+    rename(id: string, name: string): void;
+    reorder(from: string, to: string, position: "before" | "after"): void;
+    /** Activate (and reopen if closed). */
+    activate(id: string): void;
+    /** Soft close — workspace stays saved but is hidden from the active list. */
+    close(id: string): void;
+    /** Reverse of close. */
+    reopen(id: string): void;
+    /** Add an extra folder to a workspace (no-op if already present or is the primary). */
+    addFolder(id: string, folder: string): void;
+    /** Remove an extra folder from a workspace. */
+    removeFolder(id: string, folder: string): void;
+    /** Hard delete — permanent removal. */
+    delete(id: string): void;
+}
+//# sourceMappingURL=workspace-service.d.ts.map

package/dist/workspace-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-service.d.ts","sourceRoot":"","sources":["../src/workspace-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAGhD,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEhE;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,6CAA6C;IAC7C,GAAG,EAAE,SAAS,SAAS,EAAE,CAAC;IAC1B,0EAA0E;IAC1E,IAAI,EAAE,SAAS,SAAS,EAAE,CAAC;IAC3B,uEAAuE;IACvE,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC;IAC7B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,oEAAoE;IACpE,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8CAA8C;IAC9C,QAAQ,IAAI,cAAc,CAAC;IAC3B,SAAS,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,cAAc,KAAK,IAAI,GAAG,UAAU,CAAC;IAC7D;;;OAGG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;IACvC,0EAA0E;IAC1E,sBAAsB,IAAI,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IACpD,MAAM,CAAC,KAAK,EAAE,oBAAoB,GAAG,SAAS,CAAC;IAC/C,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,GAAG,IAAI,CAAC;IACtE,uCAAuC;IACvC,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,6EAA6E;IAC7E,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,wBAAwB;IACxB,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,uFAAuF;IACvF,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,+CAA+C;IAC/C,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/C,uCAAuC;IACvC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B"}

package/dist/workspace-service.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=workspace-service.js.map

package/dist/workspace-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-service.js","sourceRoot":"","sources":["../src/workspace-service.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@silo-code/sdk",
+  "version": "0.6.0",
+  "description": "The public, types-first SDK for building Silo extensions — the only surface third-party extensions import.",
+  "license": "MIT",
+  "author": "Dave Weaver",
+  "homepage": "https://github.com/silo-code/silo/tree/main/packages/sdk#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/silo-code/silo.git",
+    "directory": "packages/sdk"
+  },
+  "keywords": [
+    "silo",
+    "silo-code",
+    "extension",
+    "sdk",
+    "editor"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": "^19.1.0"
+  },
+  "dependencies": {
+    "dockview": "~6.3.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.8",
+    "typescript": "~5.8.3",
+    "vitest": "^4.1.7"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}

package/src/context-keys.ts

@@ -0,0 +1,18 @@
+/**
+ * Minimal context-keys store. Menu items, keybindings, and (later) view
+ * contributions can declare `when` clauses that read these values; the host
+ * re-evaluates the clauses whenever a key changes and updates UI state
+ * (enabled/disabled menu items, etc.).
+ *
+ * Keys are added as needed. Start narrow: only the keys we have a real use
+ * for. Avoid the temptation to mirror every piece of app state into here.
+ *
+ * @category Core Types
+ * @public
+ */
+export interface ContextKeys {
+  /** id of the viewer rendered by the dock's active panel, or null. */
+  activeViewerId: string | null;
+  /** editorId of the active dock panel if it's an editor panel, or null. */
+  activeEditorId: string | null;
+}

package/src/dnd-service.ts

@@ -0,0 +1,151 @@
+import type React from "react";
+import type { Disposable } from "./types";
+
+// `ctx.dnd` — first-class drag-and-drop for extensions (public contract). The
+// host owns the affordance (the floating drag chip + paste-mode overlay) and
+// the modifier-mode resolution; the implementation lives in the extension host.
+
+/**
+ * Well-known MIME types for Silo drag payloads. Use these constants (rather than
+ * raw strings) so drags interoperate across extensions and built-ins.
+ *
+ * @category Core Types
+ * @public
+ */
+export const DND_MIME = {
+  /** Absolute filesystem path of a file or directory being dragged. */
+  filePath: "application/x-silo-file-path",
+  /** Plain-text payload (mirrors the path today). */
+  text: "text/plain",
+} as const;
+
+/**
+ * A MIME type from the {@link DND_MIME} vocabulary.
+ *
+ * @category Core Types
+ * @public
+ */
+export type DndMime = (typeof DND_MIME)[keyof typeof DND_MIME];
+
+/**
+ * One typed item carried by a drag — a MIME type plus its string payload.
+ *
+ * @category Core Types
+ * @public
+ */
+export interface DndItem {
+  /** The item's MIME type; use a {@link DND_MIME} constant for interop. */
+  mime: string;
+  /** The string payload (e.g. an absolute path for {@link DND_MIME.filePath}). */
+  value: string;
+}
+
+/**
+ * What a drag carries and how its chip should read, passed to
+ * {@link DndService.beginDrag}.
+ *
+ * @category Core Types
+ * @public
+ */
+export interface DragInit {
+  /** Typed payload items written onto the native `dataTransfer`. */
+  items: DndItem[];
+  /** Label shown in the floating drag chip (e.g. the file name). */
+  label: string;
+  /** `dataTransfer.effectAllowed`; defaults to `"copyMove"`. */
+  effect?: "copy" | "move" | "copyMove";
+}
+
+/**
+ * The interaction mode resolved from held modifiers at hover/drop time:
+ * `"copy"` is the default (e.g. open / split); `"paste"` is Shift-held (e.g.
+ * insert path at caret / paste into the terminal). Resolved robustly even when
+ * WebKit suppresses key events mid-drag.
+ *
+ * @category Core Types
+ * @public
+ */
+export type DndMode = "copy" | "paste";
+
+/**
+ * Context delivered to a {@link DropTargetHandlers} callback for a drag over or
+ * drop on a registered target.
+ *
+ * @category Core Types
+ * @public
+ */
+export interface DropContext {
+  /**
+   * Typed items read from the native `dataTransfer`. Populated on `drop`;
+   * during `dragover` the browser exposes only MIME *types* (not values), so
+   * this may be empty there — branch on {@link DropContext.mode} / the target's
+   * `accepts` instead.
+   */
+  items: DndItem[];
+  /** The resolved modifier mode (Shift ⇒ `"paste"`). */
+  mode: DndMode;
+  /** Pointer X in client coordinates. */
+  clientX: number;
+  /** Pointer Y in client coordinates. */
+  clientY: number;
+  /** The underlying native event (escape hatch for advanced callers). */
+  nativeEvent: DragEvent;
+}
+
+/**
+ * Handlers for a target registered via {@link DndService.registerDropTarget}.
+ *
+ * @category Core Types
+ * @public
+ */
+export interface DropTargetHandlers {
+  /** MIME types this target consumes; a drag is accepted if it carries one. */
+  accepts: string[];
+  /**
+   * Called on a matching drop. Return `true` if you handled it — the host then
+   * calls `preventDefault()` + `stopPropagation()` so the drop does **not**
+   * fall through to other targets (e.g. the center dock opening a new pane).
+   */
+  onDrop(ctx: DropContext): boolean | void;
+  /**
+   * Optional: called on each accepted drag-over (drive hover styling). Return a
+   * drop effect to set the cursor, or nothing to leave it. The host already
+   * calls `preventDefault()` so the drop is allowed.
+   */
+  onDragOver?(ctx: DropContext): "copy" | "move" | "none" | void;
+  /**
+   * Optional: the pointer left the target (clear hover styling). Receives the
+   * native event so callers can ignore leaves into a descendant
+   * (`el.contains(e.relatedTarget)`).
+   */
+  onDragLeave?(e: DragEvent): void;
+  /**
+   * Attach listeners in the capture phase so this target intercepts before
+   * bubble-phase handlers (e.g. the center dock). Defaults to `false`.
+   */
+  capture?: boolean;
+}
+
+/**
+ * The drag-and-drop domain, exposed as {@link ExtensionContext.dnd}. Be a drag
+ * source with {@link DndService.beginDrag} and a drop target with
+ * {@link DndService.registerDropTarget}; payloads are typed via {@link DND_MIME}.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface DndService {
+  /**
+   * Begin a drag from inside a `dragstart` handler: writes the typed
+   * {@link DragInit.items} onto the native `dataTransfer`, hides the native
+   * drag preview, and starts the floating chip + paste-mode overlay affordance.
+   * Must be called synchronously within the `dragstart` event.
+   */
+  beginDrag(event: DragEvent | React.DragEvent, init: DragInit): void;
+  /**
+   * Register `el` as a drop target. The host attaches the drag listeners,
+   * resolves the modifier {@link DndMode}, and delivers a {@link DropContext}.
+   * Returns a {@link Disposable} that removes the listeners.
+   */
+  registerDropTarget(el: HTMLElement, handlers: DropTargetHandlers): Disposable;
+}