@phis/ui 0.4.3 → 0.4.4

package/components/shell/phi-antd-icon.js

@@ -38,6 +38,7 @@ const PHI_ANTD_ICON_LOADERS = {
     CalendarOutlined: () => import("@ant-design/icons-svg/es/asn/CalendarOutlined"),
     CheckOutlined: () => import("@ant-design/icons-svg/es/asn/CheckOutlined"),
     CloseOutlined: () => import("@ant-design/icons-svg/es/asn/CloseOutlined"),
+    CloudDownloadOutlined: () => import("@ant-design/icons-svg/es/asn/CloudDownloadOutlined"),
     CloudUploadOutlined: () => import("@ant-design/icons-svg/es/asn/CloudUploadOutlined"),
     ClusterOutlined: () => import("@ant-design/icons-svg/es/asn/ClusterOutlined"),
     CodeOutlined: () => import("@ant-design/icons-svg/es/asn/CodeOutlined"),
@@ -327,6 +328,8 @@ export const PHI_ANTD_ICON_NAMES = {
     "video-camera-two-tone": "VideoCameraTwoTone",
     warning: "WarningOutlined",
     "warning-outlined": "WarningOutlined",
+    "cloud-download": "CloudDownloadOutlined",
+    "cloud-download-outlined": "CloudDownloadOutlined",
     "cloud-upload": "CloudUploadOutlined",
     "cloud-upload-outlined": "CloudUploadOutlined",
     "eye-invisible": "EyeInvisibleOutlined",

package/components/shell/use-phi-shell-sticky-top.js

@@ -1,32 +1,35 @@
 "use client";
 import { useEffect } from "react";
+import { PHI_SHELL_STICKY_TOP_PROPERTY } from "../root/phi-shell-chrome-overlay";
 /**
  * How far down the viewport the Shell's Header holds right now, published on the Shell.
  *
  * Something that sticks to the top of the page -- a Table's header row -- has to stick under the Header
  * rather than behind it, and where the Header ends is not a constant: each band sticks or scrolls by its
  * own config, and a revealing `header_top` slides away while the visitor reads down and comes back when
- * they scroll up. So the edge is measured, not configured: the lowest bottom of every Header band that is
- * stuck at this moment, written as `--phi-shell-sticky-top` on the Shell element. Unset, a reader falls
+ * they scroll up. So the edge is measured, not configured: the lowest visible bottom of the Header bands,
+ * stuck or in the flow, written as `--phi-shell-sticky-top` on the Shell element. Unset, a reader falls
  * back to `0px`, which is right for a Shell without a sticky Header.
  *
- * Run by whatever sticks under it -- every sticky Table does -- so a page without one loads nothing for
- * it. Each runner measures all the bands and they all write the same value. Not inside an Overlay: a
- * Modal's or Drawer's body scrolls on its own, and its top edge is the line.
+ * Run by whatever sticks under it -- every sticky Table does, and the Region renderer for a stuck Sider
+ * (`phiCmsRegionSiderSticks`) -- so a page without one loads nothing for it. Each runner measures all the
+ * bands and they all write the same value. Not inside an Overlay: a Modal's or Drawer's body scrolls on
+ * its own, and its top edge is the line.
  */
-const PHI_SHELL_STICKY_TOP_PROPERTY = "--phi-shell-sticky-top";
 const HEADER_BANDS = '[data-phi-region-key^="header_"]:not([hidden])';
 function measurePhiShellStickyTop(shell) {
+    /*
+     * The lowest visible bottom of the Header bands, stuck or not. Counting only the bands stuck at this
+     * moment made the edge jump: a band leaving its sticking line for its place in the flow -- the main
+     * band while the top band scrolls back in above it -- dropped out of the count at once, and whatever
+     * stuck under it leapt up by the band's height. Counted while it is in view, the edge moves with the
+     * scroll instead. A band in the flow stands above the content anyway, so nothing sticks too low for it.
+     */
     let bottom = 0;
     for (const band of shell.querySelectorAll(HEADER_BANDS)) {
-        const style = window.getComputedStyle(band);
-        if (style.position !== "sticky" && style.position !== "fixed") {
-            continue;
-        }
         const rect = band.getBoundingClientRect();
-        const stuckAt = Number.parseFloat(style.top) || 0;
-        // Below its sticking line it is still in flow; above the viewport it has slid away.
-        if (rect.height === 0 || rect.top > stuckAt + 1 || rect.bottom <= 0) {
+        // Empty, or scrolled or slid out of the viewport.
+        if (rect.height === 0 || rect.bottom <= 0) {
             continue;
         }
         bottom = Math.max(bottom, rect.bottom);
@@ -57,10 +60,46 @@ export function usePhiShellStickyTop({ active, elementRef, }) {
             }
         };
         publish();
+        /*
+         * A revealing band moves by a transition. Measured only where it settled, whatever sticks under it
+         * would stand still while the band slides and then jump; so while a transition runs in the Shell the
+         * edge is measured every frame, and once more where it ends.
+         */
+        let following = 0;
+        let followFrame = 0;
+        const follow = () => {
+            publish();
+            followFrame = following > 0 ? window.requestAnimationFrame(follow) : 0;
+        };
+        // Only a Header band's own transitions move the edge; a button's hover elsewhere in the Shell does not.
+        const isBandTransition = (event) => event.target instanceof Element && event.target.closest(HEADER_BANDS) !== null;
+        // A transition whose element leaves the page never ends; the follow stops on its own regardless.
+        let followTimeout = 0;
+        const stopFollowing = () => {
+            following = 0;
+            followTimeout = 0;
+        };
+        const transitionStarted = (event) => {
+            if (!isBandTransition(event))
+                return;
+            following += 1;
+            window.clearTimeout(followTimeout);
+            followTimeout = window.setTimeout(stopFollowing, 2000);
+            if (followFrame === 0) {
+                followFrame = window.requestAnimationFrame(follow);
+            }
+        };
+        const transitionStopped = (event) => {
+            if (!isBandTransition(event))
+                return;
+            following = Math.max(0, following - 1);
+            schedule();
+        };
         window.addEventListener("scroll", schedule, { passive: true });
         window.addEventListener("resize", schedule);
-        // A revealing band moves by a transition; its end is where it settled.
-        shell.addEventListener("transitionend", schedule);
+        shell.addEventListener("transitionrun", transitionStarted);
+        shell.addEventListener("transitionend", transitionStopped);
+        shell.addEventListener("transitioncancel", transitionStopped);
         const observer = new ResizeObserver(schedule);
         for (const band of shell.querySelectorAll(HEADER_BANDS)) {
             observer.observe(band);
@@ -69,9 +108,15 @@ export function usePhiShellStickyTop({ active, elementRef, }) {
             if (frame !== 0) {
                 window.cancelAnimationFrame(frame);
             }
+            if (followFrame !== 0) {
+                window.cancelAnimationFrame(followFrame);
+            }
+            window.clearTimeout(followTimeout);
             window.removeEventListener("scroll", schedule);
             window.removeEventListener("resize", schedule);
-            shell.removeEventListener("transitionend", schedule);
+            shell.removeEventListener("transitionrun", transitionStarted);
+            shell.removeEventListener("transitionend", transitionStopped);
+            shell.removeEventListener("transitioncancel", transitionStopped);
             observer.disconnect();
         };
     }, [active, elementRef]);

package/components/surface/phi-surface-tone.d.ts

@@ -16,3 +16,16 @@ export declare function PhiSurfaceTone({ tone, children, }: {
     tone: PhiSurfaceToneValue | null | undefined;
     children: ReactNode;
 }): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react").JSX.Element | null | undefined;
+/**
+ * The page's own mode around something that belongs to the page's tools rather than to its content.
+ *
+ * The Builder draws its scaffolds -- tool bars, drag handles, the effects preview -- inside the Surfaces
+ * they edit, and a toned Surface would turn them with its content. This turns them back: inside a tone
+ * scope it mounts the page's mode again (its Ant Design components take it by themselves), outside one it
+ * renders the children as they are. `className` is the class an element of the caller's that reads the
+ * Theme's variables itself must carry, so they resolve in the page's mode there too; empty outside a tone.
+ */
+export declare function usePhiPageModeTone(): {
+    className: string | undefined;
+    wrap: (children: ReactNode) => ReactNode;
+};

package/components/surface/phi-surface-tone.js

@@ -34,3 +34,24 @@ export function PhiSurfaceTone({ tone, children, }) {
     }
     return (_jsx(Suspense, { fallback: null, children: _jsx(PhiSurfaceToneScope, { mode: target, cssVarKey: cssVarKey, source: source, children: children }) }));
 }
+/**
+ * The page's own mode around something that belongs to the page's tools rather than to its content.
+ *
+ * The Builder draws its scaffolds -- tool bars, drag handles, the effects preview -- inside the Surfaces
+ * they edit, and a toned Surface would turn them with its content. This turns them back: inside a tone
+ * scope it mounts the page's mode again (its Ant Design components take it by themselves), outside one it
+ * renders the children as they are. `className` is the class an element of the caller's that reads the
+ * Theme's variables itself must carry, so they resolve in the page's mode there too; empty outside a tone.
+ */
+export function usePhiPageModeTone() {
+    const { mode } = usePhiConfig();
+    const source = usePhiThemeToneSource();
+    const pageMode = source?.pageMode ?? mode;
+    if (pageMode === mode) {
+        return { className: undefined, wrap: (children) => children };
+    }
+    return {
+        className: resolvePhiSurfaceToneClassName(pageMode),
+        wrap: (children) => _jsx(PhiSurfaceTone, { tone: pageMode, children: children }),
+    };
+}

package/components/widgets/client/bullet-list-entries-editor.js

@@ -99,5 +99,11 @@ export function PhiBulletListEntriesEditor({ entries, listStyle, onCommit, state
                     resize: "none",
                     color: "inherit",
                     ...fieldStyle,
-                } })), states && onCommit ? (_entry, index) => stepState(index) : undefined) }) }));
+                }, 
+                /*
+                 * The text's own padding, stated: half of what the line leaves of the field's height, so the
+                 * first line's middle is the marker's (`markerLineHeight` above). That is the padding the
+                 * field had from Ant Design already; stated, the clear button can find the line too.
+                 */
+                inputStyle: { paddingBlock: "calc((var(--ant-control-height) - 1lh) / 2)" } })), states && onCommit ? (_entry, index) => stepState(index) : undefined) }) }));
 }

