@jini-ai/ui 0.3.13 → 0.4.0

package/dist/features/a2ui/protocol.d.ts

@@ -3,5 +3,5 @@
  * it. `agentic/core` owns the catalog/interpreter/protocol types (framework-free); this feature
  * folder is the React-facing wiring on top.
  */
-export { createA2uiInterpreter, createLabCatalog, type A2uiInterpreter, type ApplyMessageResult, type BuildActionResult, type ComponentInstance, type SurfaceSnapshot, type Catalog, type ComponentSpec, type ComponentKind, } from '@jini-ai/agentic/a2ui';
+export { createA2uiInterpreter, createLabCatalog, type A2uiInterpreter, type A2uiIdsPort, type ApplyMessageResult, type BuildActionResult, type ComponentInstance, type SurfaceSnapshot, type Catalog, type ComponentSpec, type ComponentKind, } from '@jini-ai/agentic/a2ui';
 //# sourceMappingURL=protocol.d.ts.map

package/dist/features/a2ui/renderer.js

@@ -1,5 +1,16 @@
 import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
 import { useA2uiSurfaceRoot } from './use-a2ui-surface.js';
+// Explicit provider contracts, not a guessed common callback. Display-only cards/charts
+// have no action callback; custom interactive entries can declare their own `actionProp`.
+const PROVIDER_ACTION_PROPS = new Map([
+    ['native.data-table', 'onRowClick'],
+    ['shadcn.data-table', 'onRowClick'],
+    ['shadcn.button', 'onPress'],
+    ['shadcn.checkbox', 'onCheckedChange'],
+    ['shadcn.radio-group', 'onValueChange'],
+    ['shadcn.text-input', 'onValueChange'],
+    ['shadcn.select', 'onValueChange'],
+]);
 /**
  * Recursively walks a surface's component map from `componentId` — same shape as
  * `@jini-ai/chat/react`'s `A2uiSurfaceCard`'s `RenderComponent` (cycle guard via `ancestors`,
@@ -17,7 +28,7 @@ function RenderNode({ interpreter, surfaceId, registry, componentId, ancestors,
     if (ancestors.has(componentId)) {
         return (_jsxs("span", { className: "a2ui-placeholder a2ui-placeholder-cycle", "data-a2ui-status": "cycle", "data-a2ui-component-id": componentId, children: ["\u27F2 circular reference at \"", componentId, "\""] }));
     }
-    const surface = interpreter.getSurface(surfaceId);
+    const surface = interpreter.getSurface({ surfaceId });
     const component = surface?.components.get(componentId);
     if (!component) {
         return (_jsxs("span", { className: "a2ui-placeholder a2ui-placeholder-missing", "data-a2ui-status": "missing", "data-a2ui-component-id": componentId, children: ["\u26A0 missing component \"", componentId, "\""] }));
@@ -26,7 +37,7 @@ function RenderNode({ interpreter, surfaceId, registry, componentId, ancestors,
     nextAncestors.add(componentId);
     const childProps = { interpreter, surfaceId, registry, ancestors: nextAncestors, onAction };
     function resolveText(value) {
-        const result = interpreter.resolve(surfaceId, value);
+        const result = interpreter.resolve({ surfaceId, value: value });
         if (!result.ok)
             return `⚠ unresolved (${result.reason})`;
         return typeof result.value === 'string' ? result.value : JSON.stringify(result.value);
@@ -49,15 +60,17 @@ function RenderNode({ interpreter, surfaceId, registry, componentId, ancestors,
         case 'Button':
             return (_jsx("button", { type: "button", className: `a2ui-button a2ui-button-${String(component.props.variant)}`, "data-a2ui-component-id": componentId, onClick: () => onAction(componentId), children: _jsx(RenderNode, { ...childProps, componentId: String(component.props.child) }) }));
         default: {
-            const entry = registry.resolveById(component.component);
+            const entry = registry.resolveById({ id: component.component });
             if (!entry) {
                 return (_jsxs("span", { className: "a2ui-placeholder", "data-a2ui-status": "unrenderable-type", "data-a2ui-component-id": componentId, children: ["\u26A0 no renderer yet for component type \"", component.component, "\""] }));
             }
             const RegistryComponent = entry.Component;
-            // See module doc: `onRowClick` is the one registry component that exists today
-            // (`native.data-table`/`shadcn.data-table`), not a generic per-component-type feedback
-            // convention — a future non-table provider needs its own decision here, not a guess.
-            return _jsx(RegistryComponent, { ...component.props, onRowClick: () => onAction(componentId) });
+            // `onRowClick` belongs to `native.data-table`/`shadcn.data-table`, not a generic
+            // per-component-type feedback convention — each non-table provider needs an explicit
+            // callback contract, supplied by the built-in map or its registry entry, not a guess.
+            // Unannotated custom entries retain the old table callback for compatibility.
+            const actionProp = entry.actionProp ?? PROVIDER_ACTION_PROPS.get(entry.id) ?? 'onRowClick';
+            return _jsx(RegistryComponent, { ...component.props, [actionProp]: () => onAction(componentId) });
         }
     }
 }
@@ -67,13 +80,13 @@ function RenderNode({ interpreter, surfaceId, registry, componentId, ancestors,
  * for coverage and the fallback resolution order.
  */
 export function A2uiSurfaceRenderer({ interpreter, surfaceId, registry, fallback }) {
-    const root = useA2uiSurfaceRoot(interpreter, surfaceId);
+    const root = useA2uiSurfaceRoot({ interpreter: interpreter, surfaceId: surfaceId });
     if (!root)
         return fallback ?? null;
     const onAction = (componentId) => {
-        const component = interpreter.getSurface(surfaceId)?.components.get(componentId);
+        const component = interpreter.getSurface({ surfaceId })?.components.get(componentId);
         if (component?.props.action !== undefined)
-            interpreter.buildAction(surfaceId, componentId);
+            interpreter.buildAction({ surfaceId, componentId });
     };
     return (_jsx(RenderNode, { interpreter: interpreter, surfaceId: surfaceId, registry: registry, componentId: root.id, ancestors: new Set(), onAction: onAction }));
 }

