@phis/ui 0.1.0 → 0.2.1

package/types/cms-overlay.d.ts

@@ -15,9 +15,8 @@ export type PhiCmsOverlayMaskConfig = {
     closable: boolean;
 };
 export type PhiCmsOverlaySize = string | number;
-export type PhiCmsOverlayResponsiveSize = PhiResponsiveValue<PhiCmsOverlaySize> & {
-    compact: PhiCmsOverlaySize;
-};
+/** A Modal width per responsive mode; unset modes cascade from the nearest smaller one that is set. */
+export type PhiCmsOverlayResponsiveSize = PhiResponsiveValue<PhiCmsOverlaySize>;
 export declare const PHI_OVERLAY_CLOSE_SOURCES: readonly ["close-button", "mask", "escape"];
 export type PhiOverlayCloseSource = (typeof PHI_OVERLAY_CLOSE_SOURCES)[number];
 export type PhiOverlayCloseRequest = {
@@ -41,9 +40,36 @@ export type PhiCmsOverlayConfig = PhiOverlayChromeConfig & {
         distance: string | number;
     };
     closeMode: "immediate" | "request";
+    /**
+     * Which Table action this Overlay opens for, when it is opened by one.
+     *
+     * A Table announces every action on one channel and names the action in the message. An Overlay that
+     * subscribes to that channel would otherwise open for all of them -- test and delete included -- so
+     * the only way to point a row at a dialog was a Controller whose whole job was to forward one signal.
+     *
+     * The Form and Record Widgets already answer this question with a field of this name and read it the
+     * same way: the `open` route fires only when `actionKey` matches. An Overlay filling itself from a
+     * Table sits beside a Widget doing the same thing, so it asks in the same words.
+     *
+     * Only an `open` route carried on the Table's own action channel is filtered. An Overlay opened the
+     * ordinary way -- a `dialog` route with no value -- never consults this.
+     */
+    openActionKey: string | null;
     signalRoutes: PhiSignalRouteSet | null;
 };
 export declare function isPhiCmsOverlayType(value: unknown): value is PhiCmsOverlayType;
 export declare function readPhiOverlayCloseRequest(value: unknown): PhiOverlayCloseRequest | null;
 export declare function parsePhiCmsOverlayConfig(rawConfig: Record<string, unknown>, overlayType?: PhiCmsOverlayType): PhiCmsOverlayConfig;
+/**
+ * Whether an Area Overlay ships closed, without its zones, and asks for them on first open.
+ *
+ * Every policy but `eager` does: `eager` means the content is mounted before anybody opens it. The
+ * Overlay renderer decides by this which zones to leave out of the page, and the Controller
+ * materialization decides by the same answer which Controllers to leave out of the Area -- the ones the
+ * zones bring along when they arrive (`next/overlay-zones.tsx`).
+ */
+export declare function isPhiCmsOverlayDeferredWhenClosed(overlay: {
+    config: Record<string, unknown>;
+    overlayType: PhiCmsOverlayType;
+}): boolean;
 export {};

package/types/cms-overlay.js

@@ -1,5 +1,5 @@
 import { normalizePhiBackgroundWidgetConfig } from "../components/widgets/config/background";
-import { readPhiCmsBorderWidgetConfig } from "./cms-config";
+import { readPhiCmsBorderWidgetConfig } from "./cms-border-config";
 import { isPhiLayoutEffectId, readPhiShadow } from "./layout-style";
 import { readPhiSignalRouteSet } from "./signals";
 import { readPhiCmsMountPolicy, } from "./cms-mount-policy";
