@phis/ui 0.3.0 → 0.4.0

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

@@ -0,0 +1,337 @@
+import { PHI_SIGNAL_VALUE_SCHEMAS } from "../../../types/signals";
+import { PhiCmsRegionType } from "../../../constants/phi-cms";
+import { createPhiPresetCmsInstanceId, createPhiPresetCmsInstanceIdMap, } from "../../../types/cms-instance-id";
+import { PHI_BUILDER_AREA_SETTINGS_WIDGET_IDS } from "./addresses";
+import { PHI_BUILDER_RUNTIME_MODULE_ID } from "./ids";
+import { createPhiBuilderControllerAddress } from "./controller/address";
+import { PHI_BUILDER_INSPECTOR_LAYOUT_IDS, PHI_BUILDER_INSPECTOR_OVERLAY_IDS, PHI_BUILDER_INSPECTOR_SECTION_WIDGET_IDS, } from "./inspector-overlay-addresses";
+/*
+ * The ids the workspace tree hands its nodes once it is remapped to the route's preset
+ * (`remapBuilderPresetTreeInstanceIds`): the same Module, domain and node keys, under the Page's preset
+ * key.
+ */
+function builderWorkspaceWidgetIds(presetKey) {
+    return createPhiPresetCmsInstanceIdMap({
+        domain: "area",
+        ownerModuleId: PHI_BUILDER_RUNTIME_MODULE_ID,
+        presetKey,
+    }, [
+        "widgetBuilderModeSwitch",
+        "widgetToolbar",
+        "widgetDraftStatus",
+        "widgetCanvas",
+        "widgetStructureSiderFullHeightSwitch",
+        "widgetPagesHeaderSelector",
+        "widgetPagesMetaToolbar",
+        "widgetNavigationSource",
+        "widgetNavigationItems",
+    ]);
+}
+/*
+ * The Area selector stands in the Builder's Shell and keeps the Shell's own id. A Page Tour does not make a
+ * Shell frame live; this one is found because its signal routes make it live already.
+ */
+const AREA_SELECTOR_ID = createPhiPresetCmsInstanceId({
+    domain: "area",
+    ownerModuleId: PHI_BUILDER_RUNTIME_MODULE_ID,
+    presetKey: "builder-area-preset",
+    nodeKey: "widgetBuilderAreaSelector",
+});
+/**
+ * Clicking a region, then what that click opens. The second step selects the region the first one pointed
+ * at, the way the click does -- through the Builder Controller's `selection` -- so its Inspector is open
+ * while it is described, and puts the Inspector away again when the step is left.
+ */
+function inspectorSteps(canvasId, regionKey, regionType) {
+    return [
+        {
+            key: "select",
+            target: `cms:${canvasId}:${regionKey}`,
+            title: "Setting something up",
+            description: "A click on a region, a Layout or a Widget opens its Inspector, where everything about it is set up.",
+            placement: "bottom",
+        },
+        {
+            key: "inspector",
+            target: `cms:${PHI_BUILDER_INSPECTOR_OVERLAY_IDS.regionInspector}`,
+            title: "The Inspector",
+            description: "For a region: its size and whether it stays put while the Page scrolls, the screens and the Pages it shows on, its spacing and its surface. A Layout and a Widget open an Inspector of their own, with their settings and the signals they send and hear. A change shows on the canvas at once and is part of the draft.",
+            placement: "left",
+            prepare: [{
+                    receiver: createPhiBuilderControllerAddress(),
+                    channel: "selection",
+                    action: "change",
+                    valueType: "json",
+                    valueSchema: PHI_SIGNAL_VALUE_SCHEMAS.builderNodeSelection,
+                    value: { nodeKind: "region", nodeKey: `region:${regionKey}`, regionKey, regionType },
+                }],
+            release: [INSPECTOR_CLOSE],
+        },
+    ];
+}
+const INSPECTOR_CLOSE = {
+    receiver: createPhiBuilderControllerAddress(),
+    channel: "inspectorVisibility",
+    action: "change",
+    valueType: "boolean",
+    value: false,
+};
+/**
+ * The Layout Inspector, section by section. Each step selects the Region's root Layout -- by the Region,
+ * since a Site's node ids are not known here -- and opens its section of the Inspector; it closes the
+ * Inspector when left. From one step to the next the close and the selection arrive together, so the
+ * Inspector stays open and only the section changes. A Region without a Layout opens nothing, and the
+ * steps are passed over.
+ *
+ * The slot keys follow the order of the Layout Inspector's sections in
+ * `trees/phi-builder-inspector-area-overlay-tree.server.ts`.
+ */
+function layoutInspectorSteps(regionKey) {
+    const selectLayout = {
+        receiver: createPhiBuilderControllerAddress(),
+        channel: "selection",
+        action: "change",
+        valueType: "json",
+        valueSchema: PHI_SIGNAL_VALUE_SCHEMAS.builderNodeSelection,
+        value: { nodeKind: "layout", nodeKey: "layout", regionKey },
+    };
+    const openSection = (slotKey) => ({
+        receiver: `cms:${PHI_BUILDER_INSPECTOR_LAYOUT_IDS.layoutInspectorBody}`,
+        channel: "slot",
+        action: "open",
+        valueType: "string",
+        value: slotKey,
+    });
+    const step = (key, target, slotKey, title, description) => ({
+        key,
+        target: `cms:${target}`,
+        title,
+        description,
+        placement: "left",
+        ifMissing: "skip",
+        prepare: [selectLayout, openSection(slotKey)],
+        // Back to the section the Inspector opens with, so the next click finds it as it always does.
+        release: [INSPECTOR_CLOSE, openSection("slot_0")],
+    });
+    const ids = PHI_BUILDER_INSPECTOR_SECTION_WIDGET_IDS;
+    return [
+        /*
+         * The whole Inspector rather than its Settings section: a kind that declares no settings hides the
+         * section, and a step waiting for it would hold the Tour until its wait runs out.
+         */
+        step("layout-settings", PHI_BUILDER_INSPECTOR_OVERLAY_IDS.layoutInspector, "slot_0", "What only this Layout has", "A Layout's Inspector starts with the settings of its kind: the columns of a grid, the direction and the gaps of a row, the slides of a carousel. A kind without settings of its own starts with the anchor. Every kind of Layout and Widget brings its own."),
+        step("layout-anchor", ids.layoutAnchor, "slot_1", "Where it sits", "The anchor aligns the Layout in the space it is given: to an edge, to a corner, or in the middle."),
+        step("layout-padding", ids.layoutPadding, "slot_2", "Room inside", "Besides the paddings at its edges, the Layout has a gap in the middle: the space between the things that stand in it, side by side or one below the other. One value keeps them all the same distance apart."),
+        step("layout-viewport", ids.layoutViewport, "slot_3", "On which screens", "Whether the Layout shows on compact, medium and wide screens -- hidden on one, it is still there on the others."),
+        step("layout-surface", ids.layoutSurface, "slot_4", "What it stands on", "The surface is what the Layout stands on: none, one of the Theme's styles -- Card or Wash -- or Custom, which opens its background (a colour or an image), its border and its shadow. Mode draws it in the Page's colours, always light, always dark, or the other way round. A region has one as well; a Widget usually stands on its Layout's."),
+        step("layout-signals", ids.layoutSignals, "slot_5", "What it says and hears", "Signals connect the Layout with other parts of the Page: what it sends when something happens in it, and what it answers to -- a button that opens a slot, a list that follows a choice."),
+    ];
+}
+const SHELLS_IDS = builderWorkspaceWidgetIds("builder-shells-page");
+const PAGES_IDS = builderWorkspaceWidgetIds("builder-pages-page");
+/**
+ * The Shells workspace's Tour. What the workspace does not say is what a Shell is: the frame every Page
+ * of the Area stands in, so a change here reaches all of them at once. The rest is the order a person
+ * meets the workspace in, ending where the work goes live. The canvas steps point at single Regions
+ * (`cms:<canvas>:<regionKey>`): the canvas is taller than the window, and pointing at all of it scrolled
+ * it under the Builder's header and lit the header up with it.
+ */
+export const PHI_BUILDER_SHELLS_TOUR = {
+    id: `${PHI_BUILDER_RUNTIME_MODULE_ID}/shells`,
+    version: 1,
+    steps: [
+        {
+            key: "area",
+            target: `cms:${AREA_SELECTOR_ID}`,
+            title: "Which Area you are building",
+            description: "Every Area has its own Shell, and everything in this workspace applies to the Area chosen here. Usually only Public and App are worked on; the other Areas come as their Modules build them.",
+            placement: "bottom",
+            ifMissing: "skip",
+        },
+        {
+            key: "shell",
+            target: `cms:${SHELLS_IDS.widgetCanvas}:header_main`,
+            title: "The frame of every Page",
+            description: "The Shell is what every Page of the Area shares: the rows of the header, the left sider and the footer. What you change here appears on all of them.",
+            placement: "bottom",
+        },
+        {
+            key: "regions",
+            target: `cms:${SHELLS_IDS.widgetCanvas}:sider_left`,
+            title: "Regions and what stands in them",
+            description: "A region holds only Layouts, and a Layout holds further Layouts or Widgets, so the first thing placed in an empty region is always a Layout.",
+            placement: "right",
+        },
+        ...inspectorSteps(SHELLS_IDS.widgetCanvas, "header_top", PhiCmsRegionType.HeaderTop),
+        ...layoutInspectorSteps("header_top"),
+        {
+            key: "mode",
+            target: `cms:${SHELLS_IDS.widgetBuilderModeSwitch}`,
+            title: "Editor and Preview",
+            description: "Editor shows the regions to work in. Preview gives a first impression of your changes without saving them -- a sketch, not exactly what a visitor will see.",
+            placement: "bottom",
+        },
+        {
+            key: "sider",
+            target: `cms:${SHELLS_IDS.widgetStructureSiderFullHeightSwitch}`,
+            title: "How tall the sider is",
+            description: "Whether the left sider runs the full height of the Shell, or stands beside the content between header and footer.",
+            placement: "bottom",
+            ifMissing: "skip",
+        },
+        {
+            key: "area-settings",
+            target: `cms:${PHI_BUILDER_AREA_SETTINGS_WIDGET_IDS.areaSettingsAction}`,
+            title: "What the Area says about itself",
+            description: "What the Area's own address shows, how Page titles are built, and for the public Area whether search engines may find it.",
+            placement: "bottom",
+        },
+        {
+            key: "commands",
+            target: `cms:${SHELLS_IDS.widgetToolbar}`,
+            title: "Saving and publishing",
+            description: "Save keeps your changes as a draft, and Live preview opens the Area with it. Publish puts the Shell live on every Page; publishing takes the Publisher role. Undo and Redo step through your changes, and Reset discards the draft without touching what is live.",
+            placement: "bottom",
+        },
+        {
+            key: "draft-status",
+            target: `cms:${SHELLS_IDS.widgetDraftStatus}`,
+            title: "Where your changes stand",
+            description: "What you change here is a draft. Visitors see the published Shell until the draft is published.",
+            placement: "bottom",
+        },
+    ],
+};
+/**
+ * The Pages workspace's Tour. Its first point is the split with Shells: a Page owns its own regions, and
+ * the frame around them is not edited here. A new or deleted Page is a draft like any other change.
+ */
+export const PHI_BUILDER_PAGES_TOUR = {
+    id: `${PHI_BUILDER_RUNTIME_MODULE_ID}/pages`,
+    version: 1,
+    steps: [
+        {
+            key: "area",
+            target: `cms:${AREA_SELECTOR_ID}`,
+            title: "Which Area you are building",
+            description: "Every Area has its own Pages, and the Page list below holds those of the Area chosen here. Usually only Public and App are worked on; the other Areas come as their Modules build them.",
+            placement: "bottom",
+            ifMissing: "skip",
+        },
+        {
+            key: "page-choice",
+            target: `cms:${PAGES_IDS.widgetPagesHeaderSelector}`,
+            title: "Which Page you are building",
+            description: "Every Page of the Area, the ones created here and the ones a Module brings.",
+            placement: "bottom",
+        },
+        {
+            key: "page",
+            target: `cms:${PAGES_IDS.widgetCanvas}:content`,
+            title: "What belongs to this Page",
+            description: "The content, the hero, the row under the header, the right sider, the row above the footer and the drawer are this Page's alone. The frame around them is the Shell, edited under Shells.",
+            placement: "top",
+        },
+        {
+            key: "regions",
+            target: `cms:${PAGES_IDS.widgetCanvas}:hero`,
+            title: "Regions and what stands in them",
+            description: "A region holds only Layouts, and a Layout holds further Layouts or Widgets, so the first thing placed in an empty region is always a Layout.",
+            placement: "bottom",
+        },
+        ...inspectorSteps(PAGES_IDS.widgetCanvas, "header_bottom", PhiCmsRegionType.HeaderBottom),
+        ...layoutInspectorSteps("content"),
+        {
+            key: "page-commands",
+            target: `cms:${PAGES_IDS.widgetPagesMetaToolbar}`,
+            title: "New Pages and what a Page says",
+            description: "New page creates one in this Area. Page meta sets its title, its description and whether search engines may find it. Delete takes the Page away once the change is published.",
+            placement: "bottom",
+        },
+        {
+            key: "mode",
+            target: `cms:${PAGES_IDS.widgetBuilderModeSwitch}`,
+            title: "Editor and Preview",
+            description: "Editor shows the regions to work in. Preview gives a first impression of your changes without saving them -- a sketch, not exactly what a visitor will see.",
+            placement: "bottom",
+        },
+        {
+            key: "commands",
+            target: `cms:${PAGES_IDS.widgetToolbar}`,
+            title: "Saving and publishing",
+            description: "Save keeps your changes as a draft, and Live preview opens the Page with it. Publish puts it live, and a new Page exists for visitors only from then on; publishing takes the Publisher role. Undo and Redo step through your changes, and Reset discards the draft without touching what is live.",
+            placement: "bottom",
+        },
+        {
+            key: "draft-status",
+            target: `cms:${PAGES_IDS.widgetDraftStatus}`,
+            title: "Where your changes stand",
+            description: "What you change here is a draft. Visitors see the published Page until the draft is published.",
+            placement: "bottom",
+        },
+    ],
+};
+const NAVIGATION_IDS = builderWorkspaceWidgetIds("builder-navigation-page");
+/**
+ * The Navigation workspace's Tour. What the workspace does not say is that a Site has several
+ * navigations, that a Page is linked by dragging it across rather than by typing its path, and that the
+ * items a Module brings stand in the same list as the Site's own.
+ */
+export const PHI_BUILDER_NAVIGATION_TOUR = {
+    id: `${PHI_BUILDER_RUNTIME_MODULE_ID}/navigation`,
+    version: 1,
+    steps: [
+        {
+            key: "choice",
+            target: `cms:${NAVIGATION_IDS.widgetNavigationItems}:filters`,
+            title: "Which navigation",
+            description: "A Site has more than one navigation -- the main menu, the one in the footer, a sider's. Everything below belongs to the one chosen here, and the plus beside it adds a new one under a key of its own.",
+            placement: "bottom",
+            ifMissing: "skip",
+        },
+        {
+            key: "source",
+            target: `cms:${NAVIGATION_IDS.widgetNavigationSource}`,
+            title: "The Pages to link",
+            description: "Every Page of the Area chosen above the list. Drag one into the navigation to link it, onto a container to put it inside; the link follows the Page wherever its path goes.",
+            placement: "right",
+        },
+        {
+            key: "items",
+            target: `cms:${NAVIGATION_IDS.widgetNavigationItems}:header`,
+            title: "What the navigation holds",
+            description: "A row per item, in the order it is shown. Drag a row to move it, into a container to nest it. A click on a label or an icon changes it in place. Origin says whether the item is the Site's own or came with a Module.",
+            placement: "bottom",
+        },
+        {
+            key: "add",
+            target: `cms:${NAVIGATION_IDS.widgetNavigationItems}:toolbar`,
+            title: "Links, containers, separators",
+            description: "Add link adds a link to an address outside the Site, written in its Path; a Page of the Site is linked by dragging it in. A container holds further items and opens as a group; a separator draws a line between them.",
+            placement: "bottom",
+            ifMissing: "skip",
+        },
+        {
+            key: "row-actions",
+            target: `cms:${NAVIGATION_IDS.widgetNavigationItems}:row-actions`,
+            title: "Hiding and deleting",
+            description: "A hidden item stays in the list and keeps its place, but visitors do not see it. Delete takes it out; Undo brings it back.",
+            placement: "left",
+            ifMissing: "skip",
+        },
+        {
+            key: "commands",
+            target: `cms:${NAVIGATION_IDS.widgetToolbar}`,
+            title: "Saving and publishing",
+            description: "Save keeps your changes as a draft, and Live preview shows the Site with it. Publish puts the navigation live; publishing takes the Publisher role. Undo and Redo step through your changes, and Reset discards the draft without touching what is live.",
+            placement: "bottom",
+        },
+        {
+            key: "draft-status",
+            target: `cms:${NAVIGATION_IDS.widgetDraftStatus}`,
+            title: "Where your changes stand",
+            description: "What you change here is a draft. Visitors see the published navigation until the draft is published.",
+            placement: "bottom",
+        },
+    ],
+};