package/dist/features/a2ui/use-a2ui-surface.d.ts

@@ -1,13 +1,18 @@
 import type { A2uiInterpreter, ComponentInstance } from './protocol.js';
 /**
- * Subscribes a component to one A2UI surface's root, re-rendering whenever the interpreter
- * notifies (a message applied via `interpreter.applyAgentMessage` touched any surface — the
- * interpreter has no per-surface subscription granularity, so this hook re-reads `getRoot` on
- * every notification and lets `useSyncExternalStore`'s reference-equality check skip the render
- * if this particular surface's root object is unchanged).
+ * Subscribes a component to one A2UI surface's root, re-rendering when its components or data
+ * change (a message applied via `interpreter.applyAgentMessage` notifies for any surface — the
+ * interpreter has no per-surface subscription granularity, so this hook re-reads the whole
+ * surface on every notification and lets `useSyncExternalStore`'s reference-equality check skip
+ * the render if this particular surface's components and data model are unchanged). Descendant
+ * and binding updates must render even when the root object itself is unchanged.
  *
  * Returns `undefined` when the surface doesn't exist yet, or exists but has no `'root'`
  * component yet (a legal, "still streaming in" state per the interpreter's own `getRoot` doc).
+ * @complexity O(n) time per snapshot read and O(n) retained space for n surface components.
  */
-export declare function useA2uiSurfaceRoot(interpreter: A2uiInterpreter, surfaceId: string): ComponentInstance | undefined;
+export declare function useA2uiSurfaceRoot({ interpreter, surfaceId }: {
+    interpreter: A2uiInterpreter;
+    surfaceId: string;
+}): ComponentInstance | undefined;
 //# sourceMappingURL=use-a2ui-surface.d.ts.map

package/dist/features/a2ui/use-a2ui-surface.js