@@ -22,14 +22,14 @@ function readResponsiveSize(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return undefined;
     const record = value;
-    const compact = readSize(record.compact);
-    if (compact === undefined)
-        return undefined;
-    return {
-        compact,
+    const size = {
+        compact: readSize(record.compact),
         medium: readSize(record.medium),
         wide: readSize(record.wide),
     };
+    return size.compact === undefined && size.medium === undefined && size.wide === undefined
+        ? undefined
+        : size;
 }
 function readMask(value) {
     const record = value && typeof value === "object" && !Array.isArray(value)
@@ -100,6 +100,9 @@ export function parsePhiCmsOverlayConfig(rawConfig, overlayType = "modal") {
         resizable: readBoolean(rawConfig.resizable, false),
         push: readPush(rawConfig.push),
         closeMode: rawConfig.closeMode === "request" ? "request" : "immediate",
+        openActionKey: typeof rawConfig.openActionKey === "string" && rawConfig.openActionKey.trim()
+            ? rawConfig.openActionKey.trim()
+            : null,
         background: typeof rawConfig.background === "string" && rawConfig.background.trim()
             ? rawConfig.background.trim()
             : undefined,
@@ -112,3 +115,14 @@ export function parsePhiCmsOverlayConfig(rawConfig, overlayType = "modal") {
         signalRoutes: readPhiSignalRouteSet(rawConfig.signalRoutes),
     };
 }
+/**
+ * Whether an Area Overlay ships closed, without its zones, and asks for them on first open.
+ *
+ * Every policy but `eager` does: `eager` means the content is mounted before anybody opens it. The
+ * Overlay renderer decides by this which zones to leave out of the page, and the Controller
+ * materialization decides by the same answer which Controllers to leave out of the Area -- the ones the
+ * zones bring along when they arrive (`next/overlay-zones.tsx`).
+ */
+export function isPhiCmsOverlayDeferredWhenClosed(overlay) {
+    return parsePhiCmsOverlayConfig(overlay.config, overlay.overlayType).mountPolicy !== "eager";
+}

package/types/cms-plugins.d.ts

@@ -1,12 +1,12 @@
 import type { ComponentType, ReactNode } from "react";
-import type { PhiSiteRequestContext } from "../server-helpers/runtime";
+import type { PhiSiteRequestContext } from "./site-request-context";
 import type { PhiCmsAreaKey } from "../constants/cms-areas";
 import type { PhiCmsPluginCategory } from "../constants/cms-plugin-categories";
 import type { PhiRuntimeModuleCategory } from "../constants/runtime-module-categories";
 import type { PhiControlOption, PhiControlOptionsProviderConfig } from "../components/controls/phi-control-options";
-import type { PhiRenderableBlockAnchor } from "./renderable-block";
+import type { PhiRenderableBlockAnchor, PhiRenderableBlockBase } from "./renderable-block";
+import type { PhiCmsRegionOwnership } from "../helpers/cms-region-keys";
 import type { PhiSlotSizePolicy } from "./slot-size-policy";
-import type { PhiLayoutKind } from "../components/layouts/phi-layout-contract";
 import type { PhiCmsContentWidgetNode, PhiCmsLayoutRenderNode, PhiResolvedCmsAreaPresetTree, PhiResolvedCmsRenderableTree, PhiResolvedCmsPageTree } from "./cms";
 import type { PhiCmsRegionConfig } from "./cms-presets";
 import type { PhiBlockRuntime } from "./widget-runtime";
@@ -39,6 +39,20 @@ type PhiCmsConfigFieldBase = {
     visibleWhen?: PhiCmsConfigFieldVisibilityRule;
 };
 export type PhiCmsConfigFieldChoicePresentation = "select" | "segmented" | "tabs" | "autocomplete" | "radio";
+/**
+ * Where a collection is edited.
+ *
+ * `inline` stacks the entries down the Inspector column, which is right for as long as an entry is two
+ * or three short fields.
+ *
+ * `overlay` leaves only what is in the collection at the field's place and opens an Overlay to edit it.
+ * That is not a matter of taste: the Inspector column is narrow, and an entry carrying half a dozen
+ * fields -- a table column with a key, a provider field, a title, a renderer, a width, an alignment --
+ * becomes a column of truncated Controls in it. Which of the two a collection needs is known by the
+ * collection and by nothing else, which is why it is declared here rather than decided by the Inspector
+ * from the Widget type.
+ */
+export type PhiCmsConfigFieldCollectionPresentation = "inline" | "overlay";
 export type PhiCmsConfigFieldChoiceMode = "single" | "multiple";
 export type PhiCmsConfigFieldChoiceValueType = "string" | "string[]";
 export type PhiCmsConfigFieldChoiceCreateBehavior = "none" | "accept-custom" | "create-record";
@@ -51,6 +65,21 @@ export type PhiCmsConfigFieldChoiceFilter = {
 };
 export type PhiCmsConfigField = (PhiCmsConfigFieldBase & {
     type: "string" | "url" | "icon";
+}) | (PhiCmsConfigFieldBase & {
+    /**
+     * One link, chosen rather than typed.
+     *
+     * Its own type rather than a `url`, because the two answers it accepts are not the same kind of
+     * thing: an internal Page is picked from the Area's Page tree and stored as identity, an external
+     * address is a literal URL. A text box can only take the second, which is why every Widget that
+     * offered a `url` field offered no way at all to reach a Page -- and the paths authors typed
+     * instead went stale the moment the Page moved.
+     *
+     * What is stored is a `PhiLinkTarget`, under a key the reference collector recognises. See
+     * `isPhiLinkTargetConfigKey` in `types/references.ts` for the naming rule and `REFERENCES.md` for
+     * why the name is what the server has to go on.
+     */
+    type: "link-target";
 }) | (PhiCmsConfigFieldBase & {
     type: "readonly";
 }) | (PhiCmsConfigFieldBase & {
@@ -58,6 +87,15 @@ export type PhiCmsConfigField = (PhiCmsConfigFieldBase & {
     providerKind?: PhiRuntimeDataProviderKind;
 }) | (PhiCmsConfigFieldBase & {
     type: "calendar-adapter";
+}) | (PhiCmsConfigFieldBase & {
+    /**
+     * Which place a video comes from, chosen from the providers the edited Area actually activates.
+     *
+     * Its own type rather than a `choice` with an options provider, because the list is a Module
+     * contribution that is already resolved and already travels -- see `videoProviders` -- and because
+     * what gets stored is a provider key the render path looks up in the same registry.
+     */
+    type: "video-provider";
 }) | (PhiCmsConfigFieldBase & {
     type: "dimension";
     widthKey?: string;
@@ -92,12 +130,23 @@ export type PhiCmsConfigField = (PhiCmsConfigFieldBase & {
     section?: string;
 }) | (PhiCmsConfigFieldBase & {
     type: "boolean";
+}) | (PhiCmsConfigFieldBase & {
+    /** A list of whole numbers, such as the page sizes a table offers; each at least `min`. */
+    type: "number-list";
+    min?: number;
 }) | (PhiCmsConfigFieldBase & {
     type: "number";
     min?: number;
     max?: number;
     step?: number;
     precision?: number;
+    /**
+     * The unit, standing in front of the number rather than in the label.
+     *
+     * A label that ends in "(ms)" reads as part of the field's name and is gone the moment the
+     * field is narrow; the unit belongs to the value, so it stands where the value is.
+     */
+    prefix?: string;
 }) | (PhiCmsConfigFieldBase & {
     type: "choice";
     mode?: PhiCmsConfigFieldChoiceMode;
@@ -123,6 +172,9 @@ export type PhiCmsConfigField = (PhiCmsConfigFieldBase & {
     minItems?: number;
     maxItems?: number;
     reorderable?: boolean;
+    presentation?: PhiCmsConfigFieldCollectionPresentation;
+    /** What the button that opens the Overlay says. */
+    editLabel?: string;
 }) | (PhiCmsConfigFieldBase & {
     type: "background";
     section?: string;
@@ -179,6 +231,14 @@ export type PhiCmsWidgetPluginRenderArgs<TConfig> = {
      * paying for the reads. A Widget that needs a fact unconditionally should read it itself.
      */
     features?: import("./runtime-condition").PhiRuntimeFeatureState | null;
+    /**
+     * Where this render's Page targets lead, resolved once before anything drew.
+     *
+     * Handed down rather than fetched, because the batching is the contract: a Widget that could resolve
+     * its own target would resolve one target per Widget. Absent means the page carries no internal link
+     * at all; a reference missing from it did not resolve, and `resolvePhiLinkHref` answers `null` for it.
+     */
+    links?: import("./references").PhiResolvedLinkTargets | null;
     license?: PhiCmsPluginLicenseState;
 };
 /**
@@ -202,6 +262,14 @@ export type PhiCmsWidgetAuthoringCanvas = {
     resolveNavigation: (navKey: string) => PhiBuilderNavigationTree | null;
     /** The page catalog of the edited Area, with local and persisted pages already merged in. */
     pageCatalog: PhiBuilderActivePageCatalog;
+    /**
+     * The same, for an Area that is not the one being edited.
+     *
+     * A Navigation link may point into another Area, and its Page lives only in that Area's catalog. A
+     * Widget that resolves link targets asks through this rather than assuming the edited Area, which is
+     * the assumption that made such a link read as unresolvable.
+     */
+    pageCatalogForArea: (area: PhiBuilderAreaKey) => PhiBuilderActivePageCatalog;
 };
 export type PhiCmsWidgetAuthoringContext<TConfig> = {
     /** Set only where the Widget may actually be edited; absent in a read-only canvas. */
@@ -232,7 +300,6 @@ export type PhiCmsWidgetRuntimeControllerRequirementResolver<TConfig> = PhiBivar
 ], readonly PhiRuntimeControllerRequirement[]>;
 export type PhiCmsLayoutPluginRenderArgs<TConfig> = {
     node: PhiCmsLayoutRenderNode;
-    layoutKind: PhiLayoutKind;
     runtime: PhiBlockRuntime;
     tree: PhiResolvedCmsRenderableTree;
     regionConfig?: PhiCmsRegionConfig;
@@ -259,14 +326,35 @@ export type PhiCmsWidgetPlugin<TConfig> = {
     requiredRuntimeControllers?: PhiCmsWidgetRuntimeControllerRequirementResolver<TConfig>;
     requiredDataProviders?: readonly PhiRuntimeDataProviderKey[];
     contentBinding?: PhiCmsWidgetContentBinding | null;
-    slotSizePolicy?: PhiSlotSizePolicy;
+    /**
+     * The Widget translates the text written into its own config.
+     *
+     * Turning that off is the node's `NoTranslate` flag, not a config field: the answer is the same for
+     * every Widget that writes text, so it lives where every node keeps its yes-or-no answers. A Widget
+     * that says so here gets the Inspector's switch for it.
+     */
+    translatesOwnText?: true;
+    slotSizePolicy: PhiSlotSizePolicy;
+    /**
+     * The kind of Region this Widget needs, where standing in the other kind would break it.
+     *
+     * Declared by the few Widgets it matters to and left out by the rest, which stand anywhere. "shell"
+     * says the Widget needs a Region that survives a move between Pages -- Area navigation is the case
+     * it exists for, because a Page-owned Region is built again for every Page and the navigation would
+     * visibly rebuild itself under the hand that used it.
+     *
+     * Read while authoring and by the checks that run before a build, never while rendering: a
+     * placement can only be made in the Builder or written into a preset, so a live Page paying for the
+     * question on every request would pay for a decision that was already taken.
+     */
+    requiredRegionOwnership?: PhiCmsRegionOwnership;
     defaultConfig?: Partial<TConfig>;
     fields: PhiCmsConfigField[];
     parseConfig: (raw: Record<string, unknown>) => TConfig;
     render: PhiBivariantCallback<[PhiCmsWidgetPluginRenderArgs<TConfig>], ReactNode>;
     renderPreview: PhiBivariantCallback<[PhiCmsWidgetPluginRenderArgs<TConfig>], ReactNode>;
 };
-export type PhiCmsWidgetPluginDefinition<TConfig> = Pick<PhiCmsWidgetPlugin<TConfig>, "kind" | "pluginKey" | "typeKey" | "title" | "description" | "category" | "tags" | "icon" | "iconName" | "iconFamily" | "commercial" | "runtimeSignals" | "signalSubcontrols" | "requiredRuntimeControllers" | "requiredDataProviders" | "contentBinding" | "slotSizePolicy" | "defaultConfig" | "fields" | "parseConfig">;
+export type PhiCmsWidgetPluginDefinition<TConfig> = Pick<PhiCmsWidgetPlugin<TConfig>, "kind" | "pluginKey" | "typeKey" | "title" | "description" | "category" | "tags" | "icon" | "iconName" | "iconFamily" | "commercial" | "runtimeSignals" | "signalSubcontrols" | "requiredRuntimeControllers" | "requiredDataProviders" | "contentBinding" | "translatesOwnText" | "slotSizePolicy" | "requiredRegionOwnership" | "defaultConfig" | "fields" | "parseConfig">;
 export type PhiCmsBuilderWidgetEditorInteraction = "inert" | "authoring";
 export type PhiCmsBuilderWidgetPlugin<TConfig> = Pick<PhiCmsWidgetPlugin<TConfig>, "kind" | "pluginKey" | "typeKey" | "title" | "description" | "category" | "tags" | "icon" | "iconName" | "iconFamily" | "commercial" | "runtimeSignals" | "signalSubcontrols" | "requiredRuntimeControllers" | "requiredDataProviders" | "slotSizePolicy" | "defaultConfig" | "fields" | "parseConfig"> & {
     editorInteraction?: PhiCmsBuilderWidgetEditorInteraction;
@@ -294,8 +382,18 @@ export type PhiCmsRuntimeRenderRegistry = {
     renderIssuesByLayoutType: ReadonlyMap<string, PhiCmsRenderIssue>;
     ownerModuleIdByWidgetType: ReadonlyMap<string, PhiRuntimeModuleId>;
     widgetSlotSizePoliciesByType: ReadonlyMap<string, PhiSlotSizePolicy | undefined>;
+    /**
+     * The block base a Widget declares in its `defaultConfig`, for the nodes that declare none.
+     *
+     * Merged under a node's own config before anything renders, so the slot frame and the Widget read one
+     * config rather than two. Shallow, per key: a node that states `maxSize` owns `maxSize` whole, and a
+     * height without a width does not inherit the declared width. Only types that declare something are
+     * in here.
+     */
+    widgetBlockDefaultsByType: ReadonlyMap<string, Partial<PhiRenderableBlockBase>>;
     ownerModuleIdByLayoutType: ReadonlyMap<string, PhiRuntimeModuleId>;
-    uiProvidersByModuleId: ReadonlyMap<PhiRuntimeModuleId, PhiRuntimeModuleUiProvider>;
+    /** The used Modules whose catalog entry says they bring a UI provider through their Client half. */
+    uiProviderModuleIds: ReadonlySet<PhiRuntimeModuleId>;
     /**
      * How to ask each active Module for the facts it publishes, by the namespace it publishes them under.
      *
@@ -319,7 +417,6 @@ export type PhiCmsLayoutPlugin<TConfig> = {
     kind: "layout";
     pluginKey: string;
     typeKey: string;
-    layoutKind: PhiLayoutKind;
     title: string;
     description?: string;
     category: PhiCmsPluginCategory;
@@ -329,16 +426,25 @@ export type PhiCmsLayoutPlugin<TConfig> = {
     iconFamily?: string;
     commercial?: PhiCmsPluginCommercialMeta;
     runtimeSignals?: PhiSignalPluginMeta | null;
-    slotSizePolicy?: PhiSlotSizePolicy;
+    slotSizePolicy: PhiSlotSizePolicy;
     defaultConfig?: Partial<TConfig>;
     defaultAnchor?: PhiRenderableBlockAnchor | null;
     fields: PhiCmsConfigField[];
     slots: PhiCmsLayoutSlotDefinition[];
+    /**
+     * What an emptied position does, for a Layout whose slots are all sequential.
+     *
+     * `compact`, the default, closes the gap: the Builder renumbers the children after a move or a
+     * removal, the way a row or a carousel reads. `fixed` keeps every position where it is, because each
+     * one means something on its own -- the Collapsible's panel three is panel three whether or not panel
+     * two holds anything.
+     */
+    slotPositions?: "compact" | "fixed";
     parseConfig: (raw: Record<string, unknown>) => TConfig;
     render: PhiBivariantCallback<[PhiCmsLayoutPluginRenderArgs<TConfig>], ReactNode>;
     renderEditor: PhiBivariantCallback<[PhiCmsLayoutPluginRenderArgs<TConfig>], ReactNode>;
 };
-export type PhiCmsLayoutPluginDefinition<TConfig> = Pick<PhiCmsLayoutPlugin<TConfig>, "kind" | "pluginKey" | "typeKey" | "layoutKind" | "title" | "description" | "category" | "tags" | "icon" | "iconName" | "iconFamily" | "commercial" | "runtimeSignals" | "slotSizePolicy" | "defaultConfig" | "defaultAnchor" | "fields" | "slots">;
+export type PhiCmsLayoutPluginDefinition<TConfig> = Pick<PhiCmsLayoutPlugin<TConfig>, "kind" | "pluginKey" | "typeKey" | "title" | "description" | "category" | "tags" | "icon" | "iconName" | "iconFamily" | "commercial" | "runtimeSignals" | "slotSizePolicy" | "defaultConfig" | "defaultAnchor" | "fields" | "slots" | "slotPositions">;
 export type PhiCmsResolvedRequestLoaderArgs = {
     siteKey: string;
     locale: string;
@@ -441,7 +547,7 @@ export type PhiRuntimeModuleClientWidgetDefinition = {
     ownerModuleId: PhiRuntimeModuleId;
     title: string;
     signalSubcontrols?: readonly PhiCmsWidgetSignalSubcontrolCollection[];
-    slotSizePolicy?: PhiSlotSizePolicy;
+    slotSizePolicy: PhiSlotSizePolicy;
     renderPolicies: PhiRuntimeModuleRenderPolicies;
 };
 export type { PhiRuntimeModuleId } from "./cms-module-descriptors";
@@ -459,7 +565,6 @@ export type PhiRuntimeModuleDefinition = {
     kind: "platform" | "module";
     eligibleAreas: readonly PhiCmsAreaKey[];
     serverBinding: import("./server-capabilities").PhiRuntimeModuleServerBinding;
-    accessPolicy?: import("./access").PhiViewerAccessPolicy;
     controllerType?: `${string}/${string}`;
     controller?: PhiRuntimeModuleControllerDescriptor;
     sourceLocale?: string;
@@ -487,13 +592,92 @@ export type PhiRuntimeModuleDefinition = {
             readonly kinds: readonly import("./media").PhiMediaKindValue[];
         };
     };
+    /**
+     * The kinds of conversation this Module needs a Site to offer.
+     *
+     * A declaration, on the same terms as `mediaSpaces`: the Site's availability is the union across its
+     * active Modules, two Modules declaring the same kind do not collide, and a kind that stops being
+     * declared hides its threads rather than deleting them. No administrator switches one on -- a Site
+     * gains Support conversations by running a Support Module, not by being configured to.
+     *
+     * It says which kinds exist on the Site, never who may open one. That stays with the people and the
+     * groups: a group carries its own thread flags, and Staff is what Core's roles make somebody.
+     */
+    threadKinds?: readonly import("./threads").PhisDeclarableThreadKind[];
+    /**
+     * What this Module keeps about the person looking at it, per Site.
+     *
+     * Not a declaration in the sense of the two above, despite the placement. Those tell a Site what to
+     * make available and are materialized on publish; this one travels nowhere. phi-server admits a write
+     * on the key's prefix -- an active Module's id -- and checks the value against the shape the write
+     * itself names, so it needs no list from here and is not given one.
+     *
+     * It earns its place all the same. It lets this side refuse a malformed write before spending a round
+     * trip on it, and it puts what a Module stores where somebody reading that Module will find it, rather
+     * than leaving it to be discovered from rows in production. A key that is not declared still works,
+     * and that is the honest description of what this is: the Module's own account of itself.
+     *
+     * A dismissed card is a `flag`, a read position a `marker`, a place in a guided sequence a `value`.
+     * What is not here is anything the Module needs in order to work -- an order, a booking, a submission
+     * belongs in its own storage, because losing one of these should be an annoyance and not a support
+     * case.
+     */
+    userState?: readonly import("./user-state").PhisDeclarableUserStateKey[];
+    /**
+     * The rows this Module needs a Site to have before any of it works.
+     *
+     * Not a third declaration of the two above, whatever the placement suggests. Those declare
+     * availability: the Site's is the union across its Modules, it is recomputed from that union on every
+     * publish, and withdrawing one hides what it offered without losing anything. These are rows other
+     * rows point at -- a ticket names its queue and its type -- so they are found by the key the Module
+     * gives them, created when absent, never rewritten afterwards, and never deleted. Two Modules asking
+     * for "an entry queue" do not merge into one, and a second publish finds the first one's.
+     *
+     * What it is for is the Site that has just switched a Module on and can do nothing with it: Support
+     * needs one queue marked `Entry` and one ticket type to exist before anybody can open a ticket, and
+     * nobody should have to know that. The name each row is given is a starting value; once the row is
+     * there it is the Site's, and administration renames it without the next publish undoing that.
+     *
+     * Keys are resolved within one Module's own declaration -- a queue names its group by key, because the
+     * group has no id until the same publish gives it one.
+     */
+    seed?: {
+        readonly groups?: readonly import("./seed").PhisDeclaredSiteGroup[];
+        readonly supportQueues?: readonly import("./seed").PhisDeclaredSupportQueue[];
+        readonly supportTicketTypes?: readonly import("./seed").PhisDeclaredSupportTicketType[];
+    };
+    /**
+     * Renderers this Module offers for Collection items.
+     *
+     * Separate from `dataProviders` because it is the one contribution that is deliberately about another
+     * Module's data: a Module may declare a renderer for items whose provider it does not own, and a Site
+     * chooses it in the Collection View's `itemRendererKey`. The Module owning the items is not consulted
+     * and does not have to be -- it published a contract when it named its resource's renderer.
+     */
+    collectionItemRenderers?: readonly import("./collection-provider").PhiCollectionItemRendererDescriptor[];
     calendarAdapters?: readonly PhiCalendarAdapterDescriptor[];
+    /**
+     * Places a video may be fetched from, once somebody has asked for it.
+     *
+     * A contribution rather than a Core table, for the same reason Calendar adapters are: the Video Module
+     * ships the two everybody wants, and an add-on brings the one its customer uses without Core learning
+     * its name. A provider is plain data, so unlike an adapter it needs no Client loader -- the descriptors
+     * reach the browser as props and the placeholder reads them there.
+     */
+    videoProviders?: readonly import("./video").PhiVideoProviderDescriptor[];
     formProviders?: PhiRuntimeModuleFormProviderDescriptors;
     authUiProvider?: {
         providerKey: `${string}/${string}`;
         controllerType: `${string}/${string}`;
-        capabilitiesByArea: Partial<Record<PhiCmsAreaKey, readonly ("primary-login" | "factor-challenge" | "factor-enrollment" | "recovery" | "account-security" | "site-settings")[]>>;
-        accountSecurityPath?: `/${string}`;
+        capabilitiesByArea: Partial<Record<PhiCmsAreaKey, readonly ("primary-login" | "factor-challenge" | "factor-enrollment" | "recovery" | "site-settings")[]>>;
+        /**
+         * The Area Overlay this provider signs a visitor in through, per Area.
+         *
+         * The Account Widget opens it directly; the provider's Controller arrives with the Overlay's zones
+         * and hears the open it was sent while it was not there yet. An Area without one is signed into on
+         * the Public `/login` page. Only an Area whose capabilities include `primary-login` may name one.
+         */
+        loginOverlayByArea?: Partial<Record<PhiCmsAreaKey, PhiCmsInstanceId>>;
     };
 } & PhiRuntimeModuleIconMetadata;
 export type PhiRuntimeModuleUiProvider = ComponentType<{
@@ -578,7 +762,14 @@ export type PhiRuntimeModuleCatalogEntry = {
     navigation?: readonly PhiCmsNavigationInjectionDescriptor[];
     themes?: readonly PhiCmsThemePresetDescriptor[];
     themeBlocks?: readonly PhiCmsThemeBlockDescriptor[];
-    loadUiProvider?: () => Promise<PhiRuntimeModuleUiProvider>;
+    /**
+     * That the Module brings a UI provider, which its Client contributions hold.
+     *
+     * Only the statement: the provider is Client code, and loaded from here it was a client reference of
+     * every route that reached the catalog. The Area's Client boundary holds the loader
+     * (`components/runtime/runtime-module-ui-provider-client-manifest.tsx`).
+     */
+    uiProvider?: true;
     /**
      * Named facts about this Module's own configuration, for conditions to be written against.
      *
@@ -591,6 +782,18 @@ export type PhiRuntimeModuleCatalogEntry = {
         namespace: string;
         load: () => Promise<PhiRuntimeModuleFeatureResolver>;
     };
+    /**
+     * The cards this Module offers a Dashboard, loaded only when one asks.
+     *
+     * Declared like `features` and for the same reason: the answer is assembled on the server, from label
+     * sets and endpoints that must not reach the browser, and a Site whose Dashboard nobody opens never
+     * pays for it. The Module offers; which cards a Site shows is the Site's decision.
+     *
+     * There is no namespace to declare. A card carries its own id, and that id says whose it is.
+     */
+    dashboardCards?: {
+        load: () => Promise<import("./dashboard-cards").PhiDashboardCardProvider>;
+    };
     load: PhiRuntimeModuleLoader;
 };
 export type PhiRuntimeModuleFeatureContext = {
@@ -610,6 +813,7 @@ export type PhiResolvedRuntimeModuleSet = {
     layoutDefinitionsByType: ReadonlyMap<string, PhiRuntimeModuleLayoutDefinition>;
     dataProviderDescriptorsByKey: ReadonlyMap<PhiRuntimeDataProviderKey, PhiRuntimeModuleDataProviderDescriptor>;
     calendarAdapterDescriptorsByKey: ReadonlyMap<PhiCalendarAdapterKey, PhiCalendarAdapterDescriptor>;
+    videoProviderDescriptorsByKey: ReadonlyMap<import("./video").PhiVideoProviderKey, import("./video").PhiVideoProviderDescriptor>;
     formFieldTypeProviderDescriptorsByKey: ReadonlyMap<PhiFormProviderKey, PhiFormFieldTypeProviderDescriptor>;
     formValidationProviderDescriptorsByKey: ReadonlyMap<PhiFormProviderKey, PhiFormValidationProviderDescriptor>;
     formHandlerProviderDescriptorsByKey: ReadonlyMap<PhiFormProviderKey, PhiFormHandlerProviderDescriptor>;

package/types/cms-presets.d.ts

@@ -2,7 +2,7 @@ import type { CSSProperties } from "react";
 import type { PhiCmsContentWidgetNode, PhiCmsLayoutNode } from "./cms";
 import type { PhiCmsInstanceId } from "./cms-instance-id";
 import type { PhiCmsContainerChromeConfig } from "./cms-container";
-import type { PhiRenderableBlockEffects, PhiRenderableBlockSize, PhiRenderableBlockVisibility } from "./renderable-block";
+import type { PhiRenderableBlockEffects, PhiRenderableBlockResponsiveSize, PhiRenderableBlockSize, PhiRenderableBlockVisibility } from "./renderable-block";
 import type { PhiCssLength } from "./length";
 import type { PhiShadow } from "./layout-style";
 export type PhiCmsAreaKey = "public" | "app" | "admin" | "builder" | "editor" | "accounting";
@@ -25,9 +25,9 @@ export type PhiCmsRegionConfig = Record<string, unknown> & PhiCmsContainerChrome
     centered?: boolean;
     mobileOnly?: boolean;
     desktopOnly?: boolean;
-    size?: PhiRenderableBlockSize;
-    minSize?: PhiRenderableBlockSize;
-    maxSize?: PhiRenderableBlockSize;
+    size?: PhiRenderableBlockResponsiveSize;
+    minSize?: PhiRenderableBlockResponsiveSize;
+    maxSize?: PhiRenderableBlockResponsiveSize;
     collapsedSizeHint?: PhiRenderableBlockSize;
     opacity?: number;
     effects?: PhiRenderableBlockEffects;

package/types/cms.d.ts

@@ -1,4 +1,4 @@
-import type { PhiRuntimeModuleId } from "./cms-plugins";
+import type { PhiRuntimeControllerSetting, PhiRuntimeModuleId } from "./cms-plugins";
 import type { PhiCmsInstanceId } from "./cms-instance-id";
 import type { PhiCmsPresetSource } from "./cms-module-descriptors";
 import type { PhiViewerAccessPolicy } from "./access";
@@ -41,7 +41,7 @@ export type PhiCmsPageRedirectTarget = {
 };
 export type PhiCmsPageRedirectConfig = {
     target: PhiCmsPageRedirectTarget;
-    status?: 301 | 302 | 307 | 308;
+    status: 301 | 302 | 307 | 308;
 };
 export type PhiCmsRegionNode = {
     id: number;
@@ -95,9 +95,9 @@ export type PhiCmsResolvedContent = {
     id: number;
     type: number;
     slug: string;
+    /** The version the revision pins; `assetId`, `meta` and `textFields` are that version's. */
+    versionId: number;
     assetId: number | null;
-    currentVersionId: number | null;
-    publishedVersionId: number | null;
     status: number;
     meta: Record<string, unknown>;
     textFields: Record<string, PhiCmsResolvedContentTextField>;
@@ -105,6 +105,11 @@ export type PhiCmsResolvedContent = {
 export type PhiCmsContentWidgetNode = PhiCmsNodeBase & {
     parentLayoutNodeId: PhiCmsInstanceId;
     contentId: number | null;
+    /**
+     * The content version this revision shows. The server sets it on every save that writes the content;
+     * a Widget that has written none yet has none.
+     */
+    contentVersionId?: number | null;
     resolvedContent?: PhiCmsResolvedContent | null;
 };
 export type PhiResolvedCmsPageTree = {
@@ -115,6 +120,19 @@ export type PhiResolvedCmsPageTree = {
     overlays: PhiCmsOverlayNode[];
     layoutNodes: PhiCmsLayoutNode[];
     contentWidgets: PhiCmsContentWidgetNode[];
+    /**
+     * The Controllers this Page configures, and what it tells them.
+     *
+     * An Area has had this for as long as it has had Controllers -- `areaControllerSettings` on the
+     * module set -- and a Page had nothing. So a Page-scope Controller could be brought into being by a
+     * Widget asking for it and then be told nothing, which is why the Controllers on the conversations
+     * and groups Pages addressed their Widgets out of a preset id map: there was no other way to learn
+     * who to send to, and it holds only while the same code owns both ends.
+     *
+     * A Page says it here, beside the routes it already writes for every Widget on it. Demand mounting
+     * is untouched: a setting says what a Controller is configured with, not that it is running.
+     */
+    controllerSettings?: readonly PhiRuntimeControllerSetting[] | null;
 };
 export type PhiResolvedCmsRenderableTree = Pick<PhiResolvedCmsPageTree, "regions" | "overlays" | "layoutNodes" | "contentWidgets"> & {
     page?: PhiCmsPageNode | null;

package/types/collection-provider.d.ts

@@ -1,4 +1,22 @@
-import type { PhiRuntimeDataProviderBinding } from "./runtime-data-provider";
+import type { PhiSignalValueSchema } from "./signals";
+/**
+ * A renderer a Module offers for Collection items, its own or somebody else's.
+ *
+ * `key` is the Render Client the Module registers; `rendersItemsOf` is the resource `itemRendererKey`
+ * it can stand in for. The two are the same for the renderer a provider ships with its own resource,
+ * and differ for every alternative -- which is the whole point: a Module states that it can draw items
+ * it does not own, and says so by naming the contract rather than the provider, so it never has to
+ * import the Module that owns them.
+ *
+ * Declaring is not registering. This is what the Builder reads to offer a choice; the component itself
+ * is an ordinary Render Client entry in the Area's manifest.
+ */
+export type PhiCollectionItemRendererDescriptor = {
+    key: `${string}/${string}`;
+    rendersItemsOf: `${string}/${string}`;
+    title: string;
+    description?: string;
+};
 export type PhiCollectionProviderFilterType = "string" | "enum" | "enum[]" | "path";
 export type PhiCollectionProviderFilterDescriptor = {
     key: string;
@@ -21,6 +39,18 @@ export type PhiCollectionProviderResourceDescriptor = {
     description?: string;
     itemIdentityPath: string;
     itemRendererKey: `${string}/${string}`;
+    /**
+     * The schema a selection from this resource travels under.
+     *
+     * It belongs here and not on the Widget, because the Widget is generic: `collection-view` shows
+     * whatever provider is bound to it, so a selection means whatever the bound resource says it means. A
+     * Module names its own schema -- one from this package through the ownership registry, one from
+     * another repository through `createPhiSignalValueSchema` and its own package name -- and Core passes
+     * it through without ever having to know the word.
+     *
+     * Absent means this resource announces no selection, and the Builder offers no route for one.
+     */
+    selectionValueSchema?: PhiSignalValueSchema;
     defaultForWidget?: boolean;
     query: {
         search?: boolean;
@@ -36,12 +66,9 @@ export type PhiCollectionProviderQuery = {
     pageSize?: number;
     search?: string;
     sortKey?: string;
-    sortOrder?: "ascend" | "descend";
+    sortOrder?: "ascending" | "descending";
     filters?: Record<string, PhiCollectionProviderQueryValue>;
 };
-export type PhiCollectionProviderDataSource = PhiRuntimeDataProviderBinding & {
-    resourceKey: string;
-};
 export type PhiCollectionProviderData = {
     resourceKey: string;
     items: Record<string, unknown>[];