@jini-ai/ui 0.4.7 → 0.4.9

package/README.md

@@ -467,6 +467,8 @@ extraction job at the owner's direction.
 
 ## Kernel contracts
 
+Import `FetchQueryCache` and neutral query contracts from `@jini-ai/core/fetch`.
+The existing UI fetch-query entries retain deprecated type re-exports for compatibility.
 Fetch-query caches accept the shared `Clock` from `@jini-ai/core/primitives` through
 `new FetchQueryCache({}, { clock })`; clocks implement `nowMs()`. Freshness remains ten seconds
 by default and idle retention five minutes. Browser HTTP defaults now use injected

package/dist/features/admin-widgets/components/InfoTip.d.ts

@@ -1,3 +1,4 @@
+import { type ReactNode } from "react";
 import { useInfoTip } from "./InfoTip.hooks.js";
 /**
  * Native title tooltips have an OS-dependent hover delay, inconsistent screen-reader exposure
@@ -5,14 +6,34 @@ import { useInfoTip } from "./InfoTip.hooks.js";
  * focus, which onBlur alone cannot do.
  * A body portal escapes overflow:hidden/scrolling ancestors: z-index cannot rescue an absolutely
  * positioned descendant from clipping. Measured viewport coordinates position it above by
- * preference, with the hook's headroom guard choosing below near the viewport's top.
+ * preference, with the hook's headroom guard choosing below near the viewport's top; near a side
+ * edge (or a host panel marked `data-jini-tip-bounds`) it shifts by its real width, never squeezes.
  * Keep state and DOM measurement in the injectable hook so rendering can use fixed fake state.
+ * Touch has no hover, so a tap (or Enter/Space) pins the tip open until a second tap, an outside
+ * tap, blur or Escape; a hover-opened tip still closes when the pointer leaves.
  */
 export interface InfoTipProps {
+    /** The explanation the bubble shows. */
     label: string;
+    /**
+     * Short accessible name for the icon ("About subagents"). Omitted, the icon is named by `label`
+     * itself, the original contract. Given, `label` becomes the icon's description instead, so a
+     * screen reader hears a short name plus the full text rather than one long name.
+     */
+    triggerLabel?: string | undefined;
+    /**
+     * Id for an always-present hidden copy of `label`, so the control the tip explains (a checkbox,
+     * a field) can point its own `aria-describedby` at it; the icon references it too.
+     */
+    descriptionId?: string | undefined;
+    /** Preferred side, or inline help that reserves space instead of covering nearby controls. */
+    placement?: "top" | "bottom" | "inline" | undefined;
     useTip?: typeof useInfoTip | undefined;
     agentHandle?: string | undefined;
+    /** What the trigger shows instead of the default ⓘ, e.g. a status icon whose meaning the bubble
+     *  explains. Decorative: the trigger is still named by `triggerLabel`/`label`. */
+    icon?: ReactNode | undefined;
 }
 /** Focus/hover tooltip that portals outside clipping ancestors; Escape dismisses in place. */
-export declare function InfoTip({ label, useTip, agentHandle: handle }: InfoTipProps): import("react").JSX.Element;
+export declare function InfoTip({ label, triggerLabel, descriptionId, placement: preferredPlacement, useTip, agentHandle: handle, icon }: InfoTipProps): import("react").JSX.Element;
 //# sourceMappingURL=InfoTip.d.ts.map

package/dist/features/admin-widgets/components/InfoTip.hooks.d.ts

@@ -1,16 +1,36 @@
 import { type KeyboardEvent } from "react";
+/** Separate the hook for injectable rendering state. Its only outside effect is synchronous DOM
+ * measurement, so another async dependency/port layer would provide no rejection seam to test. */
+/** Hosts mark a panel (e.g. an assistant dock) with this attribute to keep tips inside it. */
+export declare const TIP_BOUNDS_ATTRIBUTE = "data-jini-tip-bounds";
 export interface InfoTipController {
     open: boolean;
     placement: "above" | "below";
+    /** `arrowLeft` (px inside the bubble) keeps the arrow on the icon after an edge shift; optional
+     *  for injected controllers, whose arrow stays centred. */
     coords: {
         top: number;
         left: number;
+        arrowLeft?: number | undefined;
     };
     iconRef: React.RefObject<HTMLSpanElement | null>;
+    /** Portal measurement for a requested placement; optional for injected controllers. */
+    bubbleRef?: React.RefObject<HTMLSpanElement | null>;
     show: () => void;
+    /** Closes and unpins: blur, Escape, an outside tap. */
     hide: () => void;
-    /** Escape closes in place; blur only covers leaving the trigger with Tab/Shift+Tab. */
+    /** Pointer left the icon: closes only a hover-opened tip, never one the operator tapped open. */
+    leave: () => void;
+    /** Tap/click/Enter/Space: pins an open tip so it survives the pointer leaving (touch has no
+     *  hover to keep it up), or closes a pinned one. Hover alone never pins. */
+    toggle: () => void;
+    /** Escape closes in place; Enter/Space toggle like a button; blur covers Tab/Shift+Tab. */
     handleIconKeyDown: (e: KeyboardEvent<HTMLSpanElement>) => void;
 }