@@ -1,17 +1,47 @@
-import { useCallback, useSyncExternalStore } from 'react';
+import { useCallback, useMemo, useSyncExternalStore } from 'react';
 /**
- * Subscribes a component to one A2UI surface's root, re-rendering whenever the interpreter
- * notifies (a message applied via `interpreter.applyAgentMessage` touched any surface — the
- * interpreter has no per-surface subscription granularity, so this hook re-reads `getRoot` on
- * every notification and lets `useSyncExternalStore`'s reference-equality check skip the render
- * if this particular surface's root object is unchanged).
+ * Subscribes a component to one A2UI surface's root, re-rendering when its components or data
+ * change (a message applied via `interpreter.applyAgentMessage` notifies for any surface — the
+ * interpreter has no per-surface subscription granularity, so this hook re-reads the whole
+ * surface on every notification and lets `useSyncExternalStore`'s reference-equality check skip
+ * the render if this particular surface's components and data model are unchanged). Descendant
+ * and binding updates must render even when the root object itself is unchanged.
  *
  * Returns `undefined` when the surface doesn't exist yet, or exists but has no `'root'`
  * component yet (a legal, "still streaming in" state per the interpreter's own `getRoot` doc).
+ * @complexity O(n) time per snapshot read and O(n) retained space for n surface components.
  */
