@jini-ai/ui 0.5.5 → 0.6.10

package/dist/features/about/rules.js

@@ -29,6 +29,154 @@ export const ABOUT_UPDATE_KEYS = {
     notChecked: 'settings.updateStatusNotChecked',
     check: 'settings.updateCheck',
 };
+const K = ABOUT_UPDATE_KEYS;
+/**
+ * Shared by the capability gate and the reported `unsupported` state — one
+ * outcome, since the operator can do nothing about either from this panel.
+ */
+const UNSUPPORTED_CONTROL = {
+    primaryAction: null,
+    primaryLabelKey: null,
+    showReleaseLink: true,
+    statusKey: K.unsupported,
+    statusTone: 'warning',
+};
+const DEVELOPMENT_CONTROL = {
+    primaryAction: null,
+    primaryLabelKey: null,
+    showReleaseLink: true,
+    statusKey: K.development,
+    statusTone: 'neutral',
+};
+/** `{ statusVars: { version } }` when the version is known (truthy), else nothing. */
+function versionVars(model) {
+    return model.availableVersion ? { statusVars: { version: model.availableVersion } } : {};
+}
+/** Whether either install route (hand off to an installer, or apply in place) is open. */
+function canInstall(model) {
+    return Boolean(model.canOpenInstaller || model.canApplyInPlace);
+}
+function deriveAvailable(model) {
+    return {
+        primaryAction: model.canDownload ? 'download' : null,
+        primaryLabelKey: model.canDownload ? K.download : null,
+        showReleaseLink: true,
+        statusKey: model.availableVersion ? K.available : K.availableUnknown,
+        statusTone: 'warning',
+        ...versionVars(model),
+    };
+}
+function deriveDownloading(model) {
+    const percent = model.downloadProgress?.percent;
+    const known = typeof percent === 'number';
+    return {
+        primaryAction: null,
+        primaryLabelKey: K.downloadingLabel,
+        showReleaseLink: true,
+        statusKey: known ? K.downloadingPercent : K.downloading,
+        statusTone: 'neutral',
+        ...(known ? { statusVars: { percent } } : {}),
+    };
+}
+function deriveDownloaded(model) {
+    const payload = model.updateKind === 'payload';
+    // The installer is already running; the only useful act left is to get
+    // out of its way.
+    if (model.installerOpened && model.canQuitAfterInstallerOpen) {
+        return {
+            primaryAction: 'quit',
+            primaryLabelKey: K.quit,
+            showReleaseLink: false,
+            statusKey: payload ? K.installingRestart : K.opening,
+            statusTone: 'neutral',
+        };
+    }
+    const installable = canInstall(model);
+    return {
+        primaryAction: installable ? 'install' : null,
+        primaryLabelKey: installable ? (payload ? K.installRestart : K.installNow) : null,
+        showReleaseLink: true,
+        statusKey: model.availableVersion ? K.ready : K.readyUnknown,
+        statusTone: 'success',
+        ...versionVars(model),
+    };
+}
+/**
+ * Retry the furthest-along step that is still possible: re-install a
+ * download we already have, else re-download a version we know about,
+ * else start over. Sending the operator back to "check" when a finished
+ * download is sitting on disk would throw away the expensive part.
+ */
+function errorRetryAction(model) {
+    if (model.status?.downloadPath != null && canInstall(model))
+        return 'install';
+    if (model.availableVersion != null && model.canDownload)
+        return 'download';
+    return 'check';
+}
+function deriveError(model) {
+    return {
+        primaryAction: errorRetryAction(model),
+        primaryLabelKey: K.retry,
+        showReleaseLink: true,
+        statusKey: K.failed,
+        statusTone: 'error',
+    };
+}
+/**
+ * `idle`, and any state a newer backend reports that this build predates.
+ * Falling through to "you can check" is the safe default: it offers the
+ * one action that is valid from any unknown state.
+ */
+const IDLE_CONTROL = {
+    primaryAction: 'check',
+    primaryLabelKey: K.check,
+    showReleaseLink: true,
+    statusKey: K.notChecked,
+    statusTone: 'neutral',
+};
+/**
+ * One deriver per reported state. A `Map` (not an object literal) so a
+ * state string that happens to name an `Object.prototype` member can never
+ * resolve to anything but the idle fallback.
+ */
+const STATE_DERIVERS = new Map([
+    [
+        'checking',
+        () => ({
+            primaryAction: null,
+            primaryLabelKey: K.checkingLabel,
+            showReleaseLink: true,
+            statusKey: K.checking,
+            statusTone: 'neutral',
+        }),
+    ],
+    [
+        'not-available',
+        () => ({
+            primaryAction: 'check',
+            primaryLabelKey: K.recheck,
+            showReleaseLink: true,
+            statusKey: K.upToDate,
+            statusTone: 'success',
+        }),
+    ],
+    ['available', deriveAvailable],
+    ['downloading', deriveDownloading],
+    ['downloaded', deriveDownloaded],
+    [
+        'installing',
+        () => ({
+            primaryAction: null,
+            primaryLabelKey: K.installingRestart,
+            showReleaseLink: false,
+            statusKey: K.installing,
+            statusTone: 'neutral',
+        }),
+    ],
+    ['error', deriveError],
+    ['unsupported', () => ({ ...UNSUPPORTED_CONTROL })],
+]);
 /**
  * Derives what the About panel's update row should show.
  *
@@ -45,7 +193,7 @@ export const ABOUT_UPDATE_KEYS = {
  *    build — one shared "unsupported" outcome, since the operator can do
  *    nothing about any of them from this panel.
  *
- * After that it is a switch over the reported state. Two subtleties worth
+ * After that it is a lookup of the reported state in `STATE_DERIVERS`. Two subtleties worth
  * keeping when reading it:
  *
  * - `primaryLabelKey` can be set while `primaryAction` is `null`. That is the
@@ -55,136 +203,15 @@ export const ABOUT_UPDATE_KEYS = {
  *   about to disappear (installing, or quitting to let an installer run).
  *   Offering a navigation there invites a click that cannot complete.
  *
- * @complexity O(1) — a fixed switch, no iteration.
+ * @complexity O(1) — a fixed-size map lookup, no iteration.
  */
 export function deriveAboutUpdateControl(model, appVersionInfo) {
-    const K = ABOUT_UPDATE_KEYS;
-    if (appVersionInfo?.packaged === false) {
-        return {
-            primaryAction: null,
-            primaryLabelKey: null,
-            showReleaseLink: true,
-            statusKey: K.development,
-            statusTone: 'neutral',
-        };
-    }
-    if (model.environment !== 'desktop' || !model.enabled || !model.supported) {
-        return {
-            primaryAction: null,
-            primaryLabelKey: null,
-            showReleaseLink: true,
-            statusKey: K.unsupported,
-            statusTone: 'warning',
-        };
-    }
-    switch (model.status?.state) {
-        case 'checking':
-            return {
-                primaryAction: null,
-                primaryLabelKey: K.checkingLabel,
-                showReleaseLink: true,
-                statusKey: K.checking,
-                statusTone: 'neutral',
-            };
-        case 'not-available':
-            return {
-                primaryAction: 'check',
-                primaryLabelKey: K.recheck,
-                showReleaseLink: true,
-                statusKey: K.upToDate,
-                statusTone: 'success',
-            };
-        case 'available':
-            return {
-                primaryAction: model.canDownload ? 'download' : null,
-                primaryLabelKey: model.canDownload ? K.download : null,
-                showReleaseLink: true,
-                statusKey: model.availableVersion ? K.available : K.availableUnknown,
-                statusTone: 'warning',
-                ...(model.availableVersion ? { statusVars: { version: model.availableVersion } } : {}),
-            };
-        case 'downloading': {
-            const percent = model.downloadProgress?.percent;
-            const known = typeof percent === 'number';
-            return {
-                primaryAction: null,
-                primaryLabelKey: K.downloadingLabel,
-                showReleaseLink: true,
-                statusKey: known ? K.downloadingPercent : K.downloading,
-                statusTone: 'neutral',
-                ...(known ? { statusVars: { percent } } : {}),
-            };
-        }
-        case 'downloaded': {
-            // The installer is already running; the only useful act left is to get
-            // out of its way.
-            if (model.installerOpened && model.canQuitAfterInstallerOpen) {
-                return {
-                    primaryAction: 'quit',
-                    primaryLabelKey: K.quit,
-                    showReleaseLink: false,
-                    statusKey: model.updateKind === 'payload' ? K.installingRestart : K.opening,
-                    statusTone: 'neutral',
-                };
-            }
-            const canInstall = Boolean(model.canOpenInstaller || model.canApplyInPlace);
-            return {
-                primaryAction: canInstall ? 'install' : null,
-                primaryLabelKey: canInstall ? (model.updateKind === 'payload' ? K.installRestart : K.installNow) : null,
-                showReleaseLink: true,
-                statusKey: model.availableVersion ? K.ready : K.readyUnknown,
-                statusTone: 'success',
-                ...(model.availableVersion ? { statusVars: { version: model.availableVersion } } : {}),
-            };
-        }
-        case 'installing':
-            return {
-                primaryAction: null,
-                primaryLabelKey: K.installingRestart,
-                showReleaseLink: false,
-                statusKey: K.installing,
-                statusTone: 'neutral',
-            };
-        case 'error': {
-            // Retry the furthest-along step that is still possible: re-install a
-            // download we already have, else re-download a version we know about,
-            // else start over. Sending the operator back to "check" when a finished
-            // download is sitting on disk would throw away the expensive part.
-            const canRetryInstall = model.status?.downloadPath != null && Boolean(model.canOpenInstaller || model.canApplyInPlace);
-            const primaryAction = canRetryInstall
-                ? 'install'
-                : model.availableVersion != null && model.canDownload
-                    ? 'download'
-                    : 'check';
-            return {
-                primaryAction,
-                primaryLabelKey: K.retry,
-                showReleaseLink: true,
-                statusKey: K.failed,
-                statusTone: 'error',
-            };
-        }
-        case 'unsupported':
-            return {
-                primaryAction: null,
-                primaryLabelKey: null,
-                showReleaseLink: true,
-                statusKey: K.unsupported,
-                statusTone: 'warning',
-            };
-        // `idle`, and any state a newer backend reports that this build predates.
-        // Falling through to "you can check" is the safe default: it offers the
-        // one action that is valid from any unknown state.
-        case 'idle':
-        default:
-            return {
-                primaryAction: 'check',
-                primaryLabelKey: K.check,
-                showReleaseLink: true,
-                statusKey: K.notChecked,
-                statusTone: 'neutral',
-            };
-    }
+    if (appVersionInfo?.packaged === false)
+        return { ...DEVELOPMENT_CONTROL };
+    if (model.environment !== 'desktop' || !model.enabled || !model.supported)
+        return { ...UNSUPPORTED_CONTROL };
+    const derive = model.status ? STATE_DERIVERS.get(model.status.state) : undefined;
+    return derive ? derive(model) : { ...IDLE_CONTROL };
 }
 /**
  * Whether the primary button should be disabled.

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

@@ -1,16 +1,17 @@
-import { useImagePreviewModal } from "./ImagePreviewModal.hooks.js";
+import type { useLightbox } from "./Lightbox/Lightbox.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;
+    useModal?: typeof useLightbox | 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. */
+/** One image in the shared `Lightbox`; the alt text doubles as its title. Kept as a named
+ *  single-image entry point so callers need not assemble the lightbox for the common case. */
 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.js

