@phis/ui 0.3.0 → 0.4.0

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

package/helpers/cms-layout-defaults.js

@@ -1,6 +1,7 @@
 import { PHI_SPACE } from "../theme/antd-css-var-contract";
 import { PHI_RENDERABLE_BLOCK_DEFAULT_ANCHOR } from "./renderable-block-defaults";
 import { isPhiRecord } from "./is-record";
+import { PHI_SEQUENCE_DEFAULT_DURATION_MS, PHI_SEQUENCE_DEFAULT_EASING } from "./motion";
 import { PHI_SURFACE_CARD } from "./surface-presets";
 import { PHI_GRID_LAYOUT_DEFAULT_COLUMNS } from "../components/layouts/phi-grid-contract";
 import { PHI_MASONRY_LAYOUT_DEFAULT_COLUMNS } from "../components/layouts/phi-masonry-contract";
@@ -119,9 +120,13 @@ const PHI_STACK_LAYOUT_PANEL_PRESET = {
 };
 const PHI_CAROUSEL_LAYOUT_DEFAULTS = {
     // A slide is what tells somebody the slots are a run rather than a set, so it is the opening
-    // impression rather than a preference to be discovered. Everything else is left absent: the
-    // duration then follows the theme, and the window shows one slot until somebody widens it.
+    // impression rather than a preference to be discovered. The window shows one slot until
+    // somebody widens it. The pace is the sequence's own, stated so the Inspector shows the number
+    // in effect rather than an empty box.
     transition: "slide",
+    transitionDurationMs: PHI_SEQUENCE_DEFAULT_DURATION_MS,
+    transitionEasing: PHI_SEQUENCE_DEFAULT_EASING,
+    slotGap: "none",
     visibleSlots: 1,
     windowAnchor: "start",
     /*
@@ -134,6 +139,8 @@ const PHI_CAROUSEL_LAYOUT_DEFAULTS = {
      */
     controls: "arrows",
     loop: false,
+    autoplayMs: 0,
+    lookahead: 1,
 };
 const PHI_CAROUSEL_LAYOUT_PANEL_PRESET = {
     padding: PHI_SPACE.base,

package/helpers/cms-region-keys.d.ts

@@ -33,5 +33,5 @@ export declare function resolvePhiCmsRegionOwnership(regionKey: string | null |
  * know is not a placement anybody chose -- refusing it would hide Widgets over a typo.
  */
 export declare function phiCmsRegionAcceptsWidget(regionKey: string | null | undefined, required: PhiCmsRegionOwnership | null | undefined): boolean;
-export declare function resolvePhiCmsRegionType(regionKey: string | null | undefined): 10 | 40 | 50 | 11 | 12 | 20 | 21 | 25 | 30 | 39 | 41;
+export declare function resolvePhiCmsRegionType(regionKey: string | null | undefined): 10 | 40 | 12 | 50 | 11 | 20 | 21 | 25 | 30 | 39 | 41;
 export declare function resolvePhiCmsRegionKey(regionType: number | null | undefined): "content" | "header_top" | "header_main" | "header_bottom" | "sider_left" | "sider_right" | "hero" | "footer_top" | "footer_main" | "footer_bottom" | "drawer_right" | undefined;

package/helpers/motion.d.ts

@@ -43,6 +43,13 @@ export declare const PHI_SEQUENCE_TRANSITION_MAX_MS = 600000;
  * exactly, so the grid the spinner walks holds every value it offers.
  */
 export declare const PHI_SEQUENCE_TRANSITION_STEP_MS = 100;
+/**
+ * What a sequence that says nothing moves at: long enough to read as movement, short enough to
+ * ignore. Exported so that a Widget can state it as its default and the Inspector shows the number
+ * that is actually in effect instead of an empty box.
+ */
+export declare const PHI_SEQUENCE_DEFAULT_DURATION_MS = 320;
+export declare const PHI_SEQUENCE_DEFAULT_EASING: PhiMotionEasing;
 /**
  * The two ways of showing a sequence, and which end of a wider window an index means.
  *

package/helpers/motion.js

@@ -58,6 +58,13 @@ export const PHI_SEQUENCE_TRANSITION_MAX_MS = 600_000;
  * exactly, so the grid the spinner walks holds every value it offers.
  */
 export const PHI_SEQUENCE_TRANSITION_STEP_MS = 100;
+/**
+ * What a sequence that says nothing moves at: long enough to read as movement, short enough to
+ * ignore. Exported so that a Widget can state it as its default and the Inspector shows the number
+ * that is actually in effect instead of an empty box.
+ */
+export const PHI_SEQUENCE_DEFAULT_DURATION_MS = 320;
+export const PHI_SEQUENCE_DEFAULT_EASING = "ease-in-out";
 /**
  * The two ways of showing a sequence, and which end of a wider window an index means.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phis/ui",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "license": "Apache-2.0",
   "publishConfig": {
     "access": "public"

package/plugins/runtime-modules/asset/data-providers.d.ts

@@ -25,6 +25,7 @@ export declare const PHI_ASSET_RUNTIME_DATA_PROVIDER_DESCRIPTORS: ({
     settingsFields: ({
         key: string;
         type: "choice";
+        heading: string;
         label: string;
         optionsProvider: {
             providerKey: `${string}/${string}`;
@@ -38,6 +39,7 @@ export declare const PHI_ASSET_RUNTIME_DATA_PROVIDER_DESCRIPTORS: ({
         type: "boolean";
         label: string;
         description: string;
+        heading?: undefined;
         optionsProvider?: undefined;
         options?: undefined;
         min?: undefined;
@@ -50,6 +52,7 @@ export declare const PHI_ASSET_RUNTIME_DATA_PROVIDER_DESCRIPTORS: ({
             value: string;
             label: string;
         }[];
+        heading?: undefined;
         optionsProvider?: undefined;
         description?: undefined;
         min?: undefined;
@@ -60,6 +63,7 @@ export declare const PHI_ASSET_RUNTIME_DATA_PROVIDER_DESCRIPTORS: ({
         label: string;
         min: number;
         max: number;
+        heading?: undefined;
         optionsProvider?: undefined;
         description?: undefined;
         options?: undefined;

package/plugins/runtime-modules/asset/data-providers.js

@@ -36,6 +36,7 @@ export const PHI_ASSET_RUNTIME_DATA_PROVIDER_DESCRIPTORS = [
             {
                 key: "folderId",
                 type: "choice",
+                heading: "Folder",
                 label: "Folder",
                 optionsProvider: { providerKey: PHI_ASSET_RUNTIME_DATA_PROVIDER_KEYS.mediaFolderChoices },
             },

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

@@ -32,6 +32,7 @@ export declare const PHI_ASSET_RUNTIME_MODULE_DEFINITION: {
         settingsFields: ({
             key: string;
             type: "choice";
+            heading: string;
             label: string;
             optionsProvider: {
                 providerKey: `${string}/${string}`;
@@ -45,6 +46,7 @@ export declare const PHI_ASSET_RUNTIME_MODULE_DEFINITION: {
             type: "boolean";
             label: string;
             description: string;
+            heading?: undefined;
             optionsProvider?: undefined;
             options?: undefined;
             min?: undefined;
@@ -57,6 +59,7 @@ export declare const PHI_ASSET_RUNTIME_MODULE_DEFINITION: {
                 value: string;
                 label: string;
             }[];
+            heading?: undefined;
             optionsProvider?: undefined;
             description?: undefined;
             min?: undefined;
@@ -67,6 +70,7 @@ export declare const PHI_ASSET_RUNTIME_MODULE_DEFINITION: {
             label: string;
             min: number;
             max: number;
+            heading?: undefined;
             optionsProvider?: undefined;
             description?: undefined;
             options?: undefined;

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

@@ -1,2 +1,54 @@
 import type { PhiCmsRoutePresetDescriptor } from "../../../types/cms-module-descriptors";
-export declare const PHI_ASSET_RUNTIME_MODULE_ROUTES: PhiCmsRoutePresetDescriptor[];
+export declare const PHI_ASSET_RUNTIME_MODULE_ROUTES: (PhiCmsRoutePresetDescriptor | {
+    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";
+        }];
+    };
+    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/asset/presets.js

@@ -1,18 +1,22 @@
 import { PHI_ASSET_RUNTIME_MODULE_ID } from "./ids";
 import { buildPhiSidebarRoutePresetDescriptor } from "../sidebar-route";
+import { PHI_ASSET_MEDIA_TOUR } from "./tour";
 export const PHI_ASSET_RUNTIME_MODULE_ROUTES = [
-    buildPhiSidebarRoutePresetDescriptor({
-        area: "builder",
-        anchor: "main",
-        ownerModuleId: PHI_ASSET_RUNTIME_MODULE_ID,
-        presetKey: "builder-media-page",
-        title: "Media",
-        path: "/media",
-        itemKey: "@phis/ui/modules/asset/nav/builder/media",
-        icon: "antd:picture",
-        loadTree: ({ page, runtime }) => import("./trees/phi-default-builder-media-page-tree")
-            .then((module) => module.buildPhiDefaultBuilderMediaPageTree({ page, runtime })),
-    }),
+    {
+        ...buildPhiSidebarRoutePresetDescriptor({
+            area: "builder",
+            anchor: "main",
+            ownerModuleId: PHI_ASSET_RUNTIME_MODULE_ID,
+            presetKey: "builder-media-page",
+            title: "Media",
+            path: "/media",
+            itemKey: "@phis/ui/modules/asset/nav/builder/media",
+            icon: "antd:picture",
+            loadTree: ({ page, runtime }) => import("./trees/phi-default-builder-media-page-tree")
+                .then((module) => module.buildPhiDefaultBuilderMediaPageTree({ page, runtime })),
+        }),
+        tour: PHI_ASSET_MEDIA_TOUR,
+    },
     buildPhiSidebarRoutePresetDescriptor({
         area: "admin",
         anchor: "settings",