@phis/ui 0.4.2 → 0.4.4

package/components/widgets/client/shared/use-page-reference-options.js

@@ -0,0 +1,57 @@
+"use client";
+import { useEffect, useState } from "react";
+/*
+ * One request per Area for as long as the page lives: the create and the edit dialog offer the same
+ * Pages, and a list that changed meanwhile is a Page somebody published while this one was being written.
+ * A failed request is forgotten, so the next dialog asks again.
+ */
+const pageOptionsByArea = new Map();
+function loadPageOptions(area) {
+    const cached = pageOptionsByArea.get(area);
+    if (cached)
+        return cached;
+    const request = (async () => {
+        const response = await fetch(`/api/site/page-references?area=${encodeURIComponent(area)}`, {
+            cache: "no-store",
+            credentials: "same-origin",
+            headers: { accept: "application/json" },
+        });
+        const payload = (await response.json().catch(() => null));
+        if (!response.ok || !Array.isArray(payload?.options)) {
+            throw new Error(`Page references for "${area}" answered ${response.status}.`);
+        }
+        return payload.options;
+    })();
+    pageOptionsByArea.set(area, request);
+    request.catch(() => pageOptionsByArea.delete(area));
+    return request;
+}
+/**
+ * The Pages of one Area a link may point at, as the tree `PhiLinkTargetControl` offers, for a surface
+ * that stands outside the Builder's own catalog: a Form's `link-target` field, the Theme's Brand.
+ *
+ * Answered by `/api/site/page-references` (`gateway/page-references-route.ts`), which merges the Area's
+ * Module Pages and Core's the way the Builder's picker does. `failed` is set when the list could not be
+ * read, so the surface can say so instead of showing an empty list that looks like a Site without Pages.
+ */
+export function usePhiPageReferenceOptions(area, logScope) {
+    const [options, setOptions] = useState([]);
+    const [failed, setFailed] = useState(false);
+    useEffect(() => {
+        let current = true;
+        loadPageOptions(area).then((next) => {
+            if (current) {
+                setOptions(next);
+                setFailed(false);
+            }
+        }, (error) => {
+            console.warn(`[${logScope}] Page references could not be loaded.`, { area, error });
+            if (current)
+                setFailed(true);
+        });
+        return () => {
+            current = false;
+        };
+    }, [area, logScope]);
+    return { options, failed };
+}

package/components/widgets/config/background.d.ts

