@jini-ai/ui 0.4.4 → 0.4.5

package/dist/react/components/CustomSelect.js

@@ -8,8 +8,9 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // pattern (see TooltipLayer.tsx). Every seam is exported: pure helpers, the
 // `useCustomSelect` hook that owns all state/refs/effects/handlers, the
 // `CustomSelectOptionButton` leaf, and the dumb `CustomSelect` render.
-import { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react';
+import { useEffect, useId, useMemo, useRef, useState } from 'react';
 import { createPortal } from 'react-dom';
+import { useSelectPopover, isSelectEventInside, openSelectOnKey, applySelectNavigationKey, resolveSelectPortalContainer } from './select-popover.js';
 import { Icon } from './Icon.js';
 /** Space between the trigger and the menu. */
 export const CUSTOM_SELECT_MENU_GAP = 4;
@@ -88,7 +89,7 @@ export function reconcileCustomSelectActiveValue(input) {
 /** Pure: is a pointerdown target inside the trigger or the (possibly absent)
  * menu? Used to decide whether an outside click should close the menu. */
 export function isCustomSelectEventInside(target, button, menu) {
-    return Boolean(button?.contains(target)) || Boolean(menu?.contains(target));
+    return isSelectEventInside({ target, trigger: button, panel: menu });
 }
 /**
  * All of CustomSelect's behavior — ids, refs, open/active/position state, the
@@ -98,24 +99,14 @@ export function isCustomSelectEventInside(target, button, menu) {
  * logic is testable in isolation from the DOM; `CustomSelect` is the dumb
  * consumer.
  */
-export function useCustomSelect({ value, options, onChange, portal, placeholder, onOpenChange, }) {
+export function useCustomSelect({ value, options, onChange, portal, placeholder, onOpenChange, }, _optional = {}) {
     const reactId = useId();
     const idBase = reactId.replace(/:/g, '');
-    const buttonRef = useRef(null);
-    const menuRef = useRef(null);
     const wasOpenRef = useRef(false);
     const activeSourceValueRef = useRef(value);
-    const [open, setOpen] = useState(false);
-    // Stored in a ref (not a `useEffect` dependency) so an unmemoized caller
-    // passing a fresh function identity every render never re-fires this for
-    // any reason OTHER than `open` actually changing.
-    const onOpenChangeRef = useRef(onOpenChange);
-    onOpenChangeRef.current = onOpenChange;
     const [activeValue, setActiveValue] = useState(value);
-    const [position, setPosition] = useState(null);
-    useEffect(() => {
-        onOpenChangeRef.current?.(open);
-    }, [open]);
+    const popover = useSelectPopover({ measurePosition: ({ trigger }) => computeCustomSelectMenuPosition(trigger.getBoundingClientRect(), { width: window.innerWidth, height: window.innerHeight }) }, { portal, onOpenChange });
+    const { open, position, triggerRef: buttonRef, panelRef: menuRef, updatePosition } = popover;
     const flatOptions = useMemo(() => flattenCustomSelectOptions(options), [options]);
     const selected = flatOptions.find((option) => option.value === value);
     const selectedLabel = selected?.label ?? placeholder ?? value;
@@ -126,24 +117,6 @@ export function useCustomSelect({ value, options, onChange, portal, placeholder,
     enabledOptionsRef.current = enabledOptions;
     const optionIdByValue = useMemo(() => new Map(flatOptions.map((option, index) => [option.value, `${idBase}-option-${index}`])), [flatOptions, idBase]);
     const activeOptionId = open && activeValue ? optionIdByValue.get(activeValue) : undefined;
-    const updatePosition = useCallback(() => {
-        if (!buttonRef.current)
-            return;
-        const rect = buttonRef.current.getBoundingClientRect();
-        setPosition(computeCustomSelectMenuPosition(rect, {
-            width: window.innerWidth,
-            height: window.innerHeight,
-        }));
-    }, []);
-    useEffect(() => {
-        if (!portal)
-            return;
-        if (!open) {
-            setPosition(null);
-            return;
-        }
-        updatePosition();
-    }, [open, portal, updatePosition]);
     useEffect(() => {
         const result = reconcileCustomSelectActiveValue({
             open,
@@ -158,71 +131,31 @@ export function useCustomSelect({ value, options, onChange, portal, placeholder,
         if (result.nextActiveValue !== undefined)
             setActiveValue(result.nextActiveValue);
     }, [open, value]);
-    useEffect(() => {
-        if (!open)
-            return;
-        const onPointerDown = (event) => {
-            const target = event.target;
-            if (isCustomSelectEventInside(target, buttonRef.current, menuRef.current))
-                return;
-            setOpen(false);
-        };
-        const onScrollOrResize = () => {
-            if (portal)
-                updatePosition();
-        };
-        document.addEventListener('mousedown', onPointerDown);
-        window.addEventListener('resize', onScrollOrResize);
-        window.addEventListener('scroll', onScrollOrResize, true);
-        return () => {
-            document.removeEventListener('mousedown', onPointerDown);
-            window.removeEventListener('resize', onScrollOrResize);
-            window.removeEventListener('scroll', onScrollOrResize, true);
-        };
-    }, [open, portal, updatePosition]);
     const choose = (nextValue) => {
         const next = flatOptions.find((option) => option.value === nextValue);
         if (!next || next.disabled)
             return;
         onChange(next.value);
-        setOpen(false);
-        buttonRef.current?.focus();
+        popover.closePanel({ refocusTrigger: true });
     };
     const moveActive = (direction) => {
         const next = nextCustomSelectActiveValue(enabledOptions, activeValue, direction);
         if (next !== null)
             setActiveValue(next);
     };
-    const toggleOpen = () => setOpen((current) => !current);
-    const closeAndRefocusTrigger = () => {
-        setOpen(false);
-        buttonRef.current?.focus();
-    };
+    const toggleOpen = () => open ? popover.closePanel({ refocusTrigger: false }) : popover.openPanel();
     const onButtonKeyDown = (event) => {
-        if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
-            event.preventDefault();
-            if (!open) {
-                setOpen(true);
-                return;
-            }
-            moveActive(event.key === 'ArrowDown' ? 1 : -1);
+        if (popover.handleDismissKey(event))
             return;
-        }
-        if (event.key === 'Enter' || event.key === ' ') {
-            event.preventDefault();
-            if (open) {
-                choose(activeValue || value);
-            }
-            else {
-                setOpen(true);
-            }
+        if (openSelectOnKey({ event, open, openPanel: popover.openPanel }))
             return;
-        }
-        if (event.key === 'Escape' && open) {
-            event.preventDefault();
-            event.stopPropagation();
-            closeAndRefocusTrigger();
-        }
+        if (!open)
+            return;
+        applySelectNavigationKey({ key: event.key, actions: {
+                preventDefault: () => event.preventDefault(), move: moveActive,
+                edge: (edge) => setActiveValue((edge === 'first' ? enabledOptions[0] : enabledOptions.at(-1))?.value ?? ''),
+                choose: () => choose(activeValue || value),
+            } }, { spaceChooses: true });
     };
     // Escape closes even when focus has moved into custom `menuHeader` content
     // (e.g. `SearchableModelSelect`'s search input) — `onButtonKeyDown` alone
@@ -232,11 +165,7 @@ export function useCustomSelect({ value, options, onChange, portal, placeholder,
     // take real focus). Attached to the menu container, not the document, so it
     // never fires for an unrelated Escape press elsewhere on the page.
     const onMenuKeyDown = (event) => {
-        if (event.key !== 'Escape')
-            return;
-        event.preventDefault();
-        event.stopPropagation();
-        closeAndRefocusTrigger();
+        popover.handleDismissKey(event);
     };
     return {
         idBase,
@@ -262,7 +191,7 @@ export function useCustomSelect({ value, options, onChange, portal, placeholder,
  * {@link useCustomSelect}; this component only wires the hook's state to the
  * trigger button and the listbox menu.
  */
-export function CustomSelect({ value, options, onChange, ariaLabel, labelledBy, className, triggerClassName, menuClassName, disabled = false, placeholder, portal = true, title, onFocus, menuHeader, onOpenChange, useCustomSelect: useCustomSelectHook = useCustomSelect, }) {
+export function CustomSelect({ value, options, onChange, ariaLabel, labelledBy, className, triggerClassName, menuClassName, disabled = false, placeholder, portal = true, portalContainer, title, onFocus, menuHeader, onOpenChange, useCustomSelect: useCustomSelectHook = useCustomSelect, }, _optional = {}) {
     const { idBase, buttonRef, menuRef, open, activeValue, position, selectedLabel, optionIdByValue, activeOptionId, choose, setActiveValue, toggleOpen, onButtonKeyDown, onMenuKeyDown, } = useCustomSelectHook({ value, options, onChange, portal, placeholder, onOpenChange });
     /**
      * The theme of the place this menu was opened FROM.
@@ -301,7 +230,7 @@ export function CustomSelect({ value, options, onChange, ariaLabel, labelledBy,
                 }
                 return (_jsx(CustomSelectOptionButton, { option: item, selected: item.value === value, active: item.value === activeValue, id: optionIdByValue.get(item.value), onChoose: choose, onActive: setActiveValue }, item.value));
             })] }));
-    return (_jsxs("div", { className: ['jini-select', className].filter(Boolean).join(' '), children: [_jsxs("button", { ref: buttonRef, type: "button", className: ['jini-select-trigger', triggerClassName].filter(Boolean).join(' '), role: "combobox", value: value, "aria-haspopup": "listbox", "aria-expanded": open, "aria-controls": `${idBase}-menu`, "aria-activedescendant": activeOptionId, "aria-describedby": labelledBy, "aria-label": `${ariaLabel}: ${selectedLabel}`, disabled: disabled, title: title, onClick: toggleOpen, onKeyDown: onButtonKeyDown, onFocus: onFocus, children: [_jsx("span", { id: `${idBase}-value`, className: "jini-select-value", children: selectedLabel }), _jsx(Icon, { name: "chevron-down", size: 14 })] }), open ? (portal ? (position ? createPortal(menu, document.body) : null) : menu) : null] }));
+    return (_jsxs("div", { className: ['jini-select', className].filter(Boolean).join(' '), children: [_jsxs("button", { ref: buttonRef, type: "button", className: ['jini-select-trigger', triggerClassName].filter(Boolean).join(' '), role: "combobox", value: value, "aria-haspopup": "listbox", "aria-expanded": open, "aria-controls": `${idBase}-menu`, "aria-activedescendant": activeOptionId, "aria-describedby": labelledBy, "aria-label": `${ariaLabel}: ${selectedLabel}`, disabled: disabled, title: title, onClick: toggleOpen, onKeyDown: onButtonKeyDown, onFocus: onFocus, children: [_jsx("span", { id: `${idBase}-value`, className: "jini-select-value", children: selectedLabel }), _jsx(Icon, { name: "chevron-down", size: 14 })] }), open ? (portal ? (position ? createPortal(menu, resolveSelectPortalContainer({ trigger: buttonRef.current }, { container: portalContainer })) : null) : menu) : null] }));
 }
 /** One row in the listbox: a selectable option button that reports hover
  * (activation) and click (choice) back to {@link CustomSelect}. */

package/dist/react/components/Icon.d.ts

@@ -1,6 +1,12 @@
 import type { ReactElement, SVGProps } from 'react';
 import type { IconName } from '../../icon-name.js';
 export type { IconName } from '../../icon-name.js';
+/** Exact shared geometry for outlines that feature artwork decorates with different inner marks.
+ * Keep the marks with their feature; a shared outline does not make two whole icons equivalent. */
+export declare const ICON_PATH_DATA: {
+    readonly 'document-outline-compact': "M6.5 3.5h7.6l3.9 3.9v13.1H6.5z";
+    readonly 'folder-outline-compact': "M3.5 7.5V6A1.5 1.5 0 0 1 5 4.5h4l2 2h8A1.5 1.5 0 0 1 20.5 8v10A1.5 1.5 0 0 1 19 19.5H5A1.5 1.5 0 0 1 3.5 18z";
+};
 interface Props extends Omit<SVGProps<SVGSVGElement>, 'name'> {
     name: IconName;
     size?: number | string;

package/dist/react/components/Icon.js

@@ -1,9 +1,21 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/** Exact shared geometry for outlines that feature artwork decorates with different inner marks.
+ * Keep the marks with their feature; a shared outline does not make two whole icons equivalent. */
+export const ICON_PATH_DATA = {
+    'document-outline-compact': 'M6.5 3.5h7.6l3.9 3.9v13.1H6.5z',
+    'folder-outline-compact': 'M3.5 7.5V6A1.5 1.5 0 0 1 5 4.5h4l2 2h8A1.5 1.5 0 0 1 20.5 8v10A1.5 1.5 0 0 1 19 19.5H5A1.5 1.5 0 0 1 3.5 18z',
+};
 // Exported as a test seam only — call it directly to assert key-set
 // completeness and per-entry validity without rendering. NOT part of the
 // package's public API: do not re-export it from `packages/ui/src/index.ts`
 // or any entry point.
 export const ICON_RENDERERS = {
+    'package-check': (common) => (_jsxs("svg", { ...common, children: [_jsx("path", { d: "M20.5 8.2v5.1L12 17.9l-8.5-4.6V8.2" }), _jsx("path", { d: "M3.5 8.2 12 3.6l8.5 4.6L12 12.8z" }), _jsx("path", { d: "M15.6 19.4l1.9 1.9 3.4-3.9" })] })),
+    'storefront': (common) => (_jsxs("svg", { ...common, children: [_jsx("path", { d: "M3.5 8.5h17l-1.2-4H4.7z" }), _jsx("path", { d: "M5 8.5v11h14v-11" }), _jsx("path", { d: "M9.75 19.5v-5.5h4.5v5.5" })] })),
+    'package-outline': (common) => (_jsxs("svg", { ...common, children: [_jsx("path", { d: "M3.5 8.2 12 3.6l8.5 4.6v7.6L12 20.4l-8.5-4.6z" }), _jsx("path", { d: "M3.5 8.2 12 12.8l8.5-4.6M12 12.8v7.6" })] })),
+    'trash-compact': (common) => (_jsxs("svg", { ...common, children: [_jsx("path", { d: "M4.5 7h15M9.5 7V4.6h5V7" }), _jsx("path", { d: "M6.6 7l.9 12.4h9l.9-12.4" }), _jsx("path", { d: "M10.4 10.5v6M13.6 10.5v6" })] })),
+    'chevron-right-wide': (common) => (_jsx("svg", { ...common, children: _jsx("path", { d: "M9 5.5 15.5 12 9 18.5" }) })),
+    'check-long': (common) => (_jsx("svg", { ...common, children: _jsx("path", { d: "m5 13 4.5 4.5L19 6.5" }) })),
     'alert-triangle': (common) => (_jsxs("svg", { ...common, children: [_jsx("path", { d: "m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3" }), _jsx("path", { d: "M12 9v4" }), _jsx("path", { d: "M12 17h.01" })] })),
     'arrow-left': (common) => (_jsxs("svg", { ...common, children: [_jsx("path", { d: "M19 12H5" }), _jsx("path", { d: "m12 19-7-7 7-7" })] })),
     'arrow-up': (common) => (_jsxs("svg", { ...common, children: [_jsx("path", { d: "M12 19V5" }), _jsx("path", { d: "m5 12 7-7 7 7" })] })),

package/dist/react/components/select-popover.d.ts

@@ -0,0 +1,106 @@
+import type { KeyboardEvent, RefObject } from 'react';
+/** DOM-order focus candidates within root, excluding the floating panel's own controls. */
+export declare function focusableInDomOrder({ exclude }: {
+    exclude: HTMLElement | null;
+}, { root }?: {
+    root?: ParentNode | undefined;
+}): HTMLElement[];
+/** Find the trigger's Tab neighbour, wrapping within its modal dialog to avoid inert page controls. */
+export declare function resolveTabTarget({ panel, trigger, shiftKey }: {
+    panel: HTMLElement | null;
+    trigger: HTMLElement | null;
+    shiftKey: boolean;
+}, _optional?: Record<string, never>): HTMLElement | null;
+/** Resolve a portal inside the trigger's native dialog so its menu stays above inert page content. */
+export declare function resolveSelectPortalContainer({ trigger }: {
+    trigger: HTMLElement | null;
+}, { container }?: {
+    container?: Element | DocumentFragment | null | undefined;
+}): Element | DocumentFragment;
+/** Pure containment decision; outside clicks must neither select an option nor steal focus. */
+export declare function isSelectEventInside({ target, trigger, panel }: {
+    target: Node;
+    trigger: HTMLElement | null;
+    panel: HTMLElement | null;
+}, _optional?: Record<string, never>): boolean;
+/** Apply the variant's geometry port; widget selects additionally dismiss a clipped/obscured trigger. */
+export declare function repositionSelectPopover<P>({ trigger, measurePosition, setPosition }: {
+    trigger: HTMLElement;
+    measurePosition: (input: {
+        trigger: HTMLElement;
+    }) => P;
+    setPosition: (position: P) => void;
+}, { onOutOfView }?: {
+    onOutOfView?: (() => void) | undefined;
+}): void;
+/** Measure before mounting/focusing a portal, then keep it anchored until close; listeners are disposed on close/unmount.
+ * Geometry is O(1); focus/visibility effects use the live DOM. The port retains each variant's existing placement bounds.
+ */
+export declare function useSelectPopoverPosition<P>(required: {
+    open: boolean;
+    triggerRef: RefObject<HTMLButtonElement | null>;
+    panelRef: RefObject<HTMLDivElement | null>;
+    measurePosition: (input: {
+        trigger: HTMLElement;
+    }) => P;
+}, optional?: {
+    portal?: boolean | undefined;
+    focusInitial?: ((input: {
+        panel: HTMLDivElement | null;
+    }) => void) | undefined;
+    onOutOfView?: (() => void) | undefined;
+}): {
+    position: P | null;
+    setPosition: import("react").Dispatch<import("react").SetStateAction<P | null>>;
+    updatePosition: () => void;
+};
+/** Open/close, outside dismissal and Escape/Tab focus handling shared by the public select variants.
+ * Tab scans the focusable DOM in O(n); other lifecycle transitions are O(1).
+ * @example useSelectPopover({ measurePosition }, { focusInitial: ({ panel }) => panel?.focus() })
+ */
+export declare function useSelectPopover<P>(required: {
+    measurePosition: (input: {
+        trigger: HTMLElement;
+    }) => P;
+}, optional?: {
+    portal?: boolean | undefined;
+    disabled?: boolean | undefined;
+    dismissWhenHidden?: boolean | undefined;
+    focusInitial?: ((input: {
+        panel: HTMLDivElement | null;
+    }) => void) | undefined;
+    onOpenChange?: ((open: boolean) => void) | undefined;
+}): {
+    openPanel: () => void;
+    closePanel: ({ refocusTrigger }: {
+        refocusTrigger: boolean;
+    }) => void;
+    handleDismissKey: (event: KeyboardEvent<HTMLElement>) => boolean;
+    position: P | null;
+    setPosition: import("react").Dispatch<import("react").SetStateAction<P | null>>;
+    updatePosition: () => void;
+    open: boolean;
+    triggerRef: RefObject<HTMLButtonElement | null>;
+    panelRef: RefObject<HTMLDivElement | null>;
+};
+/** Open-key decision shared by variants; returns false for unrelated keys or an already-open/disabled trigger. */
+export declare function openSelectOnKey({ event, open, openPanel }: {
+    event: KeyboardEvent<HTMLElement>;
+    open: boolean;
+    openPanel: () => void;
+}, { disabled }?: {
+    disabled?: boolean | undefined;
+}): boolean;
+/** Shared keyboard dispatch; adapters map navigation onto their enabled-value or filtered-index contract. */
+export declare function applySelectNavigationKey({ key, actions }: {
+    key: string;
+    actions: {
+        preventDefault: () => void;
+        move: (delta: 1 | -1) => void;
+        edge: (edge: 'first' | 'last') => void;
+        choose: () => void;
+    };
+}, { spaceChooses }?: {
+    spaceChooses?: boolean;
+}): boolean;
+//# sourceMappingURL=select-popover.d.ts.map

package/dist/react/components/select-popover.js

@@ -0,0 +1,210 @@
+/** Shared DOM lifecycle for the two custom select variants. Option/search policy stays in each adapter. */
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+// The panel is portaled to the end of document.body, its dialog, or a host container. Native Tab
+// would follow that DOM position toward browser chrome; walk the trigger real DOM-order
+// neighbours instead, staying inside a modal dialog when one owns the trigger.
+const FOCUSABLE_SELECTOR = 'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+/** DOM-order focus candidates within root, excluding the floating panel's own controls. */
+export function focusableInDomOrder({ exclude }, { root = document } = {}) {
+    return Array.from(root.querySelectorAll(FOCUSABLE_SELECTOR)).filter((el) => !exclude || !exclude.contains(el));
+}
+/** Find the trigger's Tab neighbour, wrapping within its modal dialog to avoid inert page controls. */
+export function resolveTabTarget({ panel, trigger, shiftKey }, _optional = {}) {
+    const dialog = trigger?.closest("dialog[open]");
+    // An open non-modal dialog permits focus outside it; only showModal() creates inert neighbours.
+    const modalDialog = dialog?.matches(":modal") ? dialog : null;
+    const nodes = focusableInDomOrder({ exclude: panel }, { root: modalDialog ?? document });
+    const triggerIndex = trigger ? nodes.indexOf(trigger) : -1;
+    if (triggerIndex < 0)
+        return null;
+    const nextIndex = triggerIndex + (shiftKey ? -1 : 1);
+    return nodes[modalDialog ? (nextIndex + nodes.length) % nodes.length : nextIndex] ?? null;
+}
+/** Resolve a portal inside the trigger's native dialog so its menu stays above inert page content. */
+export function resolveSelectPortalContainer({ trigger }, { container } = {}) {
+    return container ?? trigger?.closest('dialog') ?? document.body;
+}
+/** Pure containment decision; outside clicks must neither select an option nor steal focus. */
+export function isSelectEventInside({ target, trigger, panel }, _optional = {}) {
+    return Boolean(trigger?.contains(target) || panel?.contains(target));
+}
+/** Apply the variant's geometry port; widget selects additionally dismiss a clipped/obscured trigger. */
+export function repositionSelectPopover({ trigger, measurePosition, setPosition }, { onOutOfView } = {}) {
+    if (onOutOfView) {
+        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(measurePosition({ trigger }));
+}
+/** Measure before mounting/focusing a portal, then keep it anchored until close; listeners are disposed on close/unmount.
+ * Geometry is O(1); focus/visibility effects use the live DOM. The port retains each variant's existing placement bounds.
+ */
+export function useSelectPopoverPosition(required, optional = {}) {
+    const { open, triggerRef, panelRef } = required, portal = optional.portal !== false;
+    const latest = useRef({ required, optional });
+    latest.current = { required, optional };
+    const [position, setPosition] = useState(null);
+    const updatePosition = useCallback(() => {
+        const trigger = triggerRef.current;
+        if (trigger)
+            setPosition(latest.current.required.measurePosition({ trigger }));
+    }, [triggerRef]);
+    // 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; changing search/focus callbacks are read through latest and intentionally do not redrive it.
+    useLayoutEffect(() => {
+        if (!open) {
+            setPosition(null);
+            return;
+        }
+        if (portal && !position) {
+            updatePosition();
+            return;
+        }
+        latest.current.optional.focusInitial?.({ panel: panelRef.current });
+    }, [open, position, portal, updatePosition, panelRef]);
+    // 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
+    // `repositionSelectPopover`, 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; onOutOfView is read through latest; only lifecycle/ref changes re-arm it.
+    useEffect(() => {
+        if (!open || !portal)
+            return;
+        function reposition() {
+            const trigger = triggerRef.current;
+            if (!trigger)
+                return;
+            repositionSelectPopover({ trigger, measurePosition: latest.current.required.measurePosition, setPosition }, { onOutOfView: latest.current.optional.onOutOfView });
+        }
+        window.addEventListener('scroll', reposition, true);
+        window.addEventListener('resize', reposition);
+        return () => {
+            window.removeEventListener('scroll', reposition, true);
+            window.removeEventListener('resize', reposition);
+        };
+    }, [open, portal, triggerRef]);
+    return { position, setPosition, updatePosition };
+}
+/** Open/close, outside dismissal and Escape/Tab focus handling shared by the public select variants.
+ * Tab scans the focusable DOM in O(n); other lifecycle transitions are O(1).
+ * @example useSelectPopover({ measurePosition }, { focusInitial: ({ panel }) => panel?.focus() })
+ */
+export function useSelectPopover(required, optional = {}) {
+    const [open, setOpen] = useState(false);
+    const triggerRef = useRef(null), panelRef = useRef(null);
+    // Stored in a ref (not a `useEffect` dependency) so an unmemoized caller
+    // passing a fresh function identity every render never re-fires this for
+    // any reason OTHER than `open` actually changing.
+    const latest = useRef(optional);
+    latest.current = optional;
+    useEffect(() => { latest.current.onOpenChange?.(open); }, [open]);
+    const placement = useSelectPopoverPosition({ open, triggerRef, panelRef, measurePosition: required.measurePosition }, {
+        portal: optional.portal, focusInitial: optional.focusInitial,
+        onOutOfView: optional.dismissWhenHidden ? () => closePanel({ refocusTrigger: false }) : undefined,
+    });
+    function openPanel() { if (!latest.current.disabled)
+        setOpen(true); }
+    function closePanel({ refocusTrigger }) {
+        setOpen(false);
+        placement.setPosition(null); // forces the effect through its "measure, then focus" two-phase sequence again on the next open, rather than focusing at a stale, pre-close position
+        if (refocusTrigger)
+            triggerRef.current?.focus();
+    }
+    useEffect(() => {
+        if (!open)
+            return;
+        function onOutside(event) {
+            if (isSelectEventInside({ target: event.target, trigger: triggerRef.current, panel: panelRef.current }))
+                return;
+            closePanel({ refocusTrigger: false });
+        }
+        document.addEventListener('mousedown', onOutside);
+        return () => document.removeEventListener('mousedown', onOutside);
+    }, [open]);
+    function handleDismissKey(event) {
+        if (!open)
+            return false;
+        if (event.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.
+            event.preventDefault();
+            event.stopPropagation();
+            closePanel({ refocusTrigger: true });
+            return true;
+        }
+        if (event.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`, its dialog, or a host container, not sitting next to the
+            // trigger in the DOM. Dialog-local traversal avoids focusing inert page neighbours.
+            if (optional.portal !== false) {
+                const target = resolveTabTarget({ panel: panelRef.current, trigger: triggerRef.current, shiftKey: event.shiftKey });
+                event.preventDefault();
+                closePanel({ refocusTrigger: false });
+                target?.focus();
+            }
+            else
+                closePanel({ refocusTrigger: false });
+            return true;
+        }
+        return false;
+    }
+    return { open, triggerRef, panelRef, ...placement, openPanel, closePanel, handleDismissKey };
+}
+/** Open-key decision shared by variants; returns false for unrelated keys or an already-open/disabled trigger. */
+export function openSelectOnKey({ event, open, openPanel }, { disabled } = {}) {
+    if (disabled || open || !['Enter', ' ', 'ArrowDown', 'ArrowUp'].includes(event.key))
+        return false;
+    event.preventDefault();
+    openPanel();
+    return true;
+}
+/** Shared keyboard dispatch; adapters map navigation onto their enabled-value or filtered-index contract. */
+export function applySelectNavigationKey({ key, actions }, { spaceChooses = false } = {}) {
+    if (key === 'ArrowDown' || key === 'ArrowUp') {
+        actions.preventDefault();
+        actions.move(key === 'ArrowDown' ? 1 : -1);
+        return true;
+    }
+    if (key === 'Home' || key === 'End') {
+        actions.preventDefault();
+        actions.edge(key === 'Home' ? 'first' : 'last');
+        return true;
+    }
+    if (key === 'Enter' || (spaceChooses && key === ' ')) {
+        actions.preventDefault();
+        actions.choose();
+        return true;
+    }
+    return false;
+}
+//# sourceMappingURL=select-popover.js.map

package/dist/renderers/sandbox-scripts.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared sandbox script generation. The builders have established byte-level
+ * contracts: srcdoc uses modern link-handler syntax and a different focus
+ * marker/listener spelling. Keep those serialization differences here; each
+ * builder still owns its injection positions, defaults, CSP and bridges.
+ */
+type ScriptFormat = 'sandbox' | 'srcdoc';
+/**
+ * Script that shims `localStorage`/`sessionStorage` with an in-memory store
+ * when the real Storage API throws, and intercepts `<a href>` clicks so
+ * hash-only links scroll within the document (instead of attempting a
+ * sandboxed top-level navigation) and `target="_blank"` links open via
+ * `window.open` behind an `http:`/`https:`/`mailto:` scheme allow-list
+ * (instead of being silently blocked by the iframe sandbox).
+ */
+export declare function buildStorageScript({ format }: {
+    format: ScriptFormat;
+}, _optional?: Record<string, never>): string;
+/**
+ * Script that suppresses `focus()` calls (on `window` or any element) that
+ * aren't the direct result of a real pointer/keyboard event within the
+ * last second, so embedded content can't steal keyboard focus away from
+ * the host page around it.
+ */
+export declare function buildFocusScript({ format }: {
+    format: ScriptFormat;
+}, _optional?: Record<string, never>): string;
+export {};
+//# sourceMappingURL=sandbox-scripts.d.ts.map