-export function useA2uiSurfaceRoot(interpreter, surfaceId) {
-    const subscribe = useCallback((onStoreChange) => interpreter.subscribe(onStoreChange), [interpreter]);
-    const getSnapshot = useCallback(() => interpreter.getRoot(surfaceId), [interpreter, surfaceId]);
-    return useSyncExternalStore(subscribe, getSnapshot);
+export function useA2uiSurfaceRoot({ interpreter, surfaceId }) {
+    const subscribe = useCallback((onStoreChange) => {
+        const unsubscribe = interpreter.subscribe({ listener: () => onStoreChange() });
+        return () => unsubscribe({});
+    }, [interpreter]);
+    const getSnapshot = useMemo(() => {
+        let snapshot;
+        return () => {
+            const current = interpreter.getSurface({ surfaceId });
+            if (!current) {
+                snapshot = undefined;
+                return snapshot;
+            }
+            // getSurface returns a new wrapper around a mutable component map. Cache a copy,
+            // comparing component identities and immutable data-model identity so repeated reads
+            // stay stable and changes before subscription are still visible to React's recheck.
+            let unchanged = snapshot !== undefined && snapshot.catalogId === current.catalogId
+                && Object.is(snapshot.dataModel, current.dataModel) && snapshot.components.size === current.components.size;
+            if (unchanged) {
+                for (const [id, component] of current.components) {
+                    if (snapshot.components.get(id) !== component) {
+                        unchanged = false;
+                        break;
+                    }
+                }
+            }
+            if (!unchanged)
+                snapshot = { ...current, components: new Map(current.components) };
+            return snapshot;
+        };
+    }, [interpreter, surfaceId]);
+    return useSyncExternalStore(subscribe, getSnapshot)?.components.get('root');
 }
 //# sourceMappingURL=use-a2ui-surface.js.map

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

@@ -0,0 +1,11 @@
+export interface ComingSoonNoticeProps {
+    kicker: string;
+    label: string;
+    /** Fully translated description supplied by the host. */
+    description: string;
+    note?: string | undefined;
+    agentHandle?: string | undefined;
+}
+/** A notice without navigation lookup, route knowledge, or locale state. */
+export declare function ComingSoonNotice({ kicker, label, description, note, agentHandle }: ComingSoonNoticeProps): import("react").JSX.Element;
+//# sourceMappingURL=ComingSoonNotice.d.ts.map

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

@@ -0,0 +1,7 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { agentHandle as handleProps } from '@jini-ai/agentic';
+/** A notice without navigation lookup, route knowledge, or locale state. */
+export function ComingSoonNotice({ kicker, label, description, note, agentHandle }) {
+    return (_jsx("div", { className: "coming-soon-notice", ...(agentHandle ? handleProps({ handle: agentHandle }, { role: 'status', label }) : {}), children: _jsxs("div", { className: "coming-soon-notice-header", children: [_jsx("p", { className: "coming-soon-notice-kicker", children: kicker }), _jsx("h1", { children: label }), _jsx("p", { children: description }), note ? _jsx("p", { children: note }) : null] }) }));
+}
+//# sourceMappingURL=ComingSoonNotice.js.map

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

@@ -0,0 +1,10 @@
+import type { ReactNode } from "react";
+export interface ComingSoonPanelProps {
+    /** Terse status without promised dates; label plus optional note should occupy at most two lines. */
+    label: string;
+    note?: string | undefined;
+    children: ReactNode;
+}
+/** Keeps preview content mounted inside an inert subtree, with caller-supplied status copy. */
+export declare function ComingSoonPanel({ label, note, children }: ComingSoonPanelProps): import("react").JSX.Element;
+//# sourceMappingURL=ComingSoonPanel.d.ts.map

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

@@ -0,0 +1,10 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+// Keep the real content visible so operators can see what is coming; an empty placeholder
+// would hide that context. Native inert removes the subtree from tab order, click handling and
+// the accessibility tree: opacity or pointer-events alone leaves apparently disabled controls usable.
+// The existing inert-control style uses 0.55 opacity to signal inactivity while retaining legibility.
+/** Keeps preview content mounted inside an inert subtree, with caller-supplied status copy. */
+export function ComingSoonPanel({ label, note, children }) {
+    return (_jsxs("div", { className: "coming-soon-panel", children: [_jsxs("p", { className: "settings-ui-inert-note", role: "note", children: [_jsx("strong", { children: label }), note ? _jsxs(_Fragment, { children: [" ", note] }) : null] }), _jsx("div", { className: "settings-ui-inert-control", inert: true, children: children })] }));
+}
+//# sourceMappingURL=ComingSoonPanel.js.map

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

@@ -0,0 +1,16 @@
+import { useImagePreviewModal } from "./ImagePreviewModal.hooks.js";
+export interface ImagePreviewModalProps {
+    open: boolean;
+    src: string;
+    alt: string;
+    onClose: () => void;
+    /** A fake controller can exercise rendering without a real native-dialog lifecycle. */
+    useModal?: typeof useImagePreviewModal | undefined;
+    /** Optional tagging preserves existing untagged renders when no agent handle is supplied. */
+    agentHandle?: string | undefined;
+    /** No locale is owned here; a translated caller must pass its own accessible close label. */
+    closeLabel?: string | undefined;
+}
+/** Controlled native-dialog lightbox. The host supplies image copy and a translated close label. */
+export declare function ImagePreviewModal({ open, src, alt, onClose, useModal, agentHandle: handle, closeLabel, }: ImagePreviewModalProps): import("react").JSX.Element;
+//# sourceMappingURL=ImagePreviewModal.d.ts.map

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

@@ -0,0 +1,13 @@
+import { type MouseEvent, type SyntheticEvent } from "react";
+export interface ImagePreviewModalController {
+    dialogRef: React.RefObject<HTMLDialogElement | null>;
+    /** Prevent native Escape-close and route through onClose; the open prop/effect owns lifecycle. */
+    handleNativeCancel: (e: SyntheticEvent<HTMLDialogElement>) => void;
+    /** The dialog box is content-sized: a target on the dialog itself, rather than a child, is backdrop. */
+    handleBackdropClick: (e: MouseEvent<HTMLDialogElement>) => void;
+}
+export declare function useImagePreviewModal({ open, onClose }: {
+    open: boolean;
+    onClose: () => void;
+}): ImagePreviewModalController;
+//# sourceMappingURL=ImagePreviewModal.hooks.d.ts.map

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

@@ -0,0 +1,46 @@
+import { useEffect, useRef } from "react";
+/**
+ * Isolate native dialog lifecycle in an injectable hook so rendering can use a fake controller.
+ * showModal/close are synchronous browser APIs: no async port or disposed-after-unmount guard
+ * is needed. Separate helpers keep each fallback branch shallow rather than nesting in the effect.
+ */
+/** Idempotent native open; the attribute fallback supports DOM environments without showModal. */
+function openDialog(dialog) {
+    if (typeof dialog.showModal === "function") {
+        if (!dialog.open)
+            dialog.showModal();
+        return;
+    }
+    dialog.setAttribute("open", "");
+}
+/** Mirror the attribute fallback where a DOM environment has no native close method. */
+function closeDialog(dialog) {
+    if (typeof dialog.close === "function") {
+        if (dialog.open)
+            dialog.close();
+        return;
+    }
+    dialog.removeAttribute("open");
+}
+export function useImagePreviewModal({ open, onClose }) {
+    const dialogRef = useRef(null);
+    useEffect(() => {
+        const dialog = dialogRef.current;
+        if (!dialog)
+            return;
+        if (open)
+            openDialog(dialog);
+        else
+            closeDialog(dialog);
+    }, [open]);
+    function handleNativeCancel(e) {
+        e.preventDefault();
+        onClose();
+    }
+    function handleBackdropClick(e) {
+        if (e.target === dialogRef.current)
+            onClose();
+    }
+    return { dialogRef, handleNativeCancel, handleBackdropClick };
+}
+//# sourceMappingURL=ImagePreviewModal.hooks.js.map

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

@@ -0,0 +1,13 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { agentHandle } from "@jini-ai/agentic";
+import { useImagePreviewModal } from "./ImagePreviewModal.hooks.js";
+// Native dialog supplies focus trapping, Escape and a backdrop through the browser's top layer,
+// avoiding a hand-built overlay and z-index policy. A confirm/cancel dialog's two-action contract
+// does not fit a read-only image with one close affordance. The injectable hook owns lifecycle
+// and DOM-environment fallbacks so this component stays focused on rendering.
+/** Controlled native-dialog lightbox. The host supplies image copy and a translated close label. */
+export function ImagePreviewModal({ open, src, alt, onClose, useModal = useImagePreviewModal, agentHandle: handle, closeLabel = "Close preview", }) {
+    const { dialogRef, handleNativeCancel, handleBackdropClick } = useModal({ open, onClose });
+    return (_jsxs("dialog", { ref: dialogRef, className: "image-preview-modal", "aria-label": alt, onCancel: handleNativeCancel, onClick: handleBackdropClick, children: [_jsx("button", { type: "button", className: "image-preview-modal-close", onClick: onClose, "aria-label": closeLabel, ...(handle ? agentHandle({ handle: handle }, { role: "button", label: closeLabel }) : {}), children: "\u00D7" }), _jsx("img", { src: src, alt: alt })] }));
+}
+//# sourceMappingURL=ImagePreviewModal.js.map

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

@@ -0,0 +1,18 @@
+import { useInfoTip } from "./InfoTip.hooks.js";
+/**
+ * Native title tooltips have an OS-dependent hover delay, inconsistent screen-reader exposure
+ * and no touch visibility. Hover/focus opens this affordance; Escape dismisses without moving
+ * focus, which onBlur alone cannot do.
+ * A body portal escapes overflow:hidden/scrolling ancestors: z-index cannot rescue an absolutely
+ * positioned descendant from clipping. Measured viewport coordinates position it above by
+ * preference, with the hook's headroom guard choosing below near the viewport's top.
+ * Keep state and DOM measurement in the injectable hook so rendering can use fixed fake state.
+ */
+export interface InfoTipProps {
+    label: string;
+    useTip?: typeof useInfoTip | undefined;
+    agentHandle?: string | undefined;
+}
+/** Focus/hover tooltip that portals outside clipping ancestors; Escape dismisses in place. */
+export declare function InfoTip({ label, useTip, agentHandle: handle }: InfoTipProps): import("react").JSX.Element;
+//# sourceMappingURL=InfoTip.d.ts.map

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

@@ -0,0 +1,16 @@
+import { type KeyboardEvent } from "react";
+export interface InfoTipController {
+    open: boolean;
+    placement: "above" | "below";
+    coords: {
+        top: number;
+        left: number;
+    };
+    iconRef: React.RefObject<HTMLSpanElement | null>;
+    show: () => void;
+    hide: () => void;
+    /** Escape closes in place; blur only covers leaving the trigger with Tab/Shift+Tab. */
+    handleIconKeyDown: (e: KeyboardEvent<HTMLSpanElement>) => void;
+}
+export declare function useInfoTip(): InfoTipController;
+//# sourceMappingURL=InfoTip.hooks.d.ts.map

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

@@ -0,0 +1,45 @@
+import { useRef, useState } from "react";
+/** Separate the hook for injectable rendering state. Its only outside effect is synchronous DOM
+ * measurement, so another async dependency/port layer would provide no rejection seam to test. */
+/** Above is a preference: require this much headroom before allowing an above-opening bubble. */
+const ABOVE_HEADROOM_PX = 176;
+/** Half the bubble's 18rem CSS max-width at a 16px root font. This worst-case width keeps narrow
+ * copy safe too. Pure icon-centering previously placed half a tip offscreen near a viewport edge. */
+const HALF_MAX_BUBBLE_WIDTH_PX = 144;
+/** Keep breathing room between the clamped bubble and either viewport edge. */
+const EDGE_MARGIN_PX = 8;
+/** Below 304px the clamp's minimum exceeds its maximum; center instead of using an inverted range. */
+function clampBubbleLeft(idealLeft) {
+    const minLeft = EDGE_MARGIN_PX + HALF_MAX_BUBBLE_WIDTH_PX;
+    const maxLeft = window.innerWidth - EDGE_MARGIN_PX - HALF_MAX_BUBBLE_WIDTH_PX;
+    if (maxLeft < minLeft)
+        return window.innerWidth / 2;
+    return Math.min(Math.max(idealLeft, minLeft), maxLeft);
+}
+export function useInfoTip() {
+    const [open, setOpen] = useState(false);
+    const [placement, setPlacement] = useState("above");
+    const [coords, setCoords] = useState({ top: 0, left: 0 });
+    const iconRef = useRef(null);
+    const show = () => {
+        const rect = iconRef.current?.getBoundingClientRect();
+        if (!rect)
+            return;
+        const nextPlacement = rect.top < ABOVE_HEADROOM_PX ? "below" : "above";
+        setPlacement(nextPlacement);
+        setCoords({
+            top: nextPlacement === "above" ? rect.top : rect.bottom,
+            left: clampBubbleLeft(rect.left + rect.width / 2),
+        });
+        setOpen(true);
+    };
+    const hide = () => setOpen(false);
+    function handleIconKeyDown(e) {
+        if (e.key === "Escape" && open) {
+            e.stopPropagation();
+            hide();
+        }
+    }
+    return { open, placement, coords, iconRef, show, hide, handleIconKeyDown };
+}
+//# sourceMappingURL=InfoTip.hooks.js.map

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

@@ -0,0 +1,12 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createPortal } from "react-dom";
+import { agentHandle } from "@jini-ai/agentic";
+import { useInfoTip } from "./InfoTip.hooks.js";
+/** Focus/hover tooltip that portals outside clipping ancestors; Escape dismisses in place. */
+export function InfoTip({ label, useTip = useInfoTip, agentHandle: handle }) {
+    const { open, placement, coords, iconRef, show, hide, handleIconKeyDown } = useTip();
+    return (_jsxs("span", { className: "info-tip", children: [_jsx("span", { ref: iconRef, className: "info-tip-icon", tabIndex: 0, "aria-label": label, onMouseEnter: show, onMouseLeave: hide, onFocus: show, onBlur: hide, onKeyDown: handleIconKeyDown, ...(handle ? agentHandle({ handle: handle }, { role: "button", label }) : {}), children: "\u24D8" }), open
+                ? createPortal(_jsx("span", { className: placement === "below" ? "info-tip-bubble info-tip-bubble-below" : "info-tip-bubble", role: "presentation", "aria-hidden": "true", style: { top: coords.top, left: coords.left }, children: label }), document.body)
+                : null] }));
+}
+//# sourceMappingURL=InfoTip.js.map

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

