@phis/ui 0.3.0 → 0.4.1

package/components/overlays/phi-overlay-container-client.js

@@ -12,6 +12,7 @@ import { emitPhiSignalCapability, usePhiSignalEmitter, PhiSignalIdentityProvider
 import { usePhiSignalListener } from "../runtime/runtime-signal-bus";
 import { registerPhiSignalInstance } from "../runtime/runtime-signal-registry";
 import { usePhiSignalRuntimePartition } from "../runtime/runtime-signal-partition";
+import { usePhiVisualAnchor } from "../runtime/runtime-visual-anchors";
 import { PhiModalControl } from "../controls/phi-modal-control";
 import { PhiDrawerControl } from "../controls/phi-drawer-control";
 import { PhiAlertControl } from "../controls/phi-alert-control";
@@ -72,6 +73,8 @@ export function PhiOverlayContainerClient({ overlayId, overlayType, config: rawC
     const openedAtPathname = useRef(null);
     const pathname = usePhiPathname();
     const emitSignal = usePhiSignalEmitter(receiver);
+    // The Overlay's panel, found by a Tour under the Overlay's own address while it is drawn.
+    const panelRef = usePhiVisualAnchor(receiver);
     const loadZones = usePhiOverlayZonesLoaderIfAny();
     const [loadedZones, setLoadedZones] = useState(null);
     const listenRoutes = useMemo(() => config.signalRoutes?.listens ?? [], [config.signalRoutes?.listens]);
@@ -261,7 +264,7 @@ export function PhiOverlayContainerClient({ overlayId, overlayType, config: rawC
      */
     const surfaceStyle = { ...resolvePhiCmsContainerSurface(config).style, padding: 0 };
     if (overlayType === "drawer") {
-        return (_jsxs(_Fragment, { children: [zoneControllers, _jsx(PhiDrawerControl, { open: open, title: runtimeTitle, header: renderZone(zones?.header), body: renderZone(zones?.body), footer: renderZone(zones?.footer), closable: behaviour.closable, keyboard: behaviour.keyboard, mask: behaviour.mask, mountPolicy: config.mountPolicy, placement: config.placement, size: config.size, maxSize: config.maxSize, resizable: behaviour.resizable, push: behaviour.push, containerStyle: surfaceStyle, onDismiss: requestClose })] }));
+        return (_jsxs(_Fragment, { children: [zoneControllers, _jsx(PhiDrawerControl, { open: open, title: runtimeTitle, header: renderZone(zones?.header), body: renderZone(zones?.body), footer: renderZone(zones?.footer), closable: behaviour.closable, keyboard: behaviour.keyboard, mask: behaviour.mask, mountPolicy: config.mountPolicy, placement: config.placement, size: config.size, maxSize: config.maxSize, resizable: behaviour.resizable, push: behaviour.push, containerStyle: surfaceStyle, onDismiss: requestClose, panelRef: panelRef })] }));
     }
-    return (_jsxs(_Fragment, { children: [zoneControllers, _jsx(PhiModalControl, { open: open, title: runtimeTitle, header: renderZone(zones?.header), body: renderZone(zones?.body == null ? null : _jsx(PhiDialogBodyProvider, { children: zones.body })), footer: renderZone(zones?.footer), closable: behaviour.closable, keyboard: behaviour.keyboard, mask: behaviour.mask, mountPolicy: config.mountPolicy, centered: behaviour.centered, controlSize: runtimeControlSize ?? config.controlSize, size: runtimeSize, width: config.width, containerStyle: surfaceStyle, onDismiss: requestClose })] }));
+    return (_jsxs(_Fragment, { children: [zoneControllers, _jsx(PhiModalControl, { open: open, title: runtimeTitle, header: renderZone(zones?.header), body: renderZone(zones?.body == null ? null : _jsx(PhiDialogBodyProvider, { children: zones.body })), footer: renderZone(zones?.footer), closable: behaviour.closable, keyboard: behaviour.keyboard, mask: behaviour.mask, mountPolicy: config.mountPolicy, centered: behaviour.centered, controlSize: runtimeControlSize ?? config.controlSize, size: runtimeSize, width: config.width, containerStyle: surfaceStyle, onDismiss: requestClose, panelRef: panelRef })] }));
 }

package/components/runtime/runtime-visual-anchors.d.ts

@@ -1,4 +1,4 @@
-import { type PhiVisualAnchorAddress } from "../../types/tours";
+import { type PhiVisualAnchorAddress } from "../../types/visual-anchors";
 import { type PhiSignalRuntimePartition } from "./runtime-signal-partition";
 /**
  * One registration. The element is reached through a getter rather than held as a value, so whoever reads
@@ -16,7 +16,9 @@ export type PhiVisualAnchorEntry = {
 export declare function registerPhiVisualAnchor(partition: PhiSignalRuntimePartition, entry: PhiVisualAnchorEntry): () => void;
 /**
  * The element an address is drawn as, in this partition and nowhere else, or `null` when it is not there
- * to point at: not mounted, mounted twice, detached, or rendered without a box (hidden, `display: none`).
+ * to point at: not mounted, mounted twice, detached, rendered without a box (hidden, `display: none`), or
+ * with a box of no area -- a slot that hides itself because it has nothing to show still lays out at zero
+ * height, and a Tour pointing at it pointed at nothing.
  */
 export declare function readPhiVisualAnchor(partition: PhiSignalRuntimePartition, address: PhiVisualAnchorAddress): HTMLElement | null;
 /**
@@ -28,6 +30,15 @@ export declare function waitForPhiVisualAnchor(partition: PhiSignalRuntimePartit
     timeoutMs: number;
     signal?: AbortSignal;
 }): Promise<HTMLElement | null>;
+/**
+ * Waits until a found target stops moving -- a Drawer sliding in, a slot opening -- and answers whether it
+ * did before `timeoutMs`. Whoever points at a target measures it once: measured mid-motion, the pointer
+ * stays where the target was on its way, off screen for a Drawer that is still coming in.
+ */
+export declare function waitForPhiVisualAnchorToSettle(element: HTMLElement, { timeoutMs, signal }: {
+    timeoutMs: number;
+    signal?: AbortSignal;
+}): Promise<boolean>;
 /**
  * Registers the element a ref lands on as the visual anchor of `address` in the surrounding partition.
  *

package/components/runtime/runtime-visual-anchors.js

@@ -1,6 +1,6 @@
 "use client";
 import { useCallback, useEffect, useRef } from "react";
-import { PHI_VISUAL_ANCHOR_PART_ATTRIBUTE } from "../../types/tours";
+import { PHI_VISUAL_ANCHOR_PART_ATTRIBUTE } from "../../types/visual-anchors";
 import { usePhiSignalRuntimePartition } from "./runtime-signal-partition";
 function notify(partition) {
     for (const subscriber of partition.visualAnchorSubscribers) {
@@ -33,7 +33,9 @@ export function registerPhiVisualAnchor(partition, entry) {
 }
 /**
  * The element an address is drawn as, in this partition and nowhere else, or `null` when it is not there
- * to point at: not mounted, mounted twice, detached, or rendered without a box (hidden, `display: none`).
+ * to point at: not mounted, mounted twice, detached, rendered without a box (hidden, `display: none`), or
+ * with a box of no area -- a slot that hides itself because it has nothing to show still lays out at zero
+ * height, and a Tour pointing at it pointed at nothing.
  */
 export function readPhiVisualAnchor(partition, address) {
     const entries = partition.visualAnchors.get(address);
@@ -41,7 +43,8 @@ export function readPhiVisualAnchor(partition, address) {
     if (!element || !element.isConnected || element.getClientRects().length === 0) {
         return null;
     }
-    return element;
+    const box = element.getBoundingClientRect();
+    return box.width > 0 && box.height > 0 ? element : null;
 }
 /** How often a wait looks again for a target that is registered but not yet laid out. */
 const WAIT_POLL_INTERVAL_MS = 100;
@@ -76,6 +79,49 @@ export function waitForPhiVisualAnchor(partition, address, { timeoutMs, signal }
         signal?.addEventListener("abort", abort, { once: true });
     });
 }
+/**
+ * How many frames in a row a target has to stand still before it counts as placed. More than two: an
+ * opening slot or Drawer often holds still for a frame or two before its motion starts, and measured
+ * then, the pointer is fixed to where it started.
+ */
+const SETTLE_STILL_FRAMES = 8;
+/**
+ * Waits until a found target stops moving -- a Drawer sliding in, a slot opening -- and answers whether it
+ * did before `timeoutMs`. Whoever points at a target measures it once: measured mid-motion, the pointer
+ * stays where the target was on its way, off screen for a Drawer that is still coming in.
+ */
+export function waitForPhiVisualAnchorToSettle(element, { timeoutMs, signal }) {
+    return new Promise((resolve) => {
+        let last = "";
+        let still = 0;
+        let frame = 0;
+        const finish = (settled) => {
+            window.cancelAnimationFrame(frame);
+            window.clearTimeout(timeout);
+            signal?.removeEventListener("abort", abort);
+            resolve(settled);
+        };
+        const abort = () => finish(false);
+        const look = () => {
+            const box = element.getBoundingClientRect();
+            const next = `${box.x},${box.y},${box.width},${box.height}`;
+            still = next === last ? still + 1 : 0;
+            last = next;
+            if (still >= SETTLE_STILL_FRAMES) {
+                finish(true);
+                return;
+            }
+            frame = window.requestAnimationFrame(look);
+        };
+        const timeout = window.setTimeout(() => finish(false), timeoutMs);
+        signal?.addEventListener("abort", abort, { once: true });
+        if (signal?.aborted) {
+            finish(false);
+            return;
+        }
+        frame = window.requestAnimationFrame(look);
+    });
+}
 /**
  * Registers the element a ref lands on as the visual anchor of `address` in the surrounding partition.
  *

package/components/shell/use-phi-shell-sticky-top.d.ts

@@ -0,0 +1,5 @@
+import { type RefObject } from "react";
+export declare function usePhiShellStickyTop({ active, elementRef, }: {
+    active: boolean;
+    elementRef: RefObject<HTMLElement | null>;
+}): void;

package/components/shell/use-phi-shell-sticky-top.js

@@ -0,0 +1,78 @@
+"use client";
+import { useEffect } from "react";
+/**
+ * How far down the viewport the Shell's Header holds right now, published on the Shell.
+ *
+ * Something that sticks to the top of the page -- a Table's header row -- has to stick under the Header
+ * rather than behind it, and where the Header ends is not a constant: each band sticks or scrolls by its
+ * own config, and a revealing `header_top` slides away while the visitor reads down and comes back when
+ * they scroll up. So the edge is measured, not configured: the lowest bottom of every Header band that is
+ * stuck at this moment, written as `--phi-shell-sticky-top` on the Shell element. Unset, a reader falls
+ * back to `0px`, which is right for a Shell without a sticky Header.
+ *
+ * Run by whatever sticks under it -- every sticky Table does -- so a page without one loads nothing for
+ * it. Each runner measures all the bands and they all write the same value. Not inside an Overlay: a
+ * Modal's or Drawer's body scrolls on its own, and its top edge is the line.
+ */
+const PHI_SHELL_STICKY_TOP_PROPERTY = "--phi-shell-sticky-top";
+const HEADER_BANDS = '[data-phi-region-key^="header_"]:not([hidden])';
+function measurePhiShellStickyTop(shell) {
+    let bottom = 0;
+    for (const band of shell.querySelectorAll(HEADER_BANDS)) {
+        const style = window.getComputedStyle(band);
+        if (style.position !== "sticky" && style.position !== "fixed") {
+            continue;
+        }
+        const rect = band.getBoundingClientRect();
+        const stuckAt = Number.parseFloat(style.top) || 0;
+        // Below its sticking line it is still in flow; above the viewport it has slid away.
+        if (rect.height === 0 || rect.top > stuckAt + 1 || rect.bottom <= 0) {
+            continue;
+        }
+        bottom = Math.max(bottom, rect.bottom);
+    }
+    return `${Math.round(bottom)}px`;
+}
+const OVERLAY_BODIES = "[data-phi-modal-body-content], [data-phi-drawer-body-content]";
+export function usePhiShellStickyTop({ active, elementRef, }) {
+    useEffect(() => {
+        const element = elementRef.current;
+        const shell = active && element && !element.closest(OVERLAY_BODIES)
+            ? element.closest("[data-phi-shell-layout]")
+            : null;
+        if (!element || !shell) {
+            return undefined;
+        }
+        let frame = 0;
+        const publish = () => {
+            frame = 0;
+            const next = measurePhiShellStickyTop(shell);
+            if (shell.style.getPropertyValue(PHI_SHELL_STICKY_TOP_PROPERTY) !== next) {
+                shell.style.setProperty(PHI_SHELL_STICKY_TOP_PROPERTY, next);
+            }
+        };
+        const schedule = () => {
+            if (frame === 0) {
+                frame = window.requestAnimationFrame(publish);
+            }
+        };
+        publish();
+        window.addEventListener("scroll", schedule, { passive: true });
+        window.addEventListener("resize", schedule);
+        // A revealing band moves by a transition; its end is where it settled.
+        shell.addEventListener("transitionend", schedule);
+        const observer = new ResizeObserver(schedule);
+        for (const band of shell.querySelectorAll(HEADER_BANDS)) {
+            observer.observe(band);
+        }
+        return () => {
+            if (frame !== 0) {
+                window.cancelAnimationFrame(frame);
+            }
+            window.removeEventListener("scroll", schedule);
+            window.removeEventListener("resize", schedule);
+            shell.removeEventListener("transitionend", schedule);
+            observer.disconnect();
+        };
+    }, [active, elementRef]);
+}

package/components/widgets/config/image-variant-options.d.ts

@@ -1,5 +1,3 @@
-/** The renditions an Asset is offered in, for every field that picks one. */
-export declare const PHI_IMAGE_VARIANT_OPTIONS: {
-    value: string;
-    label: string;
-}[];
+import type { PhiControlOption } from "../../controls/phi-control-options";
+/** The renditions an Asset is offered in, for every field that picks one; stored as the number the key is. */
+export declare const PHI_IMAGE_VARIANT_OPTIONS: PhiControlOption<number>[];

package/components/widgets/config/image-variant-options.js

@@ -1,14 +1,14 @@
 import { PhiImageAssetVariantKey } from "../../../constants/media";
-/** The renditions an Asset is offered in, for every field that picks one. */
+/** The renditions an Asset is offered in, for every field that picks one; stored as the number the key is. */
 export const PHI_IMAGE_VARIANT_OPTIONS = [
-    { value: String(PhiImageAssetVariantKey.Thumbnail), label: "Thumbnail" },
-    { value: String(PhiImageAssetVariantKey.Preview), label: "Preview" },
-    { value: String(PhiImageAssetVariantKey.Banner), label: "Banner" },
-    { value: String(PhiImageAssetVariantKey.Header), label: "Header" },
-    { value: String(PhiImageAssetVariantKey.Card), label: "Card" },
-    { value: String(PhiImageAssetVariantKey.Hero), label: "Hero" },
-    { value: String(PhiImageAssetVariantKey.Avatar), label: "Avatar" },
-    { value: String(PhiImageAssetVariantKey.Logo), label: "Logo" },
-    { value: String(PhiImageAssetVariantKey.Landscape), label: "Landscape" },
-    { value: String(PhiImageAssetVariantKey.Portrait), label: "Portrait" },
+    { value: PhiImageAssetVariantKey.Thumbnail, label: "Thumbnail" },
+    { value: PhiImageAssetVariantKey.Preview, label: "Preview" },
+    { value: PhiImageAssetVariantKey.Banner, label: "Banner" },
+    { value: PhiImageAssetVariantKey.Header, label: "Header" },
+    { value: PhiImageAssetVariantKey.Card, label: "Card" },
+    { value: PhiImageAssetVariantKey.Hero, label: "Hero" },
+    { value: PhiImageAssetVariantKey.Avatar, label: "Avatar" },
+    { value: PhiImageAssetVariantKey.Logo, label: "Logo" },
+    { value: PhiImageAssetVariantKey.Landscape, label: "Landscape" },
+    { value: PhiImageAssetVariantKey.Portrait, label: "Portrait" },
 ];

package/components/widgets/config/sequence-settings.d.ts

@@ -0,0 +1,75 @@
+import { type PhiMotionEasing, type PhiSequenceTransition } from "../../../helpers/motion";
+import { type PhiCmsMountPolicy } from "../../../types/cms-mount-policy";
+import type { PhiCmsConfigField, PhiCmsConfigFieldVisibilityRule } from "../../../types/cms-plugins";
+import { type PhiSpacingScaleKey } from "./spacing-options";
+/**
+ * How a Widget that shows a run of things a few at a time moves through them.
+ *
+ * The Gallery runs through the pictures of a Folder, the Entries list through cards of News or Blog;
+ * what moves differs, how it moves does not. So the settings are one vocabulary with one reader, one
+ * set of Inspector fields and one set of defaults, and `PhiSequenceRun` draws them. The Carousel Layout
+ * asks the same questions under its own older keys (`visibleSlots`, `transitionDurationMs`).
+ *
+ * No window anchor, unlike the Carousel. A run moves a page at a time -- one to three, then four to
+ * six -- and nothing outside it names an item to show; a centred anchor would only shift every page by
+ * one and leave the dots pointing between pages. The window starts at its active item.
+ */
+export declare const PHI_SEQUENCE_CONTROLS: readonly ["none", "arrows", "dots", "both"];
+export type PhiSequenceControls = (typeof PHI_SEQUENCE_CONTROLS)[number];
+export type PhiSequenceSettings = {
+    visibleCount?: number;
+    transition?: PhiSequenceTransition;
+    durationMs?: number;
+    easing?: PhiMotionEasing;
+    /** A step of the spacing scale between the items of a window. */
+    gap?: PhiSpacingScaleKey;
+    /**
+     * How many items beyond the window are kept mounted, and therefore told to load early.
+     *
+     * The browser will not do this for us. `loading="lazy"` decides from an element's distance to the
+     * viewport and knows nothing about a track: on a fade every item sits in the same place and all of
+     * them load at once, while on a slide the next one is off to the side and loads as it arrives --
+     * during the transition, which is the worst moment. Next's escape hatch for that, `lazyRoot`, is a
+     * deprecated no-op. So the window decides, and the window is ours.
+     */
+    lookahead?: number;
+    mountPolicy?: PhiCmsMountPolicy;
+    controls?: PhiSequenceControls;
+    loop?: boolean;
+    /** Absent or zero means it does not move on its own. */
+    autoplayMs?: number;
+};
+/** What a run does where nobody said otherwise, stated so the Inspector shows it as the standing answer. */
+export declare const PHI_SEQUENCE_SETTINGS_DEFAULTS: {
+    readonly visibleCount: 1;
+    readonly transition: "slide";
+    readonly durationMs: 320;
+    readonly easing: "linear" | "ease" | "ease-in" | "ease-out" | "ease-in-out";
+    readonly gap: "xs";
+    readonly lookahead: 1;
+    readonly mountPolicy: "lazy-keep";
+    readonly controls: "both";
+    readonly loop: false;
+    readonly autoplayMs: 0;
+};
+type PhiSequenceSettingsFail = (key: string, value: unknown, expected: string) => never;
+export declare function readPhiSequenceSettings(raw: Record<string, unknown>, fail: PhiSequenceSettingsFail): PhiSequenceSettings;
+/** The run's settings out of a Widget's config, for a client half that needs these and nothing else. */
+export declare function pickPhiSequenceSettings(config: PhiSequenceSettings): PhiSequenceSettings;
+/**
+ * The Inspector's fields for a run, in three groups a Widget places among its own: the window (how many
+ * stand side by side and how far apart), the movement, and the controls.
+ *
+ * `visibleWhen` is added to every field, for a Widget where the run is one presentation among others.
+ * `heading` names the window group; the Gallery leaves it out, its window stands under "Picture".
+ */
+export declare function buildPhiSequenceSettingsFields({ countLabel, heading, visibleWhen, }: {
+    countLabel: string;
+    heading?: string;
+    visibleWhen?: PhiCmsConfigFieldVisibilityRule;
+}): {
+    window: PhiCmsConfigField[];
+    movement: PhiCmsConfigField[];
+    controls: PhiCmsConfigField[];
+};
+export {};

package/components/widgets/config/sequence-settings.js

@@ -0,0 +1,173 @@
+import { PHI_MOTION_EASING_FIELD_OPTIONS, PHI_SEQUENCE_DEFAULT_DURATION_MS, PHI_SEQUENCE_DEFAULT_EASING, PHI_SEQUENCE_TRANSITION_MAX_MS, PHI_SEQUENCE_TRANSITION_MIN_MS, PHI_SEQUENCE_TRANSITION_STEP_MS, PHI_SEQUENCE_TRANSITIONS, clampPhiSequenceTransitionMs, readPhiMotionEasing, } from "../../../helpers/motion";
+import { PHI_CMS_MOUNT_POLICY_FIELD_OPTIONS, readPhiCmsMountPolicy, } from "../../../types/cms-mount-policy";
+import { PHI_SPACING_SCALE_KEYS } from "./spacing-options";
+/**
+ * How a Widget that shows a run of things a few at a time moves through them.
+ *
+ * The Gallery runs through the pictures of a Folder, the Entries list through cards of News or Blog;
+ * what moves differs, how it moves does not. So the settings are one vocabulary with one reader, one
+ * set of Inspector fields and one set of defaults, and `PhiSequenceRun` draws them. The Carousel Layout
+ * asks the same questions under its own older keys (`visibleSlots`, `transitionDurationMs`).
+ *
+ * No window anchor, unlike the Carousel. A run moves a page at a time -- one to three, then four to
+ * six -- and nothing outside it names an item to show; a centred anchor would only shift every page by
+ * one and leave the dots pointing between pages. The window starts at its active item.
+ */
+export const PHI_SEQUENCE_CONTROLS = ["none", "arrows", "dots", "both"];
+/** What a run does where nobody said otherwise, stated so the Inspector shows it as the standing answer. */
+export const PHI_SEQUENCE_SETTINGS_DEFAULTS = {
+    visibleCount: 1,
+    transition: "slide",
+    durationMs: PHI_SEQUENCE_DEFAULT_DURATION_MS,
+    easing: PHI_SEQUENCE_DEFAULT_EASING,
+    gap: "xs",
+    lookahead: 1,
+    mountPolicy: "lazy-keep",
+    controls: "both",
+    loop: false,
+    autoplayMs: 0,
+};
+function readMember(value, members, key, fail) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "string" || !members.includes(value)) {
+        fail(key, value, `one of ${members.join(", ")}`);
+    }
+    return value;
+}
+function readCount(value, key, min, fail) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "number" || !Number.isInteger(value) || value < min) {
+        fail(key, value, `a whole number of at least ${min}`);
+    }
+    return value;
+}
+export function readPhiSequenceSettings(raw, fail) {
+    const visibleCount = readCount(raw.visibleCount, "visibleCount", 1, fail);
+    const transition = readMember(raw.transition, PHI_SEQUENCE_TRANSITIONS, "transition", fail);
+    const easing = readPhiMotionEasing(raw.easing, undefined);
+    const gap = readMember(raw.gap, PHI_SPACING_SCALE_KEYS, "gap", fail);
+    const lookahead = readCount(raw.lookahead, "lookahead", 0, fail);
+    const controls = readMember(raw.controls, PHI_SEQUENCE_CONTROLS, "controls", fail);
+    if (raw.loop !== undefined && raw.loop !== null && typeof raw.loop !== "boolean") {
+        fail("loop", raw.loop, "true or false");
+    }
+    const loop = typeof raw.loop === "boolean" ? raw.loop : undefined;
+    const autoplayMs = readCount(raw.autoplayMs, "autoplayMs", 0, fail);
+    return {
+        ...(visibleCount === undefined ? {} : { visibleCount }),
+        ...(transition === undefined ? {} : { transition }),
+        ...(raw.durationMs === undefined || raw.durationMs === null
+            ? {}
+            : { durationMs: clampPhiSequenceTransitionMs(raw.durationMs) }),
+        ...(easing === undefined ? {} : { easing }),
+        ...(gap === undefined ? {} : { gap }),
+        ...(lookahead === undefined ? {} : { lookahead }),
+        mountPolicy: readPhiCmsMountPolicy(raw.mountPolicy, PHI_SEQUENCE_SETTINGS_DEFAULTS.mountPolicy),
+        ...(controls === undefined ? {} : { controls }),
+        ...(loop === undefined ? {} : { loop }),
+        // Zero is how "does not move on its own" is written, so it is the one number below the floor
+        // that means something.
+        ...(autoplayMs === undefined || autoplayMs === 0
+            ? {}
+            : { autoplayMs: clampPhiSequenceTransitionMs(autoplayMs) }),
+    };
+}
+const PHI_SEQUENCE_SETTINGS_KEYS = Object.keys(PHI_SEQUENCE_SETTINGS_DEFAULTS);
+/** The run's settings out of a Widget's config, for a client half that needs these and nothing else. */
+export function pickPhiSequenceSettings(config) {
+    return Object.fromEntries(PHI_SEQUENCE_SETTINGS_KEYS.filter((key) => config[key] !== undefined).map((key) => [key, config[key]]));
+}
+function withRule(field, rule) {
+    if (!rule)
+        return field;
+    const own = field.visibleWhen == null ? [] : Array.isArray(field.visibleWhen) ? field.visibleWhen : [field.visibleWhen];
+    return { ...field, visibleWhen: [...own, rule] };
+}
+/**
+ * The Inspector's fields for a run, in three groups a Widget places among its own: the window (how many
+ * stand side by side and how far apart), the movement, and the controls.
+ *
+ * `visibleWhen` is added to every field, for a Widget where the run is one presentation among others.
+ * `heading` names the window group; the Gallery leaves it out, its window stands under "Picture".
+ */
+export function buildPhiSequenceSettingsFields({ countLabel, heading, visibleWhen, }) {
+    const window = [
+        { key: "visibleCount", type: "number", label: countLabel, min: 1, ...(heading ? { heading } : {}) },
+        {
+            key: "gap",
+            type: "choice",
+            label: "Gap",
+            options: PHI_SPACING_SCALE_KEYS.map((key) => ({ value: key, label: key })),
+        },
+    ];
+    const movement = [
+        {
+            key: "transition",
+            type: "choice",
+            heading: "Transition",
+            label: "Transition",
+            options: [
+                { value: "none", label: "None" },
+                { value: "fade", label: "Fade" },
+                { value: "slide", label: "Slide" },
+                { value: "diagonal", label: "Diagonal" },
+            ],
+        },
+        {
+            key: "durationMs",
+            type: "number",
+            label: "Duration",
+            min: PHI_SEQUENCE_TRANSITION_MIN_MS,
+            max: PHI_SEQUENCE_TRANSITION_MAX_MS,
+            step: PHI_SEQUENCE_TRANSITION_STEP_MS,
+            prefix: "ms",
+            visibleWhen: { field: "transition", notEquals: "none" },
+        },
+        {
+            key: "easing",
+            type: "choice",
+            label: "Easing",
+            options: [...PHI_MOTION_EASING_FIELD_OPTIONS],
+            visibleWhen: { field: "transition", notEquals: "none" },
+        },
+        {
+            // Zero is the one value below the floor that means something: it does not move on its own.
+            key: "autoplayMs",
+            type: "number",
+            label: "Autoplay",
+            min: 0,
+            max: PHI_SEQUENCE_TRANSITION_MAX_MS,
+            step: PHI_SEQUENCE_TRANSITION_STEP_MS,
+            prefix: "ms",
+        },
+        { key: "lookahead", type: "number", label: "Preload Ahead", min: 0 },
+        {
+            key: "mountPolicy",
+            type: "choice",
+            label: "Mounting",
+            options: [...PHI_CMS_MOUNT_POLICY_FIELD_OPTIONS],
+        },
+    ];
+    const controls = [
+        {
+            key: "controls",
+            type: "choice",
+            heading: "Controls",
+            label: "Controls",
+            options: [
+                { value: "both", label: "Arrows and dots" },
+                { value: "arrows", label: "Arrows" },
+                { value: "dots", label: "Dots" },
+                { value: "none", label: "None" },
+            ],
+        },
+        { key: "loop", type: "boolean", label: "Wrap Around" },
+    ];
+    return {
+        window: window.map((field) => withRule(field, visibleWhen)),
+        movement: movement.map((field) => withRule(field, visibleWhen)),
+        controls: controls.map((field) => withRule(field, visibleWhen)),
+    };
+}

