@jini-ai/ui 0.4.3 → 0.4.5

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @jini-ai/ui
 
+## 0.4.5 — pending release
+
+- Add universal `./mcp-ui/secret-card`: `defineSecretCardTool` owns fail-closed emission, cancellation, blank-secret policy, exact-byte submission and safe save-failure reporting. Specs retain domain validation, copy, dynamic fields, persistence and result projections.
+- Inject the daemon's existing `askThenReport` alongside the store; core owns the shared exchange ABI. No daemon or React runtime dependency in this entry.
+- Requires core 0.4.2; build and publish the release set before consumer adoption.
+
+## 0.4.4 — 2026-10-06
+
+- Recharts charts paint with host chart tokens `--jini-chart-1..6` / `-grid` / `-axis` / `-cursor` / `-surface` / `-text`, each falling back to a base token; a host that sets no `--jini-chart-N` gets the new warm orange `--jini-chart-default-1..6` palette (light and dark) instead of `--jini-primary`.
+- Behavior change: grid and axis use `--jini-border`/`--jini-muted`, no vertical grid lines, bars get a 4px rounded top and 64px max width, lines are 2px, and the tooltip uses theme surface/ink with a soft accent hover band.
+
 ## 0.4.3 — 2026-10-05
 
 - MCP-UI resources can carry an answer deadline: `createUIResource`/`buildConfirmationSurface` take `expiresAtMs`, written to `MCP_UI_EXPIRES_AT_META_KEY`; `readExpiresAt` reads it back (undefined when absent or not a finite number).

package/README.md

@@ -1,5 +1,25 @@
 # `@jini-ai/ui` — generic, product-neutral UI primitives
 
+`@jini-ai/ui/mcp-ui/secret-card` exports the framework-free `defineSecretCardTool` lifecycle.
+Provide a spec with `prepare`, `form`, `save`, `outcome` and `result`, then register
+`tool.handler({ surfaceExchanges, askThenReport })`; both dependencies come from
+`@jini-ai/daemon/surface-exchanges`. The UI entry has no daemon or React runtime import.
+Transport ports, including `emitSurface`, remain in the handler's optional second object.
+
+Secret fields use `{ kind: 'string', name, label, secret: true }` and cannot have `value`.
+Use `allowBlank: true` for optional credentials or a host's preserve-on-update policy; the
+engine sends the blank to `save`, where the host implements that policy. Domain save ports
+receive only declared field names, exact secret bytes and the execution's abort signal.
+Whitespace-only input is refused even with `allowBlank`; nonblank secrets are never trimmed.
+Return safe summaries only; result and outcome projections never receive submitted values.
+`form` retains the builders' translation, locale, details, warning and app options, with an
+optional `cancelLabel`. `outcome` may return undefined for locally reported dismiss/expiry.
+Use `safeError` only to map known error kinds to fixed text and `logFailure` for fixed metadata.
+
+The store ABI binds actor, tool and channel. The host must also enforce run scope when routing
+human answers (or inject a store scoped to the run); the exchange ABI does not carry a run ID.
+After coordinator verification, publish core 0.4.2, daemon 0.5.4 and UI 0.4.5 before adoption.
+
 Renamed from `@jini-ai/components` in this session (2026-07-16) once it became clear
 one "components" bucket undersold the scope: this package is meant to hold more
 than flat presentational components — pure business logic, hooks, and injectable

package/dist/core/theme/default.d.ts

@@ -0,0 +1,4 @@
+import type { AdminTheme } from './types.js';
+/** Neutral chrome. Products supply their own brand theme instead of forking CSS. */
+export declare const defaultAdminTheme: AdminTheme;
+//# sourceMappingURL=default.d.ts.map

package/dist/core/theme/default.js

@@ -0,0 +1,11 @@
+/** Neutral chrome. Products supply their own brand theme instead of forking CSS. */
+export const defaultAdminTheme = Object.freeze({
+    name: 'neutral',
+    fonts: Object.freeze({ body: 'system-ui, sans-serif', heading: 'system-ui, sans-serif', mono: 'ui-monospace, monospace' }),
+    light: Object.freeze({ primary: '#363636', primaryInk: '#ffffff', bg: '#ffffff', surface: '#f5f5f5',
+        text: '#202020', muted: '#666666', border: '#d9d9d9', danger: '#b42318', success: '#18763b', warning: '#845800' }),
+    dark: Object.freeze({ primary: '#e0e0e0', primaryInk: '#202020', bg: '#171717', surface: '#242424',
+        text: '#f0f0f0', muted: '#b3b3b3', border: '#454545', danger: '#ff8b80', success: '#79d69b', warning: '#ebc36b' }),
+    radius: '8px', density: 1,
+});
+//# sourceMappingURL=default.js.map