@@ -0,0 +1,41 @@
+import { useSeeMoreClamp } from "./SeeMore.hooks.js";
+/**
+ * Clamp the rendered region instead of slicing children: hidden text must stay in the DOM so
+ * browser find and screen readers can still reach it. Truncating the string loses that content.
+ * State and DOM measurement live in the separate hook, keeping presentation independently
+ * renderable with an injected measurement seam and no real layout engine or ResizeObserver.
+ */
+export interface SeeMoreProps {
+    children: React.ReactNode;
+    lines?: number | undefined;
+    moreLabel?: string | undefined;
+    lessLabel?: string | undefined;
+    className?: string | undefined;
+    /** Keep caller typography on the text region; clamp mechanics should not dictate color or line-height. */
+    textClassName?: string | undefined;
+    toggleClassName?: string | undefined;
+    /** Distinguish repeated toggles in a screen reader's button list; expanded/controls are always set. */
+    toggleAriaLabel?: string | undefined;
+    /** Supply a fake measurement hook when rendering without real scrollHeight/clientHeight layout. */
+    useClamp?: typeof useSeeMoreClamp | undefined;
+    /** The handle identifies a rendered toggle only; fitting content has no control to address. */
+    agentHandle?: string | undefined;
+}
+export interface SeeMoreView {
+    wrapperClassName: string;
+    textClassName: string;
+    toggleClassName: string;
+    toggleLabel: string;
+}
+export declare function resolveSeeMoreView({ expanded, }: {
+    expanded: boolean;
+}, { moreLabel, lessLabel, className, textClassName, toggleClassName, }?: {
+    moreLabel?: string | undefined;
+    lessLabel?: string | undefined;
+    className?: string | undefined;
+    textClassName?: string | undefined;
+    toggleClassName?: string | undefined;
+}): SeeMoreView;
+/** Clamps overflowing text and exposes an accessible expand/collapse toggle. Labels are host-owned. */
+export declare function SeeMore({ useClamp, agentHandle: handle, ...props }: SeeMoreProps): import("react").JSX.Element;
+//# sourceMappingURL=SeeMore.d.ts.map

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

