@phis/ui 0.4.2 → 0.4.3

package/types/cms-config.js

@@ -4,42 +4,28 @@ import { readPhiCmsMountPolicy } from "./cms-mount-policy";
 import { clampPhiSequenceTransitionMs, readPhiMotionEasing, PHI_SEQUENCE_ANCHORS, PHI_SEQUENCE_TRANSITIONS, } from "../helpers/motion";
 import { readPhiLengthValue } from "./length";
 import { isPhiAnchorWidgetPlacement, resolvePhiRenderableBlockAnchor, } from "../components/controls/phi-anchor-control-contract";
-import { readBoolean, readCssSize, readNumber, readRenderableBlockConfig, readString, } from "../components/widgets/config/parser-primitives";
+import { readCssSize, readRenderableBlockConfig, } from "../components/widgets/config/parser-primitives";
 import { applyPhiLayoutDefaults } from "../helpers/cms-layout-defaults";
 import { resolvePhiLayoutDefaults } from "../helpers/cms-layout-defaults";
 import { normalizeRenderableBlockAnchor } from "../helpers/renderable-block-anchor";
 import { isPhiRecord } from "../helpers/is-record";
+import { createPhiConfigReader } from "../components/widgets/config/strict-config-reader";
 import { PHI_SPACING_SCALE_KEYS } from "../components/widgets/config/spacing-options";
 import { PHI_GRID_COLUMN_COUNTS, isPhiGridColumnCount } from "../constants/grid-columns";
