@phis/ui 0.4.1 → 0.4.3

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;
     }

package/components/widgets/config/parser-primitives.js

@@ -1,5 +1,10 @@
 import { isPhiRecord } from "../../../helpers/is-record";
 import { mergePhiCmsRenderableBlockConfigDefaults } from "../../../helpers/cms-config-serialization";
+import { readPhiViewerAccessPolicy } from "../../../types/access";
+import { createPhiConfigReader } from "./strict-config-reader";
+import { PHI_BACKGROUND_FILTERS, readPhiShadow } from "../../../types/layout-style";
+import { PHI_CMS_BORDER_SOURCES } from "../../../types/cms-border-source";
+import { PHI_SURFACE_TONES } from "../../../types/surface";
 export function readString(value) {
     return typeof value === "string" && value.trim() ? value : undefined;
 }
@@ -22,7 +27,74 @@ export function readNumberList(value) {
 export function readCssSize(value) {
     return readNumber(value) ?? readString(value);
 }
+/*
+ * The fields every block carries, checked strictly before they are normalized
+ * (`strict-config-reader.ts`): a render mode, visibility or size of the wrong kind is an error naming the
+ * field, not the default put in its place. The check is one level deep -- a surface, a size or the
+ * effects must be what they claim to be; what is inside them is still normalized as before.
+ *
+ * The normalization itself stays lenient, because the Builder runs it on drafts while an author edits.
+ * This reader is what a stored config is read with: every Widget's `parseConfig` and the Layouts'.
+ */
+/*
+ * A Surface, one level into each of its parts: a background's base, overlay, filter and motion are what
+ * they claim to be, a border is an object of the border's fields, a shadow is one the Theme knows. What is
+ * inside a gradient's stops or an overlay's pattern is still normalized as before.
+ */
+function assertPhiSurfaceConfig(surface) {
+    const cssSize = (value) => (typeof value === "number" && Number.isFinite(value)) || typeof value === "string" ? value : undefined;
+    surface.object("background", (background) => {
+        background.value("base", "a background base: a CSS value or an object with a kind", (value) => typeof value === "string" ||
+            (isPhiRecord(value) && ["color", "gradient", "image", "none"].includes(String(value.kind)))
+            ? value
+            : undefined);
+        background.value("overlay", "a background overlay", (value) => (isPhiRecord(value) ? value : undefined));
+        background.oneOf("filter", PHI_BACKGROUND_FILTERS);
+        background.value("motion", "a background motion", (value) => (isPhiRecord(value) ? value : undefined));
+    });
+    surface.oneOf("borderSource", PHI_CMS_BORDER_SOURCES);
+    surface.object("border", (border) => {
+        border.number("borderWidth");
+        border.string("borderStyle");
+        border.string("borderColor");
+        for (const corner of ["borderTopLeftRadius", "borderTopRightRadius", "borderBottomLeftRadius", "borderBottomRightRadius"]) {
+            border.value(corner, "a CSS size", cssSize);
+        }
+    });
+    surface.value("shadow", "a shadow", readPhiShadow);
+    surface.oneOf("tone", PHI_SURFACE_TONES);
+}
+function assertPhiRenderableBlockBaseConfig(config) {
+    const reader = createPhiConfigReader(config);
+    const sizeLike = (value) => isPhiRecord(value) || typeof value === "string" || (typeof value === "number" && Number.isFinite(value))
+        ? value
+        : undefined;
+    reader.oneOf("renderMode", ["live", "preview", "editor"]);
+    reader.oneOf("visibility", ["visible", "hidden", "collapsed"]);
+    reader.value("accessPolicy", "an access policy", (value) => readPhiViewerAccessPolicy(value) ?? undefined);
+    reader.value("viewportFlags", "a whole number from 0 to 6", (value) => typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 6 ? value : undefined);
+    reader.boolean("enabled");
+    reader.boolean("debugMode");
+    reader.value("anchor", "an anchor", (value) => (isPhiRecord(value) || typeof value === "string" ? value : undefined));
+    reader.integer("zIndex");
+    reader.number("opacity");
+    reader.object("surface", assertPhiSurfaceConfig);
+    reader.string("className");
+    reader.value("size", "a size", sizeLike);
+    reader.value("minSize", "a size", sizeLike);
+    reader.value("maxSize", "a size", sizeLike);
+    reader.value("collapsedSizeHint", "a size", sizeLike);
+    reader.object("effects", (effects) => {
+        effects.list("viewportEffects", (effect) => {
+            // `z` turns flat in the page plane; nothing moves or fades along it.
+            if (effect.record.axis === "z" && effect.record.property !== "rotate") {
+                effect.fail("axis", '"x" or "y" ("z" only turns a "rotate")');
+            }
+        });
+    });
+}
 export function readRenderableBlockConfig(config) {
+    assertPhiRenderableBlockBaseConfig(config);
     return mergePhiCmsRenderableBlockConfigDefaults(config);
 }
 export function readNavItems(value) {

package/components/widgets/config/stack-tabs.d.ts

@@ -1,4 +1,4 @@
-import { type PhiCmsWidgetConfigBase } from "./parser-primitives";
+import type { PhiCmsWidgetConfigBase } from "./parser-primitives";
 import { type PhiStackChoiceControlConfig } from "./choice-shared";
 export type PhiCmsTabBarWidgetConfig = PhiCmsWidgetConfigBase & PhiStackChoiceControlConfig & {
     key?: string;

package/components/widgets/config/stack-tabs.js

@@ -1,12 +1,11 @@
-import { readString } from "./parser-primitives";
+import { createPhiConfigReader } from "./strict-config-reader";
 import { PHI_CHOICE_CONTROL_OPTION_FIELDS, PHI_CHOICE_CONTROL_CONFIG_FIELDS, PHI_CHOICE_CONTROL_VALUE_MODE_FIELD, parsePhiStackChoiceControlConfig, } from "./choice-shared";
 import { createPhiCmsWidgetDefinition } from "./helpers";
 import { PHI_SELECT_CONTROL_SIGNALS } from "../signals/control-signal-capabilities";
 function parsePhiCmsTabBarWidgetConfig(config) {
-    const placement = readString(config.placement);
     return {
         ...parsePhiStackChoiceControlConfig(config),
-        placement: placement === "bottom" || placement === "left" || placement === "right" ? placement : "top",
+        placement: createPhiConfigReader(config).oneOf("placement", ["top", "bottom", "left", "right"]) ?? "top",
     };
 }
 export const PHI_TAB_BAR_WIDGET_DEFINITION = createPhiCmsWidgetDefinition({

package/components/widgets/config/strict-config-reader.d.ts

@@ -0,0 +1,40 @@
+export declare class PhiConfigError extends Error {
+    readonly path: string;
+    readonly expected: string;
+    readonly received: unknown;
+    constructor(path: string, expected: string, received: unknown);
+}
+export declare function isPhiConfigError(error: unknown): error is PhiConfigError;
+/** The render issue code for an error: a config nobody can read is said as such, not as a crash. */
+export declare function resolvePhiRenderFailureCode(error: unknown): "invalid-config" | "render-failed";
+export type PhiConfigReader = {
+    /** Where this reader stands, for nested readers and errors. */
+    readonly path: string;
+    readonly record: Readonly<Record<string, unknown>>;
+    has(key: string): boolean;
+    string(key: string): string | undefined;
+    number(key: string): number | undefined;
+    integer(key: string): number | undefined;
+    boolean(key: string): boolean | undefined;
+    /** One of a closed list of values. */
+    oneOf<const T extends string | number>(key: string, values: readonly T[]): T | undefined;
+    /** A value a reader of the caller's checks; `read` answers `undefined` for a value it does not accept. */
+    value<T>(key: string, expected: string, read: (value: unknown) => T | undefined): T | undefined;
+    /** A nested object, read by a reader of its own. */
+    object<T>(key: string, read: (reader: PhiConfigReader) => T): T | undefined;
+    /** A list of objects, each read by a reader of its own. */
+    list<T>(key: string, read: (reader: PhiConfigReader, index: number) => T): T[] | undefined;
+    /** A list of texts. */
+    stringList(key: string): string[] | undefined;
+    /** An error at a field of this reader, for a rule the field types cannot state. */
+    fail(key: string, expected: string, received?: unknown): never;
+};
+export declare function createPhiConfigReader(record: Readonly<Record<string, unknown>>, path?: string): PhiConfigReader;
+/**
+ * The same strict reader over a server's answer. `source` names who answered (`"The media listing"`),
+ * so the error says whose shape it was. A value is read as in a config: absent is allowed and reads as
+ * absent, present and wrong throws. What the answer must carry, the caller asks for with `required`.
+ */
+export declare function createPhiResponseReader(value: unknown, source: string, path?: string): PhiConfigReader;
+/** A field the record must carry: what `read` answers, or the reader's error for the field. */
+export declare function requirePhiField<T>(reader: PhiConfigReader, key: string, expected: string, read: (key: string) => T | undefined): T;

package/components/widgets/config/strict-config-reader.js

@@ -0,0 +1,174 @@
+import { isPhiRecord } from "../../../helpers/is-record";
+/*
+ * Reading a Widget's or Layout's stored config strictly.
+ *
+ * A value that is absent -- `undefined`, `null`, or an empty text -- is allowed and reads as absent; the
+ * parser decides what absent means. A value that is present and wrong is an error, never a silent
+ * `undefined` or a default put in its place: a config that says something the Widget cannot read is a
+ * config somebody has to correct, and they can only do that if it is said.
+ *
+ * The error names where it is (`columns[2].sizing.width`), what was expected and what was found. It is
+ * thrown from `parseConfig`; the renderer catches it per block (`phi-cms-layout-renderer.tsx`), so a live
+ * page leaves the one Widget out and logs it, while the Builder and the preview show it in the Widget's
+ * place, where the field can be corrected.
+ */
+export class PhiConfigError extends Error {
+    path;
+    expected;
+    received;
+    constructor(path, expected, received) {
+        super(`Config field "${path}" expects ${expected}, found ${describePhiConfigValue(received)}.`);
+        this.name = "PhiConfigError";
+        this.path = path;
+        this.expected = expected;
+        this.received = received;
+    }
+}
+export function isPhiConfigError(error) {
+    return error instanceof PhiConfigError;
+}
+/** The render issue code for an error: a config nobody can read is said as such, not as a crash. */
+export function resolvePhiRenderFailureCode(error) {
+    return error instanceof PhiConfigError || (error instanceof Error && error.name === "PhiConfigError")
+        ? "invalid-config"
+        : "render-failed";
+}
+function describePhiConfigValue(value) {
+    if (value === undefined)
+        return "nothing";
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "a list";
+    if (isPhiRecord(value))
+        return "an object";
+    if (typeof value === "string")
+        return `the text ${JSON.stringify(value.length > 40 ? `${value.slice(0, 40)}...` : value)}`;
+    return `${typeof value} ${String(value)}`;
+}
+function isAbsent(value) {
+    return value === undefined || value === null || (typeof value === "string" && value.trim() === "");
+}
+/**
+ * A field a reader found wrong, in a record that did not come from a stored config: a server's answer.
+ *
+ * The same reading, said as what it is. A response the client cannot read is the server's or the
+ * contract's fault, not something an author can correct, so it is not a `PhiConfigError` and no
+ * Builder offers to fix it.
+ */
+class PhiResponseShapeError extends Error {
+    source;
+    path;
+    expected;
+    received;
+    constructor(source, path, expected, received) {
+        super(`${source} answered "${path}" with ${describePhiConfigValue(received)}, expected ${expected}.`);
+        this.name = "PhiResponseShapeError";
+        this.source = source;
+        this.path = path;
+        this.expected = expected;
+        this.received = received;
+    }
+}
+export function createPhiConfigReader(record, path = "") {
+    return createPhiStrictReader(record, path, (at, expected, received) => new PhiConfigError(at, expected, received));
+}
+/**
+ * The same strict reader over a server's answer. `source` names who answered (`"The media listing"`),
+ * so the error says whose shape it was. A value is read as in a config: absent is allowed and reads as
+ * absent, present and wrong throws. What the answer must carry, the caller asks for with `required`.
+ */
+export function createPhiResponseReader(value, source, path = "") {
+    if (!isPhiRecord(value)) {
+        throw new PhiResponseShapeError(source, path || "(answer)", "an object", value);
+    }
+    return createPhiStrictReader(value, path, (at, expected, received) => new PhiResponseShapeError(source, at, expected, received));
+}
+/** A field the record must carry: what `read` answers, or the reader's error for the field. */
+export function requirePhiField(reader, key, expected, read) {
+    const value = read(key);
+    return value === undefined ? reader.fail(key, expected) : value;
+}
+function createPhiStrictReader(record, path, makeError) {
+    const at = (key) => (path ? `${path}.${key}` : key);
+    const fail = (key, expected, received = record[key]) => {
+        throw makeError(at(key), expected, received);
+    };
+    const reader = {
+        path,
+        record,
+        has: (key) => !isAbsent(record[key]),
+        string(key) {
+            const value = record[key];
+            if (isAbsent(value))
+                return undefined;
+            return typeof value === "string" ? value : fail(key, "a text");
+        },
+        number(key) {
+            const value = record[key];
+            if (isAbsent(value))
+                return undefined;
+            return typeof value === "number" && Number.isFinite(value) ? value : fail(key, "a number");
+        },
+        integer(key) {
+            const value = record[key];
+            if (isAbsent(value))
+                return undefined;
+            return typeof value === "number" && Number.isInteger(value) ? value : fail(key, "a whole number");
+        },
+        boolean(key) {
+            const value = record[key];
+            if (isAbsent(value))
+                return undefined;
+            return typeof value === "boolean" ? value : fail(key, "true or false");
+        },
+        oneOf(key, values) {
+            const value = record[key];
+            if (isAbsent(value))
+                return undefined;
+            return values.includes(value)
+                ? value
+                : fail(key, `one of ${values.map((entry) => JSON.stringify(entry)).join(", ")}`);
+        },
+        value(key, expected, read) {
+            const value = record[key];
+            if (isAbsent(value))
+                return undefined;
+            const result = read(value);
+            return result === undefined ? fail(key, expected) : result;
+        },
+        object(key, read) {
+            const value = record[key];
+            if (isAbsent(value))
+                return undefined;
+            return isPhiRecord(value) ? read(createPhiStrictReader(value, at(key), makeError)) : fail(key, "an object");
+        },
+        list(key, read) {
+            const value = record[key];
+            if (isAbsent(value))
+                return undefined;
+            if (!Array.isArray(value))
+                return fail(key, "a list");
+            return value.map((entry, index) => {
+                const entryPath = `${at(key)}[${index}]`;
+                if (!isPhiRecord(entry))
+                    throw makeError(entryPath, "an object", entry);
+                return read(createPhiStrictReader(entry, entryPath, makeError), index);
+            });
+        },
+        stringList(key) {
+            const value = record[key];
+            if (isAbsent(value))
+                return undefined;
+            if (!Array.isArray(value))
+                return fail(key, "a list of texts");
+            return value.map((entry, index) => {
+                if (typeof entry !== "string")
+                    throw makeError(`${at(key)}[${index}]`, "a text", entry);
+                return entry;
+            });
+        },
+        fail,
+    };
+    return reader;
+}

package/components/widgets/label-sets/effects.js

@@ -81,6 +81,7 @@ const PHI_EFFECTS_WIDGET_LABEL_SET = definePhiLabelSet({
         origin_bottom_right: PHI_EFFECTS_WIDGET_DEFAULT_LABELS.origins.bottomRight,
         viewport_x: PHI_EFFECTS_WIDGET_DEFAULT_LABELS.viewport.x,
         viewport_y: PHI_EFFECTS_WIDGET_DEFAULT_LABELS.viewport.y,
+        viewport_z: PHI_EFFECTS_WIDGET_DEFAULT_LABELS.viewport.z,
         viewport_translate: PHI_EFFECTS_WIDGET_DEFAULT_LABELS.viewport.translate,
         viewport_opacity: PHI_EFFECTS_WIDGET_DEFAULT_LABELS.viewport.opacity,
         viewport_rotate: PHI_EFFECTS_WIDGET_DEFAULT_LABELS.viewport.rotate,
@@ -191,6 +192,7 @@ export async function getPhiEffectsWidgetLabels(options) {
         viewport: {
             x: labels.viewport_x,
             y: labels.viewport_y,
+            z: labels.viewport_z,
             translate: labels.viewport_translate,
             opacity: labels.viewport_opacity,
             rotate: labels.viewport_rotate,