@jini-ai/ui 0.3.13 → 0.4.0

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

@@ -0,0 +1,105 @@
+export interface SelectOption {
+    value: string;
+    label: string;
+}
+export declare function focusableInDomOrder({ exclude }: {
+    exclude: HTMLElement | null;
+}): HTMLElement[];
+export interface PanelPosition {
+    top?: number | undefined;
+    bottom?: number | undefined;
+    left: number;
+    width: number;
+    maxHeight: number;
+}
+/**
+ * Use fixed viewport-relative coordinates to escape scrolling/overflow-hidden ancestors
+ * without coupling to their layout. maxHeight uses actual remaining space, not the estimate,
+ * so the panel scroll area clips options before the viewport edge does.
+ */
+export declare function computePosition({ trigger }: {
+    trigger: HTMLElement;
+}): PanelPosition;
+export declare function buildOptionId({ listboxId, index }: {
+    listboxId: string;
+    index: number;
+}): string;
+/**
+ * Positioning reports a clipped or obscured trigger through onOutOfView; deciding whether
+ * to close belongs to the dropdown lifecycle rather than this reusable measurement hook.
+ */
+export declare function usePanelPosition({ open, triggerRef, panelRef, searchInputRef, showSearch, onOutOfView, }: {
+    open: boolean;
+    triggerRef: React.RefObject<HTMLButtonElement | null>;
+    panelRef: React.RefObject<HTMLDivElement | null>;
+    searchInputRef: React.RefObject<HTMLInputElement | null>;
+    showSearch: boolean;
+    onOutOfView: () => void;
+}): {
+    position: PanelPosition | null;
+    setPosition: import("react").Dispatch<import("react").SetStateAction<PanelPosition | null>>;
+};
+export declare function repositionOrClose({ trigger, onOutOfView, setPosition }: {
+    trigger: HTMLElement;
+    onOutOfView: () => void;
+    setPosition: (position: PanelPosition) => void;
+}): void;
+export declare function resolveTabTarget({ panel, trigger, shiftKey }: {
+    panel: HTMLElement | null;
+    trigger: HTMLElement | null;
+    shiftKey: boolean;
+}): HTMLElement | null;
+export declare function edgeHighlightIndex({ filteredLength, edge }: {
+    filteredLength: number;
+    edge: "first" | "last";
+}): number;
+export declare function highlightedOptionOrNull({ filtered, highlightedIndex }: {
+    filtered: SelectOption[];
+    highlightedIndex: number;
+}): SelectOption | null;
+export declare function applyHighlightKey({ key, filtered, highlightedIndex, actions }: {
+    key: string;
+    filtered: SelectOption[];
+    highlightedIndex: number;
+    actions: {
+        preventDefault: () => void;
+        moveHighlight: (delta: 1 | -1) => void;
+        setHighlightedIndex: (index: number) => void;
+        selectOption: (option: SelectOption) => void;
+    };
+}): boolean;
+/**
+ * Separate hook state from rendering so search visibility, wraparound, placement and
+ * out-of-view closing can be asserted directly without coupling every case to portal DOM.
+ */
+export declare function useSelectDropdown({ value, onChange, options, }: {
+    value: string;
+    onChange: (value: string) => void;
+    options: SelectOption[];
+}, { disabled }?: {
+    disabled?: boolean | undefined;
+}): {
+    open: boolean;
+    query: string;
+    setQuery: import("react").Dispatch<import("react").SetStateAction<string>>;
+    highlightedIndex: number;
+    setHighlightedIndex: import("react").Dispatch<import("react").SetStateAction<number>>;
+    position: PanelPosition | null;
+    triggerRef: import("react").RefObject<HTMLButtonElement | null>;
+    panelRef: import("react").RefObject<HTMLDivElement | null>;
+    searchInputRef: import("react").RefObject<HTMLInputElement | null>;
+    optionRefs: import("react").RefObject<Map<number, HTMLLIElement>>;
+    listboxId: string;
+    showSearch: boolean;
+    filtered: SelectOption[];
+    selectedOption: SelectOption | null;
+    openPanel: () => void;
+    closePanel: (opts: {
+        refocusTrigger: boolean;
+    }) => void;
+    selectOption: (option: SelectOption) => void;
+    handleTriggerKeyDown: (e: React.KeyboardEvent<HTMLButtonElement>) => void;
+    handlePanelKeyDown: (e: React.KeyboardEvent<HTMLDivElement>) => void;
+    optionId: (index: number) => string;
+};
+//# sourceMappingURL=Select.hooks.d.ts.map

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