-function readInitialSlotStates(value) {
-    if (Array.isArray(value)) {
-        const normalized = value.map((candidate) => candidate === "expanded" || candidate === "collapsed" || candidate === "hidden" ? candidate : undefined);
-        return normalized.some((candidate) => candidate !== undefined) ? normalized : undefined;
-    }
-    if (!value || typeof value !== "object") {
-        return undefined;
-    }
-    const raw = value;
-    const next = {};
-    for (const [key, candidate] of Object.entries(raw)) {
-        const slotIndex = Number(key);
-        if (!Number.isInteger(slotIndex) || slotIndex < 0) {
-            continue;
-        }
-        if (candidate === "expanded" || candidate === "collapsed" || candidate === "hidden") {
-            next[slotIndex] = candidate;
+const PHI_LAYOUT_SLOT_STATES = ["expanded", "collapsed", "hidden"];
+/** A Layout's starting slot states: a list by slot, gaps allowed, or a record keyed by slot index. */
+function readInitialSlotStates(reader) {
+    return reader.value("initialSlotStates", "slot states by slot index", (value) => {
+        const isState = (candidate) => candidate == null || PHI_LAYOUT_SLOT_STATES.includes(candidate);
+        if (Array.isArray(value)) {
+            return value.every(isState) ? value : undefined;
         }
-    }
-    return Object.keys(next).length > 0 ? next : undefined;
-}
-function readStringArray(value) {
-    if (!Array.isArray(value)) {
-        return undefined;
-    }
-    const next = value
-        .map((candidate) => (typeof candidate === "string" ? candidate.trim() : ""))
-        .filter((candidate) => candidate.length > 0);
-    return [...new Set(next)];
+        if (!isPhiRecord(value))
+            return undefined;
+        return Object.entries(value).every(([key, candidate]) => Number.isInteger(Number(key)) && Number(key) >= 0 && isState(candidate))
+            ? value
+            : undefined;
+    });
 }
 export function normalizePhiPaddingWidgetConfig(config) {
     if (!isPhiRecord(config)) {
@@ -153,18 +139,14 @@ function readRenderableBlockAnchorOrPlacement(value) {
         ? resolvePhiRenderableBlockAnchor(value)
         : undefined;
 }
-function readGridResponsiveCount(value, accepts) {
-    if (!isPhiRecord(value))
-        return undefined;
-    const record = value;
-    const read = (key) => {
-        const candidate = readNumber(record[key]);
-        return candidate != null && Number.isInteger(candidate) && accepts(candidate) ? candidate : undefined;
-    };
-    const responsive = { compact: read("compact"), medium: read("medium"), wide: read("wide") };
-    return responsive.compact != null || responsive.medium != null || responsive.wide != null
-        ? responsive
-        : undefined;
+function readLayoutAnchor(reader) {
+    return reader.value("anchor", "an anchor or a placement", readRenderableBlockAnchorOrPlacement);
+}
+function readGridResponsiveCount(reader, key, expected, accepts) {
+    return reader.object(key, (countReader) => {
+        const read = (width) => countReader.value(width, expected, (candidate) => typeof candidate === "number" && Number.isInteger(candidate) && accepts(candidate) ? candidate : undefined);
+        return { compact: read("compact"), medium: read("medium"), wide: read("wide") };
+    });
 }
 const PHI_GRID_MAX_COLUMNS = Math.max(...PHI_GRID_COLUMN_COUNTS);
 /*
@@ -172,32 +154,43 @@ const PHI_GRID_MAX_COLUMNS = Math.max(...PHI_GRID_COLUMN_COUNTS);
  * they fit the row at a given width is answered where the row is known, by clamping
  * (`resolvePhiGridSlotPlacement`): a Grid whose columns were reduced keeps its stated placements.
  */
-function readGridSlotPlacement(value, slotIndexFromArray) {
-    if (!isPhiRecord(value)) {
-        return null;
-    }
-    const slot = value;
-    const slotIndex = readNumber(slot.slotIndex) ?? slotIndexFromArray;
-    if (!Number.isInteger(slotIndex) || slotIndex == null || slotIndex < 0) {
-        return null;
-    }
-    const span = readGridResponsiveCount(slot.span, (candidate) => candidate >= 1 && candidate <= PHI_GRID_MAX_COLUMNS);
-    const offset = readGridResponsiveCount(slot.offset, (candidate) => candidate >= 0 && candidate < PHI_GRID_MAX_COLUMNS);
+function readGridSlotPlacement(reader, slotIndexFromArray) {
+    const slotIndex = reader.value("slotIndex", "a slot index", (candidate) => typeof candidate === "number" && Number.isInteger(candidate) && candidate >= 0 ? candidate : undefined) ?? slotIndexFromArray;
+    const span = readGridResponsiveCount(reader, "span", `a whole number from 1 to ${PHI_GRID_MAX_COLUMNS}`, (candidate) => candidate >= 1 && candidate <= PHI_GRID_MAX_COLUMNS);
+    const offset = readGridResponsiveCount(reader, "offset", `a whole number from 0 to ${PHI_GRID_MAX_COLUMNS - 1}`, (candidate) => candidate >= 0 && candidate < PHI_GRID_MAX_COLUMNS);
     if (!span && !offset)
-        return null;
+        reader.fail("span", "a span or an offset", undefined);
     return { slotIndex, span, offset };
 }
 /**
- * A shared Layout field, read the same way wherever it appears: a line on the 24-track form grid, so
- * anything outside 2..24 is not a narrower column but a mistake, and is dropped rather than clamped.
+ * The fields many Layouts share, read the same way wherever they appear. A label end is a line on the
+ * 24-track form grid, so anything outside 2..24 is not a narrower column but a mistake.
  */
-function readPhiLayoutLabelEnd(value) {
-    const labelEnd = readNumber(value);
-    return labelEnd !== undefined && Number.isInteger(labelEnd) && labelEnd >= 2 && labelEnd <= 24
-        ? labelEnd
-        : undefined;
+function readCssSizeField(reader, key) {
+    return reader.value(key, "a CSS size", (value) => (typeof value === "number" && Number.isFinite(value)) || typeof value === "string" ? value : undefined);
+}
+function readLengthField(reader, key) {
+    return reader.value(key, "a CSS length", (value) => readPhiLengthValue(value) ?? undefined);
+}
+function readLayoutLabelEnd(reader) {
+    return reader.value("labelEnd", "a whole number from 2 to 24", (value) => typeof value === "number" && Number.isInteger(value) && value >= 2 && value <= 24 ? value : undefined);
+}
+function readLayoutPadding(reader) {
+    return {
+        padding: readCssSizeField(reader, "padding"),
+        paddingLeft: readCssSizeField(reader, "paddingLeft"),
+        paddingRight: readCssSizeField(reader, "paddingRight"),
+        paddingTop: readCssSizeField(reader, "paddingTop"),
+        paddingBottom: readCssSizeField(reader, "paddingBottom"),
+    };
+}
+function readFlexWrap(reader) {
+    return reader.value("wrap", "true, false or a flex wrap", (value) => typeof value === "boolean" || value === "nowrap" || value === "wrap" || value === "wrap-reverse"
+        ? value
+        : undefined) ?? false;
 }
 export function parsePhiCmsContentLayoutConfig(config) {
+    const reader = createPhiConfigReader(config);
     return applyPhiLayoutDefaults({
         ...readRenderableBlockConfig(config),
         /*
@@ -207,82 +200,65 @@ export function parsePhiCmsContentLayoutConfig(config) {
          * constraints never had the second way at all -- nothing has ever read a flat `maxWidth`.
          */
         size: normalizePhiRenderableBlockResponsiveSize(config.size),
-        margin: readCssSize(config.margin),
-        labelEnd: readPhiLayoutLabelEnd(config.labelEnd),
-        padding: readCssSize(config.padding),
-        paddingLeft: readCssSize(config.paddingLeft),
-        paddingRight: readCssSize(config.paddingRight),
-        paddingTop: readCssSize(config.paddingTop),
-        paddingBottom: readCssSize(config.paddingBottom),
+        margin: readCssSizeField(reader, "margin"),
+        labelEnd: readLayoutLabelEnd(reader),
+        ...readLayoutPadding(reader),
         /*
          * Handed on as the block anchor, like every other Layout's. This one used to be folded into a
          * placement name here, and the renderer then asked the name for its `horizontal` -- a string has
          * none, so a Content Layout anchored left drew centred wherever the parsed config reached it, in
          * preview and live, while the Builder, which hands the object straight through, drew it left.
          */
-        anchor: readRenderableBlockAnchorOrPlacement(config.anchor),
+        anchor: readLayoutAnchor(reader),
     }, resolvePhiLayoutDefaults("content"));
 }
 export function parsePhiCmsFlexLayoutConfig(config) {
-    const distribution = readString(config.distribution);
+    const reader = createPhiConfigReader(config);
     return applyPhiLayoutDefaults({
         ...readRenderableBlockConfig(config),
-        labelEnd: readPhiLayoutLabelEnd(config.labelEnd),
-        initialSlotStates: readInitialSlotStates(config.initialSlotStates),
-        padding: readCssSize(config.padding),
-        paddingLeft: readCssSize(config.paddingLeft),
-        paddingRight: readCssSize(config.paddingRight),
-        paddingTop: readCssSize(config.paddingTop),
-        paddingBottom: readCssSize(config.paddingBottom),
-        gap: readCssSize(config.gap),
-        verticalSeparators: readBoolean(config.verticalSeparators) ?? false,
-        separatorBeforeFirst: readBoolean(config.separatorBeforeFirst) ?? false,
-        separatorSpan: readPhiLengthValue(config.separatorSpan) ?? undefined,
-        anchor: readRenderableBlockAnchorOrPlacement(config.anchor),
-        distribution: distribution === "between" || distribution === "around" || distribution === "evenly"
-            ? distribution
-            : "anchor",
-        wrap: readBoolean(config.wrap) ??
-            readString(config.wrap) ??
-            false,
+        labelEnd: readLayoutLabelEnd(reader),
+        initialSlotStates: readInitialSlotStates(reader),
+        ...readLayoutPadding(reader),
+        gap: readCssSizeField(reader, "gap"),
+        verticalSeparators: reader.boolean("verticalSeparators") ?? false,
+        separatorBeforeFirst: reader.boolean("separatorBeforeFirst") ?? false,
+        separatorSpan: readLengthField(reader, "separatorSpan"),
+        anchor: readLayoutAnchor(reader),
+        distribution: reader.oneOf("distribution", ["anchor", "between", "around", "evenly"]) ?? "anchor",
+        wrap: readFlexWrap(reader),
     }, resolvePhiLayoutDefaults("flex"));
 }
 export function parsePhiCmsFlexVerticalLayoutConfig(config) {
+    const reader = createPhiConfigReader(config);
     return applyPhiLayoutDefaults({
         ...readRenderableBlockConfig(config),
-        labelEnd: readPhiLayoutLabelEnd(config.labelEnd),
-        initialSlotStates: readInitialSlotStates(config.initialSlotStates),
-        padding: readCssSize(config.padding),
-        paddingLeft: readCssSize(config.paddingLeft),
-        paddingRight: readCssSize(config.paddingRight),
-        paddingTop: readCssSize(config.paddingTop),
-        paddingBottom: readCssSize(config.paddingBottom),
-        gap: readCssSize(config.gap),
-        anchor: readRenderableBlockAnchorOrPlacement(config.anchor),
+        labelEnd: readLayoutLabelEnd(reader),
+        initialSlotStates: readInitialSlotStates(reader),
+        ...readLayoutPadding(reader),
+        gap: readCssSizeField(reader, "gap"),
+        anchor: readLayoutAnchor(reader),
     }, resolvePhiLayoutDefaults("verticalflex"));
 }
 export function parsePhiCmsMasonryLayoutConfig(config) {
+    const reader = createPhiConfigReader(config);
     return applyPhiLayoutDefaults({
         ...readRenderableBlockConfig(config),
-        labelEnd: readPhiLayoutLabelEnd(config.labelEnd),
-        padding: readCssSize(config.padding),
-        paddingLeft: readCssSize(config.paddingLeft),
-        paddingRight: readCssSize(config.paddingRight),
-        paddingTop: readCssSize(config.paddingTop),
-        paddingBottom: readCssSize(config.paddingBottom),
-        columns: readGridResponsiveCount(config.columns, isPhiGridColumnCount),
-        gap: readCssSize(config.gap),
+        labelEnd: readLayoutLabelEnd(reader),
+        ...readLayoutPadding(reader),
+        columns: readGridResponsiveCount(reader, "columns", "a Grid column count", isPhiGridColumnCount),
+        gap: readCssSizeField(reader, "gap"),
     }, resolvePhiLayoutDefaults("masonry"));
 }
 export function parsePhiCmsStackLayoutConfig(config) {
+    const reader = createPhiConfigReader(config);
     return applyPhiLayoutDefaults({
         ...readRenderableBlockConfig(config),
-        labelEnd: readPhiLayoutLabelEnd(config.labelEnd),
-        padding: readCssSize(config.padding),
-        defaultActiveSlotKey: readString(config.defaultActiveSlotKey),
-        slotDisplay: config.slotDisplay === "stacked" ? "stacked" : "single",
+        labelEnd: readLayoutLabelEnd(reader),
+        padding: readCssSizeField(reader, "padding"),
+        defaultActiveSlotKey: reader.string("defaultActiveSlotKey"),
+        slotDisplay: reader.oneOf("slotDisplay", ["single", "stacked"]) ?? "single",
         mountPolicy: readPhiCmsMountPolicy(config.mountPolicy, "remount"),
-        slotTransition: config.slotTransition === "fade-over" ? "fade-over" : "none",
+        slotTransition: reader.oneOf("slotTransition", ["none", "fade-over"]) ?? "none",
         // Absent means "whatever the theme does", which is why the fallback is read from the token
         // rather than written here as a number.
         ...(config.slotTransitionDurationMs === undefined ? {} : {
@@ -338,9 +314,9 @@ export function parsePhiCmsCarouselLayoutConfig(config) {
     const slotGap = readCarouselMember(config.slotGap, PHI_SPACING_SCALE_KEYS, "slotGap");
     return applyPhiLayoutDefaults({
         ...readRenderableBlockConfig(config),
-        labelEnd: readPhiLayoutLabelEnd(config.labelEnd),
-        padding: readCssSize(config.padding),
-        defaultActiveSlotKey: readString(config.defaultActiveSlotKey),
+        labelEnd: readLayoutLabelEnd(createPhiConfigReader(config)),
+        padding: readCssSizeField(createPhiConfigReader(config), "padding"),
+        defaultActiveSlotKey: createPhiConfigReader(config).string("defaultActiveSlotKey"),
         ...(visibleSlots === undefined ? {} : { visibleSlots }),
         ...(windowAnchor === undefined ? {} : { windowAnchor }),
         ...(transition === undefined ? {} : { transition }),
@@ -361,100 +337,81 @@ export function parsePhiCmsCarouselLayoutConfig(config) {
         ...(lookahead === undefined ? {} : { lookahead }),
     }, resolvePhiLayoutDefaults("carousel"));
 }
-function readCollapsibleTrigger(value) {
-    return value === "header" || value === "icon" || value === "disabled" ? value : undefined;
-}
-function readCollapsibleSize(value) {
-    return readPhiControlSize(value);
-}
-function readExpandIconPlacement(value) {
-    return value === "start" || value === "end" ? value : undefined;
-}
-function readSlotTexts(value) {
-    if (!Array.isArray(value)) {
+/** Panel titles or descriptions by slot: texts, an empty one for a slot that has none; trailing empties trimmed. */
+function readSlotTexts(reader, key) {
+    const texts = reader.value(key, "a list of texts", (value) => Array.isArray(value) && value.every((candidate) => typeof candidate === "string")
+        ? value.map((candidate) => candidate.trim())
+        : undefined);
+    if (!texts)
         return undefined;
-    }
-    const texts = value.map((candidate) => (typeof candidate === "string" ? candidate.trim() : ""));
-    while (texts.length > 0 && !texts[texts.length - 1]) {
+    while (texts.length > 0 && !texts[texts.length - 1])
         texts.pop();
-    }
     return texts.length > 0 ? texts : undefined;
 }
 export function parsePhiCmsCollapsibleLayoutConfig(config) {
+    const reader = createPhiConfigReader(config);
+    const defaultOpenSlotKeys = reader.stringList("defaultOpenSlotKeys");
     return applyPhiLayoutDefaults({
         ...readRenderableBlockConfig(config),
-        labelEnd: readPhiLayoutLabelEnd(config.labelEnd),
-        initialSlotStates: readInitialSlotStates(config.initialSlotStates),
-        padding: readCssSize(config.padding),
-        paddingLeft: readCssSize(config.paddingLeft),
-        paddingRight: readCssSize(config.paddingRight),
-        paddingTop: readCssSize(config.paddingTop),
-        paddingBottom: readCssSize(config.paddingBottom),
-        anchor: readRenderableBlockAnchorOrPlacement(config.anchor),
-        panelMinHeight: readPhiLengthValue(config.panelMinHeight) ?? undefined,
-        accordion: readBoolean(config.accordion),
-        slotTitles: readSlotTexts(config.slotTitles),
-        slotDescriptions: readSlotTexts(config.slotDescriptions),
-        defaultOpenSlotKeys: readStringArray(config.defaultOpenSlotKeys),
-        collapsible: readCollapsibleTrigger(config.collapsible),
-        ghost: readBoolean(config.ghost),
-        expandIconPlacement: readExpandIconPlacement(config.expandIconPlacement),
-        collapseSize: readCollapsibleSize(config.collapseSize),
-        titleStrong: readBoolean(config.titleStrong),
-        headerPadding: readCssSize(config.headerPadding),
-        innerPadding: readCssSize(config.innerPadding),
+        labelEnd: readLayoutLabelEnd(reader),
+        initialSlotStates: readInitialSlotStates(reader),
+        ...readLayoutPadding(reader),
+        anchor: readLayoutAnchor(reader),
+        panelMinHeight: readLengthField(reader, "panelMinHeight"),
+        accordion: reader.boolean("accordion"),
+        slotTitles: readSlotTexts(reader, "slotTitles"),
+        slotDescriptions: readSlotTexts(reader, "slotDescriptions"),
+        defaultOpenSlotKeys: defaultOpenSlotKeys
+            ? [...new Set(defaultOpenSlotKeys.map((key) => key.trim()).filter(Boolean))]
+            : undefined,
+        collapsible: reader.oneOf("collapsible", ["header", "icon", "disabled"]),
+        ghost: reader.boolean("ghost"),
+        expandIconPlacement: reader.oneOf("expandIconPlacement", ["start", "end"]),
+        collapseSize: reader.value("collapseSize", "a control size", readPhiControlSize),
+        titleStrong: reader.boolean("titleStrong"),
+        headerPadding: readCssSizeField(reader, "headerPadding"),
+        innerPadding: readCssSizeField(reader, "innerPadding"),
     }, resolvePhiLayoutDefaults("collapsible"));
 }
 export function parsePhiCmsGridLayoutConfig(config) {
+    const reader = createPhiConfigReader(config);
     return applyPhiLayoutDefaults({
         ...readRenderableBlockConfig(config),
-        labelEnd: readPhiLayoutLabelEnd(config.labelEnd),
-        padding: readCssSize(config.padding),
-        paddingLeft: readCssSize(config.paddingLeft),
-        paddingRight: readCssSize(config.paddingRight),
-        paddingTop: readCssSize(config.paddingTop),
-        paddingBottom: readCssSize(config.paddingBottom),
-        gap: readCssSize(config.gap),
-        anchor: readRenderableBlockAnchorOrPlacement(config.anchor),
-        columns: readGridResponsiveCount(config.columns, isPhiGridColumnCount),
-        slotPlacements: Array.isArray(config.slotPlacements)
-            ? config.slotPlacements
-                .map((slot, slotIndex) => readGridSlotPlacement(slot, slotIndex))
-                .filter((slot) => slot !== null)
-            : undefined,
+        labelEnd: readLayoutLabelEnd(reader),
+        ...readLayoutPadding(reader),
+        gap: readCssSizeField(reader, "gap"),
+        anchor: readLayoutAnchor(reader),
+        columns: readGridResponsiveCount(reader, "columns", "a Grid column count", isPhiGridColumnCount),
+        slotPlacements: reader.list("slotPlacements", readGridSlotPlacement),
     }, resolvePhiLayoutDefaults("grid"));
 }
 export function parsePhiCmsThreeColumnLayoutConfig(config) {
+    const reader = createPhiConfigReader(config);
     return applyPhiLayoutDefaults({
         ...readRenderableBlockConfig(config),
-        labelEnd: readPhiLayoutLabelEnd(config.labelEnd),
-        padding: readCssSize(config.padding),
-        paddingLeft: readCssSize(config.paddingLeft),
-        paddingRight: readCssSize(config.paddingRight),
-        paddingTop: readCssSize(config.paddingTop),
-        paddingBottom: readCssSize(config.paddingBottom),
-        balancedSides: readBoolean(config.balancedSides) ?? true,
-        gap: readCssSize(config.gap),
-        anchor: readRenderableBlockAnchorOrPlacement(config.anchor),
-        align: readString(config.align),
-        justify: readString(config.justify),
-        wrap: readBoolean(config.wrap) ??
-            readString(config.wrap) ??
-            false,
-        leftWidth: readPhiLengthValue(config.leftWidth) ?? undefined,
-        middleWidth: readPhiLengthValue(config.middleWidth) ?? undefined,
-        rightWidth: readPhiLengthValue(config.rightWidth) ?? undefined,
-        contentAlign: readString(config.contentAlign),
+        labelEnd: readLayoutLabelEnd(reader),
+        ...readLayoutPadding(reader),
+        balancedSides: reader.boolean("balancedSides") ?? true,
+        gap: readCssSizeField(reader, "gap"),
+        anchor: readLayoutAnchor(reader),
+        align: reader.string("align"),
+        justify: reader.string("justify"),
+        wrap: readFlexWrap(reader),
+        leftWidth: readLengthField(reader, "leftWidth"),
+        middleWidth: readLengthField(reader, "middleWidth"),
+        rightWidth: readLengthField(reader, "rightWidth"),
+        contentAlign: reader.string("contentAlign"),
     }, resolvePhiLayoutDefaults("threecol"));
 }
 export function parsePhiCmsSplitCardLayoutConfig(config) {
+    const reader = createPhiConfigReader(config);
     return applyPhiLayoutDefaults({
         ...readRenderableBlockConfig(config),
-        labelEnd: readPhiLayoutLabelEnd(config.labelEnd),
-        gap: readCssSize(config.gap),
-        swapRatio: readBoolean(config.swapRatio),
-        padding: readCssSize(config.padding),
-        paddingTop: readCssSize(config.paddingTop),
-        paddingBottom: readCssSize(config.paddingBottom),
+        labelEnd: readLayoutLabelEnd(reader),
+        gap: readCssSizeField(reader, "gap"),
+        swapRatio: reader.boolean("swapRatio"),
+        padding: readCssSizeField(reader, "padding"),
+        paddingTop: readCssSizeField(reader, "paddingTop"),
+        paddingBottom: readCssSizeField(reader, "paddingBottom"),
     }, resolvePhiLayoutDefaults("split"));
 }

package/types/cms-plugins.d.ts

@@ -101,7 +101,6 @@ export type PhiCmsConfigFieldChoiceMode = "single" | "multiple";
 export type PhiCmsConfigFieldChoiceValueType = "string" | "string[]" | "number";
 export type PhiCmsConfigFieldChoiceCreateBehavior = "none" | "accept-custom" | "create-record";
 export type PhiCmsConfigFieldColorMode = "single" | "gradient" | "both";
-export type PhiCmsConfigFieldValueStorage = "field" | "self";
 export type PhiCmsConfigFieldChoiceFilter = {
     widgetType?: string;
     group?: string;
@@ -290,14 +289,6 @@ export type PhiCmsConfigField = (PhiCmsConfigFieldBase & {
     presentation?: PhiCmsConfigFieldCollectionPresentation;
     /** What the button that opens the Overlay says. */
     editLabel?: string;
-}) | (PhiCmsConfigFieldBase & {
-    type: "background";
-    section?: string;
-    storage?: PhiCmsConfigFieldValueStorage;
-}) | (PhiCmsConfigFieldBase & {
-    type: "border";
-    section?: string;
-    storage?: PhiCmsConfigFieldValueStorage;
 }) | (PhiCmsConfigFieldBase & {
     /**
      * A Surface (`types/surface.ts`) of something the Widget draws inside itself -- each entry of a
@@ -308,7 +299,7 @@ export type PhiCmsConfigField = (PhiCmsConfigFieldBase & {
     /** Whether the mode is offered; left out, it is. */
     tone?: false;
 }) | (PhiCmsConfigFieldBase & {
-    type: "shadow" | "grid-placement" | "column-count";
+    type: "grid-placement" | "column-count";
     section?: string;
 });
 export type PhiCmsLayoutSlotDefinition = {
@@ -575,7 +566,9 @@ export type PhiCmsRuntimeRenderRegistry = {
     dataProviderDescriptorsByKey: ReadonlyMap<PhiRuntimeDataProviderKey, PhiRuntimeModuleDataProviderDescriptor>;
     formDefinitionsById: ReadonlyMap<string, PhiRuntimeModuleFormDefinition>;
 };
-export type PhiCmsRenderIssueCode = "missing-module" | "missing-renderer" | "renderer-load-failed" | "render-failed" | "invalid-render-output"
+export type PhiCmsRenderIssueCode = "missing-module" | "missing-renderer" | "renderer-load-failed" | "render-failed"
+/** The stored config holds a value the block cannot read (`PhiConfigError`); the detail names the field. */
+ | "invalid-config" | "invalid-render-output"
 /** A node whose `visibleWhen` reads a feature namespace whose Module could not be asked this render. */
  | "feature-unavailable"
 /** A Region or Overlay zone names a root layout node the tree does not contain. */

package/types/core-widget-placements.d.ts

@@ -18,7 +18,7 @@ import type { PhiTextTone } from "../components/widgets/config/text-tone";
 import type { PhiCommonControlActionKey } from "../components/widgets/label-types/common-controls";
 import type { PhiMaskConfig } from "../components/widgets/config/mask";
 import type { PhiSpacingScaleKey } from "../components/widgets/config/spacing-options";
-import type { PhiCardVariant } from "../components/widgets/shared/card-vocabulary";
+import type { PhiCardBillingPeriod, PhiCardVariant } from "../components/widgets/shared/card-vocabulary";
 import type { PhiControlBadgeConfig, PhiControlConfig } from "../components/widgets/config/control-signal-config";
 /**
  * The part of a placement every Widget shares, whatever it is.
@@ -285,10 +285,21 @@ export type PhiCmsCollectionCardPresentation = {
     actionLabel?: string;
     actionHref?: string;
     variant?: PhiCardVariant;
-    /** Every card in the View draws this body; `stat` needs `value`. */
-    body?: "text" | "stat";
+    /** Every card in the View draws this body; `stat` needs `value`, `plan` a `price`. */
+    body?: "text" | "stat" | "plan";
     /** A field whose truth marks the card as highlighted. */
     highlight?: string;
+    /** The words on the card's band. */
+    badge?: string;
+    /** A `plan`'s prices and their periods, as a provider answers them -- per country, if it knows one. */
+    price?: string;
+    pricePeriod?: string;
+    priceYearly?: string;
+    pricePeriodYearly?: string;
+    /** A field holding the plan's features, each `{ text, state? }` (`PhiBulletListEntry`). */
+    features?: string;
+    /** Which price every plan card of the View shows. Not a path: the View's own choice. */
+    billingPeriod?: PhiCardBillingPeriod;
 };
 export type PhiCollectionViewWidgetPlacement = PhiWidgetPlacementBase & {
     presentation?: {

package/types/dashboard-cards.d.ts

@@ -1,3 +1,4 @@
+import type { PhiRuntimeModuleCatalog } from "./cms-plugins";
 import type { PhiCmsAreaKey } from "../constants/cms-areas";
 import type { PhiTimelineEntry } from "@phis/contracts/timeline";
 import type { PhiAccessViewer, PhiViewerAccessPolicy } from "./access";
@@ -133,6 +134,14 @@ export type PhiDashboardCardContext = {
     locale: string;
     area: PhiCmsAreaKey;
     viewer: PhiAccessViewer;
+    /**
+     * The Module catalog of the Area the Dashboard stands in.
+     *
+     * A card about structure -- which Area has an open draft -- has to know the Area shells, and the
+     * only catalog it may know is the one it is running in. Importing the first-party catalog instead
+     * would compile every Module into the provider (MODULES.md, "The dependency rule").
+     */
+    runtimeModuleCatalog: PhiRuntimeModuleCatalog;
 };
 /**
  * One Module's answer, loaded on the server and never reached from the browser.

package/types/media.d.ts

@@ -69,7 +69,6 @@ export type PhiMediaAssetVariant = {
     deliveryUrl: string;
     contentType: string;
     bytes: number | null;
-    checksumSha256: string | null;
     width: number;
     height: number;
     blurDataUrl: string | null;
@@ -90,7 +89,6 @@ export type PhiMediaAsset = {
     contentType: string;
     kind: PhiMediaKindValue;
     bytes: number | null;
-    checksumSha256: string | null;
     width: number | null;
     height: number | null;
     blurDataUrl: string | null;
@@ -127,7 +125,6 @@ export type PhiMediaAssetTile = {
     width: number | null;
     height: number | null;
     bytes: number | null;
-    checksumSha256: string | null;
     lifecycleStatus: number;
     deliveryPolicy: number;
     deliveryRevision: number;

package/types/renderable-block.d.ts

@@ -48,7 +48,12 @@ export type PhiRenderableBlockTransitionEasing = PhiMotionEasing;
 export type PhiRenderableBlockTransitionAxis = "x" | "y" | "z";
 export type PhiRenderableBlockTransitionOrigin = "top left" | "top center" | "top right" | "center left" | "center" | "center right" | "bottom left" | "bottom center" | "bottom right";
 export type PhiRenderableBlockTransitionTrigger = "on_mount" | "on_ready" | "on_visible" | "on_hover" | "on_focus" | "manual";
-export type PhiRenderableBlockViewportEffectAxis = "x" | "y";
+/**
+ * Along which axis a viewport effect moves, or about which one it turns. `z` turns flat in the page plane
+ * and only means something for `rotate`; a translate along `z` is refused when the config is read. Progress
+ * is measured along `x` for `x`, and along the page's own scroll direction for `y` and `z`.
+ */
+export type PhiRenderableBlockViewportEffectAxis = "x" | "y" | "z";
 export type PhiRenderableBlockViewportEffectProperty = "translate" | "opacity" | "rotate" | "scale";
 export type PhiRenderableBlockViewportEffectRangePoint = "enter" | "center" | "exit";
 export type PhiRenderableBlockViewportEffectUnit = "px" | "%" | "deg" | "";

package/types/table-widget.d.ts

@@ -426,6 +426,15 @@ export type PhiTableProviderQueryCapabilities = {
     filterFields?: readonly string[];
     sorting?: "none" | "single" | "multiple";
     pagination?: "none" | "offset" | "cursor";
+    /**
+     * Whether a query of this resource answers `total`, the rows the whole query has.
+     *
+     * Counting is a query of its own on a large table, so a paging resource answers it only where it
+     * says so here. A Table that shows a count -- `totalRows` or `pageCount` in its footer or summary --
+     * needs a resource that counts or does not page; one that pages without a count is paged back and
+     * forward. A resource that does not page answers every row at once, and its rows are its count.
+     */
+    total?: boolean;
     facets?: readonly string[];
     expansion?: boolean;
 };

package/types/table-widget.js

@@ -260,6 +260,26 @@ export function validatePhiTableProviderFieldValue(field, value, row) {
 }
 export function validatePhiTableWidgetBinding(config, resource) {
     const errors = [];
+    /*
+     * A count shown needs a count given. The rows of one page are not the query's, so a Table that says
+     * how many there are, or how many pages, is bound to a resource that counts -- or one that does not
+     * page and so answers every row at once (`query.total`).
+     */
+    const resourceCounts = resource.query.total === true ||
+        (resource.query.pagination !== "offset" && resource.query.pagination !== "cursor");
+    if (!resourceCounts) {
+        const footer = config.presentation.footer;
+        const shownSources = [
+            ...(footer?.values ?? []).map((item) => item.value),
+            ...(footer?.variants ?? []).flatMap((variant) => [variant.when.value, ...(variant.values ?? []).map((item) => item.value)]),
+            ...(config.presentation.summary?.rows ?? []).flatMap((row) => row.cells.map((cell) => cell.item.value)),
+        ];
+        const counted = shownSources.find((source) => source.source === "core" && (source.fieldKey === "totalRows" || source.fieldKey === "pageCount"));
+        if (counted) {
+            errors.push(`Table shows "${counted.fieldKey}", but resource "${resource.resourceKey}" pages without a count ` +
+                "(declare query.total on a resource that answers total).");
+        }
+    }
     const fields = new Set(resource.fields.map((field) => field.key));
     const fieldsByKey = new Map(resource.fields.map((field) => [field.key, field]));
     const columns = config.presentation.columns;

package/types.d.ts

@@ -18,7 +18,7 @@ export * from "./types/spacing";
 export * from "./types/runtime-condition";
 export * from "./types/state-machine";
 export * from "./types/access";
-export type { PhiAuthoringRenderPolicy, PhiCmsBuilderWidgetEditorInteraction, PhiCmsBuilderWidgetPlugin, PhiCmsBuilderWidgetRenderArgs, PhiCmsConfigField, PhiCmsConfigFieldChoiceCreateBehavior, PhiCmsConfigFieldChoiceFilter, PhiCmsConfigFieldChoiceMode, PhiCmsConfigFieldChoicePresentation, PhiCmsConfigFieldChoiceValueType, PhiCmsConfigFieldCollectionPresentation, PhiCmsConfigFieldColorMode, PhiCmsConfigFieldValueStorage, PhiCmsConfigFieldVisibilityRule, PhiCmsLayoutPlugin, PhiCmsLayoutPluginDefinition, PhiCmsLayoutPluginRenderArgs, PhiCmsLayoutSlotDefinition, PhiCmsPluginCommercialMeta, PhiCmsPluginCommercialPlan, PhiCmsPluginLicenseState, PhiCmsPreviewWidgetPlugin, PhiCmsResolvedRequestLoaderArgs, PhiCmsRuntimeWidgetPlugin, PhiCmsServerWidgetPlugin, PhiCmsSiteBridge, PhiCmsSiteRuntime, PhiCmsWidgetAuthoringCanvas, PhiCmsWidgetAuthoringContext, PhiCmsWidgetContentBinding, PhiCmsWidgetPlugin, PhiCmsWidgetPluginDefinition, PhiCmsWidgetPluginRenderArgs, PhiCmsWidgetRuntimeControllerRequirementArgs, PhiCmsWidgetRuntimeControllerRequirementResolver, PhiCmsWidgetSignalSubcontrolCollection, PhiPreviewRenderPolicy, PhiResolvedCmsRequest, PhiRuntimeControllerDefinition, PhiRuntimeControllerFlag, PhiRuntimeControllerMountScope, PhiRuntimeControllerPlugin, PhiRuntimeControllerPreloadMap, PhiRuntimeControllerRenderArgs, PhiRuntimeControllerRequirement, PhiRuntimeControllerServerPreloadArgs, PhiRuntimeControllerSetting, PhiRuntimeModule, PhiRuntimeModuleAuthoringClientProps, PhiRuntimeModuleCalendarAdapterClientDefinition, PhiRuntimeModuleCatalog, PhiRuntimeModuleCatalogEntry, PhiRuntimeModuleClientWidgetDefinition, PhiRuntimeModuleControllerClientProps, PhiRuntimeModuleControllerDescriptor, PhiRuntimeModuleControllerMountPolicy, PhiRuntimeModuleDataProviderClientDefinition, PhiRuntimeModuleDataProviderClientProps, PhiRuntimeModuleDataProviderDescriptor, PhiRuntimeModuleDefinition, PhiRuntimeModuleFeatureContext, PhiRuntimeModuleFeatureResolver, PhiRuntimeModuleFormDefinition, PhiRuntimeModuleLayoutDefinition, PhiRuntimeModuleLoader, PhiRuntimeModuleRenderPolicies, PhiRuntimeModuleUiProvider, PhiRuntimeModuleWidgetDefinition, PhiRuntimeRenderPolicy, } from "./types/cms-plugins";
+export type { PhiAuthoringRenderPolicy, PhiCmsBuilderWidgetEditorInteraction, PhiCmsBuilderWidgetPlugin, PhiCmsBuilderWidgetRenderArgs, PhiCmsConfigField, PhiCmsConfigFieldChoiceCreateBehavior, PhiCmsConfigFieldChoiceFilter, PhiCmsConfigFieldChoiceMode, PhiCmsConfigFieldChoicePresentation, PhiCmsConfigFieldChoiceValueType, PhiCmsConfigFieldCollectionPresentation, PhiCmsConfigFieldColorMode, PhiCmsConfigFieldVisibilityRule, PhiCmsLayoutPlugin, PhiCmsLayoutPluginDefinition, PhiCmsLayoutPluginRenderArgs, PhiCmsLayoutSlotDefinition, PhiCmsPluginCommercialMeta, PhiCmsPluginCommercialPlan, PhiCmsPluginLicenseState, PhiCmsPreviewWidgetPlugin, PhiCmsResolvedRequestLoaderArgs, PhiCmsRuntimeWidgetPlugin, PhiCmsServerWidgetPlugin, PhiCmsSiteBridge, PhiCmsSiteRuntime, PhiCmsWidgetAuthoringCanvas, PhiCmsWidgetAuthoringContext, PhiCmsWidgetContentBinding, PhiCmsWidgetPlugin, PhiCmsWidgetPluginDefinition, PhiCmsWidgetPluginRenderArgs, PhiCmsWidgetRuntimeControllerRequirementArgs, PhiCmsWidgetRuntimeControllerRequirementResolver, PhiCmsWidgetSignalSubcontrolCollection, PhiPreviewRenderPolicy, PhiResolvedCmsRequest, PhiRuntimeControllerDefinition, PhiRuntimeControllerFlag, PhiRuntimeControllerMountScope, PhiRuntimeControllerPlugin, PhiRuntimeControllerPreloadMap, PhiRuntimeControllerRenderArgs, PhiRuntimeControllerRequirement, PhiRuntimeControllerServerPreloadArgs, PhiRuntimeControllerSetting, PhiRuntimeModule, PhiRuntimeModuleAuthoringClientProps, PhiRuntimeModuleCalendarAdapterClientDefinition, PhiRuntimeModuleCatalog, PhiRuntimeModuleCatalogEntry, PhiRuntimeModuleClientWidgetDefinition, PhiRuntimeModuleControllerClientProps, PhiRuntimeModuleControllerDescriptor, PhiRuntimeModuleControllerMountPolicy, PhiRuntimeModuleDataProviderClientDefinition, PhiRuntimeModuleDataProviderClientProps, PhiRuntimeModuleDataProviderDescriptor, PhiRuntimeModuleDefinition, PhiRuntimeModuleFeatureContext, PhiRuntimeModuleFeatureResolver, PhiRuntimeModuleFormDefinition, PhiRuntimeModuleLayoutDefinition, PhiRuntimeModuleLoader, PhiRuntimeModuleRenderPolicies, PhiRuntimeModuleUiProvider, PhiRuntimeModuleWidgetDefinition, PhiRuntimeRenderPolicy, } from "./types/cms-plugins";
 export type * from "./types/cms-presets";
 export type * from "./types/slot-size-policy";
 export type * from "./types/runtime-data-provider";