@phis/ui 0.3.0 → 0.4.0

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

@@ -1,46 +1,27 @@
+import { type PhiMediaAspectRatio } from "../../../../../components/media/aspect-ratios";
+import { type PhiSequenceSettings } from "../../../../../components/widgets/config/sequence-settings";
+import type { PhiImageAssetVariantKeyValue } from "../../../../../types/media";
 import { type PhiRuntimeDataProviderBinding } from "../../../../../types/runtime-data-provider";
-import { type PhiMotionEasing, type PhiSequenceAnchor, type PhiSequenceTransition } from "../../../../../helpers/motion";
-import { type PhiCmsMountPolicy } from "../../../../../types/cms-mount-policy";
 import { type PhiCmsWidgetConfigBase } from "../../../../../components/widgets/config/parser-primitives";
 /**
  * A run of pictures, shown a few at a time.
  *
  * Not a layout. A layout's slots are authored -- twelve of them, and somebody drops a Widget into
  * each -- while the pictures here are data: however many a Media Folder holds, read on the server
- * while the page is drawn through the record Provider the binding names. A Carousel over authored
- * slots could never show them, which is why the two are separate things that share a viewport rather
- * than one thing with a switch.
+ * while the page is drawn through the Folder Provider. A Carousel over authored slots could never show
+ * them, which is why the two are separate things that share a viewport rather than one thing with a
+ * switch. How the run moves is the shared vocabulary of `sequence-settings.ts`.
  */