@@ -0,0 +1,14 @@
+/** Separate measurement from JSX so callers can substitute a hook without a real layout engine.
+ * children participates in layout measurement so content changes are noticed as well as width reflow. */
+export declare function useSeeMoreClamp({ lines, children }: {
+    lines: number;
+    children: React.ReactNode;
+}): {
+    expanded: boolean;
+    setExpanded: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    overflows: boolean;
+    textRef: import("react").RefObject<HTMLDivElement | null>;
+    regionId: string;
+    lineCount: number;
+};
+//# sourceMappingURL=SeeMore.hooks.d.ts.map

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

@@ -0,0 +1,57 @@
+import { useCallback, useEffect, useId, useLayoutEffect, useRef, useState } from "react";
+/** Sub-pixel line-height rounding can make fitting text report a tiny overflow.
+ * One pixel avoids showing an expand control for an already visible single line. */
+const OVERFLOW_TOLERANCE_PX = 1;
+/** Separate measurement from JSX so callers can substitute a hook without a real layout engine.
+ * children participates in layout measurement so content changes are noticed as well as width reflow. */
+export function useSeeMoreClamp({ lines, children }) {
+    // Collapsed by default, per the request that created this component.
+    const [expanded, setExpanded] = useState(false);
+    const [overflows, setOverflows] = useState(false);
+    const textRef = useRef(null);
+    const regionId = useId();
+    const lineCount = Math.max(1, Math.round(lines));
+    const measure = useCallback(() => {
+        const el = textRef.current;
+        if (!el)
+            return;
+        setOverflows(el.scrollHeight > el.clientHeight + OVERFLOW_TOLERANCE_PX);
+    }, []);
+    // Both measuring effects bail while expanded, and that is the whole design rather than an
+    // oversight: expanding removes the clamp, at which point `scrollHeight === clientHeight` by
+    // definition and the check would report "does not overflow" for text that plainly does — which
+    // would unmount the toggle and strand the user in the expanded state with no way back. So
+    // `overflows` deliberately goes stale while expanded and is re-measured the moment it collapses.
+    // The visible consequence is narrow and self-correcting: if the children change while expanded so
+    // that they no longer overflow, the toggle lingers until the next collapse, then disappears with
+    // the (now fully visible) text.
+    //
+    // `useLayoutEffect` so the toggle's presence is settled before paint — a `useEffect` here shows
+    // one frame of clamped text with no way to expand it, then pops the button in.
+    useLayoutEffect(() => {
+        if (expanded)
+            return;
+        measure();
+        // `children` is a fresh object on every parent render, so this re-runs whenever the host
+        // re-renders (the first caller is a dialog that re-renders on each keystroke). That is two DOM
+        // reads, deliberately accepted: the alternative is missing a genuine content change. The
+        // `ResizeObserver` below is the expensive thing, and it is kept out of this dependency list.
+    }, [expanded, lineCount, children, measure]);
+    useEffect(() => {
+        if (expanded)
+            return;
+        const el = textRef.current;
+        // Guarded rather than assumed, the same way `Select.tsx` guards `elementFromPoint` and
+        // `scrollIntoView`: this app's jsdom test harness implements no `ResizeObserver` at all, so an
+        // unguarded `new ResizeObserver` throws on mount in every test that renders this component.
+        // Where it is missing, the layout effect above still measures on mount and on content change —
+        // only reflow-from-width-change goes unnoticed, which jsdom has no layout engine to produce.
+        if (!el || typeof ResizeObserver !== "function")
+            return;
+        const observer = new ResizeObserver(() => measure());
+        observer.observe(el);
+        return () => observer.disconnect();
+    }, [expanded, measure]);
+    return { expanded, setExpanded, overflows, textRef, regionId, lineCount };
+}
+//# sourceMappingURL=SeeMore.hooks.js.map

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