package/components/widgets/helpers/semantic-html-translation.d.ts

@@ -1,2 +1,4 @@
 import "server-only";
-export declare function translateSemanticHtml(sourceHtml: string, sourceLocale?: string): Promise<string>;
+export declare function translateSemanticHtml(sourceHtml: string, sourceLocale?: string, 
+/** The render's locale. Without it the request's is asked, and a static render has no request. */
+locale?: string): Promise<string>;

package/components/widgets/helpers/semantic-html-translation.js

@@ -1,7 +1,7 @@
 import "server-only";
 import renderHtml from "dom-serializer";
 import { parseDocument } from "htmlparser2";
-import { trBulk } from "../../../server-helpers/translate";
+import { trBulk, trBulkForLocale } from "../../../server-helpers/translate";
 import { sanitizePhiHtmlWidgetMarkup } from "./html-content";
 const SEMANTIC_HTML_BLOCKS = new Set([
     "p",
@@ -49,7 +49,9 @@ function renderNodes(nodes) {
 function hasVisibleText(html) {
     return html.replace(/<[^>]+>/g, "").replace(/&nbsp;/g, " ").trim().length > 0;
 }
-export async function translateSemanticHtml(sourceHtml, sourceLocale) {
+export async function translateSemanticHtml(sourceHtml, sourceLocale, 
+/** The render's locale. Without it the request's is asked, and a static render has no request. */
+locale) {
     const sanitized = sanitizePhiHtmlWidgetMarkup(sourceHtml);
     if (!sanitized) {
         return "";
@@ -64,7 +66,10 @@ export async function translateSemanticHtml(sourceHtml, sourceLocale) {
     if (units.length === 0) {
         return sanitized;
     }
-    const translated = await trBulk(units.map((unit) => unit.html), 0, "html", sourceLocale);
+    const msgs = units.map((unit) => unit.html);
+    const translated = locale
+        ? await trBulkForLocale(locale, msgs, 0, "html", sourceLocale)
+        : await trBulk(msgs, 0, "html", sourceLocale);
     units.forEach((unit, index) => {
         const fragment = parseDocument(translated[index] ?? unit.html);
         unit.node.children = fragment.children ?? [];

package/components/widgets/label-sets/content-entries.d.ts

@@ -124,5 +124,14 @@ export declare function getPhiContentEntryReaderLabels(options: PhiGlobalTransla
     unavailable: string;
     readMore: string;
     readEntry: string;
+    sequence: {
+        previous: string;
+        next: string;
+        page: string;
+        pause: string;
+        play: string;
+        region: string;
+        pages: string;
+    };
 }>;
 export type PhiContentEntryReaderLabels = Awaited<ReturnType<typeof getPhiContentEntryReaderLabels>>;

package/components/widgets/label-sets/content-entries.js

@@ -183,6 +183,14 @@ const PHI_CONTENT_ENTRY_READER_LABEL_SET = definePhiLabelSet({
         unavailable: definePhiMessageLabel("The entries could not be loaded just now."),
         read_more: "Read more",
         read_entry: "Read",
+        // A slideshow's buttons and dots, and its name for a screen reader.
+        previous: "Previous",
+        next: "Next",
+        page: definePhiMessageLabel("Show entries %1 to %2"),
+        pause: "Pause",
+        play: "Play",
+        region: "Entries",
+        pages: definePhiMessageLabel("Choose entries"),
     },
 });
 export async function getPhiContentEntryReaderLabels(options) {
@@ -193,5 +201,14 @@ export async function getPhiContentEntryReaderLabels(options) {
         unavailable: labels.unavailable,
         readMore: labels.read_more,
         readEntry: labels.read_entry,
+        sequence: {
+            previous: labels.previous,
+            next: labels.next,
+            page: labels.page,
+            pause: labels.pause,
+            play: labels.play,
+            region: labels.region,
+            pages: labels.pages,
+        },
     };
 }

package/components/widgets/label-types/gallery.d.ts

@@ -1,13 +1,5 @@
-export type PhiGalleryWidgetLabels = {
-    previous: string;
-    next: string;
-    /** `%1` and `%2` are the first and last picture the page shows. */
-    page: string;
-    pause: string;
-    play: string;
-    /** The box's name for a screen reader, which calls it a carousel. */
-    region: string;
-    pages: string;
+import type { PhiSequenceControlLabels } from "./sequence";
+export type PhiGalleryWidgetLabels = PhiSequenceControlLabels & {
     unavailable: string;
 };
 export declare const PHI_GALLERY_WIDGET_DEFAULT_LABELS: PhiGalleryWidgetLabels;

package/components/widgets/label-types/sequence.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The words around a run that moves: its buttons, its dots, and its name for a screen reader.
+ *
+ * Every Widget that draws `PhiSequenceRun` brings them from its own Label Set, because what is being
+ * stepped through is its own -- pictures in a Gallery, entries in a list -- and "Show pictures 1 to 3"
+ * is not a sentence about News.
+ */
+export type PhiSequenceControlLabels = {
+    previous: string;
+    next: string;
+    /** `%1` and `%2` are the first and last item the page shows. */
+    page: string;
+    pause: string;
+    play: string;
+    /** The box's name for a screen reader, which calls it a carousel. */
+    region: string;
+    pages: string;
+};

package/components/widgets/label-types/sequence.js

@@ -0,0 +1 @@
+export {};