package/dist/core/theme/stylesheet.d.ts

@@ -0,0 +1,8 @@
+import type { AdminTheme, ColorScheme } from './types.js';
+/** Internal document adapter: isolated previews cannot inherit the admin's stylesheet. */
+export declare function renderAdminThemeVariables({ theme }: {
+    readonly theme: AdminTheme;
+}, { colorScheme }?: {
+    readonly colorScheme?: ColorScheme;
+}): string;
+//# sourceMappingURL=stylesheet.d.ts.map

package/dist/core/theme/stylesheet.js

@@ -0,0 +1,14 @@
+import { adminThemeColorKeys, validateAdminTheme } from './validation.js';
+import { defaultAdminTheme } from './default.js';
+/** Internal document adapter: isolated previews cannot inherit the admin's stylesheet. */
+export function renderAdminThemeVariables({ theme }, { colorScheme = 'light' } = {}) {
+    if (colorScheme !== 'light' && colorScheme !== 'dark')
+        throw new TypeError('Invalid resolved color scheme');
+    const checked = validateAdminTheme({ theme });
+    if (!checked.valid)
+        throw new TypeError(checked.errors.join('; '));
+    const values = adminThemeColorKeys.map((key) => `--jini-${key.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}:${theme[colorScheme][key]};`);
+    values.push(`--jini-font-body:${theme.fonts.body};`, `--jini-font-heading:${theme.fonts.heading};`, `--jini-font-mono:${theme.fonts.mono ?? defaultAdminTheme.fonts.mono};`, `--jini-radius:${theme.radius ?? defaultAdminTheme.radius};`);
+    return `:root{color-scheme:${colorScheme};${values.join('')}}`;
+}
+//# sourceMappingURL=stylesheet.js.map

package/dist/core/theme/types.d.ts

@@ -0,0 +1,39 @@
+/** The intentionally small palette every admin theme supplies in both schemes. */
+export interface AdminThemeColors {
+    readonly primary: string;
+    readonly primaryInk: string;
+    readonly bg: string;
+    readonly surface: string;
+    readonly text: string;
+    readonly muted: string;
+    readonly border: string;
+    readonly danger: string;
+    readonly success: string;
+    readonly warning: string;
+}
+/** Product fonts and palette are data. Font loading URLs are stylesheet URLs. */
+export interface AdminTheme {
+    readonly name: string;
+    readonly fonts: {
+        readonly body: string;
+        readonly heading: string;
+        readonly mono?: string;
+        readonly load?: readonly string[];
+    };
+    readonly light: AdminThemeColors;
+    readonly dark: AdminThemeColors;
+    readonly radius?: string;
+    /** Unitless spacing multiplier, from 0.5 to 2. */
+    readonly density?: number;
+}
+export type ColorScheme = 'light' | 'dark';
+export type ColorSchemePreference = ColorScheme | 'system';
+export type MatchMediaPort = (query: string) => {
+    readonly matches: boolean;
+    addEventListener?: (type: 'change', listener: () => void) => void;
+    removeEventListener?: (type: 'change', listener: () => void) => void;
+};
+/** Only these DOM capabilities are needed; no ambient document is consulted. */
+export type AdminThemeTarget = Pick<HTMLElement, 'style' | 'getAttribute' | 'setAttribute' | 'removeAttribute'>;
+export type AdminThemeDocument = Pick<Document, 'head' | 'createElement' | 'baseURI'>;
+//# sourceMappingURL=types.d.ts.map

package/dist/core/theme/types.js

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

package/dist/core/theme/validation.d.ts

