@phis/ui 0.2.0 → 0.3.0

package/plugins/runtime-modules/asset/controller/definition.js

@@ -1,8 +1,8 @@
-import { PHI_SIGNAL_VALUE_SCHEMAS, } from "../../../../types/signals";
+import { PHI_SIGNAL_VALUE_SCHEMAS, readPhiSignalRouteSet, } from "../../../../types/signals";
 import { PHI_ASSET_CONTROLLER_KEY, PHI_ASSET_CONTROLLER_PLUGIN_KEY, } from "../../../../components/media/asset-controller-address";
 import { PHI_ASSET_SIGNAL_CHANNELS } from "../../../../components/media/asset-controller-signals";
-export function parsePhiAssetRuntimeControllerConfig() {
-    return {};
+function parsePhiAssetRuntimeControllerConfig(raw) {
+    return { signalRoutes: readPhiSignalRouteSet(raw.signalRoutes) };
 }
 export const PHI_ASSET_RUNTIME_CONTROLLER_DEFINITION = {
     kind: "controller",
@@ -20,17 +20,29 @@ export const PHI_ASSET_RUNTIME_CONTROLLER_DEFINITION = {
                 valueType: "json",
                 valueSchema: PHI_SIGNAL_VALUE_SCHEMAS.pagination,
             },
-            { id: "dialogClose", action: "close", valueType: "none" },
-            { id: "dialogOpen", action: "open", valueType: "none" },
-            { id: "formSubmit", action: "activate", valueType: "none" },
-            { id: "formReset", action: "activate", valueType: "none" },
-            { id: "reload", action: "activate", valueType: "none" },
+            { id: "inspectorOpen", action: "open", valueType: "none" },
+            { id: "inspectorClose", action: "close", valueType: "none" },
             {
-                id: "formValues",
+                id: "metadataValues",
                 action: "change",
                 valueType: "json",
                 valueSchema: PHI_SIGNAL_VALUE_SCHEMAS.formValues,
             },
+            { id: "metadataSubmit", action: "activate", valueType: "none" },
+            { id: "metadataReset", action: "activate", valueType: "none" },
+            { id: "inspectorSubmitting", action: "change", valueType: "boolean" },
+            { id: "folderDialogOpen", action: "open", valueType: "none" },
+            { id: "folderDialogClose", action: "close", valueType: "none" },
+            {
+                id: "folderValues",
+                action: "change",
+                valueType: "json",
+                valueSchema: PHI_SIGNAL_VALUE_SCHEMAS.formValues,
+            },
+            { id: "folderSubmit", action: "activate", valueType: "none" },
+            { id: "folderReset", action: "activate", valueType: "none" },
+            { id: "folderSubmitting", action: "change", valueType: "boolean" },
+            { id: "collectionReload", action: "activate", valueType: "none" },
         ],
         listens: [
             {
@@ -123,6 +135,6 @@ export const PHI_ASSET_RUNTIME_CONTROLLER_DEFINITION = {
             },
         ],
     },
-    defaultConfig: {},
+    defaultConfig: { signalRoutes: null },
     parseConfig: parsePhiAssetRuntimeControllerConfig,
 };

package/plugins/runtime-modules/asset/controller/mount.d.ts