@@ -1,13 +1,9 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx } 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 })] }));
+import { Lightbox } from "./Lightbox/Lightbox.js";
+/** One image in the shared `Lightbox`; the alt text doubles as its title. Kept as a named
+ *  single-image entry point so callers need not assemble the lightbox for the common case. */
+export function ImagePreviewModal({ open, src, alt, onClose, useModal, agentHandle: handle, closeLabel = "Close preview", }) {
+    return (_jsx(Lightbox, { open: open, title: alt, onClose: onClose, className: "image-preview-modal", labels: { close: closeLabel }, useLightboxHook: useModal, partAttrs: handle ? { close: { ...agentHandle({ handle: handle }, { role: "button", label: closeLabel }) } } : undefined, children: _jsx("img", { src: src, alt: alt }) }));
 }
 //# sourceMappingURL=ImagePreviewModal.js.map

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

@@ -5,7 +5,8 @@ import { useInfoTip } from "./InfoTip.hooks.js";
  * 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
+ * positioned descendant from clipping. Inside a modal <dialog> it portals into that dialog
+ * instead, because the dialog's top layer covers everything in body. Measured viewport coordinates position it above by
  * preference, with the hook's headroom guard choosing below near the viewport's top; near a side
  * edge (or a host panel marked `data-jini-tip-bounds`) it shifts by its real width, never squeezes.
  * Keep state and DOM measurement in the injectable hook so rendering can use fixed fake state.