@@ -0,0 +1,24 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { agentHandle } from "@jini-ai/agentic";
+import { useSeeMoreClamp } from "./SeeMore.hooks.js";
+const DEFAULT_LINES = 2;
+// Presentation depends only on props and expanded state, so this decision needs no React render.
+export function resolveSeeMoreView({ expanded, }, { moreLabel = "See more", lessLabel = "See less", className, textClassName, toggleClassName, } = {}) {
+    return {
+        wrapperClassName: className ? `see-more ${className}` : "see-more",
+        textClassName: `see-more-text${expanded ? " is-expanded" : ""}${textClassName ? ` ${textClassName}` : ""}`,
+        toggleClassName: toggleClassName ? `see-more-toggle ${toggleClassName}` : "see-more-toggle",
+        toggleLabel: expanded ? lessLabel : moreLabel,
+    };
+}
+/** Clamps overflowing text and exposes an accessible expand/collapse toggle. Labels are host-owned. */
+export function SeeMore({ useClamp = useSeeMoreClamp, agentHandle: handle, ...props }) {
+    const { children, lines = DEFAULT_LINES, moreLabel, lessLabel, className, textClassName, toggleClassName, toggleAriaLabel } = props;
+    const { expanded, setExpanded, overflows, textRef, regionId, lineCount } = useClamp({ lines, children });
+    const view = resolveSeeMoreView({ expanded }, { moreLabel, lessLabel, className, textClassName, toggleClassName });
+    return (_jsxs("div", { className: view.wrapperClassName, children: [_jsx("div", { ref: textRef, id: regionId, className: view.textClassName, 
+                // The line count rides a custom property rather than a class-per-N (`.see-more-text--3`),
+                // so `lines` can be any integer a caller needs without this file growing a rule for each.
+                style: { "--see-more-lines": lineCount }, children: children }), overflows ? (_jsx("button", { type: "button", className: view.toggleClassName, "aria-expanded": expanded, "aria-controls": regionId, "aria-label": toggleAriaLabel, onClick: () => setExpanded((current) => !current), ...(handle ? agentHandle({ handle: handle }, { role: "button", label: toggleAriaLabel ?? view.toggleLabel }) : {}), children: view.toggleLabel })) : null] }));
+}
+//# sourceMappingURL=SeeMore.js.map

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

