@phis/ui 0.4.2 → 0.4.4

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

@@ -4,6 +4,8 @@ import { useState } from "react";
 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";
@@ -14,8 +16,10 @@ import { PhiSurfaceGroundLayer } from "../../surface/phi-surface-ground";
 import { PhiSurfaceTone } from "../../surface/phi-surface-tone";
 import { resolvePhiSurfaceStyle } from "../../../helpers/surface-style";
 import { usePhiControlSignalController } from "../client/shared/phi-control-signals";
-import { PHI_SPACE } from "../../../theme/antd-css-var-contract";
-const PHI_CARD_SIGNAL_TEXT_SLOTS = new Set(["eyebrow", "title", "description", "meta", "value"]);
+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);
 /*
  * What each variant sets, in one row per variant. A further variant -- a featured card -- is a row here
  * and an entry in `PHI_CARD_VARIANTS`.
@@ -71,13 +75,19 @@ const PHI_CARD_HIDDEN_TEXT = {
     whiteSpace: "nowrap",
     border: 0,
 };
-const PHI_CARD_THEME_CORNER = "var(--phi-surface-radius, var(--ant-border-radius-lg))";
+const PHI_CARD_THEME_CORNER = "var(--phi-surface-radius)";
 /** The box a picture is shown in takes the picture's own proportion; 3:2 where nothing is known. */
 function resolveMediaAspectRatio(presentation) {
     return presentation.width && presentation.height
         ? `${presentation.width} / ${presentation.height}`
         : "3 / 2";
 }
+/*
+ * Every colour the card paints is the Theme's variable (`PHI_COLOR`), never a token's resolved value: a
+ * Surface with a `tone` writes the other mode's variables on the card's box, and only a variable reaches
+ * the words inside it. Resolved values were the page's mode written in by hand, and dark words stayed
+ * dark on a photograph darkened for light ones.
+ */
 export function PhiCardWidgetClient({ labels: placedLabels, config, binding, listContent, renderText, }) {
     const { token } = usePhiConfig();
     const [overrides, setOverrides] = useState({});
@@ -94,6 +104,11 @@ export function PhiCardWidgetClient({ labels: placedLabels, config, binding, lis
             else if (capabilityId === "loading" || capabilityId === "highlight") {
                 setOverrides((current) => ({ ...current, [capabilityId]: signal.value === true }));
             }
+            else if (capabilityId === "billingPeriod") {
+                const billingPeriod = readPhiCardBillingPeriod(signal.value);
+                if (billingPeriod)
+                    setOverrides((current) => ({ ...current, billingPeriod }));
+            }
             return true;
         },
     });