package/components/widgets/client/html-editor.js

@@ -388,7 +388,7 @@ export function PhiHtmlWidgetEditor({ blockId, html, fontFamily, fontSize, onCha
     const initialHtmlRef = useRef(normalizedHtml);
     const latestHtmlRef = useRef(normalizedHtml);
     const resolvedFontFamily = resolvePhiWidgetFontFamily(fontFamily, fonts, token);
-    const resolvedFontSize = resolvePhiWidgetFontSize(fontSize, token, "lg");
+    const resolvedFontSize = resolvePhiWidgetFontSize(fontSize, token, "base");
     const editable = onChange != null;
     useEffect(() => {
         latestHtmlRef.current = normalizedHtml;

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

@@ -0,0 +1,17 @@
+import type { PhiCmsAreaKey } from "../../../../constants/cms-areas";
+import type { PhiTreeOption } from "../../../../types/tree";
+import type { PhiPageReferenceSelection } from "./phi-page-reference-picker";
+type PageReferenceOptions = PhiTreeOption<PhiPageReferenceSelection>[];
+/**
+ * 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 declare function usePhiPageReferenceOptions(area: PhiCmsAreaKey, logScope: string): {
+    options: PageReferenceOptions;
+    failed: boolean;
+};
+export {};

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/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-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/shared/bullet-list-vocabulary.d.ts

@@ -41,6 +41,16 @@ 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;

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",

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 { PhiCardBillingPeriod, PhiCardHeadingLevel, PhiCardHoverEffect, PhiCardIconPlacement, PhiCardTextAlign, PhiCardTextSlot, PhiCardVariant, PhiCardWidgetBody } from "./card-vocabulary";
-export type { PhiCardBillingPeriod, 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;
     /**
@@ -72,6 +72,8 @@ export type PhiCardWidgetClientConfig = {
     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;
@@ -89,7 +91,7 @@ export type PhiCardWidgetAction = {
 export type PhiCardWidgetClientProps = PhiClientBlockBaseProps<PhiCardWidgetClientLabels, PhiCardWidgetClientConfig> & {
     binding?: PhiCardWidgetClientBinding;
     /**
-     * What a `list` body draws, and a `plan` body's features, 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; a plan card's

package/components/widgets/shared/card-body-client.js

@@ -5,6 +5,7 @@ import { PhiButtonControl } from "../../controls/phi-button-control";
 import { PhiFlexControl } from "../../controls/phi-flex-control";
 import { PhiImageControl } from "../../controls/phi-image-control";
 import { PhiRibbonControl } from "../../controls/phi-ribbon-control";
+import { PhiRibbonWrapControl } from "../../controls/phi-ribbon-wrap-control";
 import { PhiSkeletonControl } from "../../controls/phi-skeleton-control";
 import { PhiStatisticControl } from "../../controls/phi-statistic-control";
 import { PhiTypographyControl } from "../../controls/phi-typography-control";
@@ -16,6 +17,7 @@ import { PhiSurfaceTone } from "../../surface/phi-surface-tone";
 import { resolvePhiSurfaceStyle } from "../../../helpers/surface-style";
 import { usePhiControlSignalController } from "../client/shared/phi-control-signals";
 import { PHI_COLOR, PHI_SPACE } from "../../../theme/antd-css-var-contract";
+import { PHI_THEME_HEADING_FONT_VARIABLE } from "../../../theme/phi-theme-typography";
 import { PHI_CARD_TEXT_SLOTS, readPhiCardBillingPeriod } from "./card-vocabulary";
 const PHI_CARD_SIGNAL_TEXT_SLOTS = new Set(PHI_CARD_TEXT_SLOTS);
 /*
@@ -192,6 +194,8 @@ export function PhiCardWidgetClient({ labels: placedLabels, config, binding, lis
      * Segmented's items follow their track. The Theme's plain corner did not: a pill Site drew square marks.
      */
     const iconCorner = (side) => `calc(var(--phi-control-radius-lg, ${token.borderRadiusLG}px) * ${side / token.controlHeightLG})`;
+    /* The framed box an icon before the title stands in. */
+    const inlineIconFrame = iconSize + 16;
     const iconMark = (size, framed) => iconName ? (_jsx("span", { "aria-hidden": "true", className: "phi-card__icon", style: {
             display: "inline-flex",
             flex: "none",
@@ -207,10 +211,34 @@ export function PhiCardWidgetClient({ labels: placedLabels, config, binding, lis
      * unreadable. A card whose figure is the only thing it has makes the figure the link.
      */
     const valueText = renderText ? renderText("value", labels.value) : null;
-    const figure = valueText != null ? (_jsx("div", { style: { fontSize: token.fontSizeHeading3, color: highlight ? PHI_COLOR.primary : PHI_COLOR.textHeading, ...slotWidth }, children: valueText })) : (_jsx(PhiStatisticControl, { value: binding?.error ?? labels.value ?? "", loading: binding?.loading === true || overrides.loading === true, styles: {
+    /*
+     * Beside an icon before the title, the figure starts where the title's words do, under them rather
+     * than under the icon: the number belongs to the heading, the icon only marks it. On a line set to its
+     * start only -- centred or at the end, the figure already stands with the words.
+     */
+    const figureIndent = iconPlacement === "inline" && iconName && (textAlign === "start" || textAlign === "justify")
+        ? { paddingInlineStart: inlineIconFrame + gap }
+        : {};
+    /*
+     * The figure is set like the title it belongs to: in the font the Theme gives headings, and with digits
+     * of one width, so a figure that changes does not shift as it counts. No fallback in the `var()`, as for
+     * the headings themselves (`styles/layout.css`): a Theme that keeps headings on the body font sets no
+     * variable, and the figure inherits the body font.
+     */
+    const figureType = {
+        fontFamily: `var(${PHI_THEME_HEADING_FONT_VARIABLE})`,
+        fontVariantNumeric: "tabular-nums",
+    };
+    const figure = valueText != null ? (_jsx("div", { style: {
+            ...figureType,
+            fontSize: token.fontSizeHeading3,
+            color: highlight ? PHI_COLOR.primary : PHI_COLOR.textHeading,
+            ...slotWidth,
+            ...figureIndent,
+        }, children: valueText })) : (_jsx(PhiStatisticControl, { value: binding?.error ?? labels.value ?? "", loading: binding?.loading === true || overrides.loading === true, style: figureIndent, styles: {
             content: binding?.error
                 ? { color: PHI_COLOR.error, fontSize: token.fontSize }
-                : { color: highlight ? PHI_COLOR.primary : PHI_COLOR.textHeading },
+                : { ...figureType, color: highlight ? PHI_COLOR.primary : PHI_COLOR.textHeading },
         } }));
     /* A failure stands where the lines would, as it does for a figure; a list still coming is three lines. */
     const list = binding?.error ? (_jsx(PhiTypographyControl, { style: { color: PHI_COLOR.error, ...slotWidth }, children: binding.error })) : binding?.loading === true || overrides.loading === true ? (_jsx(PhiSkeletonControl, { lines: 3 })) : listContent ?? null;
@@ -230,7 +258,7 @@ export function PhiCardWidgetClient({ labels: placedLabels, config, binding, lis
                             color: highlight ? PHI_COLOR.primary : PHI_COLOR.textHeading,
                             ...slotWidth,
                         }, children: priceText })) : null, periodText != null ? (_jsx("span", { style: { color: PHI_COLOR.textSecondary, ...slotWidth }, children: periodText })) : null] })) : null, list != null ? _jsx("div", { style: { justifySelf: "stretch", minWidth: 0, textAlign: "start" }, children: list }) : null] })) : null;
-    const headingRow = iconPlacement === "inline" && iconName ? (_jsxs("div", { style: { display: "flex", alignItems: "center", justifyContent: justify, gap, ...slotWidth }, children: [iconMark(iconSize, iconSize + 16), heading] })) : heading;
+    const headingRow = iconPlacement === "inline" && iconName ? (_jsxs("div", { style: { display: "flex", alignItems: "center", justifyContent: justify, gap, ...slotWidth }, children: [iconMark(iconSize, inlineIconFrame), heading] })) : heading;
     const media = image ? (_jsxs("div", { className: "phi-card__media", style: {
             position: "relative",
             aspectRatio: metrics.mediaAspectRatio ?? resolveMediaAspectRatio(image.presentation),
@@ -294,19 +322,34 @@ export function PhiCardWidgetClient({ labels: placedLabels, config, binding, lis
      * The band in the card's top end corner, floating (`PhiRibbonControl`): the words below it start where
      * they start in a card without one, so plans side by side keep their headings on one line.
      */
-    const ribbon = badge != null ? (_jsx(PhiRibbonControl, { color: config?.badgeColor, placement: "corner", ...(renderText ? { style: { pointerEvents: "auto", minWidth: "6em" } } : {}), children: badge })) : null;
-    const words = (_jsxs("div", { style: { display: "grid", gap, padding: footAction ? 0 : inset, justifyItems }, children: [iconAtTop && iconName && !image ? (_jsx("div", { style: { justifySelf: markSide === "center" ? "center" : markSide === "end" ? "end" : "start" }, children: iconMark(topIconSize, topIconSize + 24) })) : null, eyebrow != null && !eyebrowOnMedia && !labels.eyebrowEnd ? (_jsx(PhiTypographyControl, { type: "secondary", style: { ...eyebrowType, color: highlight ? PHI_COLOR.primary : PHI_COLOR.textTertiary, ...slotWidth }, children: eyebrow })) : null, labels.eyebrowEnd && !eyebrowOnMedia ? (_jsxs(PhiFlexControl, { justify: "space-between", align: "baseline", wrap: true, gap: PHI_SPACE.xs, style: { justifySelf: "stretch", minWidth: 0 }, children: [_jsx(PhiTypographyControl, { type: "secondary", style: { ...eyebrowType, color: highlight ? PHI_COLOR.primary : PHI_COLOR.textTertiary }, children: eyebrow ?? "" }), _jsx(PhiTypographyControl, { type: "secondary", style: { ...eyebrowType, color: PHI_COLOR.textTertiary }, children: labels.eyebrowEnd })] })) : null, headingRow, body === "stat" ? figure : null, body === "list" && list != null ? (_jsx("div", { style: { justifySelf: "stretch", minWidth: 0 }, children: list })) : null, description != null ? (_jsx(PhiTypographyControl, { presentation: "paragraph", style: {
+    const badgeStyle = config?.badgeStyle ?? "none";
+    const ribbon = badge != null && (badgeStyle === "corner" || badgeStyle === "tag") ? (_jsx(PhiRibbonControl, { color: config?.badgeColor, placement: badgeStyle === "tag" ? "edge" : "corner", ...(!renderText && labels.badge
+            ? {
+                fullText: labels.badge,
+                ...(href
+                    ? {
+                        onClick: (event) => event.currentTarget.closest(".phi-card")?.querySelector(".phi-card__link")?.click(),
+                    }
+                    : {}),
+            }
+            : {}), ...(renderText ? { style: { pointerEvents: "auto", minWidth: "6em" } } : {}), children: badge })) : null;
+    const words = (_jsxs("div", { style: { display: "grid", gap, padding: footAction ? 0 : inset, justifyItems }, children: [iconAtTop && iconName && !image ? (_jsx("div", { style: { justifySelf: markSide === "center" ? "center" : markSide === "end" ? "end" : "start" }, children: iconMark(topIconSize, topIconSize + 24) })) : null, eyebrow != null && !eyebrowOnMedia && !labels.eyebrowEnd ? (_jsx(PhiTypographyControl, { type: "secondary", style: { ...eyebrowType, color: highlight ? PHI_COLOR.primary : PHI_COLOR.textTertiary, ...slotWidth }, children: eyebrow })) : null, labels.eyebrowEnd && !eyebrowOnMedia ? (_jsxs(PhiFlexControl, { justify: "space-between", align: "baseline", wrap: true, gap: PHI_SPACE.xs, style: { justifySelf: "stretch", minWidth: 0 }, children: [_jsx(PhiTypographyControl, { type: "secondary", style: { ...eyebrowType, color: highlight ? PHI_COLOR.primary : PHI_COLOR.textTertiary }, children: eyebrow ?? "" }), _jsx(PhiTypographyControl, { type: "secondary", style: { ...eyebrowType, color: PHI_COLOR.textTertiary }, children: labels.eyebrowEnd })] })) : null, headingRow, body === "stat" ? figure : null, body === "series" ? (_jsxs(_Fragment, { children: [labels.value || binding?.error || binding?.loading === true || overrides.loading === true ? figure : null, list != null && !binding?.error && binding?.loading !== true && overrides.loading !== true ? (_jsx("div", { style: { justifySelf: "stretch", minWidth: 0 }, children: list })) : null] })) : null, body === "list" && list != null ? (_jsx("div", { style: { justifySelf: "stretch", minWidth: 0 }, children: list })) : null, description != null ? (_jsx(PhiTypographyControl, { presentation: "paragraph", style: {
                     marginBottom: 0,
                     color: PHI_COLOR.textSecondary,
                     fontSize: descriptionSize,
                     ...slotWidth,
                 }, children: description })) : null, plan, meta != null ? (_jsx(PhiTypographyControl, { type: "secondary", style: { fontSize: token.fontSizeSM, color: PHI_COLOR.textTertiary, ...slotWidth }, children: meta })) : null, footAction ? null : actionButton] }));
     const content = (_jsxs(_Fragment, { children: [media, footAction ? (_jsxs("div", { style: { display: "flex", flexDirection: "column", gap, padding: inset, flex: "1 1 auto", minWidth: 0 }, children: [words, actionButton] })) : words, cardLink] }));
-    return (_jsxs("article", { className: [
+    const card = (_jsxs("article", { className: [
             "phi-card",
             href ? "phi-card--link" : null,
             highlight ? "phi-card--highlight" : null,
             hoverEffect !== "none" ? `phi-card--hover-${hoverEffect}` : null,
             surface.className,
         ].filter(Boolean).join(" "), "data-phi-card-variant": variant, style: boxStyle, children: [_jsx(PhiSurfaceGroundLayer, { ground: surface.ground, className: "phi-card__ground" }), ribbon, surface.className ? _jsx(PhiSurfaceTone, { tone: config?.surface?.tone, children: content }) : content] }));
+    /*
+     * A ribbon hangs over the card's edge, which the card -- clipping for its picture and its zoom -- cannot
+     * give a child of its own; it wraps the card instead (`PhiRibbonWrapControl`). An editor writes in it.
+     */
+    return badge != null && badgeStyle === "ribbon" ? (_jsx(PhiRibbonWrapControl, { text: badge, ...(config?.badgeColor ? { color: config.badgeColor } : {}), interactive: renderText != null, className: hoverEffect === "lift" ? "phi-card-ribbon phi-card-ribbon--lift" : "phi-card-ribbon", children: card })) : card;
 }