@phis/ui 0.3.0 → 0.4.1

package/plugins/runtime-modules/theme/tour.d.ts

@@ -1,34 +1,68 @@
+import type { PhiCmsInstanceId } from "../../../types/cms-instance-id";
+import type { PhiTourStepSignal } from "../../../types/tours";
 /**
  * The Theme workspace's Tour (TODOS.md, "A Tour for the Theme workspace").
  *
- * What the workspace does not say out loud is its first step: a Module's Theme is offered and never
- * taken, so installing a package that ships a look changes nothing until somebody picks it here. The
- * rest is the order a person meets the workspace in.
+ * What the workspace does not say out loud is its first step: the selector picks what a draft starts
+ * from. A Module's Theme is a base to start from, never edited through it, and installing a package
+ * that ships a look changes nothing for the Site. The rest is the order a person meets the workspace in.
  */
 export declare const PHI_THEME_WORKSPACE_TOUR: {
     readonly id: "@phis/ui/modules/theme/workspace";
     readonly version: 1;
     readonly steps: readonly [{
         readonly key: "theme-choice";
-        readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}`;
-        readonly title: "Which theme you are working on";
-        readonly description: "The Site's published theme, its draft, or a theme a Module brings. A Module's theme changes nothing until it is picked here.";
+        readonly target: `cms:${PhiCmsInstanceId}`;
+        readonly title: "What your draft starts from";
+        readonly description: "The Site's published theme, its draft, or a theme a Module brings. Picking one makes it the base of your theme draft; the Module's theme itself stays as it is.";
         readonly placement: "bottom";
     }, {
         readonly key: "theme-parts";
-        readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}`;
-        readonly title: "Colour and style";
-        readonly description: "Switch between the palette and the shapes and type of the theme.";
+        readonly target: `cms:${PhiCmsInstanceId}`;
+        readonly title: "Four parts of the theme";
+        readonly description: "Colour, style, background and brand: each opens its own controls on the left, with the preview beside them.";
         readonly placement: "bottom";
+    }, {
+        readonly key: string;
+        readonly target: `cms:${PhiCmsInstanceId}`;
+        readonly title: string;
+        readonly description: string;
+        readonly placement: "right";
+        readonly prepare: readonly [PhiTourStepSignal];
+        readonly release: readonly [PhiTourStepSignal];
+    }, {
+        readonly key: string;
+        readonly target: `cms:${PhiCmsInstanceId}`;
+        readonly title: string;
+        readonly description: string;
+        readonly placement: "right";
+        readonly prepare: readonly [PhiTourStepSignal];
+        readonly release: readonly [PhiTourStepSignal];
+    }, {
+        readonly key: string;
+        readonly target: `cms:${PhiCmsInstanceId}`;
+        readonly title: string;
+        readonly description: string;
+        readonly placement: "right";
+        readonly prepare: readonly [PhiTourStepSignal];
+        readonly release: readonly [PhiTourStepSignal];
+    }, {
+        readonly key: string;
+        readonly target: `cms:${PhiCmsInstanceId}`;
+        readonly title: string;
+        readonly description: string;
+        readonly placement: "right";
+        readonly prepare: readonly [PhiTourStepSignal];
+        readonly release: readonly [PhiTourStepSignal];
     }, {
         readonly key: "preview-mode";
-        readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}`;
+        readonly target: `cms:${PhiCmsInstanceId}`;
         readonly title: "Light and dark";
         readonly description: "See the theme in either mode. This switches the preview, not the Site.";
         readonly placement: "bottom";
     }, {
         readonly key: "draft-status";
-        readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}`;
+        readonly target: `cms:${PhiCmsInstanceId}`;
         readonly title: "Where your changes stand";
         readonly description: "What you change here is a draft. The Site keeps its published theme until the draft is published.";
         readonly placement: "bottom";

package/plugins/runtime-modules/theme/tour.js

@@ -1,11 +1,38 @@
+import { PHI_CMS_SEQUENTIAL_LAYOUT_SLOTS } from "../../../constants/cms-layout-types";
 import { PHI_THEME_RUNTIME_MODULE_ID } from "./ids";
-import { PHI_THEME_PAGE_WIDGET_IDS } from "./page-ids";
+import { PHI_THEME_PAGE_LAYOUT_IDS, PHI_THEME_PAGE_WIDGET_IDS } from "./page-ids";
+/** Turns the workspace's Stack to one of its four panels, as the Segmented above it does. */
+function showPanel(slot) {
+    return {
+        receiver: `cms:${PHI_THEME_PAGE_LAYOUT_IDS.layoutBrandStack}`,
+        channel: "activeSlotKey",
+        action: "change",
+        valueType: "string",
+        value: PHI_CMS_SEQUENTIAL_LAYOUT_SLOTS[slot].key,
+    };
+}
+/**
+ * One panel of the workspace, pointed at by its controls. The step turns the Stack to the panel and back
+ * to Color when it is left, the panel the workspace opens with; from one panel step to the next both
+ * arrive together, so the Stack simply moves on.
+ */
+function panelStep(key, slot, controls, title, description) {
+    return {
+        key,
+        target: `cms:${controls}`,
+        title,
+        description,
+        placement: "right",
+        prepare: [showPanel(slot)],
+        release: [showPanel(0)],
+    };
+}
 /**
  * The Theme workspace's Tour (TODOS.md, "A Tour for the Theme workspace").
  *
- * What the workspace does not say out loud is its first step: a Module's Theme is offered and never
- * taken, so installing a package that ships a look changes nothing until somebody picks it here. The
- * rest is the order a person meets the workspace in.
+ * What the workspace does not say out loud is its first step: the selector picks what a draft starts
+ * from. A Module's Theme is a base to start from, never edited through it, and installing a package
+ * that ships a look changes nothing for the Site. The rest is the order a person meets the workspace in.
  */
 export const PHI_THEME_WORKSPACE_TOUR = {
     id: `${PHI_THEME_RUNTIME_MODULE_ID}/workspace`,
@@ -14,17 +41,21 @@ export const PHI_THEME_WORKSPACE_TOUR = {
         {
             key: "theme-choice",
             target: `cms:${PHI_THEME_PAGE_WIDGET_IDS.widgetBrandContextSelect}`,
-            title: "Which theme you are working on",
-            description: "The Site's published theme, its draft, or a theme a Module brings. A Module's theme changes nothing until it is picked here.",
+            title: "What your draft starts from",
+            description: "The Site's published theme, its draft, or a theme a Module brings. Picking one makes it the base of your theme draft; the Module's theme itself stays as it is.",
             placement: "bottom",
         },
         {
             key: "theme-parts",
             target: `cms:${PHI_THEME_PAGE_WIDGET_IDS.widgetThemeStackSegmented}`,
-            title: "Colour and style",
-            description: "Switch between the palette and the shapes and type of the theme.",
+            title: "Four parts of the theme",
+            description: "Colour, style, background and brand: each opens its own controls on the left, with the preview beside them.",
             placement: "bottom",
         },
+        panelStep("color", 0, PHI_THEME_PAGE_WIDGET_IDS.widgetBrandThemeControls, "Colour from a few seeds", "A palette is picked whole, or each colour is set on its own. Every colour is a seed: Primary, Info, Success, Warning, Error, Link, the text and the background each grow into the shades for hover, borders and backgrounds, and Custom grows into ten steps of its own."),
+        panelStep("style", 1, PHI_THEME_PAGE_WIDGET_IDS.widgetBrandStyleControls, "Buttons and corners", "A shape sets the corners at once -- square, subtle, rounded or pill -- for buttons and fields alike. Below it the details: the buttons' shadows, the corner radius in three sizes, how tall controls are, and the fonts and their size."),
+        panelStep("background", 2, PHI_THEME_PAGE_WIDGET_IDS.widgetBrandBackgroundControls, "Behind everything", "The root background is one layer behind the whole Site: a colour, a gradient or an image, still or in parallax, with an overlay of colour, pattern or noise on top. The chrome overlay is a second ground the header, the sider and the footer share, and the chrome shadow sets how they cast onto the Page. Each is set for light and dark."),
+        panelStep("brand", 3, PHI_THEME_PAGE_WIDGET_IDS.widgetBrandIdentityControls, "The Site's own marks", "The logo, one per mode, and where a click on it leads; the wordmark, the Site's name in type; and the two short lines the Brand shows beside them."),
         {
             key: "preview-mode",
             target: `cms:${PHI_THEME_PAGE_WIDGET_IDS.widgetBrandPreviewModeSwitch}`,

package/plugins/runtime-modules/tour/controller/address.js

@@ -1,3 +1,3 @@
-import { PHI_TOUR_CONTROLLER_KEY, PHI_TOUR_CONTROLLER_PLUGIN_KEY } from "../../../../types/tours";
-// The Controller's address is the foundation's (`types/tours.ts`): the Tour button, which is Core's, asks it.
+import { PHI_TOUR_CONTROLLER_KEY, PHI_TOUR_CONTROLLER_PLUGIN_KEY } from "../../../../types/tour-controller";
+// The Controller's address is the foundation's (`types/tour-controller.ts`): the Tour button, which is Core's, asks it.
 export const PHI_TOUR_CONTROLLER_TYPE = `${PHI_TOUR_CONTROLLER_PLUGIN_KEY}/${PHI_TOUR_CONTROLLER_KEY}`;

package/plugins/runtime-modules/tour/controller/client.js

@@ -3,16 +3,19 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { PHI_SIGNAL_VALUE_SCHEMAS } from "../../../../types/signals";
 import { PhiTourControl } from "../../../../components/controls/phi-tour-control";
+import { holdPhiTourViewport, releasePhiTourViewport } from "../../../../components/controls/phi-tour-viewport";
 import { createPhiRuntimeControllerClient } from "../../../../components/runtime/runtime-controller-client-factory";
 import { usePhiSignalDispatcher, usePhiSignalListener } from "../../../../components/runtime/runtime-signal-bus";
 import { usePhiSignalRuntimePartition } from "../../../../components/runtime/runtime-signal-partition";
-import { readPhiVisualAnchor, waitForPhiVisualAnchor } from "../../../../components/runtime/runtime-visual-anchors";
+import { readPhiVisualAnchor, waitForPhiVisualAnchor, waitForPhiVisualAnchorToSettle, } from "../../../../components/runtime/runtime-visual-anchors";
 import { fetchPhiUserState, writePhiUserState } from "../../../../components/runtime/user-state-client";
 import { PHI_TOUR_PROGRESS_USER_STATE_KEY } from "../ids";
 import { PHI_TOUR_RUNTIME_CONTROLLER_DEFINITION } from "./definition";
 import { readPhiTourProgress, recordPhiTourProgress, shouldOfferPhiTour, } from "./progress";
 /** How long a step waits for its target before its `ifMissing` decides. */
 const TARGET_WAIT_MS = 4000;
+/** How long a found target may keep moving before it is pointed at where it stands. */
+const TARGET_SETTLE_MS = 1000;
 const PROGRESS_DESCRIPTOR = {
     key: PHI_TOUR_PROGRESS_USER_STATE_KEY,
     shape: "value",
@@ -115,6 +118,31 @@ function PhiTourControllerView({ address, config }) {
      * never pointed at anything but its own address in this partition.
      */
     const step = run ? run.tour.steps[run.index] ?? null : null;
+    const send = useCallback((signals) => {
+        for (const signal of signals ?? []) {
+            dispatchSignal({
+                scope: "area",
+                channel: signal.channel,
+                action: signal.action,
+                value: signal.value ?? null,
+                valueType: signal.valueType,
+                ...(signal.valueSchema ? { valueSchema: signal.valueSchema } : {}),
+                sender: address,
+                receiver: signal.receiver,
+            });
+        }
+    }, [address, dispatchSignal]);
+    /*
+     * The step asked for gets its `prepare` before its target is waited for, and its `release` the moment it
+     * is no longer the one asked for -- the next step, a step passed over, the Tour closed or finished, the
+     * Page left. One effect per step, so every prepare is answered by exactly one release.
+     */
+    useEffect(() => {
+        if (!step)
+            return undefined;
+        send(step.prepare);
+        return () => send(step.release);
+    }, [send, step]);
     // A step centered on purpose has nothing to wait for.
     const presented = run && step?.target == null ? run.index : run?.presented ?? null;
     useEffect(() => {
@@ -122,10 +150,16 @@ function PhiTourControllerView({ address, config }) {
             return undefined;
         const abort = new AbortController();
         void waitForPhiVisualAnchor(partition, step.target, { timeoutMs: TARGET_WAIT_MS, signal: abort.signal })
-            .then((element) => {
+            .then(async (element) => {
             if (abort.signal.aborted)
                 return;
             if (element) {
+                // Pointed at once it stands still: a target a `prepare` just opened is often still moving in.
+                await waitForPhiVisualAnchorToSettle(element, { timeoutMs: TARGET_SETTLE_MS, signal: abort.signal });
+                if (abort.signal.aborted)
+                    return;
+                // Scrolled to below the sticky bands, once the step is presented (`phi-tour-viewport.ts`).
+                holdPhiTourViewport(element);
                 setRun({ ...run, presented: run.index });
                 return;
             }
@@ -136,6 +170,13 @@ function PhiTourControllerView({ address, config }) {
         });
         return () => abort.abort();
     }, [partition, run, step]);
+    // The window's scroll padding is the Tour's only while a Tour runs.
+    const running = run != null;
+    useEffect(() => {
+        if (!running)
+            return undefined;
+        return releasePhiTourViewport;
+    }, [running]);
     const steps = useMemo(() => (run?.tour.steps ?? []).map((definition) => ({
         key: definition.key,
         title: definition.title,

package/plugins/runtime-modules/tour/controller/definition.js

@@ -1,5 +1,6 @@
 import { PHI_SIGNAL_VALUE_SCHEMAS } from "../../../../types/signals";
-import { PHI_PAGE_TOUR_CONFIG_KEY, PHI_PAGE_TOUR_CONTROLLER_FLAG, PHI_TOUR_CONTROLLER_KEY, PHI_TOUR_CONTROLLER_PLUGIN_KEY, readPhiResolvedPageTour, } from "../../../../types/tours";
+import { PHI_TOUR_CONTROLLER_KEY, PHI_TOUR_CONTROLLER_PLUGIN_KEY } from "../../../../types/tour-controller";
+import { PHI_PAGE_TOUR_CONFIG_KEY, PHI_PAGE_TOUR_CONTROLLER_FLAG, readPhiResolvedPageTour, } from "../../../../types/tours";
 /**
  * Runs the Tour of whichever Page is shown (design/TOURS.md).
  *

package/server-helpers/cms-request.js

@@ -320,6 +320,7 @@ export async function resolvePhiCmsRequest({ siteKey, locale, area, path, cookie
         pageTour: routeTour
             ? {
                 definition: routeTour,
+                ownerModuleId: routeBinding.descriptor.ownerModuleId,
                 sourceLocale: catalog.sourceLocaleByModuleId.get(routeBinding.descriptor.ownerModuleId),
             }
             : null,

package/server-helpers/page-tour.d.ts

@@ -1,11 +1,18 @@
 import "server-only";
+import type { PhiRuntimeModuleId } from "../types/cms-module-descriptors";
 import type { PhiResolvedPageTour, PhiTourDefinition } from "../types/tours";
 /**
- * A Page's Tour in the viewer's language: every step's words translated from the owning Module's
- * language, and the step buttons from Core's label set. Addresses and keys are not words and pass through.
+ * A Page's Tour in the viewer's language: every step's words translated, and the step buttons from Core's
+ * label set. Addresses, keys and step signals are not words and pass through.
+ *
+ * Where the words are kept depends on who wrote them. A built-in Tour's text is this package's, the same
+ * on every Site, so it is translated once in the global set. A third-party Module's Tour is translated per
+ * Site from the language that Module writes in, where the Site's own corrections apply. Either way the
+ * Tour's id is the context, so a translator sees which Tour a sentence belongs to.
  */
-export declare function resolvePhiPageTour({ definition, sourceLocale, locale, }: {
+export declare function resolvePhiPageTour({ definition, ownerModuleId, sourceLocale, locale, }: {
     definition: PhiTourDefinition;
+    ownerModuleId: PhiRuntimeModuleId;
     sourceLocale?: string;
     locale: string;
 }): Promise<PhiResolvedPageTour>;

package/server-helpers/page-tour.js

@@ -1,26 +1,39 @@
 import "server-only";
 import { getPhiTourWidgetLabels } from "../components/widgets/label-sets/tour";
+import { PHI_SHARED_PACKAGE_NAME } from "../constants/package";
 import { readPhiServerApiCredentials } from "../helpers/phis-server-credentials";
-import { trForLocale } from "./translate";
+import { trBulkForLocale, trGlobalBulkForLocale } from "./translate";
+/** A Tour this package ships, whose words are the same on every Site. */
+function isPhiBuiltInTour(ownerModuleId) {
+    return ownerModuleId.startsWith(`${PHI_SHARED_PACKAGE_NAME}/`);
+}
 /**
- * A Page's Tour in the viewer's language: every step's words translated from the owning Module's
- * language, and the step buttons from Core's label set. Addresses and keys are not words and pass through.
+ * A Page's Tour in the viewer's language: every step's words translated, and the step buttons from Core's
+ * label set. Addresses, keys and step signals are not words and pass through.
+ *
+ * Where the words are kept depends on who wrote them. A built-in Tour's text is this package's, the same
+ * on every Site, so it is translated once in the global set. A third-party Module's Tour is translated per
+ * Site from the language that Module writes in, where the Site's own corrections apply. Either way the
+ * Tour's id is the context, so a translator sees which Tour a sentence belongs to.
  */
-export async function resolvePhiPageTour({ definition, sourceLocale, locale, }) {
-    const translate = (text) => trForLocale(locale, text, 0, 0, "text", sourceLocale);
+export async function resolvePhiPageTour({ definition, ownerModuleId, sourceLocale, locale, }) {
+    const texts = definition.steps.flatMap((step) => [step.title, step.description ?? ""]);
+    const translate = isPhiBuiltInTour(ownerModuleId)
+        ? trGlobalBulkForLocale(locale, texts, definition.id)
+        : trBulkForLocale(locale, texts, definition.id, "text", sourceLocale);
     const credentials = readPhiServerApiCredentials();
-    const [labels, steps] = await Promise.all([
+    const [labels, translated] = await Promise.all([
         getPhiTourWidgetLabels({ apiBaseUrl: credentials.apiBaseUrl, internalToken: credentials.internalToken, locale }),
-        Promise.all(definition.steps.map(async (step) => ({
-            ...step,
-            title: await translate(step.title),
-            ...(step.description ? { description: await translate(step.description) } : {}),
-        }))),
+        translate,
     ]);
     return {
         id: definition.id,
         version: definition.version,
-        steps,
+        steps: definition.steps.map((step, index) => ({
+            ...step,
+            title: translated[index * 2] ?? step.title,
+            ...(step.description ? { description: translated[index * 2 + 1] ?? step.description } : {}),
+        })),
         labels: { next: labels.next, previous: labels.previous, finish: labels.finish },
     };
 }

package/server-helpers/translate.d.ts

@@ -1,10 +1,19 @@
 import "server-only";
 import { type PhiTranslationParams } from "../helpers/translation-format";
 import { PHI_TR_CTX_WEB_UI_LABEL, type PhiTranslationFormat } from "../gateway/tr";
+import { type PhiTextSource } from "../helpers/text-source";
 export { PHI_TR_CTX_WEB_UI_LABEL };
 export type { PhiTranslationParams } from "../helpers/translation-format";
 export declare function tr(msg: string, params?: PhiTranslationParams, ctx?: string | number, format?: PhiTranslationFormat): Promise<string>;
 export declare function trGlobal(msg: string, params?: PhiTranslationParams, ctx?: string | number, format?: PhiTranslationFormat): Promise<string>;
+/**
+ * A text Widget's own words in the render's locale, from the store their source names.
+ *
+ * `textSource: "preset"` is a Preset's sentence and the platform's, so the global store answers it;
+ * anything else an author wrote and the Site's store does (`helpers/text-source.ts`). The locale is the
+ * render's where there is one: a static render has no request to read it from.
+ */
+export declare function trWidgetText(locale: string | undefined, msg: string, textSource: PhiTextSource | undefined): Promise<string>;
 export declare function trForLocale(localeInput: string, msg: string, params?: PhiTranslationParams, ctx?: string | number, format?: PhiTranslationFormat, 
 /** The language `msg` is written in, when it is not the Site's own -- a Module's text. */
 sourceLocale?: string): Promise<string>;

package/server-helpers/translate.js

@@ -6,6 +6,7 @@ import { PHI_TR_CTX_WEB_UI_LABEL, trBulk as requestInternalTranslationBulk, tr a
 import { getPhiRequestRuntime } from "./request-runtime";
 import { resolvePhiRequestLocale } from "./request-locale";
 import { readPhiServerApiCredentials } from "../helpers/phis-server-credentials";
+import { PHI_TEXT_SOURCE_PRESET } from "../helpers/text-source";
 export { PHI_TR_CTX_WEB_UI_LABEL };
 function buildTranslatorOptions(locale, sourceLocale) {
     const requestRuntime = getPhiRequestRuntime();
@@ -46,6 +47,19 @@ export async function trGlobal(msg, params = 0, ctx = 0, format = "text") {
     const locale = await resolvePhiRequestLocale();
     return trGlobalForLocale(locale, msg, params, ctx, format);
 }
+/**
+ * A text Widget's own words in the render's locale, from the store their source names.
+ *
+ * `textSource: "preset"` is a Preset's sentence and the platform's, so the global store answers it;
+ * anything else an author wrote and the Site's store does (`helpers/text-source.ts`). The locale is the
+ * render's where there is one: a static render has no request to read it from.
+ */
+export async function trWidgetText(locale, msg, textSource) {
+    if (textSource === PHI_TEXT_SOURCE_PRESET) {
+        return locale ? trGlobalForLocale(locale, msg) : trGlobal(msg);
+    }
+    return locale ? trForLocale(locale, msg) : tr(msg);
+}
 /**
  * Trimmed, one per message and in order: an empty message stays in its place, and `trBulk` answers it
  * with an empty text, so every answer lines up with the message it belongs to.

package/styles/controls.css

@@ -492,10 +492,24 @@ h5.phi-typography, .phi-typography h5 {
  * as a Table closed with one instead of with a footer. Clipping the Table is what both cases want, which
  * is why the rule names neither.
  */
+/*
+ * A sticky header row sticks under the Shell's Header, which publishes where it ends right now
+ * (`components/shell/use-phi-shell-sticky-top.ts`), and at the top edge of an Overlay's body,
+ * which scrolls on its own. Ant Design writes the offset inline, so the position is stated over it.
+ */
+.phi-table-control.phi-table-control--sticky-header [class~="ant-table-sticky-holder"] {
+  top: var(--phi-table-sticky-top, var(--phi-shell-sticky-top, 0px)) !important;
+}
+
+:is([data-phi-modal-body-content], [data-phi-drawer-body-content]) {
+  --phi-table-sticky-top: 0px;
+}
+
 .phi-table-control.phi-table-control--closing-block [class~="ant-table"] {
   border-end-start-radius: var(--phi-surface-radius, var(--ant-border-radius-lg));
   border-end-end-radius: var(--phi-surface-radius, var(--ant-border-radius-lg));
-  overflow: hidden;
+  /* `clip`, not `hidden`, so the corners are cut without making this the sticky header's scroller. */
+  overflow: clip;
 }
 
 /*

package/styles/root.css

@@ -114,29 +114,30 @@ samp {
   animation-timing-function: var(--phi-effects-animation-easing, ease-out);
 }
 
-:where([data-phi-renderable-block="true"][data-phi-effects-transition="composite"][data-phi-effects-trigger="on_visible"]) {
-  animation-composition: var(--phi-effects-animation-composition, replace);
-  animation-delay: var(--phi-effects-animation-delay, 0ms);
-  animation-duration: var(--phi-effects-animation-duration, 1000ms);
-  animation-name: var(--phi-effects-animation-name);
-  animation-play-state: paused;
-  animation-timing-function: var(--phi-effects-animation-easing, ease-out);
-}
-
-:where([data-phi-renderable-block="true"][data-phi-effects-transition="composite"][data-phi-effects-trigger="on_visible"][data-phi-effects-state="running"]) {
-  animation-play-state: running;
-}
-
 /*
- * On ready, the whole rule inside the query that asks whether anything can release it.
+ * On visible and on ready, the whole rule inside the query that asks whether anything can release it.
  *
- * The animation is held at its first frame until the page has finished arriving, so a Widget whose
- * content the server streams in a segment of its own can land, and everything below it can settle,
- * behind an entrance that has not started. Only scripting sets the state that releases it; where there
- * is none the Block would stand at that first frame for good, which for a fade in means invisible. So
- * without scripting there is no animation at all and the Block is simply there.
+ * The animation is held at its first frame -- until the Block is scrolled into view, or until the page
+ * has finished arriving, so a Widget whose content the server streams in a segment of its own can land,
+ * and everything below it can settle, behind an entrance that has not started. Only scripting sets the
+ * state that releases it; where there is none the Block would stand at that first frame for good, which
+ * for a fade in means invisible. So without scripting there is no animation at all and the Block is
+ * simply there.
  */
 @media (scripting: enabled) {
+  :where([data-phi-renderable-block="true"][data-phi-effects-transition="composite"][data-phi-effects-trigger="on_visible"]) {
+    animation-composition: var(--phi-effects-animation-composition, replace);
+    animation-delay: var(--phi-effects-animation-delay, 0ms);
+    animation-duration: var(--phi-effects-animation-duration, 1000ms);
+    animation-name: var(--phi-effects-animation-name);
+    animation-play-state: paused;
+    animation-timing-function: var(--phi-effects-animation-easing, ease-out);
+  }
+
+  :where([data-phi-renderable-block="true"][data-phi-effects-transition="composite"][data-phi-effects-trigger="on_visible"][data-phi-effects-state="running"]) {
+    animation-play-state: running;
+  }
+
   :where([data-phi-renderable-block="true"][data-phi-effects-transition="composite"][data-phi-effects-trigger="on_ready"]) {
     animation-composition: var(--phi-effects-animation-composition, replace);
     animation-delay: var(--phi-effects-animation-delay, 0ms);

package/types/cms-config.d.ts

@@ -6,6 +6,7 @@ import { type PhiCssLength } from "./length";
 import type { PhiResponsiveValue } from "./responsive";
 import type { PhiRenderableBlockBase, PhiRenderableBlockAnchor, PhiRenderableBlockResponsiveSize } from "./renderable-block";
 import type { PhiBaseLayoutSlotStates } from "../components/layouts/phi-layout-contract";
+import { type PhiSpacingScaleKey } from "../components/widgets/config/spacing-options";
 export type PhiCmsPluginConfigBase = Record<string, unknown>;
 export type PhiCmsRenderableBlockConfigBase = PhiCmsPluginConfigBase & PhiRenderableBlockBase;
 export type PhiCmsLayerBase = PhiCmsRenderableBlockConfigBase & {
@@ -120,7 +121,8 @@ export type PhiCmsCarouselLayoutConfig = PhiCmsLayerBase & {
     transition?: PhiSequenceTransition;
     transitionDurationMs?: number;
     transitionEasing?: PhiMotionEasing;
-    slotGap?: string;
+    /** A step of the spacing scale between the slots of a window. */
+    slotGap?: PhiSpacingScaleKey;
     /** Which of its own controls the Carousel draws. Pager Widgets work regardless of this. */
     controls?: "none" | "arrows" | "dots" | "both";
     loop?: boolean;

package/types/cms-config.js

@@ -9,6 +9,7 @@ import { applyPhiLayoutDefaults } from "../helpers/cms-layout-defaults";
 import { resolvePhiLayoutDefaults } from "../helpers/cms-layout-defaults";
 import { normalizeRenderableBlockAnchor } from "../helpers/renderable-block-anchor";
 import { isPhiRecord } from "../helpers/is-record";
+import { PHI_SPACING_SCALE_KEYS } from "../components/widgets/config/spacing-options";
 import { PHI_GRID_COLUMN_COUNTS, isPhiGridColumnCount } from "../constants/grid-columns";
 function readInitialSlotStates(value) {
     if (Array.isArray(value)) {
@@ -334,6 +335,7 @@ export function parsePhiCmsCarouselLayoutConfig(config) {
     const loop = readCarouselFlag(config.loop, "loop");
     const autoplayMs = readCarouselCount(config.autoplayMs, "autoplayMs", 0);
     const lookahead = readCarouselCount(config.lookahead, "lookahead", 0);
+    const slotGap = readCarouselMember(config.slotGap, PHI_SPACING_SCALE_KEYS, "slotGap");
     return applyPhiLayoutDefaults({
         ...readRenderableBlockConfig(config),
         labelEnd: readPhiLayoutLabelEnd(config.labelEnd),
@@ -342,15 +344,13 @@ export function parsePhiCmsCarouselLayoutConfig(config) {
         ...(visibleSlots === undefined ? {} : { visibleSlots }),
         ...(windowAnchor === undefined ? {} : { windowAnchor }),
         ...(transition === undefined ? {} : { transition }),
-        // Absent means "whatever the theme does", which is why nothing is written here rather than a
-        // number this parser invented.
         ...(config.transitionDurationMs === undefined || config.transitionDurationMs === null ? {} : {
             transitionDurationMs: clampPhiSequenceTransitionMs(config.transitionDurationMs),
         }),
         ...(config.transitionEasing === undefined ? {} : {
             transitionEasing: readPhiMotionEasing(config.transitionEasing, undefined),
         }),
-        slotGap: readString(config.slotGap),
+        ...(slotGap === undefined ? {} : { slotGap }),
         ...(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

package/types/cms-plugins.d.ts

@@ -93,7 +93,12 @@ export type PhiCmsConfigFieldChoicePresentation = "select" | "segmented" | "tabs
  */
 export type PhiCmsConfigFieldCollectionPresentation = "inline" | "overlay" | "select";
 export type PhiCmsConfigFieldChoiceMode = "single" | "multiple";
-export type PhiCmsConfigFieldChoiceValueType = "string" | "string[]";
+/**
+ * What a `choice` stores. A text or a list of texts is the rule; `number` is a closed list of numbers --
+ * a key that is a number everywhere else, in the parser, the URL and the contracts, as the Image's
+ * Variant is -- and is stored as that number rather than spelled as a text the reader has to convert.
+ */
+export type PhiCmsConfigFieldChoiceValueType = "string" | "string[]" | "number";
 export type PhiCmsConfigFieldChoiceCreateBehavior = "none" | "accept-custom" | "create-record";
 export type PhiCmsConfigFieldColorMode = "single" | "gradient" | "both";
 export type PhiCmsConfigFieldValueStorage = "field" | "self";
@@ -135,6 +140,12 @@ export type PhiCmsConfigField = (PhiCmsConfigFieldBase & {
 }) | (PhiCmsConfigFieldBase & {
     type: "data-provider";
     providerKind?: PhiRuntimeDataProviderKind;
+    /**
+     * The one record Provider this binding names, for a Widget that can only read one: a Gallery
+     * reads a Folder, an entry header an entry. The Inspector then offers no choice of Provider -- a list
+     * that holds a single right answer and several wrong ones -- and asks only for its parameters.
+     */
+    providerKey?: PhiRuntimeDataProviderKey;
 }) | (PhiCmsConfigFieldBase & {
     type: "calendar-adapter";
 }) | (PhiCmsConfigFieldBase & {
@@ -235,10 +246,25 @@ export type PhiCmsConfigField = (PhiCmsConfigFieldBase & {
      */
     presentation?: "slider";
     suffix?: string;
+}) | (PhiCmsConfigFieldBase & {
+    type: "choice";
+    valueType: "number";
+    options: PhiControlOption<number>[];
+    emptyOption?: PhiControlOption;
+    emptyValue?: null | undefined;
+    placeholder?: string;
+    mode?: never;
+    presentation?: never;
+    optionsProvider?: never;
+    allowCustom?: never;
+    createBehavior?: never;
+    filter?: never;
+    patchOnChange?: never;
+    optionPresets?: never;
 }) | (PhiCmsConfigFieldBase & {
     type: "choice";
     mode?: PhiCmsConfigFieldChoiceMode;
-    valueType?: PhiCmsConfigFieldChoiceValueType;
+    valueType?: Exclude<PhiCmsConfigFieldChoiceValueType, "number">;
     presentation?: PhiCmsConfigFieldChoicePresentation;
     options?: PhiControlOption[];
     optionsProvider?: PhiControlOptionsProviderConfig;
@@ -635,11 +661,12 @@ export type PhiResolvedCmsRequest = {
     runtime: PhiBlockRuntime;
     serverCapabilities: import("./server-capabilities").PhiCapabilitySnapshot | null;
     /**
-     * The Tour the Page's route carries, untranslated, with the language its owning Module writes in.
-     * Translated only where the Area has a Controller to hand it to (types/tours.ts).
+     * The Tour the Page's route carries, untranslated, with the Module that owns it and the language that
+     * Module writes in. Translated only where the Area has a Controller to hand it to (types/tours.ts).
      */
     pageTour?: {
         definition: import("./tours").PhiTourDefinition;
+        ownerModuleId: PhiRuntimeModuleId;
         sourceLocale?: string;
     } | null;
 };

package/types/core-widget-placements.d.ts

@@ -1,5 +1,6 @@
 import type { PhiBulletListEntry, PhiBulletListStyle } from "../components/widgets/shared/bullet-list-vocabulary";
 import type { PhiRenderableBlockBase } from "./renderable-block";
+import type { PhiTextSource } from "../helpers/text-source";
 import type { PhiRuntimeConditionExpression } from "./runtime-condition";
 import type { PhiSignalRoute, PhiSignalValue } from "./signals";
 import type { PhiCssLength } from "./length";
@@ -71,6 +72,8 @@ export type PhiSimpleTextWidgetPlacement = PhiWidgetPlacementBase & {
     tone?: PhiTextTone;
     marks?: PhiSimpleTextMark[];
     disabled?: boolean;
+    /** `"preset"` while the words are a Preset's (`helpers/text-source.ts`). */
+    textSource?: PhiTextSource;
 };
 export type PhiDescriptionWidgetPlacement = PhiWidgetPlacementBase & {
     eyebrow?: string;
@@ -81,6 +84,8 @@ export type PhiDescriptionWidgetPlacement = PhiWidgetPlacementBase & {
     asideList?: PhiBulletListStyle;
     footer?: string;
     tone?: PhiTextTone;
+    /** `"preset"` while the words are a Preset's (`helpers/text-source.ts`). */
+    textSource?: PhiTextSource;
 };
 export type PhiButtonWidgetPlacement = PhiWidgetPlacementBase & PhiControlPlacement & PhiControlBadgeConfig & {
     action?: PhiCommonControlActionKey;

package/types/table-widget.d.ts

@@ -306,6 +306,8 @@ export type PhiTableWidgetPresentation = PhiControlPresentationConfig & {
     borders?: boolean;
     /** The header row; shown unless this says `false`. */
     header?: boolean;
+    /** Whether the header row stays at the top while the rows scroll under it; on unless this says `false`. */
+    stickyHeader?: boolean;
     footer?: PhiTableFooterConfig;
     summary?: PhiTableSummaryConfig;
     row?: {

package/types/tour-controller.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Where a Tour is asked for: the Tour Controller of the Area, which the Tour Module mounts.
+ *
+ * Here, in the foundation, rather than in that Module: the Tour button is Core's, so any Area -- and any
+ * Module's own Page -- can place it without depending on the Tour Module. With the Module off nobody
+ * answers at this address, and the button, never told that a Tour is there, stays hidden.
+ */
+export declare const PHI_TOUR_CONTROLLER_PLUGIN_KEY = "@phis/ui/modules/tour/controller";
+export declare const PHI_TOUR_CONTROLLER_KEY = "default";
+export declare const PHI_TOUR_CONTROLLER_ADDRESS: `controller:${string}/${string}:${string}`;