@@ -0,0 +1,359 @@
+/**
+ * Keep state/effects and DOM helpers separate from JSX so the dropdown hook can be
+ * injected through useDropdown and exercised directly without driving a portaled tree.
+ * Compose the smaller hooks unconditionally in their original relative order to obey
+ * React hook ordering. Extracting the live DOM key handling from pure highlight decisions
+ * reduces the review burden without changing focus or event-order contracts.
+ */
+import { useEffect, useId, useLayoutEffect, useMemo, useRef, useState } from "react";
+// Below eight options, a search field adds clutter to a list that is already easy to scan.
+const SEARCH_VISIBILITY_THRESHOLD = 8;
+// 280px is only a placement heuristic; the panel actual maxHeight and scroll limit use
+// the remaining viewport space so a low trigger does not open a mostly off-screen panel.
+const ESTIMATED_PANEL_HEIGHT = 280;
+// The panel is portaled to the end of document.body. Native Tab would follow that DOM
+// position toward browser chrome; walk the trigger real DOM-order neighbours instead.
+const FOCUSABLE_SELECTOR = 'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+export function focusableInDomOrder({ exclude }) {
+    return Array.from(document.querySelectorAll(FOCUSABLE_SELECTOR)).filter((el) => !exclude || !exclude.contains(el));
+}
+/**
+ * Use fixed viewport-relative coordinates to escape scrolling/overflow-hidden ancestors
+ * without coupling to their layout. maxHeight uses actual remaining space, not the estimate,
+ * so the panel scroll area clips options before the viewport edge does.
+ */
+export function computePosition({ trigger }) {
+    const rect = trigger.getBoundingClientRect();
+    const gap = 4;
+    const viewportHeight = window.innerHeight;
+    const spaceBelow = viewportHeight - rect.bottom;
+    const spaceAbove = rect.top;
+    const openUpward = spaceBelow < ESTIMATED_PANEL_HEIGHT && spaceAbove > spaceBelow;
+    if (openUpward) {
+        return { bottom: viewportHeight - rect.top + gap, left: rect.left, width: rect.width, maxHeight: Math.max(120, spaceAbove - gap * 2) };
+    }
+    return { top: rect.bottom + gap, left: rect.left, width: rect.width, maxHeight: Math.max(120, spaceBelow - gap * 2) };
+}
+export function buildOptionId({ listboxId, index }) {
+    return `${listboxId}-option-${index}`;
+}
+/**
+ * Positioning reports a clipped or obscured trigger through onOutOfView; deciding whether
+ * to close belongs to the dropdown lifecycle rather than this reusable measurement hook.
+ */
+export function usePanelPosition({ open, triggerRef, panelRef, searchInputRef, showSearch, onOutOfView, }) {
+    const [position, setPosition] = useState(null);
+    // Two phases, deliberately in one effect rather than two: (1) `position` starts `null` on every
+    // open (`closePanel` resets it), so the panel/`createPortal` call below isn't rendered at all yet
+    // — `panelRef`/`searchInputRef` are still unattached, so focusing them here would silently no-op.
+    // Computing `position` schedules a state update; because this is a `useLayoutEffect`, React
+    // re-renders and re-runs layout effects synchronously before the browser paints, rather than
+    // waiting a frame. (2) On that second pass `position` is non-null, the portal now exists in the
+    // DOM, and the refs are populated — only now is it correct to move focus into it. Found live via
+    // this component's own tests: every keyboard-driven test failed until this was split out, because
+    // `panelRef.current`/`searchInputRef.current` were both still `null` when focus was attempted in
+    // the same pass that first computed the position.
+    // biome-ignore lint/correctness/useExhaustiveDependencies: two-phase focus effect — see comment above; refs/showSearch intentionally excluded, only open/position redrive it.
+    useLayoutEffect(() => {
+        if (!open)
+            return;
+        if (!position) {
+            if (triggerRef.current)
+                setPosition(computePosition({ trigger: triggerRef.current }));
+            return;
+        }
+        if (showSearch) {
+            searchInputRef.current?.focus();
+        }
+        else {
+            panelRef.current?.focus();
+        }
+    }, [open, position]);
+    // Keeps the panel anchored to the trigger if the surrounding page/dialog scrolls or resizes while
+    // it's open — `.widget-picker-body`'s own `overflow-y: auto` made this a real, live scenario
+    // rather than a hypothetical one. `scroll` needs the capture phase: an inner element's own scroll
+    // does not bubble to `window` in the bubble phase. The decision logic itself is
+    // `repositionOrClose`, above; this effect is only the DOM listener wiring.
+    //
+    // Found live in a real browser, not by this component's own test suite: scrolling a host's
+    // scrolling ancestor far enough that the trigger scrolls out of its own visible clip used to leave
+    // this effect happily recomputing a mathematically-correct `position` for it — the panel just
+    // ended up following the trigger to an off-screen (or behind-the-header, obscured) spot, floating
+    // there indefinitely, nominally still "open" with no visible way to tell.
+    // biome-ignore lint/correctness/useExhaustiveDependencies: scroll/resize listener wiring — see comment above; triggerRef/onOutOfView intentionally excluded, only `open` re-arms it.
+    useEffect(() => {
+        if (!open)
+            return;
+        function reposition() {
+            const el = triggerRef.current;
+            if (!el)
+                return;
+            repositionOrClose({ trigger: el, onOutOfView: onOutOfView, setPosition: setPosition });
+        }
+        window.addEventListener("scroll", reposition, true);
+        window.addEventListener("resize", reposition);
+        return () => {
+            window.removeEventListener("scroll", reposition, true);
+            window.removeEventListener("resize", reposition);
+        };
+    }, [open]);
+    return { position, setPosition };
+}
+export function repositionOrClose({ trigger, onOutOfView, setPosition }) {
+    const rect = trigger.getBoundingClientRect();
+    const outOfViewport = rect.bottom <= 0 || rect.top >= window.innerHeight || rect.right <= 0 || rect.left >= window.innerWidth;
+    if (outOfViewport) {
+        onOutOfView();
+        return;
+    }
+    if (typeof document.elementFromPoint === "function") {
+        const topmostAtCenter = document.elementFromPoint(rect.left + rect.width / 2, rect.top + rect.height / 2);
+        const obscured = !topmostAtCenter || !(trigger.contains(topmostAtCenter) || topmostAtCenter.contains(trigger));
+        if (obscured) {
+            onOutOfView();
+            return;
+        }
+    }
+    setPosition(computePosition({ trigger: trigger }));
+}
+function useCloseOnOutsideClick({ open, triggerRef, panelRef, onOutside, }) {
+    useEffect(() => {
+        if (!open)
+            return;
+        function onDocMouseDown(e) {
+            const target = e.target;
+            if (triggerRef.current?.contains(target))
+                return;
+            if (panelRef.current?.contains(target))
+                return;
+            onOutside();
+        }
+        document.addEventListener("mousedown", onDocMouseDown);
+        return () => document.removeEventListener("mousedown", onDocMouseDown);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [open]);
+}
+// A search can remove the previously highlighted option; re-anchor to the first match
+// rather than keep a stale index outside the narrowed list.
+function useResetHighlightOnQueryChange({ open, query, hasMatches, setHighlightedIndex, }) {
+    useEffect(() => {
+        if (!open)
+            return;
+        setHighlightedIndex(hasMatches ? 0 : -1);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [query]);
+}
+/**
+ * Keyboard highlight used to move logically past the visible fold without scrolling its
+ * row into view. nearest scrolls only what is needed instead of recentering the list and
+ * fighting a user who has already scrolled it manually.
+ */
+function useScrollHighlightedIntoView({ open, highlightedIndex, optionRefs, }) {
+    useEffect(() => {
+        if (!open || highlightedIndex < 0)
+            return;
+        const el = optionRefs.current.get(highlightedIndex);
+        // Guarded the same way as `document.elementFromPoint` above — this app's own jsdom test
+        // harness doesn't implement `scrollIntoView` at all (not even as a no-op), so an unguarded call
+        // throws inside the effect on every highlight change.
+        if (el && typeof el.scrollIntoView === "function")
+            el.scrollIntoView({ block: "nearest" });
+    }, [open, highlightedIndex]);
+}
+export function resolveTabTarget({ panel, trigger, shiftKey }) {
+    const nodes = focusableInDomOrder({ exclude: panel });
+    const triggerIndex = trigger ? nodes.indexOf(trigger) : -1;
+    if (triggerIndex < 0)
+        return null;
+    return nodes[triggerIndex + (shiftKey ? -1 : 1)] ?? null;
+}
+export function edgeHighlightIndex({ filteredLength, edge }) {
+    if (filteredLength === 0)
+        return -1;
+    return edge === "first" ? 0 : filteredLength - 1;
+}
+export function highlightedOptionOrNull({ filtered, highlightedIndex }) {
+    return highlightedIndex >= 0 ? (filtered[highlightedIndex] ?? null) : null;
+}
+export function applyHighlightKey({ key, filtered, highlightedIndex, actions }) {
+    switch (key) {
+        case "ArrowDown":
+            actions.preventDefault();
+            actions.moveHighlight(1);
+            return true;
+        case "ArrowUp":
+            actions.preventDefault();
+            actions.moveHighlight(-1);
+            return true;
+        case "Home":
+            actions.preventDefault();
+            actions.setHighlightedIndex(edgeHighlightIndex({ filteredLength: filtered.length, edge: "first" }));
+            return true;
+        case "End":
+            actions.preventDefault();
+            actions.setHighlightedIndex(edgeHighlightIndex({ filteredLength: filtered.length, edge: "last" }));
+            return true;
+        case "Enter": {
+            actions.preventDefault();
+            const option = highlightedOptionOrNull({ filtered: filtered, highlightedIndex: highlightedIndex });
+            if (option)
+                actions.selectOption(option);
+            return true;
+        }
+        default:
+            return false;
+    }
+}
+// Keep live event/focus effects in the key handler; move the trigger-neighbour calculation
+// out so changing the DOM effects does not bury the independently testable focus decision.
+function useSelectKeyboardHandlers({ disabled, open, openPanel, closePanel, moveHighlight, selectOption, highlightedIndex, setHighlightedIndex, filtered, triggerRef, panelRef, }) {
+    function handleTriggerKeyDown(e) {
+        if (disabled || open)
+            return;
+        switch (e.key) {
+            case "Enter":
+            case " ":
+            case "ArrowDown":
+            case "ArrowUp":
+                e.preventDefault();
+                openPanel();
+                break;
+            default:
+                break;
+        }
+    }
+    // Escape/Tab need live propagation and focus effects. Highlight/selection keys delegate
+    // to the pure helper; preventDefault is injected to preserve its order before each action.
+    function handlePanelKeyDown(e) {
+        if (e.key === "Escape") {
+            // Must not bubble: a host dialog (`WidgetPickerDialog`) listens for Escape on `document`
+            // to cancel the whole modal. Without stopping propagation here, closing just this dropdown
+            // would also close the dialog underneath it — the regression `Select.unit.test.tsx` pins.
+            e.preventDefault();
+            e.stopPropagation();
+            closePanel({ refocusTrigger: true });
+            return;
+        }
+        if (e.key === "Tab") {
+            // See `resolveTabTarget`'s own comment: walk the trigger's real DOM-order neighbours rather
+            // than let native Tab handling run, since this event is bubbling from a panel portaled to
+            // the end of `document.body`, not sitting next to the trigger in the DOM.
+            const target = resolveTabTarget({ panel: panelRef.current, trigger: triggerRef.current, shiftKey: e.shiftKey });
+            e.preventDefault();
+            closePanel({ refocusTrigger: false });
+            target?.focus();
+            return;
+        }
+        applyHighlightKey({ key: e.key, filtered: filtered, highlightedIndex: highlightedIndex, actions: {
+                preventDefault: () => e.preventDefault(),
+                moveHighlight,
+                setHighlightedIndex,
+                selectOption,
+            } });
+    }
+    return { handleTriggerKeyDown, handlePanelKeyDown };
+}
+/**
+ * Separate hook state from rendering so search visibility, wraparound, placement and
+ * out-of-view closing can be asserted directly without coupling every case to portal DOM.
+ */
+export function useSelectDropdown({ value, onChange, options, }, { disabled } = {}) {
+    const [open, setOpen] = useState(false);
+    const [query, setQuery] = useState("");
+    const [highlightedIndex, setHighlightedIndex] = useState(-1);
+    const triggerRef = useRef(null);
+    const panelRef = useRef(null);
+    const searchInputRef = useRef(null);
+    // Index -> `<li>` node, so the highlight-follow effect below can scroll the right row into view
+    // without an id-based `querySelector` (this component's ids come from `useId()`, which can
+    // contain characters — `:`, in React's own scheme — that need escaping in a CSS selector; a
+    // direct ref avoids that entirely). Populated by each option's own ref callback below.
+    const optionRefs = useRef(new Map());
+    const listboxId = useId();
+    const showSearch = options.length >= SEARCH_VISIBILITY_THRESHOLD;
+    const filtered = useMemo(() => {
+        if (!showSearch || !query.trim())
+            return options;
+        const q = query.trim().toLowerCase();
+        return options.filter((o) => o.label.toLowerCase().includes(q));
+    }, [options, query, showSearch]);
+    const selectedOption = options.find((o) => o.value === value) ?? null;
+    function openPanel() {
+        if (disabled)
+            return;
+        const initialIndex = options.findIndex((o) => o.value === value);
+        setQuery("");
+        setOpen(true);
+        setHighlightedIndex(initialIndex >= 0 ? initialIndex : options.length ? 0 : -1);
+    }
+    function closePanel(opts) {
+        setOpen(false);
+        setPosition(null); // forces the effect below through its "measure, then focus" two-phase sequence again on the next open, rather than focusing at a stale, pre-close position
+        if (opts.refocusTrigger)
+            triggerRef.current?.focus();
+    }
+    function selectOption(option) {
+        onChange(option.value);
+        closePanel({ refocusTrigger: true });
+    }
+    function moveHighlight(delta) {
+        setHighlightedIndex((current) => {
+            if (filtered.length === 0)
+                return -1;
+            return (current + delta + filtered.length) % filtered.length;
+        });
+    }
+    const { position, setPosition } = usePanelPosition({
+        open,
+        triggerRef,
+        panelRef,
+        searchInputRef,
+        showSearch,
+        onOutOfView: () => closePanel({ refocusTrigger: false }),
+    });
+    useCloseOnOutsideClick({
+        open,
+        triggerRef,
+        panelRef,
+        onOutside: () => closePanel({ refocusTrigger: false }),
+    });
+    useResetHighlightOnQueryChange({ open, query, hasMatches: filtered.length > 0, setHighlightedIndex });
+    useScrollHighlightedIntoView({ open, highlightedIndex, optionRefs });
+    const { handleTriggerKeyDown, handlePanelKeyDown } = useSelectKeyboardHandlers({
+        disabled,
+        open,
+        openPanel,
+        closePanel,
+        moveHighlight,
+        selectOption,
+        highlightedIndex,
+        setHighlightedIndex,
+        filtered,
+        triggerRef,
+        panelRef,
+    });
+    const optionId = (index) => buildOptionId({ listboxId: listboxId, index: index });
+    return {
+        open,
+        query,
+        setQuery,
+        highlightedIndex,
+        setHighlightedIndex,
+        position,
+        triggerRef,
+        panelRef,
+        searchInputRef,
+        optionRefs,
+        listboxId,
+        showSearch,
+        filtered,
+        selectedOption,
+        openPanel,
+        closePanel,
+        selectOption,
+        handleTriggerKeyDown,
+        handlePanelKeyDown,
+        optionId,
+    };
+}
+//# sourceMappingURL=Select.hooks.js.map

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

@@ -0,0 +1,46 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { createPortal } from "react-dom";
+import { agentHandle } from "@jini-ai/agentic";
+import { buildAgentListHandles } from "@jini-ai/agentic";
+import { useSelectDropdown } from "./Select.hooks.js";
+function SelectOptionRow({ option, index, isSelected, isHighlighted, optionId, setOptionRef, onHighlight, onSelect, agentHandle: optionHandle, }) {
+    return (_jsxs("li", { ref: (el) => setOptionRef(index, el), id: optionId, role: "option", "aria-selected": isSelected, className: `select-option${isSelected ? " is-selected" : ""}${isHighlighted ? " is-highlighted" : ""}`, onMouseEnter: () => onHighlight(index), onClick: () => onSelect(option), ...(optionHandle ? agentHandle({ handle: optionHandle }, { role: "button", label: option.label }) : {}), children: [_jsx("span", { className: "select-option-label", children: option.label }), isSelected ? (_jsx("svg", { className: "select-option-check", viewBox: "0 0 16 16", fill: "none", "aria-hidden": "true", children: _jsx("path", { d: "M3.5 8.5 6.5 11.5 12.5 4.5", stroke: "currentColor", strokeWidth: "1.75", strokeLinecap: "round", strokeLinejoin: "round" }) })) : null] }));
+}
+function SelectPanel({ panelRef, position, showSearch, searchInputRef, query, setQuery, filtered, value, highlightedIndex, listboxId, optionId, setOptionRef, onHighlight, onSelect, onKeyDown, searchHandle, optionHandles, t, }) {
+    return (_jsxs("div", { ref: panelRef, className: "select-panel", style: { left: position.left, width: position.width, top: position.top, bottom: position.bottom, maxHeight: position.maxHeight }, tabIndex: -1, onKeyDown: onKeyDown, children: [showSearch ? (_jsx("input", { ref: searchInputRef, type: "text", className: "select-search", "aria-label": t("Search options"), placeholder: t("Search…"), value: query, onChange: (e) => setQuery(e.target.value), ...(searchHandle ? agentHandle({ handle: searchHandle }, { role: "field", label: "Search the option list" }) : {}) })) : null, _jsx("ul", { className: "select-list", role: "listbox", id: listboxId, children: filtered.length === 0 ? (_jsx("li", { className: "select-empty", role: "presentation", children: t("No matches") })) : (filtered.map((option, index) => (_jsx(SelectOptionRow, { option: option, index: index, isSelected: option.value === value, isHighlighted: index === highlightedIndex, optionId: optionId(index), setOptionRef: setOptionRef, onHighlight: onHighlight, onSelect: onSelect, agentHandle: optionHandles?.[index] }, option.value)))) })] }));
+}
+export function resolveSelectTriggerLabel({ selectedOption, placeholder }, { t = (key) => key } = {}) {
+    if (selectedOption)
+        return { text: selectedOption.label, className: "select-trigger-label" };
+    return { text: placeholder ?? t("Select…"), className: "select-trigger-label is-placeholder" };
+}
+function resolveSelectTriggerActiveDescendant(open, highlightedIndex, optionId) {
+    return open && highlightedIndex >= 0 ? optionId(highlightedIndex) : undefined;
+}
+function resolveSelectTriggerHandleProps(base, ariaLabel, placeholder) {
+    return base ? agentHandle({ handle: base }, { role: "button", label: ariaLabel ?? placeholder ?? "Select an option" }) : {};
+}
+/** Controlled searchable listbox with portal positioning and keyboard navigation. */
+export function Select(props) {
+    const { value, onChange, options, placeholder, id, disabled, useDropdown = useSelectDropdown, agentHandle: base, translate, t = translate ?? ((key) => key) } = props;
+    const ariaLabel = props["aria-label"];
+    const ariaLabelledBy = props["aria-labelledby"];
+    const { open, highlightedIndex, setHighlightedIndex, position, triggerRef, panelRef, searchInputRef, optionRefs, listboxId, showSearch, filtered, selectedOption, openPanel, closePanel, selectOption, handleTriggerKeyDown, handlePanelKeyDown, optionId, query, setQuery, } = useDropdown({ value, onChange, options }, { disabled });
+    function setOptionRef(index, el) {
+        if (el)
+            optionRefs.current.set(index, el);
+        else
+            optionRefs.current.delete(index);
+    }
+    const triggerLabel = resolveSelectTriggerLabel({ selectedOption: selectedOption, placeholder: placeholder }, { t: t });
+    const activeDescendant = resolveSelectTriggerActiveDescendant(open, highlightedIndex, optionId);
+    // One handle per FILTERED option, recomputed as the search query narrows the list — an option
+    // dropped by the current query has no rendered row to attach a handle to, so it is simply absent
+    // this render rather than holding a handle nothing resolves to. `undefined` (not an empty array)
+    // when `base` itself is unset, so `SelectPanel` can tell "opted out" apart from "no options match".
+    const optionHandles = base ? buildAgentListHandles({ prefix: `${base}-option`, ids: filtered.map((option) => option.value) }) : undefined;
+    return (_jsxs(_Fragment, { children: [_jsxs("button", { type: "button", ref: triggerRef, id: id, className: "select-trigger", role: "combobox", "aria-expanded": open, "aria-haspopup": "listbox", "aria-controls": open ? listboxId : undefined, "aria-activedescendant": activeDescendant, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, disabled: disabled, onClick: () => (open ? closePanel({ refocusTrigger: false }) : openPanel()), onKeyDown: handleTriggerKeyDown, ...resolveSelectTriggerHandleProps(base, ariaLabel, placeholder), children: [_jsx("span", { className: triggerLabel.className, children: triggerLabel.text }), _jsx("span", { className: "select-trigger-chevron", "aria-hidden": "true" })] }), open && position
+                ? createPortal(_jsx(SelectPanel, { panelRef: panelRef, position: position, showSearch: showSearch, searchInputRef: searchInputRef, query: query, setQuery: setQuery, filtered: filtered, value: value, highlightedIndex: highlightedIndex, listboxId: listboxId, optionId: optionId, setOptionRef: setOptionRef, onHighlight: setHighlightedIndex, onSelect: selectOption, onKeyDown: handlePanelKeyDown, searchHandle: base ? `${base}-search` : undefined, optionHandles: optionHandles, t: t }), document.body)
+                : null] }));
+}
+//# sourceMappingURL=Select.js.map

package/dist/features/admin-widgets/index.d.ts

@@ -0,0 +1,20 @@
+export { Select, resolveSelectTriggerLabel } from './components/Select/Select.js';
+export type { SelectProps, SelectOption } from './components/Select/Select.js';
+export { useSelectDropdown, usePanelPosition } from './components/Select/Select.hooks.js';
+export type { PanelPosition } from './components/Select/Select.hooks.js';
+export { InfoTip } from './components/InfoTip.js';
+export type { InfoTipProps } from './components/InfoTip.js';
+export { useInfoTip } from './components/InfoTip.hooks.js';
+export type { InfoTipController } from './components/InfoTip.hooks.js';
+export { SeeMore, resolveSeeMoreView } from './components/SeeMore/SeeMore.js';
+export type { SeeMoreProps, SeeMoreView } from './components/SeeMore/SeeMore.js';
+export { useSeeMoreClamp } from './components/SeeMore/SeeMore.hooks.js';
+export { ImagePreviewModal } from './components/ImagePreviewModal.js';
+export type { ImagePreviewModalProps } from './components/ImagePreviewModal.js';
+export { useImagePreviewModal } from './components/ImagePreviewModal.hooks.js';
+export type { ImagePreviewModalController } from './components/ImagePreviewModal.hooks.js';
+export { ComingSoonPanel } from './components/ComingSoonPanel.js';
+export type { ComingSoonPanelProps } from './components/ComingSoonPanel.js';
+export { ComingSoonNotice } from './components/ComingSoonNotice.js';
+export type { ComingSoonNoticeProps } from './components/ComingSoonNotice.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/features/admin-widgets/index.js

@@ -0,0 +1,11 @@
+export { Select, resolveSelectTriggerLabel } from './components/Select/Select.js';
+export { useSelectDropdown, usePanelPosition } from './components/Select/Select.hooks.js';
+export { InfoTip } from './components/InfoTip.js';
+export { useInfoTip } from './components/InfoTip.hooks.js';
+export { SeeMore, resolveSeeMoreView } from './components/SeeMore/SeeMore.js';
+export { useSeeMoreClamp } from './components/SeeMore/SeeMore.hooks.js';
+export { ImagePreviewModal } from './components/ImagePreviewModal.js';
+export { useImagePreviewModal } from './components/ImagePreviewModal.hooks.js';
+export { ComingSoonPanel } from './components/ComingSoonPanel.js';
+export { ComingSoonNotice } from './components/ComingSoonNotice.js';
+//# sourceMappingURL=index.js.map

package/dist/features/admin-widgets/styles/admin-widgets.css

@@ -0,0 +1,2 @@
+/* Existing ui subpath continues to load the merged admin styles. */
+@import "../../../styles/admin.css";

package/dist/features/appearance/constants.d.ts

@@ -11,6 +11,6 @@ export interface ThemeOption {
 export declare const THEME_OPTIONS: ThemeOption[];
 /** Neutral default accent — hosts are expected to override via their own
  *  config/branding; this only guarantees the CSS vars are always set. */
-export declare const DEFAULT_ACCENT_COLOR = "#2563eb";
-export declare const ACCENT_SWATCHES: readonly ["#2563eb", "#c96442", "#7c3aed", "#059669", "#dc2626", "#d97706", "#0891b2", "#db2777"];
+export declare const DEFAULT_ACCENT_COLOR: string;
+export declare const ACCENT_SWATCHES: readonly [string, "#c96442", "#7c3aed", "#059669", "#dc2626", "#d97706", "#0891b2", "#db2777"];
 //# sourceMappingURL=constants.d.ts.map

package/dist/features/appearance/constants.js

@@ -1,3 +1,4 @@
+import { defaultAdminTheme } from '../../theme/default.js';
 /** Plain-English defaults for the three segmented-control options — a host
  *  wanting localized copy overrides via `AppearanceTabProps.themeLabels` (the
  *  component wraps each through `useT()` regardless, so this is only the
@@ -9,7 +10,7 @@ export const THEME_OPTIONS = [
 ];
 /** Neutral default accent — hosts are expected to override via their own
  *  config/branding; this only guarantees the CSS vars are always set. */
-export const DEFAULT_ACCENT_COLOR = '#2563eb';
+export const DEFAULT_ACCENT_COLOR = defaultAdminTheme.light.primary;
 export const ACCENT_SWATCHES = [
     DEFAULT_ACCENT_COLOR,
     '#c96442',

package/dist/features/appearance/react/components/AppearanceTab.js

@@ -13,8 +13,8 @@ import { THEME_OPTIONS } from '../../constants.js';
  */
 export function AppearanceTab({ theme, onThemeChange, accentColor, onAccentColorChange, accentSwatches = ACCENT_SWATCHES, livePreview = true, ariaLabel, accentLabel, defaultAccentAriaLabel, customAccentAriaLabel, agentHandle, }) {
     const t = useT();
-    const resolvedAccent = resolveAccentColor(accentColor);
-    const swatchHandles = agentHandle ? buildAgentListHandles(agentSubHandle(agentHandle, 'swatch'), accentSwatches) : undefined;
+    const resolvedAccent = resolveAccentColor({ value: accentColor });
+    const swatchHandles = agentHandle ? buildAgentListHandles({ prefix: agentSubHandle({ base: agentHandle, action: 'swatch' }), ids: accentSwatches }) : undefined;
     const resolvedAriaLabel = ariaLabel ?? t('Appearance');
     const resolvedAccentLabel = accentLabel ?? t('Accent color');
     const resolvedDefaultAccentAriaLabel = defaultAccentAriaLabel ?? t('Default accent color');
@@ -25,10 +25,10 @@ export function AppearanceTab({ theme, onThemeChange, accentColor, onAccentColor
             return;
         applyAppearanceToDocument({ ...(appliedTheme ? { theme: appliedTheme } : {}), accentColor: resolvedAccent });
     }, [livePreview, appliedTheme, resolvedAccent]);
-    return (_jsxs("section", { className: "jini-settings-section jini-settings-appearance", children: [_jsx("div", { className: "jini-seg-control", role: "group", "aria-label": resolvedAriaLabel, style: { '--seg-cols': THEME_OPTIONS.length }, children: THEME_OPTIONS.map((option) => (_jsxs("button", { type: "button", className: 'jini-seg-btn' + (theme === option.value ? ' active' : ''), "aria-pressed": theme === option.value, onClick: () => onThemeChange(option.value), ...agentHandleProps(agentHandle, { action: `theme-${option.value}`, role: 'button', label: t(option.label) }), children: [option.icon ? _jsx(Icon, { name: option.icon, size: 14, "aria-hidden": "true" }) : null, _jsx("span", { className: "jini-seg-title", children: t(option.label) })] }, option.value))) }), _jsxs("div", { className: "jini-field", children: [_jsx("span", { className: "jini-field-label", children: resolvedAccentLabel }), _jsxs("div", { className: "jini-accent-swatches", role: "radiogroup", "aria-label": resolvedAccentLabel, children: [accentSwatches.map((color, index) => {
+    return (_jsxs("section", { className: "jini-settings-section jini-settings-appearance", children: [_jsx("div", { className: "jini-seg-control", role: "group", "aria-label": resolvedAriaLabel, style: { '--seg-cols': THEME_OPTIONS.length }, children: THEME_OPTIONS.map((option) => (_jsxs("button", { type: "button", className: 'jini-seg-btn' + (theme === option.value ? ' active' : ''), "aria-pressed": theme === option.value, onClick: () => onThemeChange(option.value), ...agentHandleProps({}, { base: agentHandle, ...({ action: `theme-${option.value}`, role: 'button', label: t(option.label) }) }), children: [option.icon ? _jsx(Icon, { name: option.icon, size: 14, "aria-hidden": "true" }) : null, _jsx("span", { className: "jini-seg-title", children: t(option.label) })] }, option.value))) }), _jsxs("div", { className: "jini-field", children: [_jsx("span", { className: "jini-field-label", children: resolvedAccentLabel }), _jsxs("div", { className: "jini-accent-swatches", role: "radiogroup", "aria-label": resolvedAccentLabel, children: [accentSwatches.map((color, index) => {
                                 const active = resolvedAccent === color;
                                 const swatchLabel = color === DEFAULT_ACCENT_COLOR ? resolvedDefaultAccentAriaLabel : color;
-                                return (_jsx("button", { type: "button", className: `jini-accent-swatch${active ? ' active' : ''}`, style: { background: color }, "aria-label": swatchLabel, "aria-checked": active, role: "radio", onClick: () => onAccentColorChange(normalizeAccentColor(color) ?? color), ...agentHandleProps(swatchHandles?.[index], { role: 'button', label: swatchLabel }) }, color));
-                            }), _jsx("input", { type: "color", "aria-label": resolvedCustomAccentAriaLabel, className: "jini-accent-swatch-picker", value: resolvedAccent, onChange: (event) => onAccentColorChange(event.target.value), ...agentHandleProps(agentHandle, { action: 'custom-accent', role: 'field', label: resolvedCustomAccentAriaLabel }) })] })] })] }));
+                                return (_jsx("button", { type: "button", className: `jini-accent-swatch${active ? ' active' : ''}`, style: { background: color }, "aria-label": swatchLabel, "aria-checked": active, role: "radio", onClick: () => onAccentColorChange(normalizeAccentColor({ value: color }) ?? color), ...agentHandleProps({}, { base: swatchHandles?.[index], ...({ role: 'button', label: swatchLabel }) }) }, color));
+                            }), _jsx("input", { type: "color", "aria-label": resolvedCustomAccentAriaLabel, className: "jini-accent-swatch-picker", value: resolvedAccent, onChange: (event) => onAccentColorChange(event.target.value), ...agentHandleProps({}, { base: agentHandle, ...({ action: 'custom-accent', role: 'field', label: resolvedCustomAccentAriaLabel }) }) })] })] })] }));
 }
 //# sourceMappingURL=AppearanceTab.js.map

package/dist/features/appearance/rules.d.ts

@@ -13,10 +13,14 @@ export type AccentCssVars = Record<(typeof ACCENT_VARS)[number], string>;
  *   string or does not match `#rrggbb`.
  * @complexity O(1).
  */
-export declare function normalizeAccentColor(value: unknown): string | null;
-/** `normalizeAccentColor(value) ?? DEFAULT_ACCENT_COLOR` — always returns a
+export declare function normalizeAccentColor({ value }: {
+    value: unknown;
+}): string | null;
+/** `normalizeAccentColor({ value }) ?? DEFAULT_ACCENT_COLOR` — always returns a
  *  usable color. */
-export declare function resolveAccentColor(value: unknown): string;
+export declare function resolveAccentColor({ value }: {
+    value: unknown;
+}): string;
 /**
  * Pure computation of the five `--accent*` CSS custom property values for a
  * given (already-resolved) accent color, via `color-mix()` formulas. The DOM
@@ -26,6 +30,8 @@ export declare function resolveAccentColor(value: unknown): string;
  *
  * @complexity O(1) — five template-string formulas, no DOM access.
  */
-export declare function accentVars(accentColor: string): AccentCssVars;
+export declare function accentVars({ accentColor }: {
+    accentColor: string;
+}): AccentCssVars;
 export {};
 //# sourceMappingURL=rules.d.ts.map