@phis/ui 0.4.2 → 0.4.4

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/background.js

@@ -18,6 +18,7 @@ const PHI_BACKGROUND_WIDGET_LABEL_SET = definePhiLabelSet({
         base_color: PHI_BACKGROUND_WIDGET_DEFAULT_LABELS.base.color,
         base_gradient: PHI_BACKGROUND_WIDGET_DEFAULT_LABELS.base.gradient,
         base_image: PHI_BACKGROUND_WIDGET_DEFAULT_LABELS.base.image,
+        base_theme: PHI_BACKGROUND_WIDGET_DEFAULT_LABELS.base.theme,
         image_url: PHI_BACKGROUND_WIDGET_DEFAULT_LABELS.image.url,
         image_alt: PHI_BACKGROUND_WIDGET_DEFAULT_LABELS.image.alt,
         image_position: PHI_BACKGROUND_WIDGET_DEFAULT_LABELS.image.position,
@@ -104,6 +105,7 @@ export async function getPhiBackgroundWidgetLabels(options) {
             color: labels.base_color,
             gradient: labels.base_gradient,
             image: labels.base_image,
+            theme: labels.base_theme,
         },
         image: {
             url: labels.image_url,

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,

package/components/widgets/label-types/background.d.ts

@@ -14,6 +14,7 @@ export type PhiBackgroundWidgetLabels = {
         color: string;
         gradient: string;
         image: string;
+        theme: string;
     };
     image: {
         url: string;

package/components/widgets/label-types/background.js

@@ -14,6 +14,7 @@ export const PHI_BACKGROUND_WIDGET_DEFAULT_LABELS = {
         color: "Color",
         gradient: "Gradient",
         image: "Image",
+        theme: "Theme",
     },
     image: {
         url: "Image URL",

package/components/widgets/label-types/effects.d.ts

@@ -92,6 +92,7 @@ export type PhiEffectsWidgetLabels = {
     viewport: {
         x: string;
         y: string;
+        z: string;
         translate: string;
         opacity: string;
         rotate: string;

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

@@ -91,6 +91,7 @@ export const PHI_EFFECTS_WIDGET_DEFAULT_LABELS = {
     viewport: {
         x: "X",
         y: "Y",
+        z: "Z",
         translate: "Translate",
         opacity: "Opacity",
         rotate: "Rotate",

package/components/widgets/navigation-descriptor-resolver.server.js

@@ -3,6 +3,7 @@ import { isPhiCmsNavigationOverlayTarget, readPhiCmsNavigationTargetPath, } from
 import { createPhiPresetCmsInstanceId } from "../../types/cms-instance-id";
 import { createGlobalTranslator, createSiteTranslator, PHI_TR_CTX_WEB_UI_LABEL, } from "../../gateway/tr";
 import { resolvePhiCmsNavigationOverlay, resolvePhiCmsActiveNavigationSurfaces, resolvePhiCmsRoutePresetByPageId, } from "../../plugins/runtime-modules/descriptor-compiler";
+import { cache } from "react";
 import { logRuntimeEvent } from "../../net/log";
 import { phiRuntime } from "../../server-helpers/phi-runtime";
 import { getPhiRequestNavigationContext } from "../../server-helpers/request-runtime";
@@ -58,19 +59,30 @@ function mapResolvedNavigationItem(item, translatedLabels) {
             : {}),
     };
 }
+/*
+ * Every active navigation surface of an Area, resolved once per request (audit K15).
+ *
+ * A page carries a navigation Widget per surface -- header, footer, sider -- and each one resolved all of
+ * the Area's surfaces to pick its own, hashing an instance id per item each time. The request's navigation
+ * context and its viewer are one object each per request, so React's `cache` keyed by them keeps the
+ * answer for exactly that request and nothing longer.
+ */
+const resolveActiveNavigationSurfaces = cache((context, area, viewer) => resolvePhiCmsActiveNavigationSurfaces({
+    catalog: context.catalog,
+    area,
+    activeModuleIds: context.activeModuleIds,
+    routeTable: context.routeTable,
+    viewer,
+}));
 export async function resolvePhiDescriptorNavigationItems(runtime, navKey, overlay = null) {
     const normalizedNavKey = navKey.trim().toLowerCase();
     if (!normalizedNavKey.startsWith(`${runtime.area}:`)) {
         return null;
     }
-    const { catalog, activeModuleIds, routeTable } = getPhiRequestNavigationContext(runtime.area);
-    const descriptorSurface = resolvePhiCmsActiveNavigationSurfaces({
-        catalog,
-        area: runtime.area,
-        activeModuleIds,
-        routeTable,
-        viewer: runtime.viewer,
-    }).find((candidate) => candidate.navKey === normalizedNavKey);
+    const navigationContext = getPhiRequestNavigationContext(runtime.area);
+    const { routeTable } = navigationContext;
+    const descriptorSurface = resolveActiveNavigationSurfaces(navigationContext, runtime.area, runtime.viewer)
+        .find((candidate) => candidate.navKey === normalizedNavKey);
     if (!descriptorSurface && !overlay) {
         return null;
     }

package/components/widgets/shared/bullet-list-vocabulary.d.ts

@@ -41,11 +41,30 @@ export type PhiResolvedBulletListStyle = {
     gap: PhiSpacingScaleKey;
     flags: number;
 };
+/**
+ * The markers a browser cycles through, and a tight gap. Exported so a Widget can state them as its
+ * defaults, which is what an Inspector shows for a list nobody has set yet.
+ */
+export declare const PHI_BULLET_LIST_DEFAULT_STYLE: {
+    readonly level1: "dot";
+    readonly level2: "circle";
+    readonly level3: "dash";
+    readonly gap: "xs";
+};
 /** A stored list style, part by part; whatever is not one of its values is left out. */
 export declare function readPhiBulletListStyle(value: unknown): PhiBulletListStyle | undefined;
 export declare function resolvePhiBulletListStyle(style: PhiBulletListStyle | null | undefined): PhiResolvedBulletListStyle;
 /** The level an entry at `depth` (1 for the outermost) is drawn at. */
 export declare function resolvePhiBulletListLevel(depth: number): PhiBulletListLevel;
+/**
+ * What an entry says about the thing the list belongs to, where the list is a list of what is in it -- a
+ * plan's features. `included` draws a tick, `excluded` a dash and the entry's words quieter; `neutral`
+ * is the list's own marker, and is what an entry without a state is. Stored only where it is not neutral.
+ */
+export declare const PHI_BULLET_LIST_ENTRY_STATES: readonly ["included", "excluded", "neutral"];
+export type PhiBulletListEntryState = (typeof PHI_BULLET_LIST_ENTRY_STATES)[number];
+/** The state after `state`, in the order a click on a marker steps through them. */
+export declare function nextPhiBulletListEntryState(state: PhiBulletListEntryState | undefined): PhiBulletListEntryState;
 /**
  * One entry of a list written as a list: its text, how deep it stands, and the values its text names.
  *
@@ -58,11 +77,17 @@ export type PhiBulletListEntry = {
     /** 1 for the outermost level, which is what an entry without one stands at. */
     level?: number;
     values?: string[];
+    /** Absent is `neutral`. */
+    state?: Exclude<PhiBulletListEntryState, "neutral">;
 };
 export declare function readPhiBulletListEntries(value: unknown): PhiBulletListEntry[];
 /** An entry of the tree the Control draws: what it shows, and the entries one level below it. */
 export type PhiBulletListNode<Content> = {
     content: Content;
+    /** Absent is `neutral`: the marker of the entry's level. */
+    state?: PhiBulletListEntryState;
+    /** Set by an editor: the marker becomes a button that steps the entry's state on. */
+    onMarkerClick?: () => void;
     children?: PhiBulletListNode<Content>[];
 };
 /**
@@ -72,7 +97,8 @@ export type PhiBulletListNode<Content> = {
  */
 export declare function buildPhiBulletListTree<Entry extends {
     level?: number;
-}, Content>(entries: readonly Entry[], content: (entry: Entry, index: number) => Content): PhiBulletListNode<Content>[];
+    state?: PhiBulletListEntryState;
+}, Content>(entries: readonly Entry[], content: (entry: Entry, index: number) => Content, onMarkerClick?: (entry: Entry, index: number) => void): PhiBulletListNode<Content>[];
 /**
  * The Inspector fields for a list style stored under `key`, under a divider titled `heading`. Every Widget
  * with a list offers these, so a list is set the same way wherever it stands.

package/components/widgets/shared/bullet-list-vocabulary.js

@@ -20,8 +20,11 @@ export const PhiBulletListFlag = {
     /** A line between entries, for entries without a ground of their own. */
     Dividers: 1 << 0,
 };
-/** The markers a browser cycles through, and a tight gap. */
-const PHI_BULLET_LIST_DEFAULT_STYLE = {
+/**
+ * The markers a browser cycles through, and a tight gap. Exported so a Widget can state them as its
+ * defaults, which is what an Inspector shows for a list nobody has set yet.
+ */
+export const PHI_BULLET_LIST_DEFAULT_STYLE = {
     level1: "dot",
     level2: "circle",
     level3: "dash",
@@ -69,6 +72,17 @@ export function resolvePhiBulletListLevel(depth) {
     const deepest = PHI_BULLET_LIST_LEVELS[PHI_BULLET_LIST_LEVELS.length - 1];
     return Math.min(Math.max(1, Math.trunc(depth) || 1), deepest);
 }
+/**
+ * What an entry says about the thing the list belongs to, where the list is a list of what is in it -- a
+ * plan's features. `included` draws a tick, `excluded` a dash and the entry's words quieter; `neutral`
+ * is the list's own marker, and is what an entry without a state is. Stored only where it is not neutral.
+ */
+export const PHI_BULLET_LIST_ENTRY_STATES = ["included", "excluded", "neutral"];
+/** The state after `state`, in the order a click on a marker steps through them. */
+export function nextPhiBulletListEntryState(state) {
+    const index = PHI_BULLET_LIST_ENTRY_STATES.indexOf(state ?? "neutral");
+    return PHI_BULLET_LIST_ENTRY_STATES[(index + 1) % PHI_BULLET_LIST_ENTRY_STATES.length];
+}
 export function readPhiBulletListEntries(value) {
     if (!Array.isArray(value)) {
         return [];
@@ -82,10 +96,12 @@ export function readPhiBulletListEntries(value) {
         const values = Array.isArray(record.values)
             ? record.values.map((item) => (typeof item === "string" || typeof item === "number" ? String(item) : ""))
             : [];
+        const state = record.state === "included" || record.state === "excluded" ? record.state : undefined;
         return [{
                 text: record.text,
                 ...(level > 1 ? { level } : {}),
                 ...(values.length > 0 ? { values } : {}),
+                ...(state ? { state } : {}),
             }];
     });
 }
@@ -94,14 +110,18 @@ export function readPhiBulletListEntries(value) {
  * more than a level hangs one level below it all the same: a level cannot be skipped in a nested list,
  * and an entry that tried stays with the entry it follows rather than jumping.
  */
-export function buildPhiBulletListTree(entries, content) {
+export function buildPhiBulletListTree(entries, content, onMarkerClick) {
     const root = [];
     const open = [root];
     entries.forEach((entry, index) => {
         const wanted = resolvePhiBulletListLevel(entry.level ?? 1);
         const level = Math.min(wanted, open.length);
         open.length = level;
-        const node = { content: content(entry, index) };
+        const node = {
+            content: content(entry, index),
+            ...(entry.state && entry.state !== "neutral" ? { state: entry.state } : {}),
+            ...(onMarkerClick ? { onMarkerClick: () => onMarkerClick(entry, index) } : {}),
+        };
         open[level - 1].push(node);
         node.children = [];
         open.push(node.children);

package/components/widgets/shared/card-body-client.d.ts

@@ -4,8 +4,8 @@ import type { PhiImagePresentation } from "../../media/image-presentation";
 import type { PhiClientBlockBaseProps } from "../../../types";
 import type { PhiSurface } from "../../../types/surface";
 import type { PhiSignalRouteSet } from "../../../types/signals";
-import type { PhiCardHeadingLevel, PhiCardHoverEffect, PhiCardIconPlacement, PhiCardTextAlign, PhiCardTextSlot, PhiCardVariant, PhiCardWidgetBody } from "./card-vocabulary";
-export type { PhiCardHeadingLevel, PhiCardHoverEffect, PhiCardIconPlacement, PhiCardTextAlign, PhiCardTextSlot, PhiCardVariant, PhiCardWidgetBody, } from "./card-vocabulary";
+import type { PhiCardBadgeStyle, PhiCardBillingPeriod, PhiCardHeadingLevel, PhiCardHoverEffect, PhiCardIconPlacement, PhiCardTextAlign, PhiCardTextSlot, PhiCardVariant, PhiCardWidgetBody } from "./card-vocabulary";
+export type { PhiCardBadgeStyle, PhiCardBillingPeriod, PhiCardHeadingLevel, PhiCardHoverEffect, PhiCardIconPlacement, PhiCardTextAlign, PhiCardTextSlot, PhiCardVariant, PhiCardWidgetBody, } from "./card-vocabulary";
 export type PhiCardWidgetClientLabels = {
     eyebrow?: string;
     /**
@@ -19,6 +19,13 @@ export type PhiCardWidgetClientLabels = {
     actionLabel?: string;
     /** The figure a `stat` body draws. Data rather than copy, and never translated. */
     value?: string;
+    /** The band at the card's end edge. */
+    badge?: string;
+    /** A `plan` body's prices, data and never translated, and their periods, which are words. */
+    price?: string;
+    pricePeriod?: string;
+    priceYearly?: string;
+    pricePeriodYearly?: string;
 };
 /**
  * What is true about a card's content right now, as opposed to what the card says.
@@ -63,6 +70,12 @@ export type PhiCardWidgetClientConfig = {
     variant?: PhiCardVariant;
     body?: PhiCardWidgetBody;
     highlight?: boolean;
+    /** The badge's ground; absent, the Theme's primary. */
+    badgeColor?: string;
+    /** How the badge is drawn; absent, `none`. */
+    badgeStyle?: PhiCardBadgeStyle;
+    /** Which price a `plan` shows until a `billingPeriod` signal says otherwise. Absent is `monthly`. */
+    billingPeriod?: PhiCardBillingPeriod;
     hoverEffect?: PhiCardHoverEffect;
     /** The card's wired signals (`PHI_CARD_SIGNALS`); absent where nothing is wired, as on the canvas. */
     signalRoutes?: PhiSignalRouteSet | null;
@@ -78,10 +91,11 @@ export type PhiCardWidgetAction = {
 export type PhiCardWidgetClientProps = PhiClientBlockBaseProps<PhiCardWidgetClientLabels, PhiCardWidgetClientConfig> & {
     binding?: PhiCardWidgetClientBinding;
     /**
-     * What a `list` body draws, already drawn.
+     * What a `list` body draws, a `series` body's chart, and a `plan` body's features, already drawn.
      *
      * Handed in rather than drawn here: the Card is on Public pages, and a list Control imported by it
-     * would load on every page with a Card. A Dashboard draws its entries and passes them.
+     * would load on every page with a Card. A Dashboard draws its entries and passes them; a plan card's
+     * server half draws its features on the server, and its editor draws them as fields.
      */
     listContent?: ReactNode;
     /**