@@ -0,0 +1,15 @@
+import type { AdminTheme } from './types.js';
+export declare const adminThemeColorKeys: readonly ["primary", "primaryInk", "bg", "surface", "text", "muted", "border", "danger", "success", "warning"];
+type Validation = {
+    readonly valid: true;
+    readonly theme: AdminTheme;
+} | {
+    readonly valid: false;
+    readonly errors: readonly string[];
+};
+/** Validate serializable theme data before any DOM or font-loading effect. */
+export declare function validateAdminTheme({ theme }: {
+    readonly theme: unknown;
+}): Validation;
+export {};
+//# sourceMappingURL=validation.d.ts.map

package/dist/core/theme/validation.js

@@ -0,0 +1,55 @@
+export const adminThemeColorKeys = ['primary', 'primaryInk', 'bg', 'surface', 'text', 'muted', 'border', 'danger', 'success', 'warning'];
+const record = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const safeValue = (value) => typeof value === 'string' && value.trim().length > 0
+    && value.length <= 512 && !/[;{}\x00-\x1f<>\\]/.test(value) && !/url\s*\(|\/\*|\*\//i.test(value);
+// Concrete palette values, deliberately excluding dependent var()/url() expressions.
+const component = '(?:[+-]?(?:\\d+(?:\\.\\d+)?|\\.\\d+)(?:%|deg|rad|grad|turn)?|none)';
+const components = new RegExp(`^(?:rgb|rgba|hsl|hsla|oklch|oklab|lab|lch)\\(\\s*${component}(?:\\s*,\\s*|\\s+)${component}(?:\\s*,\\s*|\\s+)${component}(?:(?:\\s*[,/]\\s*)${component})?\\s*\\)$`, 'i');
+const colorValue = (value) => safeValue(value)
+    && (/^#[\da-f]{3}(?:[\da-f]{1}|[\da-f]{3}|[\da-f]{5})?$/i.test(value)
+        || components.test(value)
+        || /^(?:transparent|black|white|red|green|blue|gray|grey)$/i.test(value));
+/** Validate serializable theme data before any DOM or font-loading effect. */
+export function validateAdminTheme({ theme }) {
+    const errors = [];
+    if (!record(theme))
+        return { valid: false, errors: ['Theme must be an object'] };
+    if (!safeValue(theme.name))
+        errors.push('name must be a nonempty safe string');
+    const fonts = theme.fonts;
+    if (!record(fonts) || !safeValue(fonts.body) || !safeValue(fonts.heading) || (fonts.mono !== undefined && !safeValue(fonts.mono))) {
+        errors.push('fonts must provide body and heading font stacks');
+    }
+    if (record(fonts) && fonts.load !== undefined) {
+        if (!Array.isArray(fonts.load) || fonts.load.length > 16 || !fonts.load.every((url) => {
+            if (typeof url !== 'string' || url.length > 4096 || /[\x00-\x20<>]/.test(url))
+                return false;
+            try {
+                return new URL(url, 'https://font-base.invalid').protocol === 'https:';
+            }
+            catch {
+                return false;
+            }
+        }))
+            errors.push('fonts.load must contain relative or HTTPS stylesheet URLs');
+    }
+    for (const scheme of ['light', 'dark']) {
+        const colors = theme[scheme];
+        if (!record(colors)) {
+            errors.push(`${scheme} must be a complete palette`);
+            continue;
+        }
+        for (const key of adminThemeColorKeys)
+            if (!Object.hasOwn(colors, key) || !colorValue(colors[key]))
+                errors.push(`${scheme}.${key} must be a concrete CSS color`);
+        for (const key of Object.keys(colors))
+            if (!adminThemeColorKeys.includes(key))
+                errors.push(`${scheme}.${key} is not a theme color`);
+    }
+    if (theme.radius !== undefined && (typeof theme.radius !== 'string' || !/^(?:0|\d+(?:\.\d+)?(?:px|rem|em))$/.test(theme.radius)))
+        errors.push('radius must be a nonnegative CSS length');
+    if (theme.density !== undefined && (typeof theme.density !== 'number' || !Number.isFinite(theme.density) || theme.density < 0.5 || theme.density > 2))
+        errors.push('density must be between 0.5 and 2');
+    return errors.length ? { valid: false, errors } : { valid: true, theme: theme };
+}
+//# sourceMappingURL=validation.js.map

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

@@ -4,7 +4,9 @@ export type { SelectOption };
 /** Use this custom listbox when in-panel search is needed: a native OS option list cannot host it.
  * Native selects otherwise avoid the accessibility/behavior tradeoffs of a simulated listbox.
  * JSX stays separate from dropdown state/DOM effects so injected useDropdown can render against a
- * fake without geometry or listeners. The body portal escapes clipping/stacking ancestors.
+ * fake without geometry or listeners. The body portal escapes clipping/stacking ancestors;
+ * inside a native dialog, a dialog-local portal also keeps options in its top layer and out of
+ * the inert page. Hosts can supply a container outside their own clipping regions.
  * Agent selection uses trigger/option clicks rather than native select_option; the -option namespace
  * keeps caller values from colliding with literal segments. Explicit base handles are not silently
  * sanitized: invalid caller choices should fail rather than publish a different handle. */
@@ -20,6 +22,12 @@ export interface SelectProps {
     /** Injectable state/effect seam; rendering tests need not drive portal positioning or listeners. */
     useDropdown?: typeof useSelectDropdown | undefined;
     agentHandle?: string | undefined;
+    /** Host-owned portal destination. Defaults to the trigger's nearest dialog, then document.body.
+     * Within a modal dialog, supply a descendant of that dialog so the panel remains interactive.
+     * Keep this container outside scrolling/clipping regions and free of transforms that establish
+     * a fixed-position containing block; panel coordinates are viewport-relative.
+     * @example <Select {...selectionProps} portalContainer={dialogOverlayElement} /> */
+    portalContainer?: Element | DocumentFragment | null | undefined;
     /** Caller-bound translation function; source copy is the default. */
     translate?: Translate | undefined;
     /** Legacy alias for callers porting the original select. */
@@ -34,6 +42,6 @@ export declare function resolveSelectTriggerLabel({ selectedOption, placeholder
     text: string;
     className: string;
 };
-/** Controlled searchable listbox with portal positioning and keyboard navigation. */
-export declare function Select(props: SelectProps): import("react").JSX.Element;
+/** Controlled searchable listbox with viewport positioning, dialog-local portals and keyboard navigation. */
+export declare function Select(props: SelectProps, _optional?: Record<string, never>): import("react").JSX.Element;
 //# sourceMappingURL=Select.d.ts.map

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

@@ -1,10 +1,8 @@
+export { focusableInDomOrder, resolveTabTarget } from '../../../../react/components/select-popover.js';
 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;
@@ -35,20 +33,17 @@ export declare function usePanelPosition({ open, triggerRef, panelRef, searchInp
     searchInputRef: React.RefObject<HTMLInputElement | null>;
     showSearch: boolean;
     onOutOfView: () => void;
-}): {
+}, _optional?: Record<string, never>): {
     position: PanelPosition | null;
     setPosition: import("react").Dispatch<import("react").SetStateAction<PanelPosition | null>>;
+    updatePosition: () => void;
 };
+/** Compatibility geometry seam; lifecycle decisions are owned by the shared popover. */
 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;
+}, _optional?: Record<string, never>): void;
 export declare function edgeHighlightIndex({ filteredLength, edge }: {
     filteredLength: number;
     edge: "first" | "last";
@@ -94,12 +89,12 @@ export declare function useSelectDropdown({ value, onChange, options, }: {
     filtered: SelectOption[];
     selectedOption: SelectOption | null;
     openPanel: () => void;
-    closePanel: (opts: {
+    closePanel: ({ refocusTrigger }: {
         refocusTrigger: boolean;
     }) => void;
     selectOption: (option: SelectOption) => void;
-    handleTriggerKeyDown: (e: React.KeyboardEvent<HTMLButtonElement>) => void;
-    handlePanelKeyDown: (e: React.KeyboardEvent<HTMLDivElement>) => void;
+    handleTriggerKeyDown: (event: React.KeyboardEvent<HTMLButtonElement>) => void;
+    handlePanelKeyDown: (event: React.KeyboardEvent<HTMLDivElement>) => void;
     optionId: (index: number) => string;
 };
 //# sourceMappingURL=Select.hooks.d.ts.map

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

@@ -5,18 +5,14 @@
  * 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";
+import { useSelectPopover, useSelectPopoverPosition, repositionSelectPopover, openSelectOnKey, applySelectNavigationKey } from '../../../../react/components/select-popover.js';
+export { focusableInDomOrder, resolveTabTarget } from '../../../../react/components/select-popover.js';
+import { useEffect, useId, 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,
@@ -41,97 +37,14 @@ export function buildOptionId({ listboxId, 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 }));
+export function usePanelPosition({ open, triggerRef, panelRef, searchInputRef, showSearch, onOutOfView, }, _optional = {}) {
+    return useSelectPopoverPosition({ open, triggerRef, panelRef, measurePosition: computePosition }, {
+        focusInitial: ({ panel }) => (showSearch ? searchInputRef.current : panel)?.focus(), onOutOfView,
+    });
 }
-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]);
+/** Compatibility geometry seam; lifecycle decisions are owned by the shared popover. */
+export function repositionOrClose({ trigger, onOutOfView, setPosition }, _optional = {}) {
+    repositionSelectPopover({ trigger, measurePosition: computePosition, setPosition }, { onOutOfView });
 }
 // A search can remove the previously highlighted option; re-anchor to the first match
 // rather than keep a stale index outside the narrowed list.
@@ -160,13 +73,6 @@ function useScrollHighlightedIntoView({ open, highlightedIndex, optionRefs, }) {
             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;
@@ -176,93 +82,25 @@ 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;
-    }
+    return applySelectNavigationKey({ key, actions: {
+            preventDefault: actions.preventDefault, move: actions.moveHighlight,
+            edge: (edge) => actions.setHighlightedIndex(edgeHighlightIndex({ filteredLength: filtered.length, edge })),
+            choose: () => {
+                const option = highlightedOptionOrNull({ filtered, highlightedIndex });
+                if (option)
+                    actions.selectOption(option);
+            },
+        } });
 }
 // 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
@@ -271,6 +109,11 @@ export function useSelectDropdown({ value, onChange, options, }, { disabled } =
     const optionRefs = useRef(new Map());
     const listboxId = useId();
     const showSearch = options.length >= SEARCH_VISIBILITY_THRESHOLD;
+    const popover = useSelectPopover({ measurePosition: computePosition }, {
+        disabled, dismissWhenHidden: true,
+        focusInitial: ({ panel }) => (showSearch ? searchInputRef.current : panel)?.focus(),
+    });
+    const { open, position, triggerRef, panelRef, closePanel } = popover;
     const filtered = useMemo(() => {
         if (!showSearch || !query.trim())
             return options;
@@ -283,15 +126,9 @@ export function useSelectDropdown({ value, onChange, options, }, { disabled } =
             return;
         const initialIndex = options.findIndex((o) => o.value === value);
         setQuery("");
-        setOpen(true);
+        popover.openPanel();
         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 });
@@ -303,35 +140,20 @@ export function useSelectDropdown({ value, onChange, options, }, { disabled } =
             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,
-    });
+    function handleTriggerKeyDown(event) {
+        openSelectOnKey({ event, open, openPanel }, { disabled });
+    }
+    // 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(event) {
+        if (popover.handleDismissKey(event))
+            return;
+        applyHighlightKey({ key: event.key, filtered, highlightedIndex, actions: {
+                preventDefault: () => event.preventDefault(), moveHighlight, setHighlightedIndex, selectOption,
+            } });
+    }
     const optionId = (index) => buildOptionId({ listboxId: listboxId, index: index });
     return {
         open,

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

@@ -1,4 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { resolveSelectPortalContainer } from '../../../../react/components/select-popover.js';
 import { createPortal } from "react-dom";
 import { agentHandle } from "@jini-ai/agentic";
 import { buildAgentListHandles } from "@jini-ai/agentic";
@@ -20,8 +21,8 @@ function resolveSelectTriggerActiveDescendant(open, highlightedIndex, optionId)
 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) {
+/** Controlled searchable listbox with viewport positioning, dialog-local portals and keyboard navigation. */
+export function Select(props, _optional = {}) {
     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"];
@@ -40,7 +41,7 @@ export function Select(props) {
     // 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)
+                ? 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 }), resolveSelectPortalContainer({ trigger: triggerRef.current }, { container: props.portalContainer }))
                 : null] }));
 }
 //# sourceMappingURL=Select.js.map