-export declare function useInfoTip(): InfoTipController;
+/** Prefer a host's placement when the measured bubble fits; default preserves automatic flipping.
+ * @complexity Time/space: O(1), with one icon and one bubble measurement.
+ */
+export declare function useInfoTip(_input?: Record<string, never>, { placement: preferredPlacement }?: {
+    placement?: "top" | "bottom" | undefined;
+}): InfoTipController;
 //# sourceMappingURL=InfoTip.hooks.d.ts.map

package/dist/features/admin-widgets/components/InfoTip.hooks.js

@@ -1,45 +1,92 @@
-import { useRef, useState } from "react";
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
+import { useDismissOnOutsideOrEscape } from "../../../browser/index.js";
+import { placeInfoTipBubble } from "./InfoTip.rules.js";
 /** Separate the hook for injectable rendering state. Its only outside effect is synchronous DOM
  * measurement, so another async dependency/port layer would provide no rejection seam to test. */
-/** Above is a preference: require this much headroom before allowing an above-opening bubble. */
-const ABOVE_HEADROOM_PX = 176;
-/** Half the bubble's 18rem CSS max-width at a 16px root font. This worst-case width keeps narrow
- * copy safe too. Pure icon-centering previously placed half a tip offscreen near a viewport edge. */
-const HALF_MAX_BUBBLE_WIDTH_PX = 144;
-/** Keep breathing room between the clamped bubble and either viewport edge. */
-const EDGE_MARGIN_PX = 8;
-/** Below 304px the clamp's minimum exceeds its maximum; center instead of using an inverted range. */
-function clampBubbleLeft(idealLeft) {
-    const minLeft = EDGE_MARGIN_PX + HALF_MAX_BUBBLE_WIDTH_PX;
-    const maxLeft = window.innerWidth - EDGE_MARGIN_PX - HALF_MAX_BUBBLE_WIDTH_PX;
-    if (maxLeft < minLeft)
-        return window.innerWidth / 2;
-    return Math.min(Math.max(idealLeft, minLeft), maxLeft);
-}
-export function useInfoTip() {
+/** Hosts mark a panel (e.g. an assistant dock) with this attribute to keep tips inside it. */
+export const TIP_BOUNDS_ATTRIBUTE = "data-jini-tip-bounds";
+/** Prefer a host's placement when the measured bubble fits; default preserves automatic flipping.
+ * @complexity Time/space: O(1), with one icon and one bubble measurement.
+ */
+export function useInfoTip(_input = {}, { placement: preferredPlacement } = {}) {
     const [open, setOpen] = useState(false);
     const [placement, setPlacement] = useState("above");
     const [coords, setCoords] = useState({ top: 0, left: 0 });
+    const [pinned, setPinned] = useState(false);
     const iconRef = useRef(null);
+    const bubbleRef = useRef(null);
+    // Placement math lives in `placeInfoTipBubble`; this only gathers the measurements. Before the
+    // portal exists the bubble is unmeasured and the rules assume the worst-case width.
+    const place = () => {
+        const icon = iconRef.current;
+        const rect = icon?.getBoundingClientRect();
+        if (!icon || !rect)
+            return false;
+        const measured = bubbleRef.current?.getBoundingClientRect();
+        const boundsRect = icon.closest(`[${TIP_BOUNDS_ATTRIBUTE}]`)?.getBoundingClientRect();
+        const next = placeInfoTipBubble({
+            anchor: { left: rect.left, top: rect.top, width: rect.width, height: rect.bottom - rect.top },
+            bubble: measured ? { width: measured.width, height: measured.height } : null,
+            viewport: { width: window.innerWidth, height: window.innerHeight },
+        }, { bounds: boundsRect ? { left: boundsRect.left, right: boundsRect.right } : undefined, preferred: preferredPlacement });
+        setPlacement(next.placement);
+        setCoords(measured && measured.width > 0 ? { top: next.top, left: next.left, arrowLeft: next.arrowLeft } : { top: next.top, left: next.left });
+        return true;
+    };
     const show = () => {
-        const rect = iconRef.current?.getBoundingClientRect();
-        if (!rect)
+        if (place())
+            setOpen(true);
+    };
+    // The portal exists only after opening. Re-place before paint with its real size, so a short tip
+    // near an edge shifts only as far as it must and a short tip fits above its label.
+    useLayoutEffect(() => {
+        if (open)
+            place();
+    }, [open, preferredPlacement]);
+    const hide = () => {
+        setOpen(false);
+        setPinned(false);
+    };
+    const leave = () => {
+        if (!pinned)
+            setOpen(false);
+    };
+    const toggle = () => {
+        if (open && pinned) {
+            hide();
             return;
-        const nextPlacement = rect.top < ABOVE_HEADROOM_PX ? "below" : "above";
-        setPlacement(nextPlacement);
-        setCoords({
-            top: nextPlacement === "above" ? rect.top : rect.bottom,
-            left: clampBubbleLeft(rect.left + rect.width / 2),
-        });
-        setOpen(true);
+        }
+        show();
+        setPinned(true);
     };
-    const hide = () => setOpen(false);
+    // A tapped-open tip stays up until the operator taps elsewhere; the bubble itself is
+    // pointer-events:none, so "outside the icon" is every other target.
+    useDismissOnOutsideOrEscape({ onDismiss: hide }, { enabled: pinned, containerRef: iconRef });
+    // The bubble is position:fixed at measured viewport coordinates, so a scroll while it is open
+    // would leave it floating over the wrong content. Re-measure instead of closing: a pinned tip
+    // the operator is reading should follow its icon.
+    useEffect(() => {
+        if (!open)
+            return;
+        const follow = () => show();
+        window.addEventListener("scroll", follow, true);
+        window.addEventListener("resize", follow);
+        return () => {
+            window.removeEventListener("scroll", follow, true);
+            window.removeEventListener("resize", follow);
+        };
+    }, [open]);
     function handleIconKeyDown(e) {
         if (e.key === "Escape" && open) {
             e.stopPropagation();
             hide();
+            return;
+        }
+        if (e.key === "Enter" || e.key === " ") {
+            e.preventDefault();
+            toggle();
         }
     }
-    return { open, placement, coords, iconRef, show, hide, handleIconKeyDown };
+    return { open, placement, coords, iconRef, bubbleRef, show, hide, leave, toggle, handleIconKeyDown };
 }
 //# sourceMappingURL=InfoTip.hooks.js.map

package/dist/features/admin-widgets/components/InfoTip.js

@@ -1,12 +1,20 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from "react";
 import { createPortal } from "react-dom";
 import { agentHandle } from "@jini-ai/agentic";
 import { useInfoTip } from "./InfoTip.hooks.js";
+import { infoTipBubbleStyle } from "./InfoTip.rules.js";
 /** Focus/hover tooltip that portals outside clipping ancestors; Escape dismisses in place. */
-export function InfoTip({ label, useTip = useInfoTip, agentHandle: handle }) {
-    const { open, placement, coords, iconRef, show, hide, handleIconKeyDown } = useTip();
-    return (_jsxs("span", { className: "info-tip", children: [_jsx("span", { ref: iconRef, className: "info-tip-icon", tabIndex: 0, "aria-label": label, onMouseEnter: show, onMouseLeave: hide, onFocus: show, onBlur: hide, onKeyDown: handleIconKeyDown, ...(handle ? agentHandle({ handle: handle }, { role: "button", label }) : {}), children: "\u24D8" }), open
-                ? createPortal(_jsx("span", { className: placement === "below" ? "info-tip-bubble info-tip-bubble-below" : "info-tip-bubble", role: "presentation", "aria-hidden": "true", style: { top: coords.top, left: coords.left }, children: label }), document.body)
+export function InfoTip({ label, triggerLabel, descriptionId, placement: preferredPlacement, useTip = useInfoTip, agentHandle: handle, icon }) {
+    const { open, placement, coords, iconRef, bubbleRef, show, hide, leave, toggle, handleIconKeyDown } = useTip({}, { placement: preferredPlacement === "inline" ? undefined : preferredPlacement });
+    const autoId = useId();
+    const name = triggerLabel ?? label;
+    // With no short name the icon is already named by the full text; describing it again would
+    // make a screen reader read it twice.
+    const textId = descriptionId ?? (triggerLabel ? autoId : undefined);
+    const describedBy = triggerLabel ? textId : undefined;
+    return (_jsxs("span", { className: preferredPlacement === "inline" ? "info-tip info-tip--inline" : "info-tip", children: [_jsx("span", { ref: iconRef, className: icon ? "info-tip-icon info-tip-icon--custom" : "info-tip-icon", role: "button", tabIndex: 0, "aria-label": name, "aria-expanded": open, ...(describedBy ? { "aria-describedby": describedBy } : {}), onMouseEnter: show, onMouseLeave: leave, onFocus: show, onBlur: hide, onClick: toggle, onKeyDown: handleIconKeyDown, ...(handle ? agentHandle({ handle: handle }, { role: "button", label: name }) : {}), children: icon ?? "ⓘ" }), textId ? _jsx("span", { id: textId, hidden: true, children: label }) : null, open && preferredPlacement === "inline" ? _jsx("span", { className: "info-tip-inline-copy", "aria-hidden": "true", children: label }) : open
+                ? createPortal(_jsx("span", { ref: bubbleRef, className: placement === "below" ? "info-tip-bubble info-tip-bubble-below" : "info-tip-bubble", role: "presentation", "aria-hidden": "true", style: infoTipBubbleStyle(coords), children: label }), document.body)
                 : null] }));
 }
 //# sourceMappingURL=InfoTip.js.map

package/dist/features/admin-widgets/components/InfoTip.rules.d.ts

@@ -0,0 +1,72 @@
+import type { CSSProperties } from "react";
+/** Above is a preference: require this much headroom before allowing an above-opening bubble
+ * whose height is not measured yet. */
+export declare const ABOVE_HEADROOM_PX = 176;
+/** The bubble's 18rem CSS max-width at a 16px root font. Before the portal renders there is no
+ * real width to measure, so the first estimate assumes the worst case. */
+export declare const MAX_BUBBLE_WIDTH_PX = 288;
+/** Keep breathing room between the bubble and either edge of its bounds. */
+export declare const EDGE_MARGIN_PX = 8;
+export interface InfoTipPlacement {
+    placement: "above" | "below";
+    /** Viewport y the CSS translates from: the icon's top (above) or bottom (below). */
+    top: number;
+    /** The bubble's centre x in viewport pixels (its CSS is `translate(-50%, …)`). */
+    left: number;
+    /** The arrow's x inside the bubble, so it still points at the icon after a shift. */
+    arrowLeft: number;
+}
+/**
+ * Where an `InfoTip`-style bubble goes: centred under/over its icon, then shifted (never squeezed)
+ * just far enough to stay inside `bounds` (e.g. the assistant dock) and the viewport.
+ *
+ * Why the real measured width: the old clamp assumed every bubble was 18rem wide, so every short tip
+ * within 152px of the right edge got the same left — "Remove" sat ~86px away from its ✕ in the
+ * dock (Chrome re-check, 2026-10-11). Shared by `useInfoTip` and Tovu's dock-header tips so both
+ * place identically.
+ * @param input.anchor The icon's `getBoundingClientRect()`.
+ * @param input.bubble The rendered bubble's measured size; `null` before the portal exists.
+ * @param input.viewport `window.innerWidth` / `innerHeight`.
+ * @param options.bounds Horizontal limits of a containing panel; ignored when the bubble cannot fit
+ *   in them (it then only has to fit the viewport).
+ * @param options.preferred A host's preferred side. Bottom flips above only when it would overflow
+ *   the viewport's bottom and fits above; top falls back below without the measured headroom.
+ * @returns Coordinates for the portal plus the arrow offset. A bubble wider than the viewport's
+ *   usable span centres in the viewport rather than using an inverted clamp range.
+ * @complexity O(1).
+ */
+export declare function placeInfoTipBubble(input: {
+    anchor: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+    bubble: {
+        width: number;
+        height: number;
+    } | null;
+    viewport: {
+        width: number;
+        height: number;
+    };
+}, { bounds, preferred }?: {
+    bounds?: {
+        left: number;
+        right: number;
+    } | undefined;
+    preferred?: "top" | "bottom" | undefined;
+}): InfoTipPlacement;
+/**
+ * The portal's inline style: position plus, once measured, the arrow offset as a CSS variable
+ * (`.info-tip-bubble::after` reads `--info-tip-arrow-left`, defaulting to centred).
+ * @param coords The controller's coordinates.
+ * @returns Inline style for the bubble.
+ * @complexity O(1).
+ */
+export declare function infoTipBubbleStyle(coords: {
+    top: number;
+    left: number;
+    arrowLeft?: number | undefined;
+}): CSSProperties;
+//# sourceMappingURL=InfoTip.rules.d.ts.map

package/dist/features/admin-widgets/components/InfoTip.rules.js

@@ -0,0 +1,68 @@
+/** Above is a preference: require this much headroom before allowing an above-opening bubble
+ * whose height is not measured yet. */
+export const ABOVE_HEADROOM_PX = 176;
+/** The bubble's 18rem CSS max-width at a 16px root font. Before the portal renders there is no
+ * real width to measure, so the first estimate assumes the worst case. */
+export const MAX_BUBBLE_WIDTH_PX = 288;
+/** Keep breathing room between the bubble and either edge of its bounds. */
+export const EDGE_MARGIN_PX = 8;
+/** The CSS gap between icon and bubble (`translate(…, 8px)`), plus the arrow. */
+const GAP_PX = 16;
+/** The arrow is 10px wide; keep its centre clear of the bubble's rounded corners. */
+const ARROW_INSET_PX = 10;
+/**
+ * Where an `InfoTip`-style bubble goes: centred under/over its icon, then shifted (never squeezed)
+ * just far enough to stay inside `bounds` (e.g. the assistant dock) and the viewport.
+ *
+ * Why the real measured width: the old clamp assumed every bubble was 18rem wide, so every short tip
+ * within 152px of the right edge got the same left — "Remove" sat ~86px away from its ✕ in the
+ * dock (Chrome re-check, 2026-10-11). Shared by `useInfoTip` and Tovu's dock-header tips so both
+ * place identically.
+ * @param input.anchor The icon's `getBoundingClientRect()`.
+ * @param input.bubble The rendered bubble's measured size; `null` before the portal exists.
+ * @param input.viewport `window.innerWidth` / `innerHeight`.
+ * @param options.bounds Horizontal limits of a containing panel; ignored when the bubble cannot fit
+ *   in them (it then only has to fit the viewport).
+ * @param options.preferred A host's preferred side. Bottom flips above only when it would overflow
+ *   the viewport's bottom and fits above; top falls back below without the measured headroom.
+ * @returns Coordinates for the portal plus the arrow offset. A bubble wider than the viewport's
+ *   usable span centres in the viewport rather than using an inverted clamp range.
+ * @complexity O(1).
+ */
+export function placeInfoTipBubble(input, { bounds, preferred } = {}) {
+    const { anchor, bubble, viewport } = input;
+    const width = bubble && bubble.width > 0 ? bubble.width : MAX_BUBBLE_WIDTH_PX;
+    const anchorCentre = anchor.left + anchor.width / 2;
+    const viewportSpan = { lo: EDGE_MARGIN_PX, hi: viewport.width - EDGE_MARGIN_PX };
+    const boundsSpan = bounds
+        ? { lo: Math.max(bounds.left, 0) + EDGE_MARGIN_PX, hi: Math.min(bounds.right, viewport.width) - EDGE_MARGIN_PX }
+        : null;
+    const span = boundsSpan && boundsSpan.hi - boundsSpan.lo >= width ? boundsSpan : viewportSpan;
+    const left = span.hi - span.lo < width
+        ? viewport.width / 2
+        : Math.min(Math.max(anchorCentre, span.lo + width / 2), span.hi - width / 2);
+    const bubbleLeftEdge = left - width / 2;
+    const arrowLeft = Math.min(Math.max(anchorCentre - bubbleLeftEdge, ARROW_INSET_PX), width - ARROW_INSET_PX);
+    const anchorBottom = anchor.top + anchor.height;
+    const height = bubble && bubble.height > 0 ? bubble.height : 0;
+    const fitsAbove = height > 0 ? anchor.top >= height + GAP_PX : anchor.top >= ABOVE_HEADROOM_PX;
+    const fitsBelow = height === 0 || anchorBottom + GAP_PX + height <= viewport.height;
+    const placement = preferred === "bottom"
+        ? (!fitsBelow && fitsAbove ? "above" : "below")
+        : fitsAbove ? "above" : "below";
+    return { placement, top: placement === "above" ? anchor.top : anchorBottom, left, arrowLeft };
+}
+/**
+ * The portal's inline style: position plus, once measured, the arrow offset as a CSS variable
+ * (`.info-tip-bubble::after` reads `--info-tip-arrow-left`, defaulting to centred).
+ * @param coords The controller's coordinates.
+ * @returns Inline style for the bubble.
+ * @complexity O(1).
+ */
+export function infoTipBubbleStyle(coords) {
+    const style = { top: coords.top, left: coords.left };
+    if (coords.arrowLeft !== undefined)
+        style["--info-tip-arrow-left"] = `${coords.arrowLeft}px`;
+    return style;
+}
+//# sourceMappingURL=InfoTip.rules.js.map

package/dist/features/admin-widgets/components/SuggestInput/SuggestInput.d.ts

@@ -0,0 +1,36 @@
+import { type KeyboardEvent } from 'react';
+import { useSuggestInput } from './SuggestInput.hooks.js';
+/**
+ * A free-text input with a styled suggestion list under it: the browser's native `<datalist>` cannot
+ * be styled (Chrome on macOS draws it as a dark bubble with a pointer and adds a large ▼ to the box),
+ * so hosts get plain `jini-suggest-input*` classes to style instead. Unlike `Select`, the typed text
+ * is the value: picking a suggestion is a shortcut, not the only way to fill it.
+ *
+ * Keys: ArrowDown/ArrowUp move through matches, Enter picks the highlighted one, Escape closes the
+ * list. Any key the list does not consume (Enter with nothing highlighted, a comma, Escape with the
+ * list closed) reaches the caller's `onKeyDown`, so "Enter adds what was typed" keeps working.
+ * Options are picked on mousedown so the input's blur doesn't close the list before the click lands.
+ * Every match is listed unless `limit` is set; the host's max-height makes the list scroll, and an
+ * arrow-key move scrolls the highlighted row into view.
+ */
+export interface SuggestInputProps {
+    value: string;
+    onValueChange: (value: string) => void;
+    suggestions: readonly string[];
+    /** A suggestion was chosen (click or Enter on a highlighted row). */
+    onPick: (value: string) => void;
+    onKeyDown?: ((event: KeyboardEvent<HTMLInputElement>) => void) | undefined;
+    placeholder?: string | undefined;
+    'aria-label'?: string | undefined;
+    disabled?: boolean | undefined;
+    className?: string | undefined;
+    /** Cap on listed matches; omit to list them all. */
+    limit?: number | undefined;
+    agentHandle?: string | undefined;
+    agentLabel?: string | undefined;
+    useSuggest?: typeof useSuggestInput | undefined;
+    /** Injectable for tests; defaults to `scrollIntoView({ block: 'nearest' })`. */
+    scrollOptionIntoView?: ((option: Element) => void) | undefined;
+}
+export declare function SuggestInput({ value, onValueChange, suggestions, onPick, onKeyDown, placeholder, disabled, className, limit, agentHandle: handle, agentLabel, useSuggest, scrollOptionIntoView, ...rest }: SuggestInputProps): import("react").JSX.Element;
+//# sourceMappingURL=SuggestInput.d.ts.map

package/dist/features/admin-widgets/components/SuggestInput/SuggestInput.hooks.d.ts

@@ -0,0 +1,58 @@
+import { type RefObject } from 'react';
+/**
+ * State for {@link SuggestInput}: which suggestions match what is typed, whether the list is open, and
+ * which row the arrow keys have highlighted. Pure state, no DOM, so the component renders against it.
+ */
+export interface SuggestInputController {
+    open: boolean;
+    /** Suggestions containing the typed text (case-insensitive): all of them unless the caller passed
+     *  `limit`. The host styles the list with a max-height so a long list scrolls inside it. */
+    matches: readonly string[];
+    /** Index into `matches`, or -1 when nothing is highlighted. */
+    highlighted: number;
+    setHighlighted: (index: number) => void;
+    /** The row an arrow key just moved to, as a fresh object per key press so the component's effect
+     *  re-runs even when the index repeats. Null until a key moves; mouse hover never sets it, so
+     *  hovering a half-visible row while wheel-scrolling doesn't yank the list. */
+    scrollTarget: {
+        index: number;
+    } | null;
+    openList: () => void;
+    closeList: () => void;
+    /** Handles the list's own keys. Returns true when it consumed the key, so the caller's own
+     *  handler (e.g. "Enter adds what was typed") must not also run. */
+    handleKey: (key: string) => {
+        consumed: boolean;
+        picked?: string | undefined;
+    };
+}
+/** Suggestions containing `typed` (case-insensitive), in their given order; capped at `limit` only when one is given. */
+export declare function matchSuggestions({ typed, suggestions }: {
+    typed: string;
+    suggestions: readonly string[];
+}, { limit }?: {
+    limit?: number | undefined;
+}): string[];
+/** @complexity O(n) over `suggestions` per render. */
+export declare function useSuggestInput({ value, suggestions }: {
+    value: string;
+    suggestions: readonly string[];
+}, { limit }?: {
+    limit?: number | undefined;
+}): SuggestInputController;
+/** Default scroller: `block: 'nearest'` moves the list only as far as needed. Optional call because
+ *  non-browser DOMs (jsdom in host test suites) don't implement `scrollIntoView`. */
+export declare function scrollOptionIntoView(option: Element): void;
+/**
+ * Keeps the arrow-key row visible in a scrolling list: when `scrollTarget` changes, scrolls the
+ * list's child at that index into view. `scrollIntoView` is injectable for tests.
+ */
+export declare function useScrollHighlightedIntoView({ listRef, scrollTarget }: {
+    listRef: RefObject<HTMLElement | null>;
+    scrollTarget: {
+        index: number;
+    } | null;
+}, { scrollIntoView }?: {
+    scrollIntoView?: ((option: Element) => void) | undefined;
+}): void;
+//# sourceMappingURL=SuggestInput.hooks.d.ts.map

package/dist/features/admin-widgets/components/SuggestInput/SuggestInput.hooks.js

@@ -0,0 +1,66 @@
+import { useEffect, useState } from 'react';
+/** Suggestions containing `typed` (case-insensitive), in their given order; capped at `limit` only when one is given. */
+export function matchSuggestions({ typed, suggestions }, { limit } = {}) {
+    const needle = typed.trim().toLowerCase();
+    const hits = needle ? suggestions.filter((s) => s.toLowerCase().includes(needle)) : [...suggestions];
+    return limit === undefined ? hits : hits.slice(0, limit);
+}
+/** @complexity O(n) over `suggestions` per render. */
+export function useSuggestInput({ value, suggestions }, { limit } = {}) {
+    const [open, setOpen] = useState(false);
+    const [highlighted, setHighlighted] = useState(-1);
+    const [scrollTarget, setScrollTarget] = useState(null);
+    const matches = matchSuggestions({ typed: value, suggestions }, { limit });
+    const visible = open && matches.length > 0;
+    const current = highlighted < matches.length ? highlighted : -1;
+    return {
+        open: visible,
+        matches,
+        highlighted: current,
+        setHighlighted,
+        scrollTarget,
+        openList: () => setOpen(true),
+        closeList: () => { setOpen(false); setHighlighted(-1); },
+        handleKey: (key) => {
+            if (key === 'ArrowDown' || key === 'ArrowUp') {
+                if (matches.length === 0)
+                    return { consumed: false };
+                setOpen(true);
+                const step = key === 'ArrowDown' ? 1 : -1;
+                const next = (current + step + matches.length + (current === -1 && step === -1 ? 1 : 0)) % matches.length;
+                setHighlighted(next);
+                setScrollTarget({ index: next });
+                return { consumed: true };
+            }
+            if (key === 'Escape' && visible) {
+                setOpen(false);
+                setHighlighted(-1);
+                return { consumed: true };
+            }
+            const picked = current >= 0 ? matches[current] : undefined;
+            if (key === 'Enter' && visible && picked !== undefined) {
+                setOpen(false);
+                setHighlighted(-1);
+                return { consumed: true, picked };
+            }
+            return { consumed: false };
+        },
+    };
+}
+/** Default scroller: `block: 'nearest'` moves the list only as far as needed. Optional call because
+ *  non-browser DOMs (jsdom in host test suites) don't implement `scrollIntoView`. */
+export function scrollOptionIntoView(option) {
+    option.scrollIntoView?.({ block: 'nearest' });
+}
+/**
+ * Keeps the arrow-key row visible in a scrolling list: when `scrollTarget` changes, scrolls the
+ * list's child at that index into view. `scrollIntoView` is injectable for tests.
+ */
+export function useScrollHighlightedIntoView({ listRef, scrollTarget }, { scrollIntoView = scrollOptionIntoView } = {}) {
+    useEffect(() => {
+        const option = scrollTarget ? listRef.current?.children.item(scrollTarget.index) : null;
+        if (option)
+            scrollIntoView(option);
+    }, [scrollTarget, listRef, scrollIntoView]);
+}
+//# sourceMappingURL=SuggestInput.hooks.js.map

package/dist/features/admin-widgets/components/SuggestInput/SuggestInput.js

@@ -0,0 +1,24 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId, useRef } from 'react';
+import { agentHandle } from '@jini-ai/agentic';
+import { useScrollHighlightedIntoView, useSuggestInput } from './SuggestInput.hooks.js';
+export function SuggestInput({ value, onValueChange, suggestions, onPick, onKeyDown, placeholder, disabled, className, limit, agentHandle: handle, agentLabel, useSuggest = useSuggestInput, scrollOptionIntoView, ...rest }) {
+    const vm = useSuggest({ value, suggestions }, { limit });
+    const listRef = useRef(null);
+    useScrollHighlightedIntoView({ listRef, scrollTarget: vm.scrollTarget }, { scrollIntoView: scrollOptionIntoView });
+    const listId = useId();
+    const optionId = (index) => `${listId}-opt-${index}`;
+    return (_jsxs("span", { className: className ? `jini-suggest-input ${className}` : 'jini-suggest-input', children: [_jsx("input", { type: "text", role: "combobox", "aria-autocomplete": "list", "aria-expanded": vm.open, "aria-controls": listId, "aria-activedescendant": vm.open && vm.highlighted >= 0 ? optionId(vm.highlighted) : undefined, "aria-label": rest['aria-label'], placeholder: placeholder, disabled: disabled, value: value, autoComplete: "off", onChange: (event) => { onValueChange(event.target.value); vm.openList(); }, onFocus: vm.openList, onBlur: vm.closeList, onKeyDown: (event) => {
+                    if (event.nativeEvent.isComposing)
+                        return onKeyDown?.(event);
+                    const result = vm.handleKey(event.key);
+                    if (result.consumed) {
+                        event.preventDefault();
+                        if (result.picked !== undefined)
+                            onPick(result.picked);
+                        return;
+                    }
+                    onKeyDown?.(event);
+                }, ...(handle ? agentHandle({ handle }, { role: 'field', label: agentLabel ?? rest['aria-label'] ?? 'Text with suggestions' }) : {}) }), vm.open ? (_jsx("ul", { ref: listRef, id: listId, role: "listbox", className: "jini-suggest-input__list", children: vm.matches.map((match, index) => (_jsx("li", { id: optionId(index), role: "option", "aria-selected": index === vm.highlighted, className: index === vm.highlighted ? 'jini-suggest-input__option is-active' : 'jini-suggest-input__option', onMouseEnter: () => vm.setHighlighted(index), onMouseDown: (event) => { event.preventDefault(); vm.closeList(); onPick(match); }, children: match }, match))) })) : (_jsx("ul", { id: listId, role: "listbox", hidden: true }))] }));
+}
+//# sourceMappingURL=SuggestInput.js.map

package/dist/features/admin-widgets/components/useDebouncedHtmlPreview.hooks.d.ts

@@ -0,0 +1,23 @@
+export type HtmlPreviewPort = (input: {
+    source: string;
+}, options: {
+    signal: AbortSignal;
+}) => Promise<string>;
+export interface HtmlPreviewState {
+    document: string;
+    loading: boolean;
+    error: string | null;
+}
+/** Debounces an unsaved source through the host's renderer; cleanup cancels timers and ignores
+ * responses even when the transport cannot abort. No rendering policy belongs to this hook.
+ * @returns The last successful document and one-line request state.
+ * @complexity O(1) per source change, excluding the injected renderer's cost.
+ */
+export declare function useDebouncedHtmlPreview({ source, render }: {
+    source: string;
+    render: HtmlPreviewPort;
+}, { revision, delayMs }?: {
+    revision?: string;
+    delayMs?: number;
+}): HtmlPreviewState;
+//# sourceMappingURL=useDebouncedHtmlPreview.hooks.d.ts.map

package/dist/features/admin-widgets/components/useDebouncedHtmlPreview.hooks.js

@@ -0,0 +1,28 @@
+import { useEffect, useState } from 'react';
+/** Debounces an unsaved source through the host's renderer; cleanup cancels timers and ignores
+ * responses even when the transport cannot abort. No rendering policy belongs to this hook.
+ * @returns The last successful document and one-line request state.
+ * @complexity O(1) per source change, excluding the injected renderer's cost.
+ */
+export function useDebouncedHtmlPreview({ source, render }, { revision = '', delayMs = 400 } = {}) {
+    // `settled` names the source+revision the stored result belongs to, so `loading` and a stale
+    // error are derived during render. Setting state from the effect on every keystroke left a
+    // pending update after each commit, and ~50 fast keystrokes then tripped React's nested-update
+    // limit, which dropped that keystroke from the host's controlled input.
+    const key = JSON.stringify([source, revision]);
+    const [state, setState] = useState({ document: '', error: null, settled: null });
+    useEffect(() => {
+        let current = true;
+        const controller = new AbortController();
+        const timer = setTimeout(() => {
+            // Promise.resolve also maps a synchronously throwing host adapter to the error state.
+            void Promise.resolve().then(() => render({ source }, { signal: controller.signal })).then(document => { if (current)
+                setState({ document, error: null, settled: key }); }, () => { if (current)
+                setState(previous => ({ ...previous, error: 'Preview unavailable.', settled: key })); });
+        }, delayMs);
+        return () => { current = false; clearTimeout(timer); controller.abort(); };
+    }, [key, source, render, delayMs]);
+    const settled = state.settled === key;
+    return { document: state.document, loading: !settled, error: settled ? state.error : null };
+}
+//# sourceMappingURL=useDebouncedHtmlPreview.hooks.js.map