@@ -0,0 +1,39 @@
+import type { Translate } from "../../../i18n/dictionary-translator.js";
+import { useSelectDropdown, type SelectOption } from "./Select.hooks.js";
+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.
+ * 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. */
+export interface SelectProps {
+    value: string;
+    onChange: (value: string) => void;
+    options: SelectOption[];
+    placeholder?: string | undefined;
+    id?: string | undefined;
+    "aria-label"?: string | undefined;
+    "aria-labelledby"?: string | undefined;
+    disabled?: boolean | undefined;
+    /** Injectable state/effect seam; rendering tests need not drive portal positioning or listeners. */
+    useDropdown?: typeof useSelectDropdown | undefined;
+    agentHandle?: string | undefined;
+    /** Caller-bound translation function; source copy is the default. */
+    translate?: Translate | undefined;
+    /** Legacy alias for callers porting the original select. */
+    t?: Translate | undefined;
+}
+export declare function resolveSelectTriggerLabel({ selectedOption, placeholder }: {
+    selectedOption: SelectOption | null;
+    placeholder: string | undefined;
+}, { t }?: {
+    t?: Translate | undefined;
+}): {
+    text: string;
+    className: string;
+};
+/** Controlled searchable listbox with portal positioning and keyboard navigation. */
+export declare function Select(props: SelectProps): import("react").JSX.Element;
+//# sourceMappingURL=Select.d.ts.map