@@ -1,4 +1,7 @@
-import type { PhiRuntimeControllerMountScope } from "../../../../types";
-export declare function PhiAssetRuntimeControllerMount({ mountScope, }: {
+import type { PhiAssetRuntimeControllerConfig } from "./definition";
+import type { PhiRuntimeControllerMountScope, PhiSignalAddress } from "../../../../types";
+export declare function PhiAssetRuntimeControllerMount({ address, mountScope, config, }: {
+    address: PhiSignalAddress;
     mountScope: PhiRuntimeControllerMountScope;
+    config: PhiAssetRuntimeControllerConfig;
 }): null;

package/plugins/runtime-modules/asset/controller/mount.js

@@ -1,6 +1,6 @@
 "use client";
 import { usePhiAssetRuntimeController } from "./runtime";
-export function PhiAssetRuntimeControllerMount({ mountScope, }) {
-    usePhiAssetRuntimeController(mountScope);
+export function PhiAssetRuntimeControllerMount({ address, mountScope, config, }) {
+    usePhiAssetRuntimeController({ address, mountScope, config });
     return null;
 }

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

@@ -1 +1,8 @@
-export declare function usePhiAssetRuntimeController(mountScope: "site" | "area" | "page"): import("../../../../components/media/phi-image-preview-store").PhiImagePreviewStoreState;
+import type { PhiSignalAddress } from "../../../../types/signals";
+import type { PhiRuntimeControllerMountScope } from "../../../../types";
+import type { PhiAssetRuntimeControllerConfig } from "./definition";
+export declare function usePhiAssetRuntimeController({ address, mountScope, config, }: {
+    address: PhiSignalAddress;
+    mountScope: PhiRuntimeControllerMountScope;
+    config: PhiAssetRuntimeControllerConfig;
+}): import("../../../../components/media/phi-image-preview-store").PhiImagePreviewStoreState;

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

@@ -1,25 +1,14 @@
 "use client";
-import { useCallback, useEffect, useState } from "react";
+import { isPhiRecord } from "../../../../helpers/is-record";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { bumpPhiImagePreviewRefreshToken, setPhiImagePreviewFlags, setPhiImagePreviewFolderId, setPhiImagePreviewFolderPath, setPhiImagePreviewKind, setPhiImagePreviewPage, setPhiImagePreviewPageSize, setPhiImagePreviewSearchQuery, usePhiImagePreviewStore, } from "../../../../components/media/phi-image-preview-store";
 import { PhiMediaAssetFlags, PhiMediaKind } from "../../../../constants/media";
-import { PHI_SIGNAL_VALUE_SCHEMAS, createPhiSignalAddress, createPhiSignalSubcontrolAddress } from "../../../../types/signals";
-import { usePhiSignalListener } from "../../../../components/runtime/runtime-signal-bus";
-import { usePhiSignalEmitter } from "../../../../components/runtime/runtime-signal-identity";
-import { createPhiRuntimeFormControllerAddress } from "../../../../components/forms/runtime-form-controller-address";
-import { createPhiAssetControllerAddress } from "../../../../components/media/asset-controller-address";
+import { PHI_SIGNAL_VALUE_SCHEMAS } from "../../../../types/signals";
+import { usePhiSignalDispatcher, usePhiSignalListener } from "../../../../components/runtime/runtime-signal-bus";
+import { dispatchPhiSignalCapability, usePhiSignalEmitter, } from "../../../../components/runtime/runtime-signal-identity";
 import { PHI_ASSET_CONTROLLER_STORE_KEY, PHI_ASSET_SIGNAL_CHANNELS, } from "../../../../components/media/asset-controller-signals";
-import { PHI_ASSET_INSPECTOR_OVERLAY_IDS, PHI_ASSET_INSPECTOR_WIDGET_IDS, PHI_ASSET_MEDIA_PAGE_WIDGET_IDS, } from "../media-page-ids";
 import { normalizeMediaFocalRect } from "../../../../components/media/focal-rect";
-import { resolvePhiMediaFolderIdFromValue, combinePhiMediaFlagValues, } from "../../../../components/media/media-folder-options";
-const ASSET_METADATA_FORM_WIDGET_ADDRESS = createPhiSignalAddress("cms", PHI_ASSET_INSPECTOR_WIDGET_IDS.widgetMediaMetadataForm);
-const ASSET_METADATA_FORM_CONTROLLER_ADDRESS = createPhiRuntimeFormControllerAddress(`widget-${PHI_ASSET_INSPECTOR_WIDGET_IDS.widgetMediaMetadataForm}`);
-const ASSET_INSPECTOR_OVERLAY_ADDRESS = createPhiSignalAddress("cms", PHI_ASSET_INSPECTOR_OVERLAY_IDS.overlayMediaInspector);
-const ASSET_COLLECTION_WIDGET_ADDRESS = createPhiSignalAddress("cms", PHI_ASSET_MEDIA_PAGE_WIDGET_IDS.widgetMediaPreview);
-const ASSET_FOLDER_FORM_WIDGET_ADDRESS = createPhiSignalAddress("cms", PHI_ASSET_INSPECTOR_WIDGET_IDS.widgetMediaFolderCreateForm);
-const ASSET_FOLDER_FORM_CONTROLLER_ADDRESS = createPhiRuntimeFormControllerAddress(`widget-${PHI_ASSET_INSPECTOR_WIDGET_IDS.widgetMediaFolderCreateForm}`);
-const ASSET_FOLDER_OVERLAY_ADDRESS = createPhiSignalAddress("cms", PHI_ASSET_INSPECTOR_OVERLAY_IDS.overlayMediaFolderCreate);
-const ASSET_INSPECTOR_SAVE_ADDRESS = createPhiSignalSubcontrolAddress("cms", PHI_ASSET_INSPECTOR_WIDGET_IDS.widgetMediaInspectorCommands, "save");
-const ASSET_FOLDER_SAVE_ADDRESS = createPhiSignalSubcontrolAddress("cms", PHI_ASSET_INSPECTOR_WIDGET_IDS.widgetMediaFolderCreateCommands, "save");
+import { buildPhiMediaFolderNamesById, resolvePhiMediaFolderIdFromValue, combinePhiMediaFlagValues, } from "../../../../components/media/media-folder-options";
 const ASSET_FORM_FLAG_VALUES = Object.values(PhiMediaAssetFlags);
 function splitPhiMediaFolderNamePath(value) {
     return (value ?? "")
@@ -28,24 +17,8 @@ function splitPhiMediaFolderNamePath(value) {
         .filter(Boolean);
 }
 function buildPhiMediaFolderNamePath(folders, folderId) {
-    if (folderId == null)
-        return "";
-    const byId = new Map(folders.map((folder) => [folder.id, folder]));
-    const path = [];
-    const visited = new Set();
-    let currentId = folderId;
-    while (currentId != null && !visited.has(currentId)) {
-        visited.add(currentId);
-        const folder = byId.get(currentId);
-        if (!folder)
-            break;
-        path.unshift(folder.name);
-        currentId = folder.parentId;
-    }
-    return path.length > 0 ? `/${path.join("/")}` : "";
-}
-function matchesAssetControllerSignal(signal) {
-    return signal.receiver === createPhiAssetControllerAddress();
+    const names = buildPhiMediaFolderNamesById(folders, folderId);
+    return names.length > 0 ? `/${names.join("/")}` : "";
 }
 function isPhiMediaKindValue(value) {
     return (value === PhiMediaKind.Image ||
@@ -66,28 +39,26 @@ function combinePhiMediaSignalFlagValues(value) {
     const presentationFlags = value.filter((entry) => typeof entry === "number" && Number.isInteger(entry));
     return presentationFlags.length > 0 ? combinePhiMediaFlagValues(presentationFlags) : null;
 }
-export function usePhiAssetRuntimeController(mountScope) {
+export function usePhiAssetRuntimeController({ address, mountScope, config, }) {
     const state = usePhiImagePreviewStore(PHI_ASSET_CONTROLLER_STORE_KEY);
-    const emitAssetSignal = usePhiSignalEmitter(createPhiAssetControllerAddress());
+    const emitAssetSignal = usePhiSignalEmitter(address);
+    const dispatchSignal = usePhiSignalDispatcher();
     const [inspectorRequest, setInspectorRequest] = useState(null);
     const [inspectorSubmitting, setInspectorSubmitting] = useState(false);
     const [folderRequest, setFolderRequest] = useState(null);
     const [folderSubmitting, setFolderSubmitting] = useState(false);
-    const sendPageSignal = useCallback((input) => {
-        emitAssetSignal({
-            scope: "page",
-            receiver: input.receiver,
-            channel: input.channel,
-            action: input.action,
-            value: input.value,
-            valueType: input.valueType,
-            valueSchema: input.valueSchema ?? null,
-            correlationId: input.correlationId,
-            timestamp: Date.now(),
-        });
-    }, [emitAssetSignal]);
+    /*
+     * One declared output, delivered through every route the Page wrote for it.
+     *
+     * The receivers -- the inspector and folder dialogs, their Forms, the collection -- used to be Widget
+     * ids of the Media Page written into this file, so the Controller worked on that one Page and on no
+     * copy of it. The Page names them now (`controllerSettings`); a Page that names none, or an Area that
+     * runs this Controller only for its pickers, gets a Controller that opens nothing.
+     */
+    const emitRoutes = useMemo(() => config.signalRoutes?.emits ?? [], [config.signalRoutes?.emits]);
+    const emitCapability = useCallback((capabilityId, value, correlationId) => dispatchPhiSignalCapability(dispatchSignal, address, emitRoutes, capabilityId, value, correlationId), [address, dispatchSignal, emitRoutes]);
     usePhiSignalListener((signal) => {
-        if (!matchesAssetControllerSignal(signal)) {
+        if (signal.receiver !== address) {
             return;
         }
         if (signal.channel !== PHI_ASSET_SIGNAL_CHANNELS.reload &&
@@ -122,14 +93,7 @@ export function usePhiAssetRuntimeController(mountScope) {
                  * the drawer still opened, on an empty form, over a Save that did nothing. A selection is
                  * reported to the Controller, and what the Controller does about it is the Controller's.
                  */
-                sendPageSignal({
-                    receiver: ASSET_INSPECTOR_OVERLAY_ADDRESS,
-                    channel: "dialog",
-                    action: "open",
-                    value: null,
-                    valueType: "none",
-                    correlationId: signal.correlationId,
-                });
+                emitCapability("inspectorOpen", null, signal.correlationId);
             }
             return;
         }
@@ -140,68 +104,61 @@ export function usePhiAssetRuntimeController(mountScope) {
             !Array.isArray(signal.value) &&
             signal.value.actionKey === "createFolder") {
             const collectionQuery = signal.value.query;
-            const filters = collectionQuery && typeof collectionQuery === "object" && !Array.isArray(collectionQuery)
+            const filters = isPhiRecord(collectionQuery)
                 ? collectionQuery.filters
                 : null;
-            const folderId = filters && typeof filters === "object" && !Array.isArray(filters)
+            const folderId = isPhiRecord(filters)
                 ? filters.folderId
                 : null;
             setFolderRequest({
                 correlationId: signal.correlationId,
                 parentPath: buildPhiMediaFolderNamePath(state.folders, typeof folderId === "number" && Number.isInteger(folderId) ? folderId : null) || "/",
             });
-            sendPageSignal({
-                receiver: ASSET_FOLDER_OVERLAY_ADDRESS,
-                channel: "dialog",
-                action: "open",
-                value: null,
-                valueType: "none",
-                correlationId: signal.correlationId,
-            });
+            emitCapability("folderDialogOpen", null, signal.correlationId);
             return;
         }
         if (signal.channel === PHI_ASSET_SIGNAL_CHANNELS.folderCommand && signal.action === "activate") {
             if (signal.value === "cancel") {
-                sendPageSignal({ receiver: ASSET_FOLDER_FORM_WIDGET_ADDRESS, channel: "reset", action: "activate", value: null, valueType: "none", correlationId: signal.correlationId });
-                sendPageSignal({ receiver: ASSET_FOLDER_OVERLAY_ADDRESS, channel: "dialog", action: "close", value: null, valueType: "none", correlationId: signal.correlationId });
+                emitCapability("folderReset", null, signal.correlationId);
+                emitCapability("folderDialogClose", null, signal.correlationId);
             }
             else if (signal.value === "save" && !folderSubmitting) {
-                sendPageSignal({ receiver: ASSET_FOLDER_FORM_WIDGET_ADDRESS, channel: "submit", action: "activate", value: null, valueType: "none", correlationId: signal.correlationId });
+                emitCapability("folderSubmit", null, signal.correlationId);
             }
             return;
         }
         if (signal.channel === PHI_ASSET_SIGNAL_CHANNELS.folderSubmitting && signal.action === "change" && typeof signal.value === "boolean") {
             setFolderSubmitting(signal.value);
-            sendPageSignal({ receiver: ASSET_FOLDER_SAVE_ADDRESS, channel: "submitting", action: "change", value: signal.value, valueType: "boolean", correlationId: signal.correlationId });
+            emitCapability("folderSubmitting", signal.value, signal.correlationId);
             return;
         }
         if (signal.channel === PHI_ASSET_SIGNAL_CHANNELS.folderSubmit && signal.action === "activate") {
             setFolderSubmitting(false);
-            sendPageSignal({ receiver: ASSET_FOLDER_OVERLAY_ADDRESS, channel: "dialog", action: "close", value: null, valueType: "none", correlationId: signal.correlationId });
-            sendPageSignal({ receiver: ASSET_COLLECTION_WIDGET_ADDRESS, channel: "reload", action: "activate", value: null, valueType: "none", correlationId: signal.correlationId });
+            emitCapability("folderDialogClose", null, signal.correlationId);
+            emitCapability("collectionReload", null, signal.correlationId);
             return;
         }
         if (signal.channel === PHI_ASSET_SIGNAL_CHANNELS.command && signal.action === "activate") {
             if (signal.value === "cancel") {
                 setInspectorRequest(null);
-                sendPageSignal({ receiver: ASSET_METADATA_FORM_WIDGET_ADDRESS, channel: "reset", action: "activate", value: null, valueType: "none", correlationId: signal.correlationId });
-                sendPageSignal({ receiver: ASSET_INSPECTOR_OVERLAY_ADDRESS, channel: "dialog", action: "close", value: null, valueType: "none", correlationId: signal.correlationId });
+                emitCapability("metadataReset", null, signal.correlationId);
+                emitCapability("inspectorClose", null, signal.correlationId);
             }
             else if (signal.value === "save" && !inspectorSubmitting) {
-                sendPageSignal({ receiver: ASSET_METADATA_FORM_WIDGET_ADDRESS, channel: "submit", action: "activate", value: null, valueType: "none", correlationId: signal.correlationId });
+                emitCapability("metadataSubmit", null, signal.correlationId);
             }
             return;
         }
         if (signal.channel === PHI_ASSET_SIGNAL_CHANNELS.submitting && signal.action === "change" && typeof signal.value === "boolean") {
             setInspectorSubmitting(signal.value);
-            sendPageSignal({ receiver: ASSET_INSPECTOR_SAVE_ADDRESS, channel: "submitting", action: "change", value: signal.value, valueType: "boolean", correlationId: signal.correlationId });
+            emitCapability("inspectorSubmitting", signal.value, signal.correlationId);
             return;
         }
         if (signal.channel === PHI_ASSET_SIGNAL_CHANNELS.submit && signal.action === "activate") {
             setInspectorSubmitting(false);
             setInspectorRequest(null);
-            sendPageSignal({ receiver: ASSET_INSPECTOR_OVERLAY_ADDRESS, channel: "dialog", action: "close", value: null, valueType: "none", correlationId: signal.correlationId });
-            sendPageSignal({ receiver: ASSET_COLLECTION_WIDGET_ADDRESS, channel: "reload", action: "activate", value: null, valueType: "none", correlationId: signal.correlationId });
+            emitCapability("inspectorClose", null, signal.correlationId);
+            emitCapability("collectionReload", null, signal.correlationId);
             return;
         }
         if (signal.channel === PHI_ASSET_SIGNAL_CHANNELS.reload) {
@@ -227,13 +184,13 @@ export function usePhiAssetRuntimeController(mountScope) {
                 setPhiImagePreviewSearchQuery(PHI_ASSET_CONTROLLER_STORE_KEY, signal.value);
                 return;
             }
-            if (signal.value && typeof signal.value === "object" && !Array.isArray(signal.value)) {
+            if (isPhiRecord(signal.value)) {
                 const queryValue = signal.value.searchQuery;
                 setPhiImagePreviewSearchQuery(PHI_ASSET_CONTROLLER_STORE_KEY, typeof queryValue === "string" ? queryValue : "");
             }
             return;
         }
-        if (signal.channel === PHI_ASSET_SIGNAL_CHANNELS.pagination && signal.value && typeof signal.value === "object" && !Array.isArray(signal.value)) {
+        if (signal.channel === PHI_ASSET_SIGNAL_CHANNELS.pagination && isPhiRecord(signal.value)) {
             const value = signal.value;
             if (typeof value.pageSize === "number" && Number.isInteger(value.pageSize) && value.pageSize > 0) {
                 setPhiImagePreviewPageSize(PHI_ASSET_CONTROLLER_STORE_KEY, value.pageSize);
@@ -264,49 +221,46 @@ export function usePhiAssetRuntimeController(mountScope) {
      * the media inspector opened with an empty form and its Save did nothing at all. The instance the
      * controller mount registers says the address exists; this says somebody is behind it.
      */
-    createPhiAssetControllerAddress());
+    address);
+    /*
+     * The form is filled once per opening. Sent again on every change of the collection -- a reload, a
+     * folder count -- it overwrote what somebody was typing, and an Overlay closed by its X never ended
+     * the request, so a background reload could still write into the next opening.
+     */
+    const filledInspectorRequestRef = useRef(null);
     useEffect(() => {
-        if (!inspectorRequest)
+        if (!inspectorRequest || filledInspectorRequestRef.current === inspectorRequest)
             return;
         const asset = state.selectedAsset?.id === inspectorRequest.assetId
             ? state.selectedAsset
             : state.assets.find((entry) => entry.id === inspectorRequest.assetId) ?? null;
         if (!asset)
             return;
-        sendPageSignal({
-            receiver: ASSET_METADATA_FORM_CONTROLLER_ADDRESS,
-            channel: "values",
-            action: "change",
-            value: {
-                values: {
-                    assetId: asset.id,
-                    imageUrl: asset.previewUrl ?? asset.deliveryUrl,
-                    imageAlt: asset.altText ?? asset.title ?? asset.originalName,
-                    folderPath: buildPhiMediaFolderNamePath(state.folders, asset.folderId),
-                    title: asset.title ?? "",
-                    altText: asset.altText ?? "",
-                    presentationFlags: ASSET_FORM_FLAG_VALUES.filter((flag) => (asset.presentationFlags & flag) === flag).map(String),
-                    focalRect: normalizeMediaFocalRect(asset.meta?.focalRect) ?? null,
-                },
+        filledInspectorRequestRef.current = inspectorRequest;
+        emitCapability("metadataValues", {
+            values: {
+                assetId: asset.id,
+                imageUrl: asset.previewUrl ?? asset.deliveryUrl,
+                imageAlt: asset.altText ?? asset.title ?? asset.originalName,
+                /*
+                 * The field is `folderId`, a Select whose options carry the id as a string (`valueMode: "id"`).
+                 * Handing it the name path under another key left the Select empty, and a submit that only
+                 * changed the alt text then sent `folderId: null` -- which the server reads as "move to the
+                 * root folder".
+                 */
+                folderId: asset.folderId == null ? null : String(asset.folderId),
+                title: asset.title ?? "",
+                altText: asset.altText ?? "",
+                presentationFlags: ASSET_FORM_FLAG_VALUES.filter((flag) => (asset.presentationFlags & flag) === flag).map(String),
+                focalRect: normalizeMediaFocalRect(asset.meta?.focalRect) ?? null,
             },
-            valueType: "json",
-            valueSchema: PHI_SIGNAL_VALUE_SCHEMAS.formValues,
-            correlationId: inspectorRequest.correlationId,
-        });
-    }, [inspectorRequest, sendPageSignal, state.assets, state.folders, state.selectedAsset]);
+        }, inspectorRequest.correlationId);
+    }, [emitCapability, inspectorRequest, state.assets, state.folders, state.selectedAsset]);
     useEffect(() => {
         if (!folderRequest)
             return;
-        sendPageSignal({
-            receiver: ASSET_FOLDER_FORM_CONTROLLER_ADDRESS,
-            channel: "values",
-            action: "change",
-            value: { values: { name: "", parentPath: folderRequest.parentPath } },
-            valueType: "json",
-            valueSchema: PHI_SIGNAL_VALUE_SCHEMAS.formValues,
-            correlationId: folderRequest.correlationId,
-        });
-    }, [folderRequest, sendPageSignal]);
+        emitCapability("folderValues", { values: { name: "", parentPath: folderRequest.parentPath } }, folderRequest.correlationId);
+    }, [emitCapability, folderRequest]);
     useEffect(() => {
         emitAssetSignal({
             scope: mountScope,

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

@@ -1,3 +1,8 @@
+/** How the Folder's pictures are ordered; the words a record binding's `sort` takes. */
+export declare const PHI_MEDIA_FOLDER_IMAGES_SORTS: readonly ["name_asc", "created_at_desc"];
+export declare const PHI_MEDIA_FOLDER_IMAGES_DEFAULT_LIMIT = 50;
+/** What the server hands out at most (`/api/v1/site/media/folder-images`). */
+export declare const PHI_MEDIA_FOLDER_IMAGES_MAX_LIMIT = 200;
 export declare const PHI_ASSET_RUNTIME_DATA_PROVIDER_DESCRIPTORS: ({
     key: `${string}/${string}`;
     ownerModuleId: "@phis/ui/modules/asset";
@@ -7,6 +12,59 @@ export declare const PHI_ASSET_RUNTIME_DATA_PROVIDER_DESCRIPTORS: ({
     title: string;
     description: string;
     availableToAuthoringChrome: true;
+    settingsFields?: undefined;
+    resources?: undefined;
+} | {
+    key: `${string}/${string}`;
+    ownerModuleId: "@phis/ui/modules/asset";
+    kind: "record";
+    executionMode: "live";
+    authoringMode: "none";
+    title: string;
+    description: string;
+    settingsFields: ({
+        key: string;
+        type: "choice";
+        label: string;
+        optionsProvider: {
+            providerKey: `${string}/${string}`;
+        };
+        description?: undefined;
+        options?: undefined;
+        min?: undefined;
+        max?: undefined;
+    } | {
+        key: string;
+        type: "boolean";
+        label: string;
+        description: string;
+        optionsProvider?: undefined;
+        options?: undefined;
+        min?: undefined;
+        max?: undefined;
+    } | {
+        key: string;
+        type: "choice";
+        label: string;
+        options: {
+            value: string;
+            label: string;
+        }[];
+        optionsProvider?: undefined;
+        description?: undefined;
+        min?: undefined;
+        max?: undefined;
+    } | {
+        key: string;
+        type: "number";
+        label: string;
+        min: number;
+        max: number;
+        optionsProvider?: undefined;
+        description?: undefined;
+        options?: undefined;
+    })[];
+    availableToAuthoringChrome?: undefined;
     resources?: undefined;
 } | {
     key: `${string}/${string}`;
@@ -58,4 +116,5 @@ export declare const PHI_ASSET_RUNTIME_DATA_PROVIDER_DESCRIPTORS: ({
             title: string;
         }[];
     }[];
+    settingsFields?: undefined;
 })[];

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

@@ -1,7 +1,57 @@
 import { PHI_SIGNAL_VALUE_SCHEMAS } from "../../../types/signals";
 import { PHI_ASSET_RUNTIME_DATA_PROVIDER_KEYS, PHI_ASSET_RUNTIME_ITEM_RENDERER_KEY } from "./ids";
 import { PHI_ASSET_RUNTIME_MODULE_ID } from "./ids";
+/** How the Folder's pictures are ordered; the words a record binding's `sort` takes. */
+export const PHI_MEDIA_FOLDER_IMAGES_SORTS = ["name_asc", "created_at_desc"];
+export const PHI_MEDIA_FOLDER_IMAGES_DEFAULT_LIMIT = 50;
+/** What the server hands out at most (`/api/v1/site/media/folder-images`). */
+export const PHI_MEDIA_FOLDER_IMAGES_MAX_LIMIT = 200;
 export const PHI_ASSET_RUNTIME_DATA_PROVIDER_DESCRIPTORS = [
+    {
+        key: PHI_ASSET_RUNTIME_DATA_PROVIDER_KEYS.mediaFolderChoices,
+        ownerModuleId: PHI_ASSET_RUNTIME_MODULE_ID,
+        kind: "options",
+        executionMode: "live",
+        authoringMode: "none",
+        title: "Media folder choices",
+        description: "Every folder of the Site's media, by its path, for a setting that names one.",
+        // Named in a record binding's parameters, which the Builder edits on any page.
+        availableToAuthoringChrome: true,
+    },
+    /*
+     * The pictures of a Folder, read on the server while the page is drawn (`types/record-provider.ts`).
+     * A Folder is a thing somebody keeps filling, so the page reads it rather than naming each picture:
+     * what is public in the branch at render time is what the Gallery shows.
+     */
+    {
+        key: PHI_ASSET_RUNTIME_DATA_PROVIDER_KEYS.mediaFolderImages,
+        ownerModuleId: PHI_ASSET_RUNTIME_MODULE_ID,
+        kind: "record",
+        executionMode: "live",
+        // The Builder draws a placeholder for a Gallery and reads nothing.
+        authoringMode: "none",
+        title: "Media folder pictures",
+        description: "The public pictures of one media folder, with its subfolders unless told otherwise.",
+        settingsFields: [
+            {
+                key: "folderId",
+                type: "choice",
+                label: "Folder",
+                optionsProvider: { providerKey: PHI_ASSET_RUNTIME_DATA_PROVIDER_KEYS.mediaFolderChoices },
+            },
+            { key: "topLevelOnly", type: "boolean", label: "This folder only", description: "Leave the pictures in its subfolders out." },
+            {
+                key: "sort",
+                type: "choice",
+                label: "Order",
+                options: [
+                    { value: "name_asc", label: "By file name" },
+                    { value: "created_at_desc", label: "Newest first" },
+                ],
+            },
+            { key: "limit", type: "number", label: "At most", min: 1, max: PHI_MEDIA_FOLDER_IMAGES_MAX_LIMIT },
+        ],
+    },
     {
         key: PHI_ASSET_RUNTIME_DATA_PROVIDER_KEYS.mediaFolders,
         ownerModuleId: PHI_ASSET_RUNTIME_MODULE_ID,

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

@@ -19,6 +19,59 @@ export declare const PHI_ASSET_RUNTIME_MODULE_DEFINITION: {
         title: string;
         description: string;
         availableToAuthoringChrome: true;
+        settingsFields?: undefined;
+        resources?: undefined;
+    } | {
+        key: `${string}/${string}`;
+        ownerModuleId: "@phis/ui/modules/asset";
+        kind: "record";
+        executionMode: "live";
+        authoringMode: "none";
+        title: string;
+        description: string;
+        settingsFields: ({
+            key: string;
+            type: "choice";
+            label: string;
+            optionsProvider: {
+                providerKey: `${string}/${string}`;
+            };
+            description?: undefined;
+            options?: undefined;
+            min?: undefined;
+            max?: undefined;
+        } | {
+            key: string;
+            type: "boolean";
+            label: string;
+            description: string;
+            optionsProvider?: undefined;
+            options?: undefined;
+            min?: undefined;
+            max?: undefined;
+        } | {
+            key: string;
+            type: "choice";
+            label: string;
+            options: {
+                value: string;
+                label: string;
+            }[];
+            optionsProvider?: undefined;
+            description?: undefined;
+            min?: undefined;
+            max?: undefined;
+        } | {
+            key: string;
+            type: "number";
+            label: string;
+            min: number;
+            max: number;
+            optionsProvider?: undefined;
+            description?: undefined;
+            options?: undefined;
+        })[];
+        availableToAuthoringChrome?: undefined;
         resources?: undefined;
     } | {
         key: `${string}/${string}`;
@@ -70,6 +123,7 @@ export declare const PHI_ASSET_RUNTIME_MODULE_DEFINITION: {
                 title: string;
             }[];
         }[];
+        settingsFields?: undefined;
     })[];
     collectionItemRenderers: {
         key: `${string}/${string}`;

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

@@ -7,6 +7,12 @@ export declare const PHI_ASSET_RUNTIME_MODULE_ID: "@phis/ui/modules/asset";
 export declare const PHI_ASSET_RUNTIME_DATA_PROVIDER_KEYS: {
     readonly mediaFolders: `${string}/${string}`;
     readonly mediaCollection: `${string}/${string}`;
+    readonly mediaFolderImages: `${string}/${string}`;
+    /**
+     * Every Folder of the Site Space as a choice, loaded by the choice itself. `mediaFolders` reads the
+     * Media page's store, which is not there when a Gallery is configured on some other page.
+     */
+    readonly mediaFolderChoices: `${string}/${string}`;
 };
 /** The card this Module ships for its own items; a Site may name another. */
 export declare const PHI_ASSET_RUNTIME_ITEM_RENDERER_KEY: `${string}/${string}`;

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

@@ -1,4 +1,5 @@
 import { PHI_SHARED_PACKAGE_NAME } from "../../../types/signals";
+import { createPhiSharedRuntimeDataProviderKey } from "../../../constants/runtime-data-provider-key";
 import { PHI_MEDIA_LIBRARY_DATA_PROVIDER_KEYS, PHI_MEDIA_LIBRARY_ITEM_RENDERER_KEY, } from "../../../constants/media-library-provider-keys";
 export const PHI_ASSET_RUNTIME_MODULE_ID = `${PHI_SHARED_PACKAGE_NAME}/modules/asset`;
 /**
@@ -9,6 +10,12 @@ export const PHI_ASSET_RUNTIME_MODULE_ID = `${PHI_SHARED_PACKAGE_NAME}/modules/a
 export const PHI_ASSET_RUNTIME_DATA_PROVIDER_KEYS = {
     mediaFolders: PHI_MEDIA_LIBRARY_DATA_PROVIDER_KEYS.folders,
     mediaCollection: PHI_MEDIA_LIBRARY_DATA_PROVIDER_KEYS.collection,
+    mediaFolderImages: PHI_MEDIA_LIBRARY_DATA_PROVIDER_KEYS.folderImages,
+    /**
+     * Every Folder of the Site Space as a choice, loaded by the choice itself. `mediaFolders` reads the
+     * Media page's store, which is not there when a Gallery is configured on some other page.
+     */
+    mediaFolderChoices: createPhiSharedRuntimeDataProviderKey("options", "media-folder-choices"),
 };
 /** The card this Module ships for its own items; a Site may name another. */
 export const PHI_ASSET_RUNTIME_ITEM_RENDERER_KEY = PHI_MEDIA_LIBRARY_ITEM_RENDERER_KEY;

package/plugins/runtime-modules/asset/metadata-form.d.ts

@@ -1,7 +1,5 @@
 export declare const PHI_ASSET_METADATA_FORM_ID: `${string}/forms/${string}`;
 export declare const PHI_ASSET_FOLDER_FORM_ID: `${string}/forms/${string}`;
-export declare const PHI_ASSET_METADATA_FORM_HANDLER_KEY = "site.asset.metadata.update";
-export declare const PHI_ASSET_FOLDER_FORM_HANDLER_KEY = "site.asset.folder.create";
 export declare const PHI_ASSET_METADATA_FORM_DESCRIPTOR: {
     readonly schemaVersion: 1;
     readonly key: `${string}/forms/${string}`;

package/plugins/runtime-modules/asset/metadata-form.js

@@ -10,8 +10,8 @@ import { PHI_ASSET_FOCAL_RECT_FORM_PROVIDER_KEY } from "./form-providers";
 import { readPhiServerApiCredentials } from "../../../helpers/phis-server-credentials";
 export const PHI_ASSET_METADATA_FORM_ID = createPhiFormId(PHI_SHARED_PACKAGE_NAME, "asset/metadata");
 export const PHI_ASSET_FOLDER_FORM_ID = createPhiFormId(PHI_SHARED_PACKAGE_NAME, "asset/folder-create");
-export const PHI_ASSET_METADATA_FORM_HANDLER_KEY = "site.asset.metadata.update";
-export const PHI_ASSET_FOLDER_FORM_HANDLER_KEY = "site.asset.folder.create";
+const PHI_ASSET_METADATA_FORM_HANDLER_KEY = "site.asset.metadata.update";
+const PHI_ASSET_FOLDER_FORM_HANDLER_KEY = "site.asset.folder.create";
 const PHI_ASSET_FORM_LABEL_SET_KEY = "@phis/ui/modules/asset/labels/metadata";
 const label = (key, fallback) => ({ kind: "label", key, fallback });
 const required = (key, fallback) => [{