@phis/ui 0.3.0 → 0.4.0

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

@@ -0,0 +1,44 @@
+/**
+ * The Media Tour. What the Page does not say is that it is the one library every picker of the Site
+ * draws from, and that what is set on an asset here -- its words, its folder, its focal rectangle -- goes
+ * wherever the asset is used. The Inspector is described rather than opened: it opens on an asset, and a
+ * Tour cannot know which assets a Site has.
+ */
+export declare const PHI_ASSET_MEDIA_TOUR: {
+    readonly id: "@phis/ui/modules/asset/media";
+    readonly version: 1;
+    readonly steps: readonly [{
+        readonly key: "find";
+        readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}:filters`;
+        readonly title: "Finding an asset";
+        readonly description: "Kind narrows the library to images or other files, Flags to assets marked Featured, Locked, Mask or Background, Folder to one folder. The plus beside Folder creates a new folder. The search looks through file names, titles and alternative texts.";
+        readonly placement: "bottom";
+        readonly ifMissing: "skip";
+    }, {
+        readonly key: "upload";
+        readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}:toolbar`;
+        readonly title: "Adding files";
+        readonly description: "Upload opens a field to drop files into. They arrive in the folder and with the flags chosen in the filters, so choosing the folder first saves sorting later. Reset clears the filters, Reload fetches the library again.";
+        readonly placement: "bottom";
+        readonly ifMissing: "skip";
+    }, {
+        readonly key: "library";
+        readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}:items`;
+        readonly title: "The Site's library";
+        readonly description: "Every image and file the Site has, newest first. It is the same library every image picker of the Site opens, so what is uploaded here can be placed anywhere.";
+        readonly placement: "top";
+    }, {
+        readonly key: "inspector";
+        readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}:items`;
+        readonly title: "What an asset says about itself";
+        readonly description: "A click on an asset opens its Inspector: its folder, its title, the alternative text read out to those who cannot see it, its flags, and the focal rectangle -- the part of a picture that stays in view when a variant cuts it to another shape. Saved there, it applies wherever the asset is used.";
+        readonly placement: "top";
+    }, {
+        readonly key: "pages";
+        readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}:pagination`;
+        readonly title: "Page by page";
+        readonly description: "The library is shown a page at a time; how many fit on one is chosen here.";
+        readonly placement: "top";
+        readonly ifMissing: "skip";
+    }];
+};

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

@@ -0,0 +1,53 @@
+import { PHI_ASSET_RUNTIME_MODULE_ID } from "./ids";
+import { PHI_ASSET_MEDIA_PAGE_WIDGET_IDS } from "./media-page-ids";
+const LIBRARY_ID = PHI_ASSET_MEDIA_PAGE_WIDGET_IDS.widgetMediaPreview;
+/**
+ * The Media Tour. What the Page does not say is that it is the one library every picker of the Site
+ * draws from, and that what is set on an asset here -- its words, its folder, its focal rectangle -- goes
+ * wherever the asset is used. The Inspector is described rather than opened: it opens on an asset, and a
+ * Tour cannot know which assets a Site has.
+ */
+export const PHI_ASSET_MEDIA_TOUR = {
+    id: `${PHI_ASSET_RUNTIME_MODULE_ID}/media`,
+    version: 1,
+    steps: [
+        {
+            key: "find",
+            target: `cms:${LIBRARY_ID}:filters`,
+            title: "Finding an asset",
+            description: "Kind narrows the library to images or other files, Flags to assets marked Featured, Locked, Mask or Background, Folder to one folder. The plus beside Folder creates a new folder. The search looks through file names, titles and alternative texts.",
+            placement: "bottom",
+            ifMissing: "skip",
+        },
+        {
+            key: "upload",
+            target: `cms:${LIBRARY_ID}:toolbar`,
+            title: "Adding files",
+            description: "Upload opens a field to drop files into. They arrive in the folder and with the flags chosen in the filters, so choosing the folder first saves sorting later. Reset clears the filters, Reload fetches the library again.",
+            placement: "bottom",
+            ifMissing: "skip",
+        },
+        {
+            key: "library",
+            target: `cms:${LIBRARY_ID}:items`,
+            title: "The Site's library",
+            description: "Every image and file the Site has, newest first. It is the same library every image picker of the Site opens, so what is uploaded here can be placed anywhere.",
+            placement: "top",
+        },
+        {
+            key: "inspector",
+            target: `cms:${LIBRARY_ID}:items`,
+            title: "What an asset says about itself",
+            description: "A click on an asset opens its Inspector: its folder, its title, the alternative text read out to those who cannot see it, its flags, and the focal rectangle -- the part of a picture that stays in view when a variant cuts it to another shape. Saved there, it applies wherever the asset is used.",
+            placement: "top",
+        },
+        {
+            key: "pages",
+            target: `cms:${LIBRARY_ID}:pagination`,
+            title: "Page by page",
+            description: "The library is shown a page at a time; how many fit on one is chosen here.",
+            placement: "top",
+            ifMissing: "skip",
+        },
+    ],
+};

package/plugins/runtime-modules/builder/clients/inspector-config-field.js

@@ -314,6 +314,21 @@ function resolveInspectorChoiceOptions(field, widgetReferenceOptions, resolvedOp
     }
     return resolvedOptions;
 }
+/**
+ * A closed list of numbers. The select holds the numbers themselves, so what is picked is what is
+ * stored; only the empty line is a word, and it stands for `emptyValue`.
+ */
+function renderPhiInspectorNumberChoiceField({ field, value, defaultValue, disabled, onChange, }) {
+    const stored = value ?? defaultValue;
+    const emptyOptionValue = field.emptyOption?.value;
+    const selectedValue = typeof stored === "number" ? stored : emptyOptionValue;
+    const options = field.emptyOption
+        ? [field.emptyOption, ...field.options]
+        : field.options;
+    return renderPhiInspectorConfigFieldControl(field, _jsx(PhiSelectControl, { options: options, placeholder: field.placeholder, value: selectedValue, disabled: disabled, style: { width: "100%" }, onChange: (next) => onChange?.({
+            [field.key]: emptyOptionValue != null && next === emptyOptionValue ? field.emptyValue : next,
+        }) }));
+}
 function PhiInspectorChoiceFieldControl({ field, config, value, defaultValue, disabled, widgetReferenceOptions, labels, onChange, }) {
     const staticOptions = useMemo(() => field.filter?.widgetType
         ? widgetReferenceOptions
@@ -524,7 +539,7 @@ function renderPhiInspectorConfigFieldBody({ field, value, defaultValue, config,
          * other kinds are a Provider or nothing.
          */
         const supportsStaticOptions = !field.providerKind || field.providerKind === "options" || field.providerKind === "timeline";
-        const selectedProvider = dataProviderDescriptors.find((descriptor) => descriptor.key === providerConfig?.providerKey) ?? null;
+        const selectedProvider = dataProviderDescriptors.find((descriptor) => descriptor.key === (field.providerKey ?? providerConfig?.providerKey)) ?? null;
         const options = [
             ...(supportsStaticOptions
                 ? [{
@@ -540,7 +555,7 @@ function renderPhiInspectorConfigFieldBody({ field, value, defaultValue, config,
                 description: descriptor.description,
             })),
         ];
-        return renderPhiInspectorConfigFieldControl(field, _jsxs(PhiFlexControl, { vertical: true, gap: 8, style: { width: "100%" }, children: [_jsx(PhiSelectControl, { options: options, placeholder: fieldLabels.selectDataProvider, value: providerConfig?.providerKey ?? (supportsStaticOptions ? PHI_STATIC_OPTIONS_PROVIDER_VALUE : undefined), disabled: disabled || !onChange, style: { width: "100%" }, onChange: (providerKey) => onChange?.({
+        const bindingRow = renderPhiInspectorConfigFieldControl(field, _jsxs(PhiFlexControl, { vertical: true, gap: 8, style: { width: "100%" }, children: [_jsx(PhiSelectControl, { options: options, placeholder: fieldLabels.selectDataProvider, value: providerConfig?.providerKey ?? (supportsStaticOptions ? PHI_STATIC_OPTIONS_PROVIDER_VALUE : undefined), disabled: disabled || !onChange, style: { width: "100%" }, onChange: (providerKey) => onChange?.({
                         [field.key]: providerKey === PHI_STATIC_OPTIONS_PROVIDER_VALUE
                             ? null
                             : field.providerKind === "table" || field.providerKind === "tree" || field.providerKind === "collection"
@@ -575,22 +590,28 @@ function renderPhiInspectorConfigFieldBody({ field, value, defaultValue, config,
                             resourceKey,
                             params: isPhiRecord(rawProviderConfig.params) ? rawProviderConfig.params : undefined,
                         },
-                    }) })) : null, field.providerKind === "record" && selectedProvider
-                    ? (selectedProvider.settingsFields ?? []).map((paramField) => {
-                        const params = isPhiRecord(rawProviderConfig.params) ? rawProviderConfig.params : {};
-                        return _jsx(Fragment, { children: renderPhiInspectorConfigField({
-                                field: paramField,
-                                value: params[paramField.key],
-                                defaultValue: undefined,
-                                config: params,
-                                disabled,
-                                fieldLabels,
-                                onChange: (patch) => onChange?.({
-                                    [field.key]: { providerKey: selectedProvider.key, params: { ...params, ...patch } },
-                                }),
-                            }) }, paramField.key);
-                    })
-                    : null] }));
+                    }) })) : null] }));
+        if (field.providerKind !== "record" || !selectedProvider)
+            return bindingRow;
+        /*
+         * A record is one thing, named by its parameters -- an entry by kind and address -- and the
+         * Provider says which it takes in its `settingsFields`. They are rows of their own under the
+         * binding, words on the left like every other field; inside the binding's control column they
+         * would draw a second pair of columns squeezed into the first one's right half. A binding fixed
+         * to one Provider shows only them.
+         */
+        const params = isPhiRecord(rawProviderConfig.params) ? rawProviderConfig.params : {};
+        return (_jsxs(Fragment, { children: [field.providerKey ? null : bindingRow, (selectedProvider.settingsFields ?? []).map((paramField) => (_jsx(Fragment, { children: renderPhiInspectorConfigField({
+                        field: paramField,
+                        value: params[paramField.key],
+                        defaultValue: undefined,
+                        config: params,
+                        disabled,
+                        fieldLabels,
+                        onChange: (patch) => onChange?.({
+                            [field.key]: { providerKey: selectedProvider.key, params: { ...params, ...patch } },
+                        }),
+                    }) }, paramField.key)))] }, field.key));
     }
     if (field.type === "calendar-adapter") {
         return renderPhiInspectorConfigFieldControl(field, _jsx(PhiSelectControl, { options: calendarAdapterDescriptors.map((descriptor) => ({
@@ -692,6 +713,9 @@ function renderPhiInspectorConfigFieldBody({ field, value, defaultValue, config,
             ...(onChange ? { onChange: (checked) => onChange({ [field.key]: checked }) } : {}),
         });
     }
+    if (field.type === "choice" && field.valueType === "number") {
+        return renderPhiInspectorNumberChoiceField({ field, value, defaultValue, disabled: disabled || !onChange, onChange });
+    }
     if (field.type === "choice") {
         return (_jsx(PhiInspectorChoiceFieldControl, { field: field, config: config, value: value, defaultValue: defaultValue, disabled: disabled || !onChange, widgetReferenceOptions: widgetReferenceOptions ?? [], labels: fieldLabels, onChange: onChange }, field.key));
     }

package/plugins/runtime-modules/builder/clients/inspector-image-field.js

@@ -26,7 +26,7 @@ export function PhiInspectorImageFieldControl({ config, blockId, disabled, onCha
     const assetId = config.sourceKind === "asset" && typeof config.assetId === "number" ? config.assetId : null;
     const asset = usePhiAuthoringAssetDetails(assetId);
     const sourceUrl = typeof config.sourceUrl === "string" ? config.sourceUrl : "";
-    const variantKey = typeof config.variantKey === "number" ? String(config.variantKey) : PHI_IMAGE_FIELD_ORIGINAL_VARIANT;
+    const variantKey = typeof config.variantKey === "number" ? config.variantKey : PHI_IMAGE_FIELD_ORIGINAL_VARIANT;
     const editable = !disabled && onChange != null;
     return (_jsxs(PhiFlexControl, { vertical: true, gap: 8, style: { width: "100%", minWidth: 0 }, children: [_jsx(PhiMediaPickerBinding, { config: {
                     mediaType: PhiMediaKind.Image,
@@ -52,7 +52,7 @@ export function PhiInspectorImageFieldControl({ config, blockId, disabled, onCha
                         sourceUrl: undefined,
                     })
                     : undefined }), assetId != null ? (_jsx(PhiInspectorFieldRow, { label: "Variant", children: _jsx(PhiSelectControl, { value: variantKey, options: [{ value: PHI_IMAGE_FIELD_ORIGINAL_VARIANT, label: "Original", separator: "after" }, ...PHI_IMAGE_VARIANT_OPTIONS], disabled: !editable, style: { width: "100%" }, onChange: (next) => onChange?.({
-                        variantKey: next === PHI_IMAGE_FIELD_ORIGINAL_VARIANT ? null : Number(next),
+                        variantKey: next === PHI_IMAGE_FIELD_ORIGINAL_VARIANT ? null : next,
                     }) }) })) : (_jsx(PhiInspectorFieldRow, { label: "URL", children: _jsx(PhiTextControl, { value: sourceUrl, inputType: "url", placeholder: "https://", disabled: !editable, style: { width: "100%" }, onChange: (next) => onChange?.({ sourceKind: "url", sourceUrl: next?.trim() || undefined }) }) })), _jsx(PhiInspectorFieldRow, { label: "Alt text", children: _jsx(PhiTextControl, { value: typeof config.alt === "string" ? config.alt : "", 
                     /* An Asset brings its own; this replaces it for this placement only. */
                     placeholder: asset?.altText ?? undefined, disabled: !editable, style: { width: "100%" }, onChange: (next) => onChange?.({ alt: next || undefined }) }) })] }));

package/plugins/runtime-modules/builder/clients/workspace-scope-boundary.js

@@ -4,10 +4,20 @@ import { PhiBuilderWorkspacePreviewSkeleton } from "../../../../components/widge
 import { usePhiDeveloperBuilderStateValue, } from "../developer-workspace-store";
 import { PhiSignalRuntimePartitionProvider } from "../../../../components/runtime/runtime-signal-partition";
 import { PhiBuilderCanvasRegionOverrides } from "./builder-region-overrides";
+import { usePhiSignalIdentity } from "../../../../components/runtime/runtime-signal-identity";
+import { usePhiVisualAnchorParts } from "../../../../components/runtime/runtime-visual-anchors";
+import { PHI_BUILDER_PAGE_REGION_KEYS, PHI_BUILDER_SHELL_REGION_KEYS } from "../region-keys";
 export function PhiBuilderWorkspaceScopeBoundary({ kind, targetArea, targetPageKey, children, }) {
     const activeArea = usePhiDeveloperBuilderStateValue("public", (state) => state.area);
     const activePageKey = usePhiDeveloperBuilderStateValue("public", (state) => state.pageKey);
     const scopeMatches = activeArea === targetArea &&
         (targetPageKey == null || activePageKey === targetPageKey);
+    /*
+     * Each Region on the canvas, offered to a Tour as `cms:<workspace>:<regionKey>`. Registered here, on
+     * this side of the canvas partition: the Tour looks in the Page's partition, and the canvas below runs
+     * in an isolated one of its own.
+     */
+    const signalIdentity = usePhiSignalIdentity();
+    usePhiVisualAnchorParts(signalIdentity.receiver?.startsWith("cms:") ? signalIdentity.receiver : null, kind === "shells" ? PHI_BUILDER_SHELL_REGION_KEYS : PHI_BUILDER_PAGE_REGION_KEYS);
     return scopeMatches ? (_jsx(PhiSignalRuntimePartitionProvider, { id: `canvas:${kind}:${targetArea}:${targetPageKey ?? "area"}`, kind: "canvas", context: { area: targetArea, pageKey: targetPageKey ?? null }, isolated: true, children: _jsx(PhiBuilderCanvasRegionOverrides, { children: children }) })) : _jsx(PhiBuilderWorkspacePreviewSkeleton, { kind: kind });
 }

package/plugins/runtime-modules/builder/controller/workspace-controller.js

@@ -22,7 +22,7 @@ import { isPhiBuilderAreaKey, resolvePhiBuilderAreaAsCmsArea, } from "../../../.
 import { resolvePhiRuntimeAreaDefinition } from "../../../../plugins/runtime-modules/area-definitions";
 import { resolvePhiBuilderNavigationWidgetNavKey } from "../navigation-widget-runtime";
 import { parsePhiBuilderNavigationScopeKey } from "../../../../helpers/cms-navigation-catalog";
-import { builderWorkspaceStore, usePhiDeveloperBuilderWorkspaceState, completePhiDeveloperBuilderEffectsEditor, normalizePhiDeveloperBuilderArea as normalizeBuilderArea, previewPhiDeveloperBuilderEffects, resetPhiBuilderSelectionToPage, selectPhiDeveloperBuilderNode, usePhiDeveloperRegionDraft, getPhiDeveloperBuilderStateSnapshot, readPhiBuilderEffectiveAreaRootRoute, setPhiDeveloperBuilderAreaRootRoutes, setPhiDeveloperBuilderAreaMetaBaseline, setPhiDeveloperBuilderAreaControllerSettings, readPhiBuilderEffectiveAreaMeta, closePhiBuilderModuleDeactivationRequest, closePhiBuilderPublicRouteCollisionRequest, } from "../developer-workspace-store";
+import { builderWorkspaceStore, usePhiDeveloperBuilderWorkspaceState, completePhiDeveloperBuilderEffectsEditor, normalizePhiDeveloperBuilderArea as normalizeBuilderArea, previewPhiDeveloperBuilderEffects, resetPhiBuilderSelectionToPage, selectPhiDeveloperBuilderNode, usePhiDeveloperRegionDraft, getPhiDeveloperBuilderStateSnapshot, getPhiDeveloperRegionDraftsSnapshot, readPhiBuilderEffectiveAreaRootRoute, setPhiDeveloperBuilderAreaRootRoutes, setPhiDeveloperBuilderAreaMetaBaseline, setPhiDeveloperBuilderAreaControllerSettings, readPhiBuilderEffectiveAreaMeta, closePhiBuilderModuleDeactivationRequest, closePhiBuilderPublicRouteCollisionRequest, } from "../developer-workspace-store";
 import {} from "../options-providers";
 import { PHI_AREA_META_PUBLIC_DEFAULTS } from "../../../../helpers/cms-area-config";
 import { getPhiBuilderRegionDraftKey } from "../region-keys";
@@ -1072,13 +1072,28 @@ function usePhiDeveloperBuilderWorkspaceController(defaultArea, options) {
             if (!next || typeof next.nodeKey !== "string" || typeof next.nodeKind !== "string") {
                 return;
             }
-            const nextNodeKey = next.nodeKey;
+            let nextNodeKey = next.nodeKey;
+            let nextNodeId = readPhiCmsInstanceId(next.nodeId);
             const nextPageKey = typeof next.pageKey === "string" ? next.pageKey : undefined;
+            /*
+             * A Layout named only by its Region is that Region's root Layout, read from its draft. A sender that
+             * cannot know a Site's node ids -- a Tour step showing the Layout Inspector -- names it this way. A
+             * Region without a root Layout selects nothing.
+             */
+            if (next.nodeKind === "layout" && nextNodeId == null && typeof next.regionKey === "string") {
+                const current = getPhiDeveloperBuilderStateSnapshot(defaultArea);
+                const rootNode = getPhiDeveloperRegionDraftsSnapshot()[getPhiBuilderRegionDraftKey(typeof next.area === "string" ? next.area : current.area, next.regionKey, nextPageKey ?? current.pageKey)]?.rootNode;
+                if (!rootNode) {
+                    return;
+                }
+                nextNodeId = rootNode.id;
+                nextNodeKey = rootNode.widgetType;
+            }
             selectPhiDeveloperBuilderNode(defaultArea, {
                 ...(typeof next.area === "string" ? { area: next.area } : {}),
                 ...(nextPageKey ? { pageKey: nextPageKey } : {}),
                 nodeKey: nextNodeKey,
-                nodeId: readPhiCmsInstanceId(next.nodeId),
+                nodeId: nextNodeId,
                 nodeKind: next.nodeKind,
                 regionType: typeof next.regionType === "number" ? next.regionType : null,
                 regionKey: typeof next.regionKey === "string" ? next.regionKey : null,

package/plugins/runtime-modules/builder/plugin-meta-labels.js

@@ -38,6 +38,14 @@ function mapPhiConfigFieldText(field, mapText) {
         ...(field.description == null ? {} : { description: mapOptionalText(field.description, mapText) }),
         ...(field.heading == null ? {} : { heading: mapOptionalText(field.heading, mapText) }),
     };
+    if (mapped.type === "choice" && mapped.valueType === "number") {
+        return {
+            ...mapped,
+            options: mapped.options.map((option) => mapPhiControlOptionText(option, mapText)),
+            ...(mapped.emptyOption == null ? {} : { emptyOption: mapPhiControlOptionText(mapped.emptyOption, mapText) }),
+            ...(mapped.placeholder == null ? {} : { placeholder: mapOptionalText(mapped.placeholder, mapText) }),
+        };
+    }
     if (mapped.type === "choice") {
         return {
             ...mapped,

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

@@ -2,6 +2,7 @@ import { PHI_BASE_PAGE_LAYOUT_VERSION } from "../../../components/regions/preset
 import { buildPhiAreaRootRoutePresetDescriptor } from "../area-root-route";
 import { PHI_BUILDER_RUNTIME_MODULE_ID } from "./ids";
 import { PHI_BUILDER_PAGE_PRESET_VERSION } from "../../../components/regions/presets/phi-builder-page-preset-version";
+import { PHI_BUILDER_NAVIGATION_TOUR, PHI_BUILDER_PAGES_TOUR, PHI_BUILDER_SHELLS_TOUR } from "./tour";
 export const PHI_BUILDER_RUNTIME_MODULE_AREA_SHELLS = [{
         ownerModuleId: PHI_BUILDER_RUNTIME_MODULE_ID,
         presetKey: "builder-area-preset",
@@ -11,9 +12,9 @@ export const PHI_BUILDER_RUNTIME_MODULE_AREA_SHELLS = [{
             .then((module) => module.buildPhiDefaultBuilderAreaPresetTree({ page, runtime })),
     }];
 const BUILDER_ROUTE_PRESETS = [
-    { presetKey: "builder-shells-page", title: "Shells", path: "/shells" },
-    { presetKey: "builder-pages-page", title: "Pages", path: "/pages" },
-    { presetKey: "builder-navigation-page", title: "Navigation", path: "/navigation" },
+    { presetKey: "builder-shells-page", title: "Shells", path: "/shells", tour: PHI_BUILDER_SHELLS_TOUR },
+    { presetKey: "builder-pages-page", title: "Pages", path: "/pages", tour: PHI_BUILDER_PAGES_TOUR },
+    { presetKey: "builder-navigation-page", title: "Navigation", path: "/navigation", tour: PHI_BUILDER_NAVIGATION_TOUR },
     { presetKey: "builder-modules-page", title: "Modules", path: "/modules" },
 ];
 const BUILDER_WORKSPACE_ROUTES = BUILDER_ROUTE_PRESETS.map((route) => ({
@@ -23,6 +24,7 @@ const BUILDER_WORKSPACE_ROUTES = BUILDER_ROUTE_PRESETS.map((route) => ({
     area: "builder",
     title: route.title,
     path: route.path,
+    ...("tour" in route ? { tour: route.tour } : {}),
     loadTree: ({ page, runtime }) => import("./trees/phi-default-builder-area-preset-tree")
         .then((module) => module.buildPhiDefaultBuilderPagePresetTree({
         page,

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

@@ -0,0 +1,316 @@
+import { type PhiCmsInstanceId } from "../../../types/cms-instance-id";
+/**
+ * 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 declare const PHI_BUILDER_SHELLS_TOUR: {
+    readonly id: "@phis/ui/modules/builder/shells";
+    readonly version: 1;
+    readonly steps: readonly [{
+        readonly key: "area";
+        readonly target: `cms:${PhiCmsInstanceId}`;
+        readonly title: "Which Area you are building";
+        readonly 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.";
+        readonly placement: "bottom";
+        readonly ifMissing: "skip";
+    }, {
+        readonly key: "shell";
+        readonly target: `cms:${PhiCmsInstanceId}:header_main`;
+        readonly title: "The frame of every Page";
+        readonly 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.";
+        readonly placement: "bottom";
+    }, {
+        readonly key: "regions";
+        readonly target: `cms:${PhiCmsInstanceId}:sider_left`;
+        readonly title: "Regions and what stands in them";
+        readonly 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.";
+        readonly placement: "right";
+    }, {
+        readonly key: "select";
+        readonly target: `cms:${PhiCmsInstanceId}:header_top` | `cms:${PhiCmsInstanceId}:header_bottom`;
+        readonly title: "Setting something up";
+        readonly description: "A click on a region, a Layout or a Widget opens its Inspector, where everything about it is set up.";
+        readonly placement: "bottom";
+    }, {
+        readonly key: "inspector";
+        readonly target: `cms:${PhiCmsInstanceId}`;
+        readonly title: "The Inspector";
+        readonly 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.";
+        readonly placement: "left";
+        readonly prepare: readonly [{
+            readonly receiver: `controller:${string}/${string}:${string}`;
+            readonly channel: "selection";
+            readonly action: "change";
+            readonly valueType: "json";
+            readonly valueSchema: `${string}/signals/${string}`;
+            readonly value: {
+                readonly nodeKind: "region";
+                readonly nodeKey: "region:header_top" | "region:header_bottom";
+                readonly regionKey: "header_top" | "header_bottom";
+                readonly regionType: number;
+            };
+        }];
+        readonly release: readonly [{
+            readonly receiver: `controller:${string}/${string}:${string}`;
+            readonly channel: "inspectorVisibility";
+            readonly action: "change";
+            readonly valueType: "boolean";
+            readonly value: false;
+        }];
+    }, ...{
+        readonly key: string;
+        readonly target: `cms:${PhiCmsInstanceId}`;
+        readonly title: string;
+        readonly description: string;
+        readonly placement: "left";
+        readonly ifMissing: "skip";
+        readonly prepare: readonly [{
+            readonly receiver: `controller:${string}/${string}:${string}`;
+            readonly channel: "selection";
+            readonly action: "change";
+            readonly valueType: "json";
+            readonly valueSchema: `${string}/signals/${string}`;
+            readonly value: {
+                readonly nodeKind: "layout";
+                readonly nodeKey: "layout";
+                readonly regionKey: "content" | "header_top";
+            };
+        }, {
+            readonly receiver: `cms:${PhiCmsInstanceId}`;
+            readonly channel: "slot";
+            readonly action: "open";
+            readonly valueType: "string";
+            readonly value: string;
+        }];
+        readonly release: readonly [{
+            readonly receiver: `controller:${string}/${string}:${string}`;
+            readonly channel: "inspectorVisibility";
+            readonly action: "change";
+            readonly valueType: "boolean";
+            readonly value: false;
+        }, {
+            readonly receiver: `cms:${PhiCmsInstanceId}`;
+            readonly channel: "slot";
+            readonly action: "open";
+            readonly valueType: "string";
+            readonly value: string;
+        }];
+    }[], {
+        readonly key: "mode";
+        readonly target: `cms:${PhiCmsInstanceId}`;
+        readonly title: "Editor and Preview";
+        readonly 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.";
+        readonly placement: "bottom";
+    }, {
+        readonly key: "sider";
+        readonly target: `cms:${PhiCmsInstanceId}`;
+        readonly title: "How tall the sider is";
+        readonly description: "Whether the left sider runs the full height of the Shell, or stands beside the content between header and footer.";
+        readonly placement: "bottom";
+        readonly ifMissing: "skip";
+    }, {
+        readonly key: "area-settings";
+        readonly target: `cms:${PhiCmsInstanceId}`;
+        readonly title: "What the Area says about itself";
+        readonly description: "What the Area's own address shows, how Page titles are built, and for the public Area whether search engines may find it.";
+        readonly placement: "bottom";
+    }, {
+        readonly key: "commands";
+        readonly target: `cms:${PhiCmsInstanceId}`;
+        readonly title: "Saving and publishing";
+        readonly 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.";
+        readonly placement: "bottom";
+    }, {
+        readonly key: "draft-status";
+        readonly target: `cms:${PhiCmsInstanceId}`;
+        readonly title: "Where your changes stand";
+        readonly description: "What you change here is a draft. Visitors see the published Shell until the draft is published.";
+        readonly 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 declare const PHI_BUILDER_PAGES_TOUR: {
+    readonly id: "@phis/ui/modules/builder/pages";
+    readonly version: 1;
+    readonly steps: readonly [{
+        readonly key: "area";
+        readonly target: `cms:${PhiCmsInstanceId}`;
+        readonly title: "Which Area you are building";
+        readonly 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.";
+        readonly placement: "bottom";
+        readonly ifMissing: "skip";
+    }, {
+        readonly key: "page-choice";
+        readonly target: `cms:${PhiCmsInstanceId}`;
+        readonly title: "Which Page you are building";
+        readonly description: "Every Page of the Area, the ones created here and the ones a Module brings.";
+        readonly placement: "bottom";
+    }, {
+        readonly key: "page";
+        readonly target: `cms:${PhiCmsInstanceId}:content`;
+        readonly title: "What belongs to this Page";
+        readonly 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.";
+        readonly placement: "top";
+    }, {
+        readonly key: "regions";
+        readonly target: `cms:${PhiCmsInstanceId}:hero`;
+        readonly title: "Regions and what stands in them";
+        readonly 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.";
+        readonly placement: "bottom";
+    }, {
+        readonly key: "select";
+        readonly target: `cms:${PhiCmsInstanceId}:header_top` | `cms:${PhiCmsInstanceId}:header_bottom`;
+        readonly title: "Setting something up";
+        readonly description: "A click on a region, a Layout or a Widget opens its Inspector, where everything about it is set up.";
+        readonly placement: "bottom";
+    }, {
+        readonly key: "inspector";
+        readonly target: `cms:${PhiCmsInstanceId}`;
+        readonly title: "The Inspector";
+        readonly 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.";
+        readonly placement: "left";
+        readonly prepare: readonly [{
+            readonly receiver: `controller:${string}/${string}:${string}`;
+            readonly channel: "selection";
+            readonly action: "change";
+            readonly valueType: "json";
+            readonly valueSchema: `${string}/signals/${string}`;
+            readonly value: {
+                readonly nodeKind: "region";
+                readonly nodeKey: "region:header_top" | "region:header_bottom";
+                readonly regionKey: "header_top" | "header_bottom";
+                readonly regionType: number;
+            };
+        }];
+        readonly release: readonly [{
+            readonly receiver: `controller:${string}/${string}:${string}`;
+            readonly channel: "inspectorVisibility";
+            readonly action: "change";
+            readonly valueType: "boolean";
+            readonly value: false;
+        }];
+    }, ...{
+        readonly key: string;
+        readonly target: `cms:${PhiCmsInstanceId}`;
+        readonly title: string;
+        readonly description: string;
+        readonly placement: "left";
+        readonly ifMissing: "skip";
+        readonly prepare: readonly [{
+            readonly receiver: `controller:${string}/${string}:${string}`;
+            readonly channel: "selection";
+            readonly action: "change";
+            readonly valueType: "json";
+            readonly valueSchema: `${string}/signals/${string}`;
+            readonly value: {
+                readonly nodeKind: "layout";
+                readonly nodeKey: "layout";
+                readonly regionKey: "content" | "header_top";
+            };
+        }, {
+            readonly receiver: `cms:${PhiCmsInstanceId}`;
+            readonly channel: "slot";
+            readonly action: "open";
+            readonly valueType: "string";
+            readonly value: string;
+        }];
+        readonly release: readonly [{
+            readonly receiver: `controller:${string}/${string}:${string}`;
+            readonly channel: "inspectorVisibility";
+            readonly action: "change";
+            readonly valueType: "boolean";
+            readonly value: false;
+        }, {
+            readonly receiver: `cms:${PhiCmsInstanceId}`;
+            readonly channel: "slot";
+            readonly action: "open";
+            readonly valueType: "string";
+            readonly value: string;
+        }];
+    }[], {
+        readonly key: "page-commands";
+        readonly target: `cms:${PhiCmsInstanceId}`;
+        readonly title: "New Pages and what a Page says";
+        readonly 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.";
+        readonly placement: "bottom";
+    }, {
+        readonly key: "mode";
+        readonly target: `cms:${PhiCmsInstanceId}`;
+        readonly title: "Editor and Preview";
+        readonly 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.";
+        readonly placement: "bottom";
+    }, {
+        readonly key: "commands";
+        readonly target: `cms:${PhiCmsInstanceId}`;
+        readonly title: "Saving and publishing";
+        readonly 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.";
+        readonly placement: "bottom";
+    }, {
+        readonly key: "draft-status";
+        readonly target: `cms:${PhiCmsInstanceId}`;
+        readonly title: "Where your changes stand";
+        readonly description: "What you change here is a draft. Visitors see the published Page until the draft is published.";
+        readonly placement: "bottom";
+    }];
+};
+/**
+ * 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 declare const PHI_BUILDER_NAVIGATION_TOUR: {
+    readonly id: "@phis/ui/modules/builder/navigation";
+    readonly version: 1;
+    readonly steps: readonly [{
+        readonly key: "choice";
+        readonly target: `cms:${PhiCmsInstanceId}:filters`;
+        readonly title: "Which navigation";
+        readonly 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.";
+        readonly placement: "bottom";
+        readonly ifMissing: "skip";
+    }, {
+        readonly key: "source";
+        readonly target: `cms:${PhiCmsInstanceId}`;
+        readonly title: "The Pages to link";
+        readonly 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.";
+        readonly placement: "right";
+    }, {
+        readonly key: "items";
+        readonly target: `cms:${PhiCmsInstanceId}:header`;
+        readonly title: "What the navigation holds";
+        readonly 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.";
+        readonly placement: "bottom";
+    }, {
+        readonly key: "add";
+        readonly target: `cms:${PhiCmsInstanceId}:toolbar`;
+        readonly title: "Links, containers, separators";
+        readonly 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.";
+        readonly placement: "bottom";
+        readonly ifMissing: "skip";
+    }, {
+        readonly key: "row-actions";
+        readonly target: `cms:${PhiCmsInstanceId}:row-actions`;
+        readonly title: "Hiding and deleting";
+        readonly 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.";
+        readonly placement: "left";
+        readonly ifMissing: "skip";
+    }, {
+        readonly key: "commands";
+        readonly target: `cms:${PhiCmsInstanceId}`;
+        readonly title: "Saving and publishing";
+        readonly 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.";
+        readonly placement: "bottom";
+    }, {
+        readonly key: "draft-status";
+        readonly target: `cms:${PhiCmsInstanceId}`;
+        readonly title: "Where your changes stand";
+        readonly description: "What you change here is a draft. Visitors see the published navigation until the draft is published.";
+        readonly placement: "bottom";
+    }];
+};