-export type PhiCmsGalleryWidgetConfig = PhiCmsWidgetConfigBase & {
-    /** The record Provider the pictures come from; starts on the Media Folder Provider. */
+export type PhiCmsGalleryWidgetConfig = PhiCmsWidgetConfigBase & PhiSequenceSettings & {
+    /** The Folder the pictures come from: always the Media Folder Provider, with its parameters. */
     source: PhiRuntimeDataProviderBinding | null;
     /** The rendition each picture is drawn in; absent is the original. */
-    variantKey?: string;
+    variantKey?: PhiImageAssetVariantKeyValue;
     /** Opens a picture larger over the page when clicked. */
     preview?: boolean;
-    visibleCount?: number;
-    windowAnchor?: PhiSequenceAnchor;
-    transition?: PhiSequenceTransition;
-    durationMs?: number;
-    easing?: PhiMotionEasing;
-    gap?: string;
-    /**
-     * How many pictures 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 picture 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;
-    aspectRatio?: string;
+    /** The frame's proportion for originals; a variant brings its own. */
+    aspectRatio?: PhiMediaAspectRatio;
     fit?: "cover" | "contain";
-    controls?: "none" | "arrows" | "dots" | "both";
-    loop?: boolean;
-    /** Absent or zero means it does not move on its own. */
-    autoplayMs?: number;
 };
 export declare function parsePhiCmsGalleryWidgetConfig(raw: Record<string, unknown>): PhiCmsGalleryWidgetConfig;
 export declare const PHI_GALLERY_WIDGET_DEFINITION: {
@@ -53,147 +34,359 @@ export declare const PHI_GALLERY_WIDGET_DEFINITION: {
     category: "media";
     icon: string;
     iconFamily: string;
-    fields: ({
+    fields: (({
         key: string;
+        label: string;
+        description?: string;
+        required?: boolean;
+        editorPlacement?: "inspector" | "geometry" | "toolbar";
+        visibleWhen?: import("../../../../../types").PhiCmsConfigFieldVisibilityRule | readonly import("../../../../../types").PhiCmsConfigFieldVisibilityRule[];
+        heading?: string;
+    } & {
+        type: "string" | "url" | "icon";
+        emptyValue?: "";
+    }) | ({
+        key: string;
+        label: string;
+        description?: string;
+        required?: boolean;
+        editorPlacement?: "inspector" | "geometry" | "toolbar";
+        visibleWhen?: import("../../../../../types").PhiCmsConfigFieldVisibilityRule | readonly import("../../../../../types").PhiCmsConfigFieldVisibilityRule[];
+        heading?: string;
+    } & {
+        type: "link-target";
+        clearsWhenEmpty?: readonly string[];
+    }) | ({
+        key: string;
+        label: string;
+        description?: string;
+        required?: boolean;
+        editorPlacement?: "inspector" | "geometry" | "toolbar";
+        visibleWhen?: import("../../../../../types").PhiCmsConfigFieldVisibilityRule | readonly import("../../../../../types").PhiCmsConfigFieldVisibilityRule[];
+        heading?: string;
+    } & {
+        type: "readonly";
+    }) | ({
+        key: string;
+        label: string;
+        description?: string;
+        required?: boolean;
+        editorPlacement?: "inspector" | "geometry" | "toolbar";
+        visibleWhen?: import("../../../../../types").PhiCmsConfigFieldVisibilityRule | readonly import("../../../../../types").PhiCmsConfigFieldVisibilityRule[];
+        heading?: string;
+    } & {
         type: "data-provider";
-        providerKind: "record";
-        label: string;
-        description: string;
-        options?: undefined;
-        emptyOption?: undefined;
-        emptyValue?: undefined;
-        min?: undefined;
-        max?: undefined;
-        step?: undefined;
-        prefix?: undefined;
-    } | {
+        providerKind?: import("../../../../../types").PhiRuntimeDataProviderKind;
+        providerKey?: import("@phis/contracts/controls").PhiRuntimeDataProviderKey;
+    }) | ({
         key: string;
-        type: "choice";
         label: string;
-        options: {
-            value: string;
-            label: string;
-        }[];
-        emptyOption: {
-            value: string;
-            label: string;
-        };
-        emptyValue: null;
-        providerKind?: undefined;
-        description?: undefined;
-        min?: undefined;
-        max?: undefined;
-        step?: undefined;
-        prefix?: undefined;
-    } | {
+        description?: string;
+        required?: boolean;
+        editorPlacement?: "inspector" | "geometry" | "toolbar";
+        visibleWhen?: import("../../../../../types").PhiCmsConfigFieldVisibilityRule | readonly import("../../../../../types").PhiCmsConfigFieldVisibilityRule[];
+        heading?: string;
+    } & {
+        type: "calendar-adapter";
+    }) | ({
+        key: string;
+        label: string;
+        description?: string;
+        required?: boolean;
+        editorPlacement?: "inspector" | "geometry" | "toolbar";
+        visibleWhen?: import("../../../../../types").PhiCmsConfigFieldVisibilityRule | readonly import("../../../../../types").PhiCmsConfigFieldVisibilityRule[];
+        heading?: string;
+    } & {
+        type: "video-provider";
+    }) | ({
+        key: string;
+        label: string;
+        description?: string;
+        required?: boolean;
+        editorPlacement?: "inspector" | "geometry" | "toolbar";
+        visibleWhen?: import("../../../../../types").PhiCmsConfigFieldVisibilityRule | readonly import("../../../../../types").PhiCmsConfigFieldVisibilityRule[];
+        heading?: string;
+    } & {
+        type: "dimension";
+        widthKey?: string;
+        heightKey?: string;
+        widthPlaceholder?: string;
+        heightPlaceholder?: string;
+        patchOnChange?: Record<string, unknown>;
+    }) | ({
+        key: string;
+        label: string;
+        description?: string;
+        required?: boolean;
+        editorPlacement?: "inspector" | "geometry" | "toolbar";
+        visibleWhen?: import("../../../../../types").PhiCmsConfigFieldVisibilityRule | readonly import("../../../../../types").PhiCmsConfigFieldVisibilityRule[];
+        heading?: string;
+    } & {
+        type: "length";
+        min?: number;
+        max?: number;
+        step?: number;
+        precision?: number;
+    }) | ({
+        key: string;
+        label: string;
+        description?: string;
+        required?: boolean;
+        editorPlacement?: "inspector" | "geometry" | "toolbar";
+        visibleWhen?: import("../../../../../types").PhiCmsConfigFieldVisibilityRule | readonly import("../../../../../types").PhiCmsConfigFieldVisibilityRule[];
+        heading?: string;
+    } & {
+        type: "radius";
+        topLeftKey: string;
+        topRightKey: string;
+        bottomLeftKey: string;
+        bottomRightKey: string;
+    }) | ({
+        key: string;
+        label: string;
+        description?: string;
+        required?: boolean;
+        editorPlacement?: "inspector" | "geometry" | "toolbar";
+        visibleWhen?: import("../../../../../types").PhiCmsConfigFieldVisibilityRule | readonly import("../../../../../types").PhiCmsConfigFieldVisibilityRule[];
+        heading?: string;
+    } & {
+        type: "padding";
+        paddingKey?: string;
+        gapKey?: string;
+        paddingTopKey?: string;
+        paddingRightKey?: string;
+        paddingBottomKey?: string;
+        paddingLeftKey?: string;
+        section?: string;
+    }) | ({
+        key: string;
+        label: string;
+        description?: string;
+        required?: boolean;
+        editorPlacement?: "inspector" | "geometry" | "toolbar";
+        visibleWhen?: import("../../../../../types").PhiCmsConfigFieldVisibilityRule | readonly import("../../../../../types").PhiCmsConfigFieldVisibilityRule[];
+        heading?: string;
+    } & {
+        type: "color";
+        mode?: import("../../../../../types").PhiCmsConfigFieldColorMode;
+        defaultToken?: import("../../../../../theme/phi-theme-tokens").PhiThemeTokenKey;
+        section?: string;
+    }) | ({
         key: string;
+        label: string;
+        description?: string;
+        required?: boolean;
+        editorPlacement?: "inspector" | "geometry" | "toolbar";
+        visibleWhen?: import("../../../../../types").PhiCmsConfigFieldVisibilityRule | readonly import("../../../../../types").PhiCmsConfigFieldVisibilityRule[];
+        heading?: string;
+    } & {
         type: "boolean";
+    }) | ({
+        key: string;
         label: string;
-        description: string;
-        providerKind?: undefined;
-        options?: undefined;
-        emptyOption?: undefined;
-        emptyValue?: undefined;
-        min?: undefined;
-        max?: undefined;
-        step?: undefined;
-        prefix?: undefined;
-    } | {
+        description?: string;
+        required?: boolean;
+        editorPlacement?: "inspector" | "geometry" | "toolbar";
+        visibleWhen?: import("../../../../../types").PhiCmsConfigFieldVisibilityRule | readonly import("../../../../../types").PhiCmsConfigFieldVisibilityRule[];
+        heading?: string;
+    } & {
+        type: "image";
+    }) | ({
         key: string;
-        type: "number";
         label: string;
-        min: number;
-        providerKind?: undefined;
-        description?: undefined;
-        options?: undefined;
-        emptyOption?: undefined;
-        emptyValue?: undefined;
-        max?: undefined;
-        step?: undefined;
-        prefix?: undefined;
-    } | {
+        description?: string;
+        required?: boolean;
+        editorPlacement?: "inspector" | "geometry" | "toolbar";
+        visibleWhen?: import("../../../../../types").PhiCmsConfigFieldVisibilityRule | readonly import("../../../../../types").PhiCmsConfigFieldVisibilityRule[];
+        heading?: string;
+    } & {
+        type: "slot-texts";
+    }) | ({
         key: string;
-        type: "choice";
         label: string;
-        options: {
-            value: string;
+        description?: string;
+        required?: boolean;
+        editorPlacement?: "inspector" | "geometry" | "toolbar";
+        visibleWhen?: import("../../../../../types").PhiCmsConfigFieldVisibilityRule | readonly import("../../../../../types").PhiCmsConfigFieldVisibilityRule[];
+        heading?: string;
+    } & {
+        type: "number-list";
+        min?: number;
+    }) | ({
+        key: string;
+        label: string;
+        description?: string;
+        required?: boolean;
+        editorPlacement?: "inspector" | "geometry" | "toolbar";
+        visibleWhen?: import("../../../../../types").PhiCmsConfigFieldVisibilityRule | readonly import("../../../../../types").PhiCmsConfigFieldVisibilityRule[];
+        heading?: string;
+    } & {
+        type: "flags";
+        options: readonly {
+            value: number;
             label: string;
         }[];
-        providerKind?: undefined;
-        description?: undefined;
-        emptyOption?: undefined;
-        emptyValue?: undefined;
-        min?: undefined;
-        max?: undefined;
-        step?: undefined;
-        prefix?: undefined;
-    } | {
+    }) | ({
         key: string;
+        label: string;
+        description?: string;
+        required?: boolean;
+        editorPlacement?: "inspector" | "geometry" | "toolbar";
+        visibleWhen?: import("../../../../../types").PhiCmsConfigFieldVisibilityRule | readonly import("../../../../../types").PhiCmsConfigFieldVisibilityRule[];
+        heading?: string;
+    } & {
         type: "number";
+        min?: number;
+        max?: number;
+        step?: number;
+        precision?: number;
+        prefix?: string;
+        presentation?: "slider";
+        suffix?: string;
+    }) | ({
+        key: string;
         label: string;
-        min: number;
-        max: number;
-        step: number;
-        prefix: string;
-        providerKind?: undefined;
-        description?: undefined;
-        options?: undefined;
-        emptyOption?: undefined;
-        emptyValue?: undefined;
-    } | {
-        key: string;
-        type: "string";
-        label: string;
-        providerKind?: undefined;
-        description?: undefined;
-        options?: undefined;
-        emptyOption?: undefined;
-        emptyValue?: undefined;
-        min?: undefined;
-        max?: undefined;
-        step?: undefined;
-        prefix?: undefined;
-    } | {
+        description?: string;
+        required?: boolean;
+        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?: Exclude<import("../../../../../types").PhiCmsConfigFieldChoiceValueType, "number">;
+        presentation?: import("../../../../../types").PhiCmsConfigFieldChoicePresentation;
+        options?: import("@phis/contracts/controls").PhiControlOption[];
+        optionsProvider?: import("@phis/contracts/controls").PhiControlOptionsProviderConfig;
+        allowCustom?: boolean;
+        createBehavior?: import("../../../../../types").PhiCmsConfigFieldChoiceCreateBehavior;
+        placeholder?: string;
+        filter?: import("../../../../../types").PhiCmsConfigFieldChoiceFilter;
+        emptyOption?: import("@phis/contracts/controls").PhiControlOption;
+        emptyValue?: null | undefined;
+        patchOnChange?: Record<string, unknown>;
+        optionPresets?: import("../../../../../types/cms-plugins").PhiCmsConfigFieldOptionPresets;
+    }) | ({
+        key: string;
         label: string;
-        options: ({
-            readonly value: "remount";
-            readonly label: "Remount on return";
-        } | {
-            readonly value: "lazy-keep";
-            readonly label: "Keep once shown";
-        } | {
-            readonly value: "eager";
-            readonly label: "Mount everything";
-        })[];
-        providerKind?: undefined;
-        description?: undefined;
-        emptyOption?: undefined;
-        emptyValue?: undefined;
-        min?: undefined;
-        max?: undefined;
-        step?: undefined;
-        prefix?: undefined;
-    } | {
+        description?: string;
+        required?: boolean;
+        editorPlacement?: "inspector" | "geometry" | "toolbar";
+        visibleWhen?: import("../../../../../types").PhiCmsConfigFieldVisibilityRule | readonly import("../../../../../types").PhiCmsConfigFieldVisibilityRule[];
+        heading?: string;
+    } & {
+        type: "collection";
+        itemKeyField: string;
+        itemLabelField?: string;
+        itemFields: import("../../../../../types").PhiCmsConfigField[];
+        defaultItem?: Record<string, unknown>;
+        addLabel?: string;
+        emptyLabel?: string;
+        minItems?: number;
+        maxItems?: number;
+        reorderable?: boolean;
+        presentation?: import("../../../../../types").PhiCmsConfigFieldCollectionPresentation;
+        editLabel?: string;
+    }) | ({
         key: string;
-        type: "boolean";
         label: string;
-        providerKind?: undefined;
-        description?: undefined;
-        options?: undefined;
-        emptyOption?: undefined;
-        emptyValue?: undefined;
-        min?: undefined;
-        max?: undefined;
-        step?: undefined;
-        prefix?: undefined;
+        description?: string;
+        required?: boolean;
+        editorPlacement?: "inspector" | "geometry" | "toolbar";
+        visibleWhen?: import("../../../../../types").PhiCmsConfigFieldVisibilityRule | readonly import("../../../../../types").PhiCmsConfigFieldVisibilityRule[];
+        heading?: string;
+    } & {
+        type: "background";
+        section?: string;
+        storage?: import("../../../../../types").PhiCmsConfigFieldValueStorage;
+    }) | ({
+        key: string;
+        label: string;
+        description?: string;
+        required?: boolean;
+        editorPlacement?: "inspector" | "geometry" | "toolbar";
+        visibleWhen?: import("../../../../../types").PhiCmsConfigFieldVisibilityRule | readonly import("../../../../../types").PhiCmsConfigFieldVisibilityRule[];
+        heading?: string;
+    } & {
+        type: "border";
+        section?: string;
+        storage?: import("../../../../../types").PhiCmsConfigFieldValueStorage;
+    }) | ({
+        key: string;
+        label: string;
+        description?: string;
+        required?: boolean;
+        editorPlacement?: "inspector" | "geometry" | "toolbar";
+        visibleWhen?: import("../../../../../types").PhiCmsConfigFieldVisibilityRule | readonly import("../../../../../types").PhiCmsConfigFieldVisibilityRule[];
+        heading?: string;
+    } & {
+        type: "surface";
+        tone?: false;
+    }) | ({
+        key: string;
+        label: string;
+        description?: string;
+        required?: boolean;
+        editorPlacement?: "inspector" | "geometry" | "toolbar";
+        visibleWhen?: import("../../../../../types").PhiCmsConfigFieldVisibilityRule | readonly import("../../../../../types").PhiCmsConfigFieldVisibilityRule[];
+        heading?: string;
+    } & {
+        type: "shadow" | "grid-placement" | "column-count";
+        section?: string;
+    }) | {
+        key: string;
+        type: "choice";
+        label: string;
+        options: {
+            value: "16:9" | "3:2" | "4:3" | "1:1" | "3:4" | "2:3" | "9:16" | "21:9";
+            label: "16:9" | "3:2" | "4:3" | "1:1" | "3:4" | "2:3" | "9:16" | "21:9";
+        }[];
+        visibleWhen: {
+            field: string;
+            equals: null;
+        };
     })[];
     defaultConfig: {
+        visibleCount: 1;
+        transition: "slide";
+        durationMs: 320;
+        easing: "linear" | "ease" | "ease-in" | "ease-out" | "ease-in-out";
+        gap: "xs";
+        lookahead: 1;
+        mountPolicy: "lazy-keep";
+        controls: "both";
+        loop: false;
+        autoplayMs: 0;
         source: {
             providerKey: `${string}/${string}`;
             params: {};
         };
+        preview: false;
+        aspectRatio: "16:9" | "3:2" | "4:3" | "1:1" | "3:4" | "2:3" | "9:16" | "21:9";
+        fit: "cover";
     };
     parseConfig: typeof parsePhiCmsGalleryWidgetConfig;
 };