@@ -157,15 +172,30 @@ export function PhiCardWidgetClient({ labels: placedLabels, config, binding, lis
     const title = textOf("title");
     const description = textOf("description");
     const meta = textOf("meta");
+    const badge = textOf("badge");
     const eyebrowType = { fontSize: token.fontSizeSM, letterSpacing: "0.04em", textTransform: "uppercase" };
     /* On the picture's corner where the variant puts it there and there is a picture to put it on. */
     const eyebrowOnMedia = metrics.eyebrowOnMedia === true && image != null;
-    const heading = title != null ? (_jsx(PhiTypographyControl, { presentation: "title", level: Number(headingLevel.slice(1)), style: { margin: 0, ...headingType[headingLevel], color: token.colorTextHeading, ...slotWidth }, children: title })) : null;
+    const heading = title != null ? (_jsx(PhiTypographyControl, { presentation: "title", level: Number(headingLevel.slice(1)), style: { margin: 0, ...headingType[headingLevel], color: PHI_COLOR.textHeading, ...slotWidth }, children: title })) : null;
     /*
      * The icon's colours as custom properties, which `.phi-card__icon` paints (`styles/layout.css`): the
      * `icon` hover effect turns them round, and a colour stated inline could not be turned by a rule.
      */
-    const iconColours = (color, background) => ({ "--phi-card-icon-color": color, "--phi-card-icon-background": background });
+    const iconColours = (color, background) => ({
+        "--phi-card-icon-color": color,
+        "--phi-card-icon-background": background,
+        /* The mark's colour once the `icon` effect turns them round: a ground it can be read on. */
+        "--phi-card-icon-hover-color": config?.iconBackground ?? PHI_COLOR.bgContainer,
+    });
+    /*
+     * The corner of the icon's ground: the Theme's Control shape at the large size, scaled from a large
+     * Control's height to the ground's side. So `square` draws a square, `pill` a circle -- half the large
+     * height scaled to the side is half the side -- and the steps between keep their proportion, as a
+     * 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",
@@ -173,22 +203,62 @@ export function PhiCardWidgetClient({ labels: placedLabels, config, binding, lis
             justifyContent: "center",
             width: framed,
             height: framed,
-            borderRadius: token.borderRadius,
-            ...iconColours(config?.iconColor ?? (highlight ? token.colorPrimary : token.colorTextSecondary), config?.iconBackground ?? token.colorFillQuaternary),
+            borderRadius: iconCorner(framed),
+            ...iconColours(config?.iconColor ?? (highlight ? PHI_COLOR.primary : PHI_COLOR.textSecondary), config?.iconBackground ?? PHI_COLOR.fillQuaternary),
         }, children: _jsx(PhiIcon, { name: iconName, size: size }) })) : null;
     /*
      * A failure stands where the figure would, at body size, because a sentence in figure type is
      * 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 ? token.colorPrimary : token.colorTextHeading, ...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: token.colorError, fontSize: token.fontSize }
-                : { color: highlight ? token.colorPrimary : token.colorTextHeading },
+                ? { color: PHI_COLOR.error, fontSize: token.fontSize }
+                : { ...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: token.colorError, ...slotWidth }, children: binding.error })) : binding?.loading === true || overrides.loading === true ? (_jsx(PhiSkeletonControl, { lines: 3 })) : listContent ?? 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 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;
+    /*
+     * A plan's price: the period's own where it states one, the monthly one where it does not, so a switch
+     * to yearly never leaves a card without a price. An editor is asked for the shown period's fields.
+     */
+    const yearly = (overrides.billingPeriod ?? config?.billingPeriod) === "yearly";
+    const showsYearly = yearly && (renderText != null || Boolean(labels.priceYearly));
+    const priceText = body === "plan" ? textOf(showsYearly ? "priceYearly" : "price") : null;
+    const periodText = body === "plan" ? textOf(showsYearly ? "pricePeriodYearly" : "pricePeriod") : null;
+    const plan = body === "plan" ? (_jsxs("div", { style: { display: "grid", gap, justifySelf: "stretch", justifyItems, minWidth: 0 }, children: [priceText != null || periodText != null ? (_jsxs("div", { style: { display: "flex", flexWrap: "wrap", alignItems: "baseline", justifyContent: justify, columnGap: PHI_SPACE.xs, ...slotWidth }, children: [priceText != null ? (_jsx("span", { className: "phi-card__price", style: {
+                            fontSize: token.fontSizeHeading2,
+                            lineHeight: token.lineHeightHeading2,
+                            fontWeight: 600,
+                            fontVariantNumeric: "tabular-nums",
+                            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, inlineIconFrame), heading] })) : heading;
     const media = image ? (_jsxs("div", { className: "phi-card__media", style: {
             position: "relative",
             aspectRatio: metrics.mediaAspectRatio ?? resolveMediaAspectRatio(image.presentation),
@@ -208,9 +278,9 @@ export function PhiCardWidgetClient({ labels: placedLabels, config, binding, lis
                     justifyContent: "center",
                     width: topIconSize + 24,
                     height: topIconSize + 24,
-                    borderRadius: "50%",
+                    borderRadius: iconCorner(topIconSize + 24),
                     // A ground of its own, so the mark reads on a bright picture and on a dark one alike.
-                    ...iconColours(config?.iconColor ?? (highlight ? token.colorPrimary : token.colorText), config?.iconBackground ?? `color-mix(in srgb, ${token.colorBgContainer} 88%, transparent)`),
+                    ...iconColours(config?.iconColor ?? (highlight ? PHI_COLOR.primary : PHI_COLOR.text), config?.iconBackground ?? `color-mix(in srgb, ${PHI_COLOR.bgContainer} 88%, transparent)`),
                     boxShadow: token.boxShadowTertiary,
                 }, children: _jsx(PhiIcon, { name: iconName, size: topIconSize }) })) : null, eyebrowOnMedia && eyebrow != null ? (_jsx(PhiTypographyControl, { type: "secondary", style: {
                     ...eyebrowType,
@@ -222,8 +292,8 @@ export function PhiCardWidgetClient({ labels: placedLabels, config, binding, lis
                     paddingInline: token.paddingXS,
                     borderRadius: token.borderRadiusSM,
                     // A ground of its own, as the icon has, so the words read on any picture.
-                    background: `color-mix(in srgb, ${token.colorBgContainer} 88%, transparent)`,
-                    color: highlight ? token.colorPrimary : token.colorText,
+                    background: `color-mix(in srgb, ${PHI_COLOR.bgContainer} 88%, transparent)`,
+                    color: highlight ? PHI_COLOR.primary : PHI_COLOR.text,
                 }, children: eyebrow })) : null] })) : null;
     const boxStyle = {
         ...(config?.surface ? {} : { borderRadius: PHI_CARD_THEME_CORNER }),
@@ -235,21 +305,51 @@ export function PhiCardWidgetClient({ labels: placedLabels, config, binding, lis
         minWidth: 0,
         overflow: "hidden",
         textAlign,
-        color: token.colorText,
+        color: PHI_COLOR.text,
         /* The ring's colour; `.phi-card--highlight` draws it (`styles/layout.css`). */
-        ...(highlight ? { "--phi-card-highlight-color": token.colorPrimary } : {}),
+        ...(highlight ? { "--phi-card-highlight-color": PHI_COLOR.primary } : {}),
     };
-    const content = (_jsxs(_Fragment, { children: [media, _jsxs("div", { style: { display: "grid", gap, padding: 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 ? token.colorPrimary : token.colorTextTertiary, ...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 ? token.colorPrimary : token.colorTextTertiary }, children: eyebrow ?? "" }), _jsx(PhiTypographyControl, { type: "secondary", style: { ...eyebrowType, color: token.colorTextTertiary }, 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: {
-                            marginBottom: 0,
-                            color: token.colorTextSecondary,
-                            fontSize: descriptionSize,
-                            ...slotWidth,
-                        }, children: description })) : null, meta != null ? (_jsx(PhiTypographyControl, { type: "secondary", style: { fontSize: token.fontSizeSM, color: token.colorTextTertiary, ...slotWidth }, children: meta })) : null, action ? (_jsx("div", { className: "phi-card__action", children: _jsx(PhiButtonControl, { type: highlight ? "primary" : "default", size: buttonSize, ...(action.href ? { href: action.href, newTab: action.newTab, external: action.external } : {}), label: labels.actionLabel || undefined, ...(labels.actionLabel ? {} : { ariaLabel: action.ariaLabel }), ...(action.icon ? { icon: _jsx(PhiIcon, { name: action.icon, size: "1em" }) } : {}), ...(activates ? { onClick: () => controlSignals.emitCapability("activate", null) } : {}) }) })) : null] }), cardLink] }));
-    return (_jsxs("article", { className: [
+    /*
+     * A plan's button stands at the card's foot: plans side by side in a row have lists of different
+     * lengths, and their buttons belong on one line. The words keep their grid; the grid and the button
+     * stand in a column that fills the card, and the button takes what is left above it.
+     */
+    const footAction = body === "plan" && action != null;
+    const actionButton = action ? (_jsx("div", { className: "phi-card__action", 
+        /* At the foot, it stands where the words' alignment puts it, as it does among them. */
+        style: footAction ? { marginTop: "auto", alignSelf: textAlign === "center" ? "center" : textAlign === "end" ? "flex-end" : "flex-start" } : undefined, children: _jsx(PhiButtonControl, { type: highlight ? "primary" : "default", size: buttonSize, ...(action.href ? { href: action.href, newTab: action.newTab, external: action.external } : {}), label: labels.actionLabel || undefined, ...(labels.actionLabel ? {} : { ariaLabel: action.ariaLabel }), ...(action.icon ? { icon: _jsx(PhiIcon, { name: action.icon, size: "1em" }) } : {}), ...(activates ? { onClick: () => controlSignals.emitCapability("activate", null) } : {}) }) })) : null;
+    /*
+     * 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 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] }));
+    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" }), surface.className ? _jsx(PhiSurfaceTone, { tone: config?.surface?.tone, children: content }) : content] }));
+        ].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;
 }

package/components/widgets/shared/card-vocabulary.d.ts

@@ -4,12 +4,26 @@
  * `text` is a heading. `stat` is a labelled figure: the label is the heading, so a card that counts
  * something says what it counted in the same place and type a text card says what it is about, and the
  * figure is drawn by the house's one statistic Control. `list` is a heading over a few lines the caller
- * draws and hands in (`listContent`), which only a Dashboard does today.
+ * draws and hands in (`listContent`), which only a Dashboard does today. `series` is a figure over time:
+ * the headline as a `stat` draws it, over a chart the caller draws and hands in the same way -- a Dashboard
+ * again, so the chart Control never loads with a Card on a Public page. `plan` is an offer: a price
+ * and what it is paid per, a monthly and a yearly one of each, over a list of what the plan includes and
+ * what it does not (`PhiBulletListEntry.state`). Several plan cards side by side are a Layout's row, and
+ * the recommended one is the card that is `highlight`ed.
  *
  * The body is chosen, never inferred from whether a value happens to have arrived. A card that decided
  * by presence would draw as text and reflow into a statistic the moment its figure landed.
  */
-export type PhiCardWidgetBody = "text" | "stat" | "list";
+export type PhiCardWidgetBody = "text" | "stat" | "list" | "series" | "plan";
+/**
+ * Which of a plan card's two prices it shows. A plan states one, the other, or both; one that states
+ * only the monthly price shows it under `yearly` as well, so a period switch on the page never leaves a
+ * card without a price. The page switches every plan at once by sending `billingPeriod`.
+ */
+export declare const PHI_CARD_BILLING_PERIODS: readonly ["monthly", "yearly"];
+export type PhiCardBillingPeriod = (typeof PHI_CARD_BILLING_PERIODS)[number];
+/** A sent period as one of the two; anything else is not a period and changes nothing. */
+export declare function readPhiCardBillingPeriod(value: unknown): PhiCardBillingPeriod | undefined;
 /**
  * The tag of the card's heading, and the step it is drawn at.
  *
@@ -24,6 +38,14 @@ export type PhiCardHeadingLevel = (typeof PHI_CARD_HEADING_LEVELS)[number];
 /** Logical, so `start` is the left in a left-to-right page and the right in a right-to-left one. */
 export declare const PHI_CARD_TEXT_ALIGNS: readonly ["start", "center", "end", "justify"];
 export type PhiCardTextAlign = (typeof PHI_CARD_TEXT_ALIGNS)[number];
+/**
+ * How a card's badge is drawn. `corner` is a band flush in the top end corner, `tag` a rounded mark a
+ * little down the end edge -- both inside the card. `ribbon` hangs over the end edge with a fold behind
+ * it, and needs room beside the card. `none` draws nothing and keeps the words, to hide a badge for a
+ * while. Absent is `none`: a card has a badge once a style is chosen for it.
+ */
+export declare const PHI_CARD_BADGE_STYLES: readonly ["none", "corner", "tag", "ribbon"];
+export type PhiCardBadgeStyle = (typeof PHI_CARD_BADGE_STYLES)[number];
 /**
  * Where the icon stands: before the heading, small, or at the top, large -- at the start, the middle or
  * the end of the line, over the picture when the card has one, on a ground of its own so it reads on any
@@ -48,6 +70,11 @@ export type PhiCardHoverEffect = (typeof PHI_CARD_HOVER_EFFECTS)[number];
  */
 export declare const PHI_CARD_VARIANTS: readonly ["default", "compact", "center"];
 export type PhiCardVariant = (typeof PHI_CARD_VARIANTS)[number];
-/** The words a card shows, each in its own place; what an editor can put a field in. */
-export declare const PHI_CARD_TEXT_SLOTS: readonly ["eyebrow", "title", "description", "meta", "value"];
+/**
+ * The words a card shows, each in its own place; what an editor can put a field in, and what a signal can
+ * write. `badge` is the band at the card's end edge, any body may carry one. The prices are figures like
+ * `value` and are never translated: a price that differs by country is sent by a Controller or comes
+ * from a Provider's row, not from a translator. The periods (`/ month`) are words and are.
+ */
+export declare const PHI_CARD_TEXT_SLOTS: readonly ["eyebrow", "title", "description", "meta", "value", "badge", "price", "pricePeriod", "priceYearly", "pricePeriodYearly"];
 export type PhiCardTextSlot = (typeof PHI_CARD_TEXT_SLOTS)[number];

package/components/widgets/shared/card-vocabulary.js

@@ -2,6 +2,16 @@
  * The Card Widget's words, apart from its Client half: the Widget's definition is read on the server, and
  * a value imported from the Client file would make that file a client reference of every route.
  */
+/**
+ * Which of a plan card's two prices it shows. A plan states one, the other, or both; one that states
+ * only the monthly price shows it under `yearly` as well, so a period switch on the page never leaves a
+ * card without a price. The page switches every plan at once by sending `billingPeriod`.
+ */
+export const PHI_CARD_BILLING_PERIODS = ["monthly", "yearly"];
+/** A sent period as one of the two; anything else is not a period and changes nothing. */
+export function readPhiCardBillingPeriod(value) {
+    return PHI_CARD_BILLING_PERIODS.includes(value) ? value : undefined;
+}
 /**
  * The tag of the card's heading, and the step it is drawn at.
  *
@@ -14,6 +24,13 @@
 export const PHI_CARD_HEADING_LEVELS = ["h2", "h3", "h4"];
 /** Logical, so `start` is the left in a left-to-right page and the right in a right-to-left one. */
 export const PHI_CARD_TEXT_ALIGNS = ["start", "center", "end", "justify"];
+/**
+ * How a card's badge is drawn. `corner` is a band flush in the top end corner, `tag` a rounded mark a
+ * little down the end edge -- both inside the card. `ribbon` hangs over the end edge with a fold behind
+ * it, and needs room beside the card. `none` draws nothing and keeps the words, to hide a badge for a
+ * while. Absent is `none`: a card has a badge once a style is chosen for it.
+ */
+export const PHI_CARD_BADGE_STYLES = ["none", "corner", "tag", "ribbon"];
 /**
  * Where the icon stands: before the heading, small, or at the top, large -- at the start, the middle or
  * the end of the line, over the picture when the card has one, on a ground of its own so it reads on any
@@ -35,5 +52,21 @@ export const PHI_CARD_HOVER_EFFECTS = ["none", "lift", "zoom", "icon"];
  * not another branch in every size the card draws. `default` is what a card without one is.
  */
 export const PHI_CARD_VARIANTS = ["default", "compact", "center"];
-/** The words a card shows, each in its own place; what an editor can put a field in. */
-export const PHI_CARD_TEXT_SLOTS = ["eyebrow", "title", "description", "meta", "value"];
+/**
+ * The words a card shows, each in its own place; what an editor can put a field in, and what a signal can
+ * write. `badge` is the band at the card's end edge, any body may carry one. The prices are figures like
+ * `value` and are never translated: a price that differs by country is sent by a Controller or comes
+ * from a Provider's row, not from a translator. The periods (`/ month`) are words and are.
+ */
+export const PHI_CARD_TEXT_SLOTS = [
+    "eyebrow",
+    "title",
+    "description",
+    "meta",
+    "value",
+    "badge",
+    "price",
+    "pricePeriod",
+    "priceYearly",
+    "pricePeriodYearly",
+];

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

@@ -68,9 +68,16 @@ function renderInlineNodes(inlines) {
         }
     });
 }
-function renderBlocks(blocks, token, paragraphBlockStyle, headingBlockStyle, lists) {
+function renderBlocks(blocks, token, paragraphStyle, headingStyle, lists, atStart = false) {
     return blocks.map((block, index) => {
         const key = `${block.kind}-${index}`;
+        /*
+         * The first block of a text, or of a quote, keeps no space before it: the space before a block
+         * parts it from the block above, and there is none -- the Widget's own edge stands there.
+         */
+        const leading = atStart && index === 0;
+        const paragraphBlockStyle = leading ? { ...paragraphStyle, marginBlockStart: 0 } : paragraphStyle;
+        const headingBlockStyle = leading ? { ...headingStyle, paddingBlockStart: 0 } : headingStyle;
         switch (block.kind) {
             case "heading":
                 return (_jsx(PhiTypographyControl, { presentation: "title", id: block.id, level: block.level, style: headingBlockStyle, children: renderInlineNodes(block.inlines) }, key));
@@ -81,19 +88,31 @@ function renderBlocks(blocks, token, paragraphBlockStyle, headingBlockStyle, lis
                         margin: 0,
                         paddingInlineStart: PHI_SPACE.md,
                         borderInlineStart: `3px solid ${token.colorBorderSecondary}`,
-                    }, children: _jsx("div", { style: { display: "grid", gap: 0 }, children: renderBlocks(block.children, token, paragraphBlockStyle, headingBlockStyle, lists) }) }, key));
+                    }, children: _jsx("div", { style: { display: "grid", gap: 0 }, children: renderBlocks(block.children, token, paragraphStyle, headingStyle, lists, true) }) }, key));
             case "list":
                 /*
                  * The house's list, set by the Widget's list settings. A `1.` list counts whatever its level's
                  * marker says: the numbers are the text's, not a look. A list inside an entry is one level down.
                  */
-                return (_jsx(PhiBulletListControl, { listStyle: lists.style, depth: lists.depth, ordered: block.ordered, start: block.start, items: block.items.map((itemBlocks) => ({
-                        content: (_jsx("div", { style: { display: "grid", gap: PHI_SPACE.xs, minWidth: 0 }, children: renderBlocks(itemBlocks, token, paragraphBlockStyle, headingBlockStyle, { ...lists, depth: lists.depth + 1 }) })),
+                return (_jsx(PhiBulletListControl, { listStyle: lists.style, depth: lists.depth, ordered: block.ordered, start: block.start, 
+                    /*
+                     * The list stands among the text's blocks as a paragraph does: the entries draw close, but the
+                     * block after the last one keeps the text's spacing. A list inside an entry gets the entry's
+                     * zeroed spacing, so it sits in its entry's grid.
+                     */
+                    blockSpacing: {
+                        marginBlockStart: paragraphBlockStyle.marginBlockStart,
+                        marginBlockEnd: paragraphBlockStyle.marginBlockEnd,
+                    }, items: block.items.map((itemBlocks) => ({
+                        content: (_jsx("div", { style: { display: "grid", gap: PHI_SPACE.xs, minWidth: 0 }, children: renderBlocks(itemBlocks, token, { ...paragraphStyle, marginBlockStart: 0, marginBlockEnd: 0 }, headingStyle, { ...lists, depth: lists.depth + 1 }) })),
                     })) }, key));
             case "code":
                 return (_jsx("pre", { "data-phi-code-language": block.language ?? undefined, style: {
                         margin: 0,
-                        padding: PHI_SPACE.md,
+                        // A code block stands among the text's blocks as a paragraph does, with the text's spacing.
+                        marginBlockStart: paragraphBlockStyle.marginBlockStart,
+                        marginBlockEnd: paragraphBlockStyle.marginBlockEnd,
+                        padding: PHI_SPACE.base,
                         overflowX: "auto",
                         borderRadius: token.borderRadiusSM,
                         background: token.colorFillQuaternary,
@@ -157,15 +176,25 @@ export function PhiMarkdownWidgetClient({ config }) {
         marginBlockStart: resolvePhiSpacingScaleValue(config?.textBlockSpacingBefore ?? "none"),
         marginBlockEnd: resolvePhiSpacingScaleValue(config?.textBlockSpacingAfter ?? "sm"),
     };
+    /*
+     * The space before a heading is padding, not margin, so it adds to the space after the block above
+     * however the text is laid out: in the grid margins never collapse, in the flow that pictures need
+     * they would, and the same setting would part a heading from its paragraph by less there.
+     */
     const headingBlockStyle = {
         margin: 0,
-        marginBlockStart: resolvePhiSpacingScaleValue(config?.headingBlockSpacingBefore ?? "none"),
+        paddingBlockStart: resolvePhiSpacingScaleValue(config?.headingBlockSpacingBefore ?? "sm"),
         marginBlockEnd: resolvePhiSpacingScaleValue(config?.headingBlockSpacingAfter ?? "sm"),
     };
-    return (_jsx("div", { className: config?.imageFloat ? `phi-markdown-body phi-markdown-body--float-${config.imageFloat}` : undefined, style: config?.imageFloat
-            ? { display: "flow-root", width: "100%", textAlign: config.textAlign, containerType: "inline-size" }
-            : { display: "grid", gap: 0, width: "100%", textAlign: config?.textAlign }, children: renderBlocks(blocks, token, paragraphBlockStyle, headingBlockStyle, {
+    return (_jsx("div", { className: config?.imageFloat
+            ? `phi-markdown-text phi-markdown-body phi-markdown-body--float-${config.imageFloat}`
+            : "phi-markdown-text", 
+        // The text's line height for everything in it, lists included: a list entry otherwise takes the
+        // browser's `normal`, and its marker centres on a line shorter than the one its words stand on.
+        style: config?.imageFloat
+            ? { display: "flow-root", width: "100%", textAlign: config.textAlign, containerType: "inline-size", lineHeight: token.lineHeight }
+            : { display: "grid", gap: 0, width: "100%", textAlign: config?.textAlign, lineHeight: token.lineHeight }, children: renderBlocks(blocks, token, paragraphBlockStyle, headingBlockStyle, {
             style: resolvePhiBulletListStyle(config?.list),
             depth: 1,
-        }) }));
+        }, true) }));
 }

package/components/widgets/signals/control-signal-capabilities.d.ts

@@ -328,21 +328,3 @@ export declare const PHI_MULTI_SELECT_CONTROL_SIGNALS: {
         valueType: "none";
     })[];
 };
-export declare const PHI_DRAG_SOURCE_CONTROL_SIGNALS: {
-    emits: ({
-        id: string;
-        action: "start";
-        valueType: "json";
-        valueSchema: `${string}/signals/${string}`;
-    } | {
-        id: string;
-        action: "change";
-        valueType: "json";
-        valueSchema: `${string}/signals/${string}`;
-    } | {
-        id: string;
-        action: "stop";
-        valueType: "json";
-        valueSchema: `${string}/signals/${string}`;
-    })[];
-};

package/components/widgets/signals/control-signal-capabilities.js

@@ -89,6 +89,16 @@ export const PHI_CARD_SIGNALS = {
         { id: "description", channel: "description", action: "change", valueType: "string" },
         { id: "meta", channel: "meta", action: "change", valueType: "string" },
         { id: "highlight", channel: "highlight", action: "change", valueType: "boolean" },
+        { id: "badge", channel: "badge", action: "change", valueType: "string" },
+        /*
+         * A plan's prices, for a Controller that knows them better than the page does -- by the reader's
+         * country, say -- and the period a switch on the page shows (`monthly` or `yearly`).
+         */
+        { id: "price", channel: "price", action: "change", valueType: "string" },
+        { id: "pricePeriod", channel: "pricePeriod", action: "change", valueType: "string" },
+        { id: "priceYearly", channel: "priceYearly", action: "change", valueType: "string" },
+        { id: "pricePeriodYearly", channel: "pricePeriodYearly", action: "change", valueType: "string" },
+        { id: "billingPeriod", channel: "billingPeriod", action: "change", valueType: "string" },
     ],
 };
 export const PHI_TEXT_CONTROL_SIGNALS = {
@@ -227,25 +237,3 @@ export const PHI_MULTI_SELECT_CONTROL_SIGNALS = {
         { ...PHI_CONTROL_CLEAR_SIGNAL, channel: "selection" },
     ],
 };
-export const PHI_DRAG_SOURCE_CONTROL_SIGNALS = {
-    emits: [
-        {
-            id: "dragStart",
-            action: "start",
-            valueType: "json",
-            valueSchema: PHI_SIGNAL_VALUE_SCHEMAS.dragDrop,
-        },
-        {
-            id: "dragChange",
-            action: "change",
-            valueType: "json",
-            valueSchema: PHI_SIGNAL_VALUE_SCHEMAS.dragDrop,
-        },
-        {
-            id: "dragEnd",
-            action: "stop",
-            valueType: "json",
-            valueSchema: PHI_SIGNAL_VALUE_SCHEMAS.dragDrop,
-        },
-    ],
-};

package/components/workspace/catalog-store.d.ts

@@ -1,9 +1,10 @@
 import type { PhiWorkspaceCatalogState } from "./catalog-state";
 export type { PhiWorkspaceCatalogArea, PhiWorkspaceCatalogState } from "./catalog-state";
 /**
- * One scope per workspace host. Both the Builder and, later, the Editor write into "public".
+ * One scope per workspace host, not one per Area. Both the Builder and, later, the Editor write into it;
+ * which Area is open is `area` inside it, and what belongs to an Area is keyed by Area there.
  */
 export declare const PHI_WORKSPACE_CATALOG_SCOPE = "public";
 export declare const phiWorkspaceCatalogStore: import("../state/plugin-state-store").PhiPluginStateStore<PhiWorkspaceCatalogState>;
-export declare function usePhiWorkspaceCatalogValue<TSelected>(scopeKey: string, selector: (state: PhiWorkspaceCatalogState) => TSelected): TSelected;
-export declare function getPhiWorkspaceCatalogSnapshot(scopeKey: string): PhiWorkspaceCatalogState;
+export declare function usePhiWorkspaceCatalogValue<TSelected>(selector: (state: PhiWorkspaceCatalogState) => TSelected): TSelected;
+export declare function getPhiWorkspaceCatalogSnapshot(): PhiWorkspaceCatalogState;

package/components/workspace/catalog-store.js

@@ -2,7 +2,8 @@
 import { createEmptyPhiBuilderModulePresetPagesByArea } from "../../helpers/cms-page-catalog";
 import { createPhiPluginStateStore } from "../state/plugin-state-store";
 /**
- * One scope per workspace host. Both the Builder and, later, the Editor write into "public".
+ * One scope per workspace host, not one per Area. Both the Builder and, later, the Editor write into it;
+ * which Area is open is `area` inside it, and what belongs to an Area is keyed by Area there.
  */
 export const PHI_WORKSPACE_CATALOG_SCOPE = "public";
 function createDefaultWorkspaceCatalogState(scopeKey) {
@@ -25,9 +26,9 @@ function createDefaultWorkspaceCatalogState(scopeKey) {
     };
 }
 export const phiWorkspaceCatalogStore = createPhiPluginStateStore("@phis/ui/workspace-catalog", createDefaultWorkspaceCatalogState);
-export function usePhiWorkspaceCatalogValue(scopeKey, selector) {
-    return phiWorkspaceCatalogStore.useStoreSelector(scopeKey, selector);
+export function usePhiWorkspaceCatalogValue(selector) {
+    return phiWorkspaceCatalogStore.useStoreSelector(PHI_WORKSPACE_CATALOG_SCOPE, selector);
 }
-export function getPhiWorkspaceCatalogSnapshot(scopeKey) {
-    return phiWorkspaceCatalogStore.getSnapshot(scopeKey);
+export function getPhiWorkspaceCatalogSnapshot() {
+    return phiWorkspaceCatalogStore.getSnapshot(PHI_WORKSPACE_CATALOG_SCOPE);
 }

package/gateway/dashboard-cards-route.js

@@ -79,6 +79,7 @@ async function resolveDashboardCardScope({ bridge, area, locale, path, cookieHea
         locale,
         area,
         viewer: requestContext.viewer,
+        runtimeModuleCatalog: bridge.runtimeModuleCatalog,
     };
     /*
      * A route handler has no request runtime bound, and the label sets a card reads for its own title

package/gateway/internal-references.d.ts

@@ -11,7 +11,12 @@ export type PhiResolvedInternalReferences = {
     pages: readonly PhiResolvedPageReference[];
     assets: ReadonlyMap<number, PhiPublicMediaAssetReference>;
 };
-/** One Asset of the public reference projection, as the server writes it; a shape it does not match throws. */
+/**
+ * One Asset of the public reference projection, as the server writes it; a shape it does not match throws.
+ *
+ * Every field, not five of them: what passed here went straight into a rendered page under a type that
+ * promised a focal rectangle and font metrics nobody had looked at.
+ */
 export declare function readPhiPublicMediaAssetReference(entry: unknown): PhiPublicMediaAssetReference;
 /**
  * Resolves both internal reference kinds, together with whatever else asks in the same turn.