@@ -18,6 +18,19 @@ export type PhiBackgroundBaseColor = {
 export type PhiBackgroundBaseNone = {
     kind: "none";
 };
+/**
+ * The Theme's Chrome Overlay as the ground (LAYOUTING.md "Surface tone", SHELL.md "Root Background and
+ * Shell Backdrop Layers").
+ *
+ * The box paints what the Theme workspace calls the Chrome Overlay -- its colour or picture and its glass
+ * pane -- instead of a ground of its own. It carries nothing else: the Overlay is the Theme's, per mode
+ * (`root.chrome[mode]`), and the box reads the mode it stands in. A Surface `tone` is that mode, so an
+ * `inverse` Footer is the dark Overlay on a light page and the light one on a dark page. It is a stated
+ * ground: a tone does not paint its own container ground beneath it.
+ */
+export type PhiBackgroundBaseTheme = {
+    kind: "theme";
+};
 export type PhiBackgroundBaseGradient = {
     kind: "gradient";
     direction: PhiBackgroundDirection;
@@ -50,6 +63,24 @@ export type PhiBackgroundImageSourceKind = "asset" | "url";
  */
 export declare const PHI_BACKGROUND_IMAGE_SOURCE_KINDS: readonly PhiBackgroundImageSourceKind[];
 export declare const PHI_BACKGROUND_BASE_KINDS: readonly PhiCmsBackgroundWidgetConfig["base"]["kind"][];
+/**
+ * The container ground of the mode a box stands in. What a toned Surface paints where it states no
+ * ground (`PHI_SURFACE_TONE_GROUND`), and what a `theme` ground falls back to where the Theme's Overlay
+ * is not published.
+ */
+export declare const PHI_BACKGROUND_CONTAINER_GROUND = "var(--ant-color-bg-container)";
+/**
+ * What a `theme` Base paints: the Shell Chrome Overlay's custom properties, the same ones the Shell's
+ * chrome panes paint from (components/shell/phi-cms-shell.tsx).
+ *
+ * The Root Layout publishes them for the page's mode, and `styles/shell.css` publishes them again under a
+ * tone's class for the tone's mode, so the box needs no colour of its own and turns with the mode switch.
+ * Outside the Root Layout -- a Modal or Drawer portalled to `<body>` -- nothing publishes them, and the box
+ * takes the container ground of its mode instead: the tone's ground, or the Overlay's own where it has no
+ * tone. Fixed attachment for the reason the Chrome Regions have it: every box is a window onto one
+ * viewport-sized painting.
+ */
+export declare const PHI_BACKGROUND_THEME_STYLE: Readonly<CSSProperties>;
 export declare const PHI_BACKGROUND_MOTION_MODES: readonly PhiBackgroundMotionMode[];
 export type PhiBackgroundMotionDirection = "natural" | "reverse";
 /**
@@ -103,7 +134,7 @@ export type PhiBackgroundOverlay = PhiBackgroundColorOverlay | PhiBackgroundPatt
 /** What an Overlay that states no opacity is painted at, shared by every kind. */
 export declare const PHI_BACKGROUND_OVERLAY_DEFAULT_OPACITY = 0.14;
 export type PhiCmsBackgroundWidgetConfig = {
-    base: PhiBackgroundBaseColor | PhiBackgroundBaseGradient | PhiBackgroundBaseImage | PhiBackgroundBaseNone;
+    base: PhiBackgroundBaseColor | PhiBackgroundBaseGradient | PhiBackgroundBaseImage | PhiBackgroundBaseNone | PhiBackgroundBaseTheme;
     overlay?: PhiBackgroundOverlay | null;
     filter?: PhiBackgroundFilter | null;
     motion?: PhiBackgroundMotion | null;

package/components/widgets/config/background.js

@@ -30,7 +30,35 @@ export const PHI_BACKGROUND_BASE_KINDS = [
     "color",
     "gradient",
     "image",
+    "theme",
 ];
+/**
+ * The container ground of the mode a box stands in. What a toned Surface paints where it states no
+ * ground (`PHI_SURFACE_TONE_GROUND`), and what a `theme` ground falls back to where the Theme's Overlay
+ * is not published.
+ */
+export const PHI_BACKGROUND_CONTAINER_GROUND = "var(--ant-color-bg-container)";
+/**
+ * What a `theme` Base paints: the Shell Chrome Overlay's custom properties, the same ones the Shell's
+ * chrome panes paint from (components/shell/phi-cms-shell.tsx).
+ *
+ * The Root Layout publishes them for the page's mode, and `styles/shell.css` publishes them again under a
+ * tone's class for the tone's mode, so the box needs no colour of its own and turns with the mode switch.
+ * Outside the Root Layout -- a Modal or Drawer portalled to `<body>` -- nothing publishes them, and the box
+ * takes the container ground of its mode instead: the tone's ground, or the Overlay's own where it has no
+ * tone. Fixed attachment for the reason the Chrome Regions have it: every box is a window onto one
+ * viewport-sized painting.
+ */
+export const PHI_BACKGROUND_THEME_STYLE = {
+    backgroundColor: `var(--phi-shell-chrome-color, ${PHI_BACKGROUND_CONTAINER_GROUND})`,
+    backgroundImage: "var(--phi-shell-chrome-image, none)",
+    backgroundSize: "var(--phi-shell-chrome-size, auto)",
+    backgroundPosition: "var(--phi-shell-chrome-position, 0 0)",
+    backgroundRepeat: "var(--phi-shell-chrome-repeat, repeat)",
+    backgroundAttachment: "fixed",
+    backdropFilter: "var(--phi-shell-chrome-filter, none)",
+    WebkitBackdropFilter: "var(--phi-shell-chrome-filter, none)",
+};
 export const PHI_BACKGROUND_MOTION_MODES = [
     "static",
     "fixed",
@@ -145,7 +173,7 @@ function normalizePhiBackgroundBase(value) {
             ? { ...normalized, ...source }
             : { ...normalized, ...source };
     }
-    if (kind === "none")
+    if (kind === "none" || kind === "theme")
         return { kind };
     if (kind === "color") {
         const color = readString(raw.color);
@@ -253,6 +281,10 @@ export function normalizePhiBackgroundWidgetConfig(config) {
     }
     const raw = config;
     const base = normalizePhiBackgroundBase(raw.base) ?? normalizePhiBackgroundBase(raw) ?? { kind: "none" };
+    // The Theme's Overlay is the whole ground: it carries its own Overlay and pane, and takes none of the box's.
+    if (base.kind === "theme") {
+        return { base, overlay: null, filter: null, motion: null };
+    }
     return {
         base,
         overlay: readBackgroundOverlay(raw.overlay),
@@ -278,6 +310,9 @@ export function readPhiBackgroundPatternInkFromCss(css) {
 export function serializePhiBackgroundBaseCss(base) {
     if (base.kind === "none")
         return "none";
+    // Not a value a Base can be read back from: the Overlay's colour, as far as one CSS value can say it.
+    if (base.kind === "theme")
+        return String(PHI_BACKGROUND_THEME_STYLE.backgroundColor);
     if (base.kind === "color")
         return base.color;
     if (base.kind === "gradient") {
@@ -320,6 +355,9 @@ function resolvePhiBackgroundOverlayLayer(overlay) {
 export function resolvePhiBackgroundWidgetStyle(config) {
     const normalized = normalizePhiBackgroundWidgetConfig(config);
     const base = normalized.base;
+    if (base.kind === "theme") {
+        return { ...PHI_BACKGROUND_THEME_STYLE };
+    }
     const style = {};
     if (base.kind === "color")
         style.backgroundColor = base.color;
@@ -397,7 +435,8 @@ export function phiBackgroundWidgetConfigPaintsGround(config) {
  * nor honoured there.
  */
 export function phiBackgroundBaseSupportsGlassEffect(base) {
-    return base.kind !== "image" && base.kind !== "gradient";
+    // The Theme's Overlay brings its own pane, and a second one over it is nothing anybody asked for.
+    return base.kind !== "image" && base.kind !== "gradient" && base.kind !== "theme";
 }
 /**
  * Whether `blur` has anything to soften: a picture, a gradient, or a patterned Overlay.

package/components/widgets/config/choice-shared.js

@@ -1,5 +1,5 @@
 import { parsePhiControlOptionsProviderConfig, readPhiControlOptions, } from "../../controls/phi-control-options";
-import { readBoolean, readString } from "./parser-primitives";
+import { createPhiConfigReader } from "./strict-config-reader";
 import { PHI_CONTROL_PRESENTATION_FIELDS, PHI_CONTROL_STATE_FIELDS, parsePhiControlConfig, } from "./control-signal-config";
 export function buildPhiChoiceControlOptionFields(editorPlacement = "inspector") {
     return [{
@@ -28,9 +28,10 @@ export function buildPhiChoiceControlOptionFields(editorPlacement = "inspector")
 }
 export const PHI_CHOICE_CONTROL_OPTION_FIELDS = buildPhiChoiceControlOptionFields();
 export function parsePhiChoiceOptionsConfig(config) {
+    const reader = createPhiConfigReader(config);
     return {
-        optionsProvider: parsePhiControlOptionsProviderConfig(config.optionsProvider),
-        options: readPhiControlOptions(config.options),
+        optionsProvider: reader.value("optionsProvider", "an options provider", (value) => parsePhiControlOptionsProviderConfig(value) ?? undefined) ?? null,
+        options: reader.value("options", "a list of options", (value) => (Array.isArray(value) ? readPhiControlOptions(value) : undefined)) ?? readPhiControlOptions(undefined),
     };
 }
 export const PHI_CHOICE_CONTROL_CONFIG_FIELDS = [
@@ -46,27 +47,25 @@ export const PHI_CHOICE_CONTROL_VALUE_MODE_FIELD = {
         { value: "stack-slot-index", label: "Stack Slot Index" },
     ],
 };
-function readPhiChoiceValueMode(value) {
-    return readString(value) === "stack-slot-index" ? "stack-slot-index" : "raw";
-}
 export function parsePhiChoiceControlConfig(config) {
     const controlState = parsePhiControlConfig(config, {
         key: "choice",
     });
+    const reader = createPhiConfigReader(config);
     return {
         ...controlState,
-        label: readString(config.label),
-        description: readString(config.description),
-        value: readString(config.value),
-        placeholder: readString(config.placeholder),
-        presentation: readString(config.presentation) === "autocomplete" ? "autocomplete" : "select",
-        allowCustom: readBoolean(config.allowCustom),
+        label: reader.string("label"),
+        description: reader.string("description"),
+        value: reader.string("value"),
+        placeholder: reader.string("placeholder"),
+        presentation: reader.oneOf("presentation", ["select", "autocomplete"]) ?? "select",
+        allowCustom: reader.boolean("allowCustom"),
         ...parsePhiChoiceOptionsConfig(config),
     };
 }
 export function parsePhiStackChoiceControlConfig(config) {
     return {
         ...parsePhiChoiceControlConfig(config),
-        valueMode: readPhiChoiceValueMode(config.valueMode),
+        valueMode: createPhiConfigReader(config).oneOf("valueMode", ["raw", "stack-slot-index"]) ?? "raw",
     };
 }

package/components/widgets/config/command-buttons.d.ts

@@ -2,7 +2,11 @@ import type { PhiCommandButtonConfig } from "../../../types/core-widget-placemen
 import type { PhiCmsConfigField } from "../../../types";
 import type { PhiCmsConfigFieldVisibilityRule } from "../../../types/cms-plugins";
 import { type PhiAccessViewer, type PhiRoleProviderId } from "../../../types/access";
-export declare function readPhiCommandButtons(value: unknown): PhiCommandButtonConfig[];
+/**
+ * A Widget's buttons. Strict (`strict-config-reader.ts`): a button without a key or without an emit is
+ * an error naming it, not a button left out.
+ */
+export declare function readPhiCommandButtons(value: unknown, path?: string): PhiCommandButtonConfig[];
 export declare function filterPhiCommandButtonsForViewer(buttons: readonly PhiCommandButtonConfig[], viewer: PhiAccessViewer, ownerProviderId?: PhiRoleProviderId | null): PhiCommandButtonConfig[];
 /**
  * A new button: the first free `buttonN` key, labelled after it, sending its key as the command. The

package/components/widgets/config/command-buttons.js

@@ -4,7 +4,7 @@ import { PHI_COMMON_CONTROL_DEFAULT_LABELS, readPhiCommonControlActionKey, } fro
 import { PHI_BUTTON_VARIANT_FIELD_OPTIONS, readPhiButtonVariant } from "./button-variant";
 import { createPhiCommonActionField, readPhiControlLabel } from "./common-action-field";
 import { PHI_CONTROL_BADGE_FIELDS, parsePhiControlBadgeConfig } from "./control-signal-config";
-import { readBoolean, readNumber, readString } from "./parser-primitives";
+import { createPhiConfigReader } from "./strict-config-reader";
 /*
  * The buttons of a Widget that holds several: the Command Toolbar's row, and the Float Button's corner.
  *
@@ -12,102 +12,59 @@ import { readBoolean, readNumber, readString } from "./parser-primitives";
  * emit, and the Signals panel wires both. The two Widgets differ in how the buttons stand, never in what
  * a button is, so the parser, the Inspector fields, the viewer filter and the scaffold's count are one.
  */
+/** What a button sends: a text, a number, true/false, a list of texts or of numbers, or an object. */
 function readButtonEmitValue(value) {
-    const stringValue = readString(value);
-    if (stringValue !== undefined) {
-        return stringValue;
-    }
-    const numberValue = readNumber(value);
-    if (numberValue !== undefined) {
-        return numberValue;
-    }
-    const booleanValue = readBoolean(value);
-    if (booleanValue !== undefined) {
-        return booleanValue;
-    }
-    if (value == null) {
-        return undefined;
-    }
+    if (typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : undefined;
     if (Array.isArray(value)) {
-        const stringItems = value.filter((item) => typeof item === "string");
-        if (stringItems.length === value.length) {
-            return stringItems;
-        }
-        const numberItems = value.filter((item) => typeof item === "number" && Number.isFinite(item));
-        if (numberItems.length === value.length) {
-            return numberItems;
-        }
+        if (value.every((item) => typeof item === "string"))
+            return value;
+        if (value.every((item) => typeof item === "number" && Number.isFinite(item)))
+            return value;
         return undefined;
     }
-    if (typeof value === "object") {
-        return value;
-    }
-    return undefined;
+    return isPhiRecord(value) ? value : undefined;
 }
-function readCommandButtonEmitConfig(value) {
-    if (!isPhiRecord(value)) {
-        return null;
-    }
-    const record = value;
-    const capabilityId = readString(record.capabilityId);
-    if (!capabilityId) {
-        return null;
-    }
+function readCommandButtonEmitConfig(reader) {
     return {
-        capabilityId,
-        value: readButtonEmitValue(record.value),
+        capabilityId: reader.string("capabilityId") ?? reader.fail("capabilityId", "a capability id"),
+        value: reader.value("value", "a text, number, true/false, list or object", readButtonEmitValue),
     };
 }
-function readCommandButtonEmits(value) {
-    if (!Array.isArray(value)) {
-        return [];
-    }
-    return value
-        .map(readCommandButtonEmitConfig)
-        .filter((item) => item != null);
-}
-function readCommandButtonConfig(value) {
-    if (!isPhiRecord(value)) {
-        return null;
-    }
-    const record = value;
-    const key = readString(record.key);
-    const emits = readCommandButtonEmits(record.emits);
-    if (!key || emits.length === 0) {
-        return null;
-    }
-    const hasAccessPolicy = Object.prototype.hasOwnProperty.call(record, "accessPolicy");
-    const accessPolicy = hasAccessPolicy
-        ? readPhiViewerAccessPolicy(record.accessPolicy)
+function readCommandButtonConfig(reader) {
+    const key = reader.string("key") ?? reader.fail("key", "a text");
+    const emits = reader.list("emits", readCommandButtonEmitConfig) ?? [];
+    if (emits.length === 0)
+        reader.fail("emits", "at least one emit");
+    const accessPolicy = Object.prototype.hasOwnProperty.call(reader.record, "accessPolicy")
+        ? readPhiViewerAccessPolicy(reader.record.accessPolicy) ?? reader.fail("accessPolicy", "an access policy")
         : null;
-    if (hasAccessPolicy && !accessPolicy) {
-        return null;
-    }
     return {
         key,
         emits,
         ...(accessPolicy ? { accessPolicy } : {}),
-        ...parsePhiControlBadgeConfig(record),
-        action: readPhiCommonControlActionKey(readString(record.action)) ?? undefined,
-        label: readPhiControlLabel(record.label),
-        tooltip: readString(record.tooltip),
-        icon: readString(record.icon),
-        display: record.display === "icon" || record.display === "label" || record.display === "icon-label"
-            ? record.display
-            : undefined,
-        danger: readBoolean(record.danger),
-        disabled: readBoolean(record.disabled),
-        readOnly: readBoolean(record.readOnly),
-        variant: readPhiButtonVariant(record.variant),
+        ...parsePhiControlBadgeConfig(reader.record, reader.path),
+        action: reader.value("action", "a common action", (value) => typeof value === "string" ? readPhiCommonControlActionKey(value) ?? undefined : undefined),
+        label: readPhiControlLabel(reader.record.label),
+        tooltip: reader.string("tooltip"),
+        icon: reader.string("icon"),
+        display: reader.oneOf("display", ["icon", "label", "icon-label"]),
+        danger: reader.boolean("danger"),
+        disabled: reader.boolean("disabled"),
+        readOnly: reader.boolean("readOnly"),
+        variant: reader.value("variant", "a button variant", readPhiButtonVariant),
     };
 }
-export function readPhiCommandButtons(value) {
-    if (!Array.isArray(value)) {
+/**
+ * A Widget's buttons. Strict (`strict-config-reader.ts`): a button without a key or without an emit is
+ * an error naming it, not a button left out.
+ */
+export function readPhiCommandButtons(value, path = "buttons") {
+    if (value === undefined || value === null)
         return [];
-    }
-    return value
-        .map(readCommandButtonConfig)
-        .filter((item) => item != null);
+    return createPhiConfigReader({ [path]: value }).list(path, readCommandButtonConfig) ?? [];
 }
 export function filterPhiCommandButtonsForViewer(buttons, viewer, ownerProviderId) {
     return buttons.filter((button) => canPhiViewerAccessOwnedPolicy(viewer, button.accessPolicy, ownerProviderId));

package/components/widgets/config/control-signal-config.d.ts

@@ -143,4 +143,6 @@ export declare function parsePhiControlSignalConfig(config: Record<string, unkno
 export declare function parsePhiControlStateConfig(config: Record<string, unknown>, defaults: PhiControlSignalConfigDefaults): Required<Pick<PhiControlStateConfig, "key">> & Pick<PhiControlStateConfig, "signalRoutes" | "readOnly" | "disabled">;
 export declare function parsePhiControlPresentationConfig<TSize extends PhiControlSize = PhiControlSize>(config: Record<string, unknown>, allowedSizes?: readonly TSize[]): PhiControlPresentationConfig<TSize>;
 export declare function parsePhiControlConfig<TSize extends PhiControlSize = PhiControlSize>(config: Record<string, unknown>, defaults: PhiControlSignalConfigDefaults, allowedSizes?: readonly TSize[]): Required<Pick<PhiControlConfig<TSize>, "key">> & Pick<PhiControlConfig<TSize>, "signalRoutes" | "readOnly" | "disabled" | "controlSize">;
-export declare function parsePhiControlBadgeConfig(config: Record<string, unknown>): PhiControlBadgeConfig;
+export declare function parsePhiControlBadgeConfig(config: Record<string, unknown>, 
+/** Where the config stands, when it is an entry of a list -- a button of a toolbar. */
+path?: string): PhiControlBadgeConfig;

package/components/widgets/config/control-signal-config.js

@@ -1,6 +1,6 @@
 import { readPhiSignalRouteSet, } from "../../../types/signals";
-import { PHI_CONTROL_SIZES, readPhiControlSize, } from "../../../types/control";
-import { readBoolean, readNumber, readString } from "./parser-primitives";
+import { PHI_CONTROL_SIZES, } from "../../../types/control";
+import { createPhiConfigReader } from "./strict-config-reader";
 export const PHI_CONTROL_READ_ONLY_FIELD = {
     key: "readOnly",
     type: "boolean",
@@ -83,23 +83,22 @@ export const PHI_CONTROL_BADGE_FIELDS = [
 export function parsePhiControlSignalConfig(config, defaults) {
     return {
         signalRoutes: readPhiSignalRouteSet(config.signalRoutes),
-        key: readString(config.key) ?? defaults.key,
+        key: createPhiConfigReader(config).string("key") ?? defaults.key,
     };
 }
 export function parsePhiControlStateConfig(config, defaults) {
+    const reader = createPhiConfigReader(config);
     return {
         ...parsePhiControlSignalConfig(config, defaults),
-        readOnly: readBoolean(config.readOnly),
-        disabled: readBoolean(config.disabled),
+        readOnly: reader.boolean("readOnly"),
+        disabled: reader.boolean("disabled"),
     };
 }
 export function parsePhiControlPresentationConfig(config, allowedSizes) {
-    const controlSize = readPhiControlSize(config.controlSize);
-    const resolvedAllowedSizes = allowedSizes ?? PHI_CONTROL_SIZES;
+    // A size this Control does not offer is an error, not the default in its place.
+    const resolvedAllowedSizes = (allowedSizes ?? PHI_CONTROL_SIZES);
     return {
-        controlSize: controlSize != null && resolvedAllowedSizes.includes(controlSize)
-            ? controlSize
-            : undefined,
+        controlSize: createPhiConfigReader(config).oneOf("controlSize", resolvedAllowedSizes),
     };
 }
 export function parsePhiControlConfig(config, defaults, allowedSizes) {
@@ -113,13 +112,16 @@ export function parsePhiControlConfig(config, defaults, allowedSizes) {
         controlSize: controlSize ?? ((allowedSizes ?? PHI_CONTROL_SIZES).includes("medium") ? "medium" : undefined),
     };
 }
-export function parsePhiControlBadgeConfig(config) {
+export function parsePhiControlBadgeConfig(config, 
+/** Where the config stands, when it is an entry of a list -- a button of a toolbar. */
+path = "") {
+    const reader = createPhiConfigReader(config, path);
     return {
-        badgeEnabled: readBoolean(config.badgeEnabled),
-        badgeText: readString(config.badgeText),
-        badgeCount: readNumber(config.badgeCount),
-        badgeShowZero: readBoolean(config.badgeShowZero),
-        badgeOverflowCount: readNumber(config.badgeOverflowCount),
-        badgeColor: readString(config.badgeColor),
+        badgeEnabled: reader.boolean("badgeEnabled"),
+        badgeText: reader.string("badgeText"),
+        badgeCount: reader.number("badgeCount"),
+        badgeShowZero: reader.boolean("badgeShowZero"),
+        badgeOverflowCount: reader.number("badgeOverflowCount"),
+        badgeColor: reader.string("badgeColor"),
     };
 }

package/components/widgets/config/image-source-parser.d.ts

@@ -1,2 +1,3 @@
 import type { PhiMediaImageSourceConfig } from "../../../types/media";
+/** Where an image comes from: an Asset of the Media library, or a URL. Strict: an unknown kind is an error. */
 export declare function readPhiMediaImageSourceConfig(value: Record<string, unknown>): PhiMediaImageSourceConfig;

package/components/widgets/config/image-source-parser.js

@@ -1,19 +1,18 @@
 import { normalizePhiImageAssetVariantKey } from "../../../constants/media";
-import { readNumber, readString } from "./parser-primitives";
-function readPhiImageSourceKind(value) {
-    return readString(value) === "asset" ? "asset" : "url";
-}
+import { createPhiConfigReader } from "./strict-config-reader";
+/** Where an image comes from: an Asset of the Media library, or a URL. Strict: an unknown kind is an error. */
 export function readPhiMediaImageSourceConfig(value) {
-    if (readPhiImageSourceKind(value.sourceKind) === "asset") {
+    const reader = createPhiConfigReader(value);
+    if ((reader.oneOf("sourceKind", ["url", "asset"]) ?? "url") === "asset") {
         return {
             sourceKind: "asset",
-            assetId: readNumber(value.assetId),
+            assetId: reader.number("assetId"),
             variantKey: normalizePhiImageAssetVariantKey(value.variantKey),
-            variantVersion: readNumber(value.variantVersion),
+            variantVersion: reader.number("variantVersion"),
         };
     }
     return {
         sourceKind: "url",
-        sourceUrl: readString(value.sourceUrl),
+        sourceUrl: reader.string("sourceUrl"),
     };
 }

package/components/widgets/config/mask.d.ts

@@ -24,7 +24,12 @@ export declare const PHI_MASK_PRESET_OPTIONS: ReadonlyArray<{
     label: string;
 }>;
 export declare function resolvePhiMaskStyle(mask: PhiMaskConfig | null | undefined): CSSProperties | undefined;
-export declare function normalizePhiMaskConfig(value: unknown): PhiMaskConfig | undefined;
+/**
+ * A stored mask, read strictly (`strict-config-reader.ts`) before it is normalized: a field that is
+ * there and of the wrong kind is an error naming it. The normalization below stays lenient for the
+ * editor, which normalizes drafts while an author is still choosing.
+ */
+export declare function readPhiMaskConfig(value: unknown, path?: string): PhiMaskConfig | undefined;
 export declare function mergePhiMaskConfigDefaults(mask: PhiMaskConfig | null | undefined): PhiMaskConfig;
 /** A picker's change on top of the current mask: the defaults filled, the patch applied, the mask enabled. */
 export declare function mergePhiMaskConfigPatch(mask: PhiMaskConfig | null | undefined, patch: PhiMaskConfig): PhiMaskConfig;

package/components/widgets/config/mask.js

@@ -1,5 +1,6 @@
 import { isPhiRecord } from "../../../helpers/is-record";
 import { readBoolean, readCssSize, readNumber, readString } from "./parser-primitives";
+import { createPhiConfigReader } from "./strict-config-reader";
 /** The preset shapes and their names, in the order a picker lists them. */
 const PHI_MASK_PRESET_ENTRIES = [
     ["circle", "Circle"],
@@ -129,7 +130,29 @@ function readMaskRotation(value) {
     }
     return Math.min(180, Math.max(-180, rotation));
 }
-export function normalizePhiMaskConfig(value) {
+/**
+ * A stored mask, read strictly (`strict-config-reader.ts`) before it is normalized: a field that is
+ * there and of the wrong kind is an error naming it. The normalization below stays lenient for the
+ * editor, which normalizes drafts while an author is still choosing.
+ */
+export function readPhiMaskConfig(value, path = "mask") {
+    createPhiConfigReader({ [path]: value }).object(path, (reader) => {
+        reader.boolean("enabled");
+        reader.oneOf("source", ["asset", "preset"]);
+        reader.oneOf("preset", [...PHI_MASK_PRESETS]);
+        reader.number("assetId");
+        reader.string("assetUrl");
+        reader.number("scale");
+        reader.number("offsetX");
+        reader.number("offsetY");
+        reader.number("rotationDeg");
+        reader.value("position", "a CSS position", (position) => typeof position === "string" || (typeof position === "number" && Number.isFinite(position)) ? position : undefined);
+        reader.oneOf("repeat", ["repeat", "no-repeat"]);
+        reader.oneOf("mode", ["luminance", "alpha"]);
+    });
+    return normalizePhiMaskConfig(value);
+}
+function normalizePhiMaskConfig(value) {
     if (!isPhiRecord(value)) {
         return undefined;
     }