package/plugins/runtime-modules/builder/trees/phi-builder-inspector-area-overlay-tree.server.js

@@ -243,7 +243,7 @@ export async function buildPhiBuilderInspectorAreaOverlayTree({ page, runtime, }
                 ], [
                     PHI_BUILDER_INSPECTOR_LAYOUT_IDS.widgetInspectorBody,
                     PHI_BUILDER_INSPECTOR_SECTIONS.widget,
-                ]].map(([id, sections]) => nodes.layout({
+                ]].map(([id, sections], index) => nodes.layout({
                 typeKey: "collapsible",
                 id,
                 parentLayoutNodeId: null,
@@ -262,6 +262,13 @@ export async function buildPhiBuilderInspectorAreaOverlayTree({ page, runtime, }
                     innerPadding: PHI_SPACE.sm,
                     slotTitles: sections.map(([, , sectionKey]) => resolveBuilderInspectorSectionTitle(inspectorLabels, sectionKey)),
                     defaultOpenSlotKeys: ["slot_0"],
+                    /*
+                     * A section opened by name: the Builder Tour opens one after another while it describes them
+                     * (`builder/tour.ts`). `slot_<index>` in the order of `PHI_BUILDER_INSPECTOR_SECTIONS`.
+                     */
+                    signalRoutes: {
+                        listens: [{ routeKey: `builder-inspector-section-open-${index}`, capabilityId: "slotOpen", scope: "area", channel: "slot", action: "open", valueType: "string", receiver: createPhiSignalAddress("cms", id) }],
+                    },
                 },
             })),
             nodes.layout({

package/plugins/runtime-modules/builder/widgets/structure-region/built-in.js

@@ -18,6 +18,7 @@ import { createPhiSignalAddress, } from "../../../../../types/signals";
 import { resolvePhiShellRegionTypography, resolvePhiShellRegionZIndex } from "../../../../../helpers/shell-region-style";
 import { phiCmsRegionAcceptsWidget, resolvePhiCmsRegionType } from "../../../../../helpers/cms-region-keys";
 import { usePhiRuntimeModuleState } from "../../../../../components/runtime/runtime-module-context";
+import { PHI_VISUAL_ANCHOR_PART_ATTRIBUTE } from "../../../../../types/visual-anchors";
 import { renderPhiRootNodeScaffold, resolveLayoutNodeRootProps, } from "../../../../../plugins/runtime-modules/builder/render-root-node-scaffold";
 import { PhiBuilderInsertPickerControl } from "../../../../../components/controls/phi-builder-insert-picker-control";
 import { readPhiBuilderRegionRootChildLayouts, readPhiBuilderRegionRootChildWidgets, withPhiBuilderRegionRootChildren, } from "../../../../../plugins/runtime-modules/builder/region-root-node";
@@ -1193,7 +1194,7 @@ export function PhiStructureRegionScaffold({ config, serverPreview, structureDra
             : shouldStretchAvailableHeight
                 ? "100%"
                 : undefined;
-        return (_jsx("div", { "data-phi-region-slot": config.regionKey, className: ["phi-builder-structure-region__slot", regionToneClassName].filter(Boolean).join(" "), "data-phi-builder-region-mode": "preview", "data-phi-builder-region-has-root-node": hasRootNode ? "true" : "false", "data-phi-builder-region-selected": "false", "data-phi-builder-region-picking": "false", style: {
+        return (_jsx("div", { "data-phi-region-slot": config.regionKey, [PHI_VISUAL_ANCHOR_PART_ATTRIBUTE]: config.regionKey, className: ["phi-builder-structure-region__slot", regionToneClassName].filter(Boolean).join(" "), "data-phi-builder-region-mode": "preview", "data-phi-builder-region-has-root-node": hasRootNode ? "true" : "false", "data-phi-builder-region-selected": "false", "data-phi-builder-region-picking": "false", style: {
                 width: slotWidth,
                 minWidth: slotMinWidth,
                 maxWidth: slotMaxWidth,
@@ -1226,7 +1227,7 @@ export function PhiStructureRegionScaffold({ config, serverPreview, structureDra
             shouldFillAvailableHeight ? "phi-builder-structure-region--full-height" : null,
             !shouldFillAvailableHeight ? "phi-builder-structure-region--compact" : null,
             containerClassName,
-        ].filter(Boolean).join(" "), "data-phi-builder-region-mode": isPreviewMode ? "preview" : "editor", "data-phi-builder-region-has-root-node": hasRootNode ? "true" : "false", "data-phi-builder-region-selected": isSelected ? "true" : "false", "data-phi-builder-region-picking": isPicking ? "true" : "false", role: config.allowSelect && !isPreviewMode ? "button" : undefined, tabIndex: config.allowSelect && !isPreviewMode ? 0 : undefined, style: {
+        ].filter(Boolean).join(" "), [PHI_VISUAL_ANCHOR_PART_ATTRIBUTE]: config.regionKey, "data-phi-builder-region-mode": isPreviewMode ? "preview" : "editor", "data-phi-builder-region-has-root-node": hasRootNode ? "true" : "false", "data-phi-builder-region-selected": isSelected ? "true" : "false", "data-phi-builder-region-picking": isPicking ? "true" : "false", role: config.allowSelect && !isPreviewMode ? "button" : undefined, tabIndex: config.allowSelect && !isPreviewMode ? 0 : undefined, style: {
             border: `1px dashed ${token.colorBorderSecondary}`,
             // The area a Region lives in: a faint layout tint so the Theme Root Background stays visible.
             backgroundColor: `color-mix(in srgb, ${token.colorBgLayout} 20%, transparent)`,

package/plugins/runtime-modules/core/widgets/collection-view/client.js

@@ -6,15 +6,25 @@ import { PhiCollectionViewSkeletonControl } from "../../../../../components/cont
 import { normalizePhiCssSize } from "../../../../../components/layouts/phi-layout-contract";
 import { usePhiConfig } from "../../../../../components/root/phi-config-provider";
 import { usePhiRuntimeModuleRenderClient } from "../../../../../components/runtime/runtime-module-render-client-manifest";
+import { usePhiSignalIdentity } from "../../../../../components/runtime/runtime-signal-identity";
+import { usePhiVisualAnchorParts } from "../../../../../components/runtime/runtime-visual-anchors";
 import { createPhiSignalAddress } from "../../../../../types/signals";
 import { usePhiControlSignalController } from "../../../../../components/widgets/client/shared/phi-control-signals";
 import { usePhiCollectionViewBinding } from "../../../../../components/widgets/client/shared/phi-collection-view-binding";
+/**
+ * The parts of a Collection View a Tour can point at, as `cms:<instanceId>:<part>` (design/TOURS.md): the
+ * filters and search, the toolbar, the items and the pagination. A part the view does not draw is simply
+ * not found, and the step pointing at it does what its `ifMissing` says.
+ */
+const PHI_COLLECTION_VIEW_VISUAL_ANCHOR_PARTS = ["filters", "toolbar", "items", "pagination"];
 function PhiCollectionViewWidgetPreview({ config, skeletonActive = true, }) {
     const { token } = usePhiConfig();
     const presentation = config?.presentation;
     return (_jsx(PhiCollectionViewSkeletonControl, { mode: presentation?.mode ?? "grid", gap: normalizePhiCssSize(presentation?.gap) ?? token.paddingSM, minColumnWidth: normalizePhiCssSize(presentation?.minColumnWidth) ?? 102, active: skeletonActive }));
 }
 function PhiCollectionViewWidgetLive({ config, labels, widgetId, }) {
+    const signalIdentity = usePhiSignalIdentity();
+    usePhiVisualAnchorParts(signalIdentity.receiver?.startsWith("cms:") ? signalIdentity.receiver : null, PHI_COLLECTION_VIEW_VISUAL_ANCHOR_PARTS);
     const source = config?.source ?? null;
     const { resource, bindingError, binding } = usePhiCollectionViewBinding({
         source,

package/plugins/runtime-modules/core/widgets/description/config.d.ts

@@ -68,6 +68,7 @@ export declare const PHI_DESCRIPTION_WIDGET_DEFINITION: {
     } & {
         type: "data-provider";
         providerKind?: import("../../../../../types").PhiRuntimeDataProviderKind;
+        providerKey?: import("@phis/contracts/controls").PhiRuntimeDataProviderKey;
     }) | ({
         key: string;
         label: string;
@@ -241,10 +242,33 @@ export declare const PHI_DESCRIPTION_WIDGET_DEFINITION: {
         editorPlacement?: "inspector" | "geometry" | "toolbar";
         visibleWhen?: import("../../../../../types").PhiCmsConfigFieldVisibilityRule | readonly import("../../../../../types").PhiCmsConfigFieldVisibilityRule[];
         heading?: string;
+    } & {
+        type: "choice";
+        valueType: "number";
+        options: import("@phis/contracts/controls").PhiControlOption<number>[];
+        emptyOption?: import("@phis/contracts/controls").PhiControlOption;
+        emptyValue?: null | undefined;
+        placeholder?: string;
+        mode?: never;
+        presentation?: never;
+        optionsProvider?: never;
+        allowCustom?: never;
+        createBehavior?: never;
+        filter?: never;
+        patchOnChange?: never;
+        optionPresets?: never;
+    }) | ({
+        key: string;
+        label: string;
+        description?: string;
+        required?: boolean;
+        editorPlacement?: "inspector" | "geometry" | "toolbar";
+        visibleWhen?: import("../../../../../types").PhiCmsConfigFieldVisibilityRule | readonly import("../../../../../types").PhiCmsConfigFieldVisibilityRule[];
+        heading?: string;
     } & {
         type: "choice";
         mode?: import("../../../../../types").PhiCmsConfigFieldChoiceMode;
-        valueType?: import("../../../../../types").PhiCmsConfigFieldChoiceValueType;
+        valueType?: Exclude<import("../../../../../types").PhiCmsConfigFieldChoiceValueType, "number">;
         presentation?: import("../../../../../types").PhiCmsConfigFieldChoicePresentation;
         options?: import("@phis/contracts/controls").PhiControlOption[];
         optionsProvider?: import("@phis/contracts/controls").PhiControlOptionsProviderConfig;

package/plugins/runtime-modules/core/widgets/entry-detail/config.d.ts

@@ -24,6 +24,7 @@ export declare const PHI_ENTRY_DETAIL_WIDGET_DEFINITION: {
         key: string;
         type: "data-provider";
         providerKind: "record";
+        providerKey: `${string}/${string}`;
         label: string;
         options?: undefined;
     } | {
@@ -56,6 +57,7 @@ export declare const PHI_ENTRY_DETAIL_WIDGET_DEFINITION: {
             readonly label: "Link";
         })[];
         providerKind?: undefined;
+        providerKey?: undefined;
     })[];
     defaultConfig: PhiEntryDetailWidgetConfig;
     parseConfig: (config: Record<string, unknown>) => PhiEntryDetailWidgetConfig;

package/plugins/runtime-modules/core/widgets/entry-detail/config.js

@@ -1,3 +1,4 @@
+import { PHI_CORE_RUNTIME_DATA_PROVIDER_KEYS } from "../../../../../constants/core-data-provider-keys";
 import { isPhiRecord } from "../../../../../helpers/is-record";
 import { resolvePhiCmsWidgetPluginKey } from "../../../../../constants/cms-widget-types";
 import { readPhiContentEntryRecordBinding } from "../../../../../helpers/content-entry-record-binding";
@@ -27,7 +28,13 @@ export const PHI_ENTRY_DETAIL_WIDGET_DEFINITION = {
     icon: "antd:read",
     slotSizePolicy: "fill-inline",
     fields: [
-        { key: "entry", type: "data-provider", providerKind: "record", label: "Entry" },
+        {
+            key: "entry",
+            type: "data-provider",
+            providerKind: "record",
+            providerKey: PHI_CORE_RUNTIME_DATA_PROVIDER_KEYS.contentEntry,
+            label: "Entry",
+        },
         { key: "show", type: "flags", label: "Show", options: phiContentEntryPartOptions(PHI_ENTRY_DETAIL_PARTS) },
     ],
     defaultConfig: normalizePhiEntryDetailWidgetConfig(null),

package/plugins/runtime-modules/core/widgets/entry-header/config.d.ts

@@ -30,6 +30,7 @@ export declare const PHI_ENTRY_HEADER_WIDGET_DEFINITION: {
         key: string;
         type: "data-provider";
         providerKind: "record";
+        providerKey: `${string}/${string}`;
         label: string;
         options?: undefined;
     } | {
@@ -62,6 +63,7 @@ export declare const PHI_ENTRY_HEADER_WIDGET_DEFINITION: {
             readonly label: "Link";
         })[];
         providerKind?: undefined;
+        providerKey?: undefined;
     } | {
         key: string;
         type: "choice";
@@ -71,6 +73,7 @@ export declare const PHI_ENTRY_HEADER_WIDGET_DEFINITION: {
             label: string;
         }[];
         providerKind?: undefined;
+        providerKey?: undefined;
     })[];
     defaultConfig: PhiEntryHeaderWidgetConfig;
     parseConfig: (config: Record<string, unknown>) => PhiEntryHeaderWidgetConfig;

package/plugins/runtime-modules/core/widgets/entry-header/config.js

@@ -1,3 +1,4 @@
+import { PHI_CORE_RUNTIME_DATA_PROVIDER_KEYS } from "../../../../../constants/core-data-provider-keys";
 import { isPhiRecord } from "../../../../../helpers/is-record";
 import { resolvePhiCmsWidgetPluginKey } from "../../../../../constants/cms-widget-types";
 import { readPhiContentEntryRecordBinding } from "../../../../../helpers/content-entry-record-binding";
@@ -32,7 +33,13 @@ export const PHI_ENTRY_HEADER_WIDGET_DEFINITION = {
     icon: "antd:profile",
     slotSizePolicy: "fill-inline",
     fields: [
-        { key: "entry", type: "data-provider", providerKind: "record", label: "Entry" },
+        {
+            key: "entry",
+            type: "data-provider",
+            providerKind: "record",
+            providerKey: PHI_CORE_RUNTIME_DATA_PROVIDER_KEYS.contentEntry,
+            label: "Entry",
+        },
         { key: "show", type: "flags", label: "Show", options: phiContentEntryPartOptions(PHI_ENTRY_HEADER_PARTS) },
         {
             key: "titleLevel",

package/plugins/runtime-modules/core/widgets/entry-list/client.d.ts

@@ -1,4 +1,5 @@
 import { type PhiMarkdownBlock } from "../../../../../components/widgets/shared/markdown-body-client";
+import type { PhiSequenceSettings } from "../../../../../components/widgets/config/sequence-settings";
 import type { PhiEntryListPresentation } from "./config";
 import type { PhiContentEntryReaderLabels } from "../../../../../components/widgets/label-sets/content-entries";
 /**
@@ -53,6 +54,8 @@ export type PhiEntryListWidgetClientProps = {
     parts: number;
     /** The list's own heading, drawn only above entries -- an empty related list leaves no heading behind. */
     title?: string;
+    /** How a slideshow moves; only a slideshow is handed one. */
+    sequence?: PhiSequenceSettings;
     /** Whether no entries is said or simply nothing: a related list under an entry says nothing. */
     emptyBehavior?: "say" | "hide";
 };
@@ -92,4 +95,4 @@ export declare function PhiEntryBody({ entry, parts, labels, }: {
  * through one: the Controls are where antd lives, and a server component cannot use them. Nothing here
  * depends on the visitor, so the first paint already carries every entry.
  */
-export declare function PhiEntryListWidgetClient({ entries, labels, presentation, parts, title, emptyBehavior, }: PhiEntryListWidgetClientProps): import("react").JSX.Element | null;
+export declare function PhiEntryListWidgetClient({ entries, labels, presentation, parts, title, sequence, emptyBehavior, }: PhiEntryListWidgetClientProps): import("react").JSX.Element | null;

package/plugins/runtime-modules/core/widgets/entry-list/client.js

@@ -10,6 +10,7 @@ import { PhiLink } from "../../../../../components/navigation/phi-link";
 import { PhiMarkdownWidgetClient, } from "../../../../../components/widgets/shared/markdown-body-client";
 import { PhiCollectionLayoutControl } from "../../../../../components/controls/phi-collection-layout-control";
 import { PhiCardWidgetClient } from "../../../../../components/widgets/shared/card-body-client";
+import { PhiSequenceRun } from "../../../../../components/motion/phi-sequence-run";
 import { PHI_SURFACE_CARD } from "../../../../../helpers/surface-presets";
 import { PHI_FONT_SIZE, PHI_SPACE } from "../../../../../theme/antd-css-var-contract";
 import { hasPhiContentEntryPart, PhiContentEntryPart } from "../../../../../constants/content-entry-parts";
@@ -113,7 +114,7 @@ function PhiEntryArticle({ entry, labels, parts, }) {
  * through one: the Controls are where antd lives, and a server component cannot use them. Nothing here
  * depends on the visitor, so the first paint already carries every entry.
  */
-export function PhiEntryListWidgetClient({ entries, labels, presentation, parts, title, emptyBehavior = "say", }) {
+export function PhiEntryListWidgetClient({ entries, labels, presentation, parts, title, sequence, emptyBehavior = "say", }) {
     if (entries.length === 0) {
         if (emptyBehavior === "hide")
             return null;
@@ -125,6 +126,6 @@ export function PhiEntryListWidgetClient({ entries, labels, presentation, parts,
      * Still an `h2`, in the rule, so the Page's outline keeps it.
      */
     const heading = title ? (_jsx(PhiDividerControl, { titlePlacement: "start", style: { margin: 0 }, children: _jsx(PhiTypographyControl, { presentation: "title", level: 2, style: { margin: 0, fontSize: PHI_FONT_SIZE.lg }, children: title }) })) : null;
-    const body = presentation === "cards" ? (_jsx(PhiCollectionLayoutControl, { mode: "grid", gap: PHI_SPACE.base, minColumnWidth: ENTRY_CARD_MIN_COLUMN_WIDTH, items: entries.map((entry) => _jsx(PhiEntryCard, { entry: entry, parts: parts }, entry.id)) })) : presentation === "compact" ? (_jsx(PhiFlexControl, { vertical: true, gap: PHI_SPACE.base, children: entries.map((entry) => _jsx(PhiEntryLine, { entry: entry, parts: parts }, entry.id)) })) : (_jsx(PhiFlexControl, { vertical: true, gap: PHI_SPACE.lg, children: entries.map((entry, index) => (_jsxs(PhiFlexControl, { vertical: true, gap: PHI_SPACE.lg, children: [index > 0 ? _jsx(PhiDividerControl, { style: { margin: 0 } }) : null, _jsx(PhiEntryArticle, { entry: entry, labels: labels, parts: parts })] }, entry.id))) }));
+    const body = presentation === "slideshow" ? (_jsx(PhiSequenceRun, { items: entries.map((entry) => _jsx(PhiEntryCard, { entry: entry, parts: parts }, entry.id)), settings: sequence, labels: labels.sequence })) : presentation === "cards" ? (_jsx(PhiCollectionLayoutControl, { mode: "grid", gap: PHI_SPACE.base, minColumnWidth: ENTRY_CARD_MIN_COLUMN_WIDTH, items: entries.map((entry) => _jsx(PhiEntryCard, { entry: entry, parts: parts }, entry.id)) })) : presentation === "compact" ? (_jsx(PhiFlexControl, { vertical: true, gap: PHI_SPACE.base, children: entries.map((entry) => _jsx(PhiEntryLine, { entry: entry, parts: parts }, entry.id)) })) : (_jsx(PhiFlexControl, { vertical: true, gap: PHI_SPACE.lg, children: entries.map((entry, index) => (_jsxs(PhiFlexControl, { vertical: true, gap: PHI_SPACE.lg, children: [index > 0 ? _jsx(PhiDividerControl, { style: { margin: 0 } }) : null, _jsx(PhiEntryArticle, { entry: entry, labels: labels, parts: parts })] }, entry.id))) }));
     return heading ? (_jsxs(PhiFlexControl, { vertical: true, gap: PHI_SPACE.base, children: [heading, body] })) : body;
 }