@@ -13,7 +14,7 @@ import { useInfoTip } from "./InfoTip.hooks.js";
  * tap, blur or Escape; a hover-opened tip still closes when the pointer leaves.
  */
 export interface InfoTipProps {
-    /** The explanation the bubble shows. */
+    /** The explanation the bubble shows; newlines separate lines, and "• " lines show as a hanging list. */
     label: string;
     /**
      * Short accessible name for the icon ("About subagents"). Omitted, the icon is named by `label`

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

@@ -78,6 +78,8 @@ export function useInfoTip(_input = {}, { placement: preferredPlacement } = {})
     }, [open]);
     function handleIconKeyDown(e) {
         if (e.key === "Escape" && open) {
+            // preventDefault also stops an enclosing modal <dialog> from closing on the same keypress.
+            e.preventDefault();
             e.stopPropagation();
             hide();
             return;

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

@@ -3,18 +3,45 @@ import { useId } from "react";
 import { createPortal } from "react-dom";
 import { agentHandle } from "@jini-ai/agentic";
 import { useInfoTip } from "./InfoTip.hooks.js";
-import { infoTipBubbleStyle } from "./InfoTip.rules.js";
+import { infoTipBubbleStyle, infoTipLines } from "./InfoTip.rules.js";
 /** Focus/hover tooltip that portals outside clipping ancestors; Escape dismisses in place. */
 export function InfoTip({ label, triggerLabel, descriptionId, placement: preferredPlacement, useTip = useInfoTip, agentHandle: handle, icon }) {
-    const { open, placement, coords, iconRef, bubbleRef, show, hide, leave, toggle, handleIconKeyDown } = useTip({}, { placement: preferredPlacement === "inline" ? undefined : preferredPlacement });
+    const inline = preferredPlacement === "inline";
+    const { open, placement, coords, iconRef, bubbleRef, show, hide, leave, toggle, handleIconKeyDown } = useTip({}, { placement: inline ? undefined : preferredPlacement });
     const autoId = useId();
-    const name = triggerLabel ?? label;
+    const { name, textId, describedBy } = infoTipNaming({ label, autoId }, { triggerLabel, descriptionId });
+    return (_jsxs("span", { className: inline ? "info-tip info-tip--inline" : "info-tip", children: [_jsx("span", { ref: iconRef, className: icon ? "info-tip-icon info-tip-icon--custom" : "info-tip-icon", role: "button", tabIndex: 0, "aria-label": name, "aria-expanded": open, ...(describedBy ? { "aria-describedby": describedBy } : {}), onMouseEnter: show, onMouseLeave: leave, onFocus: show, onBlur: hide, onClick: toggle, onKeyDown: handleIconKeyDown, ...(handle ? agentHandle({ handle }, { role: "button", label: name }) : {}), children: icon ?? "ⓘ" }), textId ? _jsx("span", { id: textId, hidden: true, children: label }) : null, open ? _jsx(InfoTipOpenCopy, { label: label, inline: inline, placement: placement, coords: coords, iconRef: iconRef, bubbleRef: bubbleRef }) : null] }));
+}
+/**
+ * The icon's accessible name and the id of the hidden copy of `label` (if any).
+ * @returns `name` for `aria-label`, `textId` for the hidden copy, `describedBy` for `aria-describedby`.
+ * @complexity O(1).
+ */
+function infoTipNaming({ label, autoId }, { triggerLabel, descriptionId }) {
     // With no short name the icon is already named by the full text; describing it again would
     // make a screen reader read it twice.
     const textId = descriptionId ?? (triggerLabel ? autoId : undefined);
-    const describedBy = triggerLabel ? textId : undefined;
-    return (_jsxs("span", { className: preferredPlacement === "inline" ? "info-tip info-tip--inline" : "info-tip", children: [_jsx("span", { ref: iconRef, className: icon ? "info-tip-icon info-tip-icon--custom" : "info-tip-icon", role: "button", tabIndex: 0, "aria-label": name, "aria-expanded": open, ...(describedBy ? { "aria-describedby": describedBy } : {}), onMouseEnter: show, onMouseLeave: leave, onFocus: show, onBlur: hide, onClick: toggle, onKeyDown: handleIconKeyDown, ...(handle ? agentHandle({ handle: handle }, { role: "button", label: name }) : {}), children: icon ?? "ⓘ" }), textId ? _jsx("span", { id: textId, hidden: true, children: label }) : null, open && preferredPlacement === "inline" ? _jsx("span", { className: "info-tip-inline-copy", "aria-hidden": "true", children: label }) : open
-                ? createPortal(_jsx("span", { ref: bubbleRef, className: placement === "below" ? "info-tip-bubble info-tip-bubble-below" : "info-tip-bubble", role: "presentation", "aria-hidden": "true", style: infoTipBubbleStyle(coords), children: label }), document.body)
-                : null] }));
+    return { name: triggerLabel ?? label, textId, describedBy: triggerLabel ? textId : undefined };
+}
+/** The open tip: inline copy beside the icon, or the bubble portaled out of clipping ancestors. */
+function InfoTipOpenCopy({ label, inline, placement, coords, iconRef, bubbleRef }) {
+    if (inline)
+        return _jsx("span", { className: "info-tip-inline-copy", "aria-hidden": "true", children: label });
+    return createPortal(_jsx("span", { ref: bubbleRef, className: placement === "below" ? "info-tip-bubble info-tip-bubble-below" : "info-tip-bubble", role: "presentation", "aria-hidden": "true", style: { ...infoTipBubbleStyle(coords), whiteSpace: "pre-line" }, children: _jsx(InfoTipBubbleText, { label: label }) }), 
+    // A modal <dialog> sits in the browser's top layer, above anything portaled to body.
+    iconRef.current?.closest("dialog") ?? document.body);
+}
+/** The bubble's text: a hanging list when any line is a "• " bullet, else the label as-is. */
+function InfoTipBubbleText({ label }) {
+    const lines = infoTipLines(label);
+    if (!lines)
+        return label;
+    // Keep the label's text separators; flex layout alone loses them from textContent.
+    return lines.map((line, index) => {
+        const separator = index < lines.length - 1 ? "\n" : null;
+        return line.bullet
+            ? _jsxs("span", { className: "info-tip-bullet", children: [_jsx("span", { "aria-hidden": "true", children: "\u2022" }), " ", _jsx("span", { children: line.text }), separator] }, index)
+            : _jsxs("span", { className: "info-tip-line", children: [line.text, separator] }, index);
+    });
 }
 //# sourceMappingURL=InfoTip.js.map

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

@@ -69,4 +69,17 @@ export declare function infoTipBubbleStyle(coords: {
     left: number;
     arrowLeft?: number | undefined;
 }): CSSProperties;
+/** One line of a bubble that holds a bulleted list. */
+export interface InfoTipLine {
+    text: string;
+    bullet: boolean;
+}
+/**
+ * Splits a label into lines when any line is a "• " bullet (e.g. a settings group's one tip, a line
+ * per option), so each bullet's wrapped text can hang past its dot; `pre-line` alone wraps under it.
+ * @param label The tip text; newlines separate lines.
+ * @returns The lines with their "• " removed, or `null` when the label has no bullet line.
+ * @complexity O(n) in the label's length.
+ */
+export declare function infoTipLines(label: string): InfoTipLine[] | null;
 //# sourceMappingURL=InfoTip.rules.d.ts.map

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

@@ -32,25 +32,45 @@ const ARROW_INSET_PX = 10;
 export function placeInfoTipBubble(input, { bounds, preferred } = {}) {
     const { anchor, bubble, viewport } = input;
     const width = bubble && bubble.width > 0 ? bubble.width : MAX_BUBBLE_WIDTH_PX;
+    const height = bubble && bubble.height > 0 ? bubble.height : 0;
+    const { left, arrowLeft } = placeHorizontally({ anchor, width, viewportWidth: viewport.width }, { bounds });
+    const placement = placeVertically({ anchor, height, viewportHeight: viewport.height }, { preferred });
+    return { placement, top: placement === "above" ? anchor.top : anchor.top + anchor.height, left, arrowLeft };
+}
+/**
+ * The horizontal half of {@link placeInfoTipBubble}: the bubble's centre x and the arrow's offset.
+ * @param input.width The bubble's measured width, or the worst-case estimate before measurement.
+ * @param options.bounds A host panel's limits; used only when the bubble fits inside them.
+ * @returns The bubble's centre x and the arrow's x inside the bubble.
+ * @complexity O(1).
+ */
+function placeHorizontally({ anchor, width, viewportWidth }, { bounds }) {
     const anchorCentre = anchor.left + anchor.width / 2;
-    const viewportSpan = { lo: EDGE_MARGIN_PX, hi: viewport.width - EDGE_MARGIN_PX };
+    const viewportSpan = { lo: EDGE_MARGIN_PX, hi: viewportWidth - EDGE_MARGIN_PX };
     const boundsSpan = bounds
-        ? { lo: Math.max(bounds.left, 0) + EDGE_MARGIN_PX, hi: Math.min(bounds.right, viewport.width) - EDGE_MARGIN_PX }
+        ? { lo: Math.max(bounds.left, 0) + EDGE_MARGIN_PX, hi: Math.min(bounds.right, viewportWidth) - EDGE_MARGIN_PX }
         : null;
     const span = boundsSpan && boundsSpan.hi - boundsSpan.lo >= width ? boundsSpan : viewportSpan;
     const left = span.hi - span.lo < width
-        ? viewport.width / 2
+        ? viewportWidth / 2
         : Math.min(Math.max(anchorCentre, span.lo + width / 2), span.hi - width / 2);
     const bubbleLeftEdge = left - width / 2;
     const arrowLeft = Math.min(Math.max(anchorCentre - bubbleLeftEdge, ARROW_INSET_PX), width - ARROW_INSET_PX);
-    const anchorBottom = anchor.top + anchor.height;
-    const height = bubble && bubble.height > 0 ? bubble.height : 0;
+    return { left, arrowLeft };
+}
+/**
+ * The vertical half of {@link placeInfoTipBubble}: which side of the icon the bubble opens on.
+ * @param input.height The bubble's measured height, or 0 before measurement.
+ * @param options.preferred A host's preferred side; only "bottom" changes the default above-first rule.
+ * @returns The side the bubble opens on.
+ * @complexity O(1).
+ */
+function placeVertically({ anchor, height, viewportHeight }, { preferred }) {
     const fitsAbove = height > 0 ? anchor.top >= height + GAP_PX : anchor.top >= ABOVE_HEADROOM_PX;
-    const fitsBelow = height === 0 || anchorBottom + GAP_PX + height <= viewport.height;
-    const placement = preferred === "bottom"
-        ? (!fitsBelow && fitsAbove ? "above" : "below")
-        : fitsAbove ? "above" : "below";
-    return { placement, top: placement === "above" ? anchor.top : anchorBottom, left, arrowLeft };
+    if (preferred !== "bottom")
+        return fitsAbove ? "above" : "below";
+    const fitsBelow = height === 0 || anchor.top + anchor.height + GAP_PX + height <= viewportHeight;
+    return !fitsBelow && fitsAbove ? "above" : "below";
 }
 /**
  * The portal's inline style: position plus, once measured, the arrow offset as a CSS variable
@@ -65,4 +85,17 @@ export function infoTipBubbleStyle(coords) {
         style["--info-tip-arrow-left"] = `${coords.arrowLeft}px`;
     return style;
 }
+/**
+ * Splits a label into lines when any line is a "• " bullet (e.g. a settings group's one tip, a line
+ * per option), so each bullet's wrapped text can hang past its dot; `pre-line` alone wraps under it.
+ * @param label The tip text; newlines separate lines.
+ * @returns The lines with their "• " removed, or `null` when the label has no bullet line.
+ * @complexity O(n) in the label's length.
+ */
+export function infoTipLines(label) {
+    const lines = label.split("\n");
+    if (!lines.some((line) => line.startsWith("• ")))
+        return null;
+    return lines.map((line) => line.startsWith("• ") ? { text: line.slice(2), bullet: true } : { text: line, bullet: false });
+}
 //# sourceMappingURL=InfoTip.rules.js.map

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

@@ -0,0 +1,30 @@
+import { type ReactNode } from "react";
+import { useLightbox } from "./Lightbox.hooks.js";
+type LightboxPart = "dialog" | "close" | "previous" | "next";
+export interface LightboxProps {
+    open: boolean;
+    /** Shown above the media (usually the file name) and used as the dialog's accessible name. */
+    title: string;
+    onClose: () => void;
+    /** The media itself. `img`/`video` children are contain-fit to the viewport and never upscaled. */
+    children?: ReactNode;
+    /** Zero-based position and set size; with `onNavigate` and `count > 1` the arrow pair renders. */
+    index?: number | undefined;
+    count?: number | undefined;
+    onNavigate?: ((index: number) => void) | undefined;
+    /** Caller-specific controls (download, copy, metadata), placed bottom-left opposite the arrows. */
+    actions?: ReactNode;
+    /** No locale is owned here; a translated caller passes its own accessible labels. */
+    labels?: Partial<Record<"close" | "previous" | "next", string>> | undefined;
+    /** Extra class on the `<dialog>` so a caller can scope its own media rules. */
+    className?: string | undefined;
+    /** Per-part attributes (agent handles, `data-jini-part` markers) without the shell knowing them. */
+    partAttrs?: Partial<Record<LightboxPart, Record<string, string>>> | undefined;
+    /** A fake controller can exercise rendering without a real native-dialog lifecycle. */
+    useLightboxHook?: typeof useLightbox | undefined;
+}
+/** Full-viewport media lightbox: title and counter top-left, close top-right, the media as large
+ *  as fits, caller actions bottom-left and the previous/next pair together bottom-right. */
+export declare function Lightbox(props: LightboxProps): import("react").JSX.Element;
+export {};
+//# sourceMappingURL=Lightbox.d.ts.map

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

@@ -0,0 +1,40 @@
+import { type MouseEvent, type RefObject, type SyntheticEvent } from "react";
+/**
+ * Lifecycle for the shared `Lightbox`: native `<dialog>` open/close, focus capture and return,
+ * arrow-key navigation, Escape and backdrop dismissal. Absorbs the open/close and focus logic the
+ * media lightboxes and `ImagePreviewModal` each carried, so every caller gets the same behavior.
+ */
+/** Idempotent native open. `showModal()` throws on an already-open dialog in real browsers; the
+ *  attribute fallback covers DOM environments without it (jsdom). */
+export declare function openLightboxDialog(dialog: HTMLDialogElement): void;
+/** The close-side mirror of {@link openLightboxDialog} — same fallback and already-closed guard. */
+export declare function closeLightboxDialog(dialog: HTMLDialogElement): void;
+export interface LightboxHookInput {
+    open: boolean;
+    onClose: () => void;
+    /** Zero-based position in the set; with `count > 1` and `onNavigate` the arrow pair renders. */
+    index?: number | undefined;
+    count?: number | undefined;
+    onNavigate?: ((index: number) => void) | undefined;
+}
+export interface LightboxController {
+    dialogRef: RefObject<HTMLDialogElement | null>;
+    closeRef: RefObject<HTMLButtonElement | null>;
+    prevRef: RefObject<HTMLButtonElement | null>;
+    nextRef: RefObject<HTMLButtonElement | null>;
+    /** Whether the arrow pair renders at all (a single item has nowhere to go). */
+    navigable: boolean;
+    hasPrev: boolean;
+    hasNext: boolean;
+    /** "3 / 12", or "" when there is no set to count. */
+    counter: string;
+    previous: () => void;
+    next: () => void;
+    handleCancel: (event: SyntheticEvent<HTMLDialogElement>) => void;
+    handleClick: (event: MouseEvent<HTMLDialogElement>) => void;
+}
+/** Marks the stage's empty area: the dialog fills the viewport, so "backdrop" is any click that
+ *  lands on the dialog itself or the stage around the media rather than on a control or the media. */
+export declare const LIGHTBOX_DISMISS_ATTR = "data-jini-lightbox-dismiss";
+export declare function useLightbox(input: LightboxHookInput): LightboxController;
+//# sourceMappingURL=Lightbox.hooks.d.ts.map