@phis/ui 0.3.0 → 0.4.1

package/plugins/runtime-modules/core/widgets/simple-text/config.js

@@ -1,4 +1,5 @@
 import { resolvePhiCmsWidgetPluginKey } from "../../../../../constants/cms-widget-types";
+import { readPhiTextSource } from "../../../../../helpers/text-source";
 import { PHI_SIMPLE_TEXT_MARKS } from "../../../../../types/core-widget-placements";
 import { PhiCmsWidgetType } from "../../../../../constants/cms-widget-types";
 import { PHI_RENDERABLE_BLOCK_GEOMETRY_FIELDS } from "../../../../../helpers/renderable-block-plugin-fields";
@@ -27,6 +28,7 @@ function parsePhiCmsSimpleTextWidgetConfig(config) {
         tone: readPhiTextTone(config.tone),
         marks: readSimpleTextMarks(config.marks),
         disabled: readBoolean(config.disabled),
+        textSource: readPhiTextSource(config.textSource),
     };
 }
 export const PHI_SIMPLE_TEXT_WIDGET_DEFINITION = {

package/plugins/runtime-modules/core/widgets/simple-text/plugin.js

@@ -9,7 +9,7 @@ export const PHI_SIMPLE_TEXT_WIDGET_PLUGIN = {
         const noTranslate = hasPhiFlag(widget.flags, PhiCmsFlags.NoTranslate);
         // A record's text is already translated; only the Widget's own still has to be.
         const hasResolvedText = Boolean(widget.resolvedContent?.textFields.text);
-        return (_jsx(PhiSimpleTextWidget, { blockId: widget.id, translate: !noTranslate && !hasResolvedText, labels: {
+        return (_jsx(PhiSimpleTextWidget, { blockId: widget.id, translate: !noTranslate && !hasResolvedText, textSource: config.textSource, labels: {
                 text: resolvePhiSimpleTextWidgetText({
                     ...config,
                     label: widget.label ?? undefined,

package/plugins/runtime-modules/core/widgets/simple-text/server.d.ts

@@ -1,3 +1,4 @@
+import type { PhiTextSource } from "../../../../../helpers/text-source";
 import type { PhiCmsInstanceId, PhiRenderableBlockBase, PhiServerBlockBaseProps } from "../../../../../types";
 import type { PhiSimpleTextWidgetClientConfig } from "./client";
 export type PhiSimpleTextWidgetLabels = {
@@ -6,6 +7,8 @@ export type PhiSimpleTextWidgetLabels = {
 export type PhiSimpleTextWidgetConfig = PhiSimpleTextWidgetClientConfig & PhiRenderableBlockBase;
 export type PhiSimpleTextWidgetProps = PhiServerBlockBaseProps<PhiSimpleTextWidgetLabels, PhiSimpleTextWidgetConfig> & {
     blockId: PhiCmsInstanceId;
+    /** Whose words the text is, which decides the store that translates it (`helpers/text-source.ts`). */
+    textSource?: PhiTextSource;
     /**
      * Whether the text still has to be translated, which is true only where it is the Widget's own.
      *
@@ -16,4 +19,4 @@ export type PhiSimpleTextWidgetProps = PhiServerBlockBaseProps<PhiSimpleTextWidg
      */
     translate?: boolean;
 };
-export declare function PhiSimpleTextWidget({ blockId, labels, config, translate, runtime, }: PhiSimpleTextWidgetProps): Promise<import("react").JSX.Element>;
+export declare function PhiSimpleTextWidget({ blockId, labels, config, translate, textSource, runtime, }: PhiSimpleTextWidgetProps): Promise<import("react").JSX.Element>;

package/plugins/runtime-modules/core/widgets/simple-text/server.js

@@ -1,9 +1,9 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { trGlobal, trGlobalForLocale, } from "../../../../../server-helpers/translate";
+import { trWidgetText } from "../../../../../server-helpers/translate";
 import { maskPhiTextPlaceholders, resolvePhiTextPlaceholders } from "../../../../../helpers/text-placeholders";
 import { PhiCmsWidgetType } from "../../../../../constants/cms-widget-types";
 import { PhiRuntimeModuleRenderClientHost } from "../../../../../components/runtime/runtime-module-render-client-manifest";
-export async function PhiSimpleTextWidget({ blockId, labels, config, translate, runtime, }) {
+export async function PhiSimpleTextWidget({ blockId, labels, config, translate, textSource, runtime, }) {
     const locale = runtime?.locale.current;
     /*
      * Masked before the translation and filled after it.
@@ -14,7 +14,7 @@ export async function PhiSimpleTextWidget({ blockId, labels, config, translate,
      */
     const masked = maskPhiTextPlaceholders(labels.text);
     const translated = translate && masked.text
-        ? locale ? await trGlobalForLocale(locale, masked.text) : await trGlobal(masked.text)
+        ? await trWidgetText(locale, masked.text, textSource)
         : masked.text;
     const text = resolvePhiTextPlaceholders(translated, masked.names, runtime);
     return (_jsx(PhiRuntimeModuleRenderClientHost, { type: PhiCmsWidgetType.SimpleText, componentProps: {

package/plugins/runtime-modules/core/widgets/table/client.js

@@ -913,7 +913,7 @@ export function PhiTableWidgetClient({ config: inputConfig, externalSearch, exte
                             afterRowIdentity: null,
                         }).catch(() => undefined).finally(clearPhiDataDragPayload);
                     }
-                    : undefined, loading: effectiveLoading, bordered: presentation.borders, striped: presentation.row?.striped, showHeader: presentation.header, size: resolvedControlSize, emptyText: (_jsxs(PhiFlexControl, { vertical: true, gap: "small", children: [_jsx(PhiTypographyControl, { strong: true, children: presentation.emptyState?.title ?? labels.emptyTitle }), _jsx(PhiTypographyControl, { type: "secondary", children: presentation.emptyState?.description ?? labels.emptyDescription })] })), layout: presentation.layout, footer: footer, summary: tableSummary })] }));
+                    : undefined, loading: effectiveLoading, bordered: presentation.borders, striped: presentation.row?.striped, showHeader: presentation.header, stickyHeader: presentation.stickyHeader !== false, size: resolvedControlSize, emptyText: (_jsxs(PhiFlexControl, { vertical: true, gap: "small", children: [_jsx(PhiTypographyControl, { strong: true, children: presentation.emptyState?.title ?? labels.emptyTitle }), _jsx(PhiTypographyControl, { type: "secondary", children: presentation.emptyState?.description ?? labels.emptyDescription })] })), layout: presentation.layout, footer: footer, summary: tableSummary })] }));
 }
 function TableAction({ action, disabled = false, disabledReason, templateValue, size, onActivate }) {
     const icon = action.icon ? resolvePhiButtonIcon(action.icon) : null;

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

@@ -105,6 +105,7 @@ export declare const PHI_TABLE_WIDGET_DEFINITION: {
     } & {
         type: "data-provider";
         providerKind?: import("../../../../../types").PhiRuntimeDataProviderKind;
+        providerKey?: import("@phis/contracts/controls").PhiRuntimeDataProviderKey;
     }) | ({
         key: string;
         label: string;
@@ -278,10 +279,33 @@ export declare const PHI_TABLE_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;
@@ -411,6 +435,7 @@ export declare const PHI_TABLE_WIDGET_DEFINITION: {
         heading?: string;
         type: "data-provider";
         providerKind?: import("../../../../../types").PhiRuntimeDataProviderKind;
+        providerKey?: import("@phis/contracts/controls").PhiRuntimeDataProviderKey;
     } | {
         visibleWhen: {
             field: string;
@@ -602,6 +627,31 @@ export declare const PHI_TABLE_WIDGET_DEFINITION: {
         prefix?: string;
         presentation?: "slider";
         suffix?: string;
+    } | {
+        visibleWhen: {
+            field: string;
+            notEquals: string;
+        };
+        key: string;
+        label: string;
+        description?: string;
+        required?: boolean;
+        editorPlacement?: "inspector" | "geometry" | "toolbar";
+        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;
     } | {
         visibleWhen: {
             field: string;
@@ -615,7 +665,7 @@ export declare const PHI_TABLE_WIDGET_DEFINITION: {
         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;
@@ -778,6 +828,7 @@ export declare const PHI_TABLE_WIDGET_DEFINITION: {
             heading?: string;
             type: "data-provider";
             providerKind?: import("../../../../../types").PhiRuntimeDataProviderKind;
+            providerKey?: import("@phis/contracts/controls").PhiRuntimeDataProviderKey;
         } | {
             visibleWhen: {
                 field: string;
@@ -969,6 +1020,31 @@ export declare const PHI_TABLE_WIDGET_DEFINITION: {
             prefix?: string;
             presentation?: "slider";
             suffix?: string;
+        } | {
+            visibleWhen: {
+                field: string;
+                equals: boolean;
+            };
+            key: string;
+            label: string;
+            description?: string;
+            required?: boolean;
+            editorPlacement?: "inspector" | "geometry" | "toolbar";
+            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;
         } | {
             visibleWhen: {
                 field: string;
@@ -982,7 +1058,7 @@ export declare const PHI_TABLE_WIDGET_DEFINITION: {
             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;
@@ -1141,6 +1217,7 @@ export declare const PHI_TABLE_WIDGET_DEFINITION: {
             };
             borders: false;
             header: true;
+            stickyHeader: true;
             row: {
                 striped: false;
             };

package/plugins/runtime-modules/core/widgets/table/config.js

@@ -537,6 +537,7 @@ export function parsePhiTableWidgetConfig(config) {
             },
             borders: readBoolean(presentation.borders),
             header: readBoolean(presentation.header),
+            stickyHeader: readBoolean(presentation.stickyHeader),
             footer: readTableFooter(presentation.footer),
             summary: readTableSummary(presentation.summary),
             row: {
@@ -1153,6 +1154,7 @@ export const PHI_TABLE_WIDGET_DEFINITION = {
         { ...PHI_CONTROL_SIZE_FIELD, key: "presentation.controlSize" },
         { key: "presentation.borders", type: "boolean", label: "Borders" },
         { key: "presentation.header", type: "boolean", label: "Header" },
+        { key: "presentation.stickyHeader", type: "boolean", label: "Sticky Header" },
         { key: "presentation.row.striped", type: "boolean", label: "Striped Rows" },
         ...buildPhiTableConditionExpressionConfigFields("presentation.row.mutedWhen", "Muted Row Conditions", "any", "No muted rows"),
     ],
@@ -1162,6 +1164,7 @@ export const PHI_TABLE_WIDGET_DEFINITION = {
             layout: { mode: "auto", overflowX: "auto" },
             borders: false,
             header: true,
+            stickyHeader: true,
             row: { striped: false },
         },
         features: {

package/plugins/runtime-modules/core/widgets/tour-button/client.js

@@ -4,7 +4,7 @@ import { useCallback, useEffect, useMemo, useState } from "react";
 import { usePhiSignalDispatcher, usePhiSignalListener } from "../../../../../components/runtime/runtime-signal-bus";
 import { PhiButtonControl } from "../../../../../components/controls/phi-button-control";
 import { PhiIcon } from "../../../../../components/shell/phi-icon";
-import { PHI_TOUR_CONTROLLER_ADDRESS } from "../../../../../types/tours";
+import { PHI_TOUR_CONTROLLER_ADDRESS } from "../../../../../types/tour-controller";
 function readAvailable(value) {
     return typeof value === "object" && value !== null && value.available === true;
 }

package/plugins/runtime-modules/phi-default-site-area-preset-tree.js

@@ -4,8 +4,7 @@ import { PhiCmsFlags, PhiCmsRegionType } from "../../constants/phi-cms";
 import { resolvePhiCmsWidgetPluginKey } from "../../constants/cms-widget-types";
 import { buildPhiCmsLayoutNamespacedTypeKey } from "../../constants/cms-layout-types";
 import { resolvePhiCmsLayoutPluginKey } from "../../constants/cms-layout-type-keys";
-import { trGlobal } from "../../server-helpers/translate";
-import { PHI_TR_CTX_WEB_UI_LABEL } from "../../gateway/tr";
+import { PHI_TEXT_SOURCE_PRESET } from "../../helpers/text-source";
 import { PHI_SPACE } from "../../theme/antd-css-var-contract";
 import { buildPhiCmsWidgetNamespacedTypeKey } from "../../constants/cms-widget-types";
 import { createPhiCmsPresetNodes } from "../../helpers/cms-preset-nodes";
@@ -44,7 +43,12 @@ export async function buildPhiDefaultSiteAreaPresetTree({ page, runtime, presetK
     const footerTopRegion = PHI_DEFAULT_PUB_AREA_PRESET.regions.find((region) => region.key === "footer_top");
     const footerBottomRegion = PHI_DEFAULT_PUB_AREA_PRESET.regions.find((region) => region.key === "footer_bottom");
     const { label: contactLabel, href: contactHref, icon: contactIcon, } = resolvePhiBrandContact(runtime);
-    const defaultQuickLinksTitle = await trGlobal("Quick Links", 0, PHI_TR_CTX_WEB_UI_LABEL);
+    /*
+     * The Preset's words stay in the source language and say they are the Preset's; the Widgets translate
+     * them through the global store (`helpers/text-source.ts`). The contact label is the Preset's only
+     * while the Site's theme names none.
+     */
+    const contactLabelIsPreset = !runtime.site.theme?.contact?.label?.trim();
     /*
      * A template rather than a finished sentence, and left untranslated here.
      *
@@ -477,6 +481,7 @@ export async function buildPhiDefaultSiteAreaPresetTree({ page, runtime, presetK
                         label: "pub header top right",
                         config: {
                             text: contactLabel,
+                            ...(contactLabelIsPreset ? { textSource: PHI_TEXT_SOURCE_PRESET } : {}),
                             href: contactHref,
                             icon: contactIcon,
                         },
@@ -581,7 +586,8 @@ export async function buildPhiDefaultSiteAreaPresetTree({ page, runtime, presetK
                         visibilityMask: page.visibilityMask,
                         label: "pub footer main quick links",
                         config: {
-                            title: defaultQuickLinksTitle,
+                            title: "Quick Links",
+                            textSource: PHI_TEXT_SOURCE_PRESET,
                             navKey: `${navigationArea}:footer`,
                             columns: 2,
                             separator: true,
@@ -601,6 +607,7 @@ export async function buildPhiDefaultSiteAreaPresetTree({ page, runtime, presetK
                         label: "pub footer main right",
                         config: {
                             text: contactLabel,
+                            ...(contactLabelIsPreset ? { textSource: PHI_TEXT_SOURCE_PRESET } : {}),
                             href: contactHref,
                             icon: contactIcon,
                         },
@@ -623,6 +630,7 @@ export async function buildPhiDefaultSiteAreaPresetTree({ page, runtime, presetK
                         label: "pub footer bottom text",
                         config: {
                             text: footerBottomText,
+                            textSource: PHI_TEXT_SOURCE_PRESET,
                             tone: "secondary",
                         },
                         contentVersionId: null,

package/plugins/runtime-modules/public/trees/phi-default-pub-contact-page-tree.js

@@ -1,3 +1,4 @@
+import { PHI_TEXT_SOURCE_PRESET } from "../../../../helpers/text-source";
 import { createPhiPresetCmsInstanceIdMap } from "../../../../types/cms-instance-id";
 import { PHI_SPACE } from "../../../../theme/antd-css-var-contract";
 import { PHI_PUBLIC_RUNTIME_MODULE_ID } from "../ids";
@@ -73,6 +74,7 @@ export async function buildPhiDefaultPubContactPageTree({ page, }) {
                 sortOrder: 0,
                 label: "pub contact description widget",
                 config: {
+                    textSource: PHI_TEXT_SOURCE_PRESET,
                     eyebrow: "Contact",
                     title: "Get in touch",
                     description: "Send us your question, project request, or product inquiry and we will get back to you.",

package/plugins/runtime-modules/public/trees/phi-default-pub-unsubscribe-page-tree.js

@@ -1,3 +1,4 @@
+import { PHI_TEXT_SOURCE_PRESET } from "../../../../helpers/text-source";
 import { createPhiPresetCmsInstanceIdMap } from "../../../../types/cms-instance-id";
 import { PHI_PUBLIC_RUNTIME_MODULE_ID } from "../ids";
 import { PhiCmsPageType } from "../../../../constants/phi-cms";
@@ -58,6 +59,7 @@ export async function buildPhiDefaultPubUnsubscribePageTree({ page, presetKey, }
                 sortOrder: 0,
                 label: "pub unsubscribe intro widget",
                 config: {
+                    textSource: PHI_TEXT_SOURCE_PRESET,
                     title: "Stop receiving updates",
                     description: "Press the button below and this site will send you no further updates.",
                     visibleWhen: withToken,
@@ -75,6 +77,7 @@ export async function buildPhiDefaultPubUnsubscribePageTree({ page, presetKey, }
                 sortOrder: 0,
                 label: "pub unsubscribe incomplete widget",
                 config: {
+                    textSource: PHI_TEXT_SOURCE_PRESET,
                     title: "This link is incomplete",
                     description: "Open the unsubscribe link from the message itself, or use the most recent one you received.",
                     tone: "secondary",

package/plugins/runtime-modules/public/trees/phi-default-pub-welcome-page-tree.js

@@ -1,3 +1,4 @@
+import { PHI_TEXT_SOURCE_PRESET } from "../../../../helpers/text-source";
 import { createPhiPresetCmsInstanceIdMap } from "../../../../types/cms-instance-id";
 import { PHI_PUBLIC_RUNTIME_MODULE_ID } from "../ids";
 import { PHI_PUBLIC_BASE_PAGE_REFERENCES } from "../../public-base-page-references";
@@ -125,7 +126,7 @@ export async function buildPhiDefaultPubWelcomePageTree({ page, runtime, }) {
                 sortOrder: 0,
                 label: "pub welcome greeting",
                 // English source, like every Preset sentence: the Site translator makes it "Herzlich willkommen".
-                config: { text: "A warm welcome" },
+                config: { textSource: PHI_TEXT_SOURCE_PRESET, text: "A warm welcome" },
             }),
             nodes.widget({
                 typeKey: "markdown",

package/plugins/runtime-modules/revisions/presets.d.ts

@@ -1,2 +1,53 @@
-import type { PhiCmsRoutePresetDescriptor } from "../../../types/cms-module-descriptors";
-export declare const PHI_REVISIONS_RUNTIME_MODULE_ROUTES: PhiCmsRoutePresetDescriptor[];
+export declare const PHI_REVISIONS_RUNTIME_MODULE_ROUTES: {
+    tour: {
+        readonly id: "@phis/ui/modules/revisions/revisions";
+        readonly version: 1;
+        readonly steps: readonly [{
+            readonly key: "history";
+            readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}:filters`;
+            readonly title: "Whose history";
+            readonly description: "Every save is kept as a revision. Kind chooses what the list shows: an Area's Shell, a Page, a Navigation or the Theme. Scope chooses which Page or which Navigation.";
+            readonly placement: "bottom";
+            readonly ifMissing: "skip";
+        }, {
+            readonly key: "list";
+            readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}:header`;
+            readonly title: "One row per revision";
+            readonly description: "Newest first, with when it was saved, by whom and what changed. The tags say which revision is live and which is the draft being worked on; those two cannot be deleted.";
+            readonly placement: "bottom";
+        }, {
+            readonly key: "answer";
+            readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}:row-actions`;
+            readonly title: "Looking back and going back";
+            readonly description: "Review opens the revision as it was, in a new tab. Restore makes a new draft from it: nothing live changes until that draft is published. Delete removes a revision for good; selected rows can be deleted together.";
+            readonly placement: "left";
+            readonly ifMissing: "skip";
+        }, {
+            readonly key: "reset";
+            readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}:toolbar`;
+            readonly title: "Back to the preset";
+            readonly description: "A Page a Module brings can go back to that Module's version. Every revision the Site stored for it goes with it, so this is offered only while a Page's history is shown.";
+            readonly placement: "bottom";
+            readonly ifMissing: "skip";
+        }, {
+            readonly key: "delete-area";
+            readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}`;
+            readonly title: "Deleting an Area";
+            readonly description: "Clears everything the Site stored for an Area's Shell and Module selection, live included, and leaves no revision to restore. The Area keeps its Pages, its Navigation and its Theme. It asks for the Area's key before it does anything.";
+            readonly placement: "bottom";
+        }];
+    };
+    ownerModuleId: import("../contracts").PhiRuntimeModuleId;
+    presetKey: string;
+    presetVersion: number;
+    area: import("@phis/contracts/cms").PhiCmsAreaKey;
+    path: string;
+    landingPage?: true;
+    title: string;
+    defaultPageFlags?: number;
+    loadTree: (context: import("../../../types").PhiCmsDescriptorBuildContext & {
+        activeModuleIds: ReadonlySet<import("../contracts").PhiRuntimeModuleId>;
+        params: Readonly<Record<string, string>>;
+    }) => import("../../../types").PhiResolvedCmsPageTree | Promise<import("../../../types").PhiResolvedCmsPageTree>;
+    navigation?: readonly import("../../../types").PhiCmsNavigationInjectionDescriptor[];
+}[];

package/plugins/runtime-modules/revisions/presets.js

@@ -1,16 +1,20 @@
 import { buildPhiSidebarRoutePresetDescriptor } from "../sidebar-route";
 import { PHI_REVISIONS_RUNTIME_MODULE_ID } from "./ids";
+import { PHI_REVISIONS_TOUR } from "./tour";
 export const PHI_REVISIONS_RUNTIME_MODULE_ROUTES = [
-    buildPhiSidebarRoutePresetDescriptor({
-        area: "builder",
-        anchor: "main",
-        ownerModuleId: PHI_REVISIONS_RUNTIME_MODULE_ID,
-        presetKey: "builder-revisions-page",
-        title: "Revisions",
-        path: "/revisions",
-        itemKey: "@phis/ui/modules/revisions/nav/builder/revisions",
-        icon: "antd:history",
-        loadTree: ({ page, runtime }) => import("./trees/phi-default-builder-revisions-page-tree")
-            .then((module) => module.buildPhiDefaultBuilderRevisionsPageTree({ page, runtime })),
-    }),
+    {
+        ...buildPhiSidebarRoutePresetDescriptor({
+            area: "builder",
+            anchor: "main",
+            ownerModuleId: PHI_REVISIONS_RUNTIME_MODULE_ID,
+            presetKey: "builder-revisions-page",
+            title: "Revisions",
+            path: "/revisions",
+            itemKey: "@phis/ui/modules/revisions/nav/builder/revisions",
+            icon: "antd:history",
+            loadTree: ({ page, runtime }) => import("./trees/phi-default-builder-revisions-page-tree")
+                .then((module) => module.buildPhiDefaultBuilderRevisionsPageTree({ page, runtime })),
+        }),
+        tour: PHI_REVISIONS_TOUR,
+    },
 ];

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

@@ -0,0 +1,43 @@
+/**
+ * The Revisions Tour. What the Page does not say is that every save is kept, that going back never
+ * touches what is live -- a restored revision is a new draft -- and that the one act here that cannot be
+ * taken back stands apart from the rest.
+ */
+export declare const PHI_REVISIONS_TOUR: {
+    readonly id: "@phis/ui/modules/revisions/revisions";
+    readonly version: 1;
+    readonly steps: readonly [{
+        readonly key: "history";
+        readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}:filters`;
+        readonly title: "Whose history";
+        readonly description: "Every save is kept as a revision. Kind chooses what the list shows: an Area's Shell, a Page, a Navigation or the Theme. Scope chooses which Page or which Navigation.";
+        readonly placement: "bottom";
+        readonly ifMissing: "skip";
+    }, {
+        readonly key: "list";
+        readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}:header`;
+        readonly title: "One row per revision";
+        readonly description: "Newest first, with when it was saved, by whom and what changed. The tags say which revision is live and which is the draft being worked on; those two cannot be deleted.";
+        readonly placement: "bottom";
+    }, {
+        readonly key: "answer";
+        readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}:row-actions`;
+        readonly title: "Looking back and going back";
+        readonly description: "Review opens the revision as it was, in a new tab. Restore makes a new draft from it: nothing live changes until that draft is published. Delete removes a revision for good; selected rows can be deleted together.";
+        readonly placement: "left";
+        readonly ifMissing: "skip";
+    }, {
+        readonly key: "reset";
+        readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}:toolbar`;
+        readonly title: "Back to the preset";
+        readonly description: "A Page a Module brings can go back to that Module's version. Every revision the Site stored for it goes with it, so this is offered only while a Page's history is shown.";
+        readonly placement: "bottom";
+        readonly ifMissing: "skip";
+    }, {
+        readonly key: "delete-area";
+        readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}`;
+        readonly title: "Deleting an Area";
+        readonly description: "Clears everything the Site stored for an Area's Shell and Module selection, live included, and leaves no revision to restore. The Area keeps its Pages, its Navigation and its Theme. It asks for the Area's key before it does anything.";
+        readonly placement: "bottom";
+    }];
+};

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

@@ -0,0 +1,51 @@
+import { PHI_REVISIONS_RUNTIME_MODULE_ID } from "./ids";
+import { PHI_REVISIONS_PAGE_WIDGET_IDS, PHI_REVISIONS_TABLE_WIDGET_ID } from "./page-ids";
+/**
+ * The Revisions Tour. What the Page does not say is that every save is kept, that going back never
+ * touches what is live -- a restored revision is a new draft -- and that the one act here that cannot be
+ * taken back stands apart from the rest.
+ */
+export const PHI_REVISIONS_TOUR = {
+    id: `${PHI_REVISIONS_RUNTIME_MODULE_ID}/revisions`,
+    version: 1,
+    steps: [
+        {
+            key: "history",
+            target: `cms:${PHI_REVISIONS_TABLE_WIDGET_ID}:filters`,
+            title: "Whose history",
+            description: "Every save is kept as a revision. Kind chooses what the list shows: an Area's Shell, a Page, a Navigation or the Theme. Scope chooses which Page or which Navigation.",
+            placement: "bottom",
+            ifMissing: "skip",
+        },
+        {
+            key: "list",
+            target: `cms:${PHI_REVISIONS_TABLE_WIDGET_ID}:header`,
+            title: "One row per revision",
+            description: "Newest first, with when it was saved, by whom and what changed. The tags say which revision is live and which is the draft being worked on; those two cannot be deleted.",
+            placement: "bottom",
+        },
+        {
+            key: "answer",
+            target: `cms:${PHI_REVISIONS_TABLE_WIDGET_ID}:row-actions`,
+            title: "Looking back and going back",
+            description: "Review opens the revision as it was, in a new tab. Restore makes a new draft from it: nothing live changes until that draft is published. Delete removes a revision for good; selected rows can be deleted together.",
+            placement: "left",
+            ifMissing: "skip",
+        },
+        {
+            key: "reset",
+            target: `cms:${PHI_REVISIONS_TABLE_WIDGET_ID}:toolbar`,
+            title: "Back to the preset",
+            description: "A Page a Module brings can go back to that Module's version. Every revision the Site stored for it goes with it, so this is offered only while a Page's history is shown.",
+            placement: "bottom",
+            ifMissing: "skip",
+        },
+        {
+            key: "delete-area",
+            target: `cms:${PHI_REVISIONS_PAGE_WIDGET_IDS.widgetRevisionsAreaShellDelete}`,
+            title: "Deleting an Area",
+            description: "Clears everything the Site stored for an Area's Shell and Module selection, live included, and leaves no revision to restore. The Area keeps its Pages, its Navigation and its Theme. It asks for the Area's key before it does anything.",
+            placement: "bottom",
+        },
+    ],
+};

package/plugins/runtime-modules/revisions/trees/phi-default-builder-revisions-page-tree.js

@@ -265,6 +265,8 @@ export async function buildPhiDefaultBuilderRevisionsPageTree({ page, runtime, }
              */
             nodes.widget({
                 typeKey: "simple-text",
+                /* Label set text, translated already; a second pass would hand the translator a non-source text. */
+                flags: PhiCmsFlags.NoTranslate,
                 id: PHI_REVISIONS_DELETE_AREA_WIDGET_IDS.deleteAreaWarning,
                 parentLayoutNodeId: PHI_REVISIONS_DELETE_AREA_LAYOUT_IDS.deleteAreaBody,
                 slotIndex: PHI_CMS_DEFAULT_SLOT_INDEX,
@@ -279,6 +281,8 @@ export async function buildPhiDefaultBuilderRevisionsPageTree({ page, runtime, }
             }),
             nodes.widget({
                 typeKey: "simple-text",
+                /* Label set text, translated already; a second pass would hand the translator a non-source text. */
+                flags: PhiCmsFlags.NoTranslate,
                 id: PHI_REVISIONS_DELETE_AREA_WIDGET_IDS.deleteAreaSurvives,
                 parentLayoutNodeId: PHI_REVISIONS_DELETE_AREA_LAYOUT_IDS.deleteAreaBody,
                 slotIndex: PHI_CMS_SEQUENTIAL_LAYOUT_SLOTS[1].slotIndex,

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

@@ -5,15 +5,47 @@ export declare const PHI_THEME_RUNTIME_MODULE_ROUTES: {
         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 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 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:${import("@phis/contracts/cms").PhiCmsInstanceId}`;
+            readonly title: string;
+            readonly description: string;
+            readonly placement: "right";
+            readonly prepare: readonly [import("../../../types").PhiTourStepSignal];
+            readonly release: readonly [import("../../../types").PhiTourStepSignal];
+        }, {
+            readonly key: string;
+            readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}`;
+            readonly title: string;
+            readonly description: string;
+            readonly placement: "right";
+            readonly prepare: readonly [import("../../../types").PhiTourStepSignal];
+            readonly release: readonly [import("../../../types").PhiTourStepSignal];
+        }, {
+            readonly key: string;
+            readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}`;
+            readonly title: string;
+            readonly description: string;
+            readonly placement: "right";
+            readonly prepare: readonly [import("../../../types").PhiTourStepSignal];
+            readonly release: readonly [import("../../../types").PhiTourStepSignal];
+        }, {
+            readonly key: string;
+            readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}`;
+            readonly title: string;
+            readonly description: string;
+            readonly placement: "right";
+            readonly prepare: readonly [import("../../../types").PhiTourStepSignal];
+            readonly release: readonly [import("../../../types").PhiTourStepSignal];
         }, {
             readonly key: "preview-mode";
             readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}`;