@phis/ui 0.4.3 → 0.4.4

package/styles/shell.css

@@ -294,6 +294,33 @@
   --phi-shell-chrome-filter: var(--phi-shell-chrome-filter-dark, none);
 }
 
+/* The Overlay in a tone's mode (LAYOUTING.md "Surface tone"), for a box whose Background is the Theme's
+   (`PHI_BACKGROUND_THEME_STYLE`). The tone's class publishes the Overlay of the mode it asks for, so the
+   box -- and an untoned box inside it -- reads that mode's variables; `inverse` is read against the page's
+   mode, as the tone scope reads it, and turns with the mode switch. Inside the Root Layout only: a Modal
+   or Drawer portalled to `<body>` has no Overlay published, and its box falls back to the container
+   ground of the tone's mode. The Root Layout's own values above stay what the Chrome Regions and panes
+   read; those are computed on the Root Layout and inherited, so a tone below cannot touch them. */
+:where([data-phi-root-layout="true"]) :where(.phi-tone-light),
+:where([data-phi-root-layout="true"][data-phi-theme-mode="dark"]) :where(.phi-tone-inverse) {
+  --phi-shell-chrome-image: var(--phi-shell-chrome-image-light, none);
+  --phi-shell-chrome-size: var(--phi-shell-chrome-size-light, auto);
+  --phi-shell-chrome-position: var(--phi-shell-chrome-position-light, 0 0);
+  --phi-shell-chrome-repeat: var(--phi-shell-chrome-repeat-light, repeat);
+  --phi-shell-chrome-color: var(--phi-shell-chrome-color-light, transparent);
+  --phi-shell-chrome-filter: var(--phi-shell-chrome-filter-light, none);
+}
+
+:where([data-phi-root-layout="true"]) :where(.phi-tone-dark),
+:where([data-phi-root-layout="true"]:not([data-phi-theme-mode="dark"])) :where(.phi-tone-inverse) {
+  --phi-shell-chrome-image: var(--phi-shell-chrome-image-dark, none);
+  --phi-shell-chrome-size: var(--phi-shell-chrome-size-dark, auto);
+  --phi-shell-chrome-position: var(--phi-shell-chrome-position-dark, 0 0);
+  --phi-shell-chrome-repeat: var(--phi-shell-chrome-repeat-dark, repeat);
+  --phi-shell-chrome-color: var(--phi-shell-chrome-color-dark, transparent);
+  --phi-shell-chrome-filter: var(--phi-shell-chrome-filter-dark, none);
+}
+
 /* A Chrome Region carries the marker only while it authored no ground of its own, so there is nothing
    left to fall back through here: the shared colour is the ground. It needs no light and dark pair
    either, because the pair above has already resolved the mode. This rule follows the two that set the
@@ -332,6 +359,17 @@
   z-index: 50;
 }
 
+/*
+ * The Header's panes stand above every Sider's. Both are grid items at the same level, and a Sider's
+ * pane comes later in the DOM, so at an equal `z-index` it painted over the Header's where the two meet:
+ * the Sider's ground hid the Header's and cut its Shadow at the Sider's edge. Still below every Chrome
+ * Region (100 and up).
+ */
+.phi-shell-chrome-pane--header,
+.phi-shell-chrome-pane--header-bottom {
+  z-index: 51;
+}
+
 /*
  * What the pane paints is set inline by the Shell, not here.
  *
@@ -430,6 +468,41 @@
   --phi-region-chrome-attachment: scroll;
 }
 
+/*
+ * A toned band takes no paint from its family's pane (LAYOUTING.md "Surface tone").
+ *
+ * A toned Chrome Region paints its own ground -- the tone's container ground, a stated Background, or
+ * the Overlay of its tone's mode -- and never carries the marker. The pane behind it keeps the page's
+ * mode, so where that ground lets anything through, the page-mode glass showed under the tone's. The
+ * pane cannot be cut around one band without knowing its height, so it stops painting for the whole
+ * family and the family's marker bands paint the Overlay themselves, as they do without panes. Its
+ * geometry and Shadow stay: the frame's edge is where it was, and the Header still stands over the
+ * Sider. The pane's paint is inline and reads these properties on the pane itself, so they are set
+ * there. Untoned families match nothing here.
+ */
+.shell-sider-full:has(> :is([data-phi-region-key="header_top"], [data-phi-region-key="header_main"], [data-phi-region-key="header_bottom"]):is(.phi-tone-light, .phi-tone-dark, .phi-tone-inverse)) > .phi-shell-chrome-pane--header,
+.shell-sider-embedded:has(> :is([data-phi-region-key="header_top"], [data-phi-region-key="header_main"]):is(.phi-tone-light, .phi-tone-dark, .phi-tone-inverse)) > .phi-shell-chrome-pane--header,
+.shell-sider-embedded:has(> [data-phi-region-key="header_bottom"]:is(.phi-tone-light, .phi-tone-dark, .phi-tone-inverse)) > .phi-shell-chrome-pane--header-bottom,
+[data-phi-shell-chrome-panes="true"]:has(> [data-phi-region-key="sider_left"]:is(.phi-tone-light, .phi-tone-dark, .phi-tone-inverse)) > .phi-shell-chrome-pane--sider,
+[data-phi-shell-chrome-panes="true"]:has(> [data-phi-region-key="sider_right"]:is(.phi-tone-light, .phi-tone-dark, .phi-tone-inverse)) > .phi-shell-chrome-pane--sider-right,
+[data-phi-shell-chrome-panes="true"]:has(> :is([data-phi-region-key="footer_top"], [data-phi-region-key="footer_main"], [data-phi-region-key="footer_bottom"]):is(.phi-tone-light, .phi-tone-dark, .phi-tone-inverse)) > .phi-shell-chrome-pane--footer {
+  --phi-shell-chrome-image: none;
+  --phi-shell-chrome-color: transparent;
+  --phi-shell-chrome-filter: none;
+}
+
+.shell-sider-full:has(> :is([data-phi-region-key="header_top"], [data-phi-region-key="header_main"], [data-phi-region-key="header_bottom"]):is(.phi-tone-light, .phi-tone-dark, .phi-tone-inverse))
+  > .phi-cms-region-shell[data-phi-shell-chrome="true"]:is([data-phi-region-key="header_top"], [data-phi-region-key="header_main"], [data-phi-region-key="header_bottom"]),
+.shell-sider-embedded:has(> :is([data-phi-region-key="header_top"], [data-phi-region-key="header_main"]):is(.phi-tone-light, .phi-tone-dark, .phi-tone-inverse))
+  > .phi-cms-region-shell[data-phi-shell-chrome="true"]:is([data-phi-region-key="header_top"], [data-phi-region-key="header_main"]),
+[data-phi-shell-chrome-panes="true"]:has(> :is([data-phi-region-key="footer_top"], [data-phi-region-key="footer_main"], [data-phi-region-key="footer_bottom"]):is(.phi-tone-light, .phi-tone-dark, .phi-tone-inverse))
+  > .phi-cms-region-shell[data-phi-shell-chrome="true"]:is([data-phi-region-key="footer_top"], [data-phi-region-key="footer_main"], [data-phi-region-key="footer_bottom"]) {
+  --phi-region-chrome-image: var(--phi-shell-chrome-image, none);
+  --phi-region-chrome-color: var(--phi-shell-chrome-color, transparent);
+  --phi-region-chrome-filter: var(--phi-shell-chrome-filter, none);
+  --phi-region-chrome-attachment: fixed;
+}
+
 /* ---------------------------------------------------------------------------------------------
    Revealing `header_top` (SHELL.md "Region visibility per Page")
 

package/theme/phi-antd-token-resolver.js

@@ -1,4 +1,5 @@
 import darkAlgorithm from "antd/es/theme/themes/dark";
+import { generateColorPalettes as generateDarkColorPalettes } from "antd/es/theme/themes/dark/colors";
 import defaultAlgorithm from "antd/es/theme/themes/default";
 import seedToken from "antd/es/theme/themes/seed";
 import formatToken from "antd/es/theme/util/alias";
@@ -34,13 +35,31 @@ export function createPhiAntdThemeCssVarKey(scope, identity) {
         .replace(/^-+|-+$/g, "") || "theme";
     return `phi-${normalizedScope}-${hashPhiAntdThemeIdentity(identity)}`;
 }
+/*
+ * A link and an info colour pointed at turn lighter in the dark mode, as a primary button does.
+ *
+ * Ant Design takes both hovers from step 4 of the colour's palette in either mode. In the light palette
+ * that step is a lighter tint; the dark algorithm reorders its palette so the low steps fade into the dark
+ * ground for borders and fills, and step 4 there is the border's -- darker than the colour itself, so a
+ * link went dim on a dark ground when pointed at (#3867b5 to #274069 on #08153a). The primary hover takes
+ * step 5, which in the dark palette is the lighter one; these take it too. A hover a Theme states itself
+ * still wins: `formatToken` lays the stated tokens over this.
+ */
+function withPhiDarkHoverSteps(seed, derived) {
+    const linkBase = seed.colorLink || seed.colorInfo;
+    return {
+        ...derived,
+        ...(linkBase ? { colorLinkHover: generateDarkColorPalettes(linkBase)[5] } : {}),
+        ...(seed.colorInfo ? { colorInfoHover: generateDarkColorPalettes(seed.colorInfo)[5] } : {}),
+    };
+}
 export function resolvePhiAntdAliasTokens(mode, token) {
     const mergedSeedToken = {
         ...seedToken,
         ...token,
     };
     const derivativeToken = mode === "dark"
-        ? darkAlgorithm(mergedSeedToken)
+        ? withPhiDarkHoverSteps(mergedSeedToken, darkAlgorithm(mergedSeedToken))
         : defaultAlgorithm(mergedSeedToken);
     return formatToken({
         ...derivativeToken,

package/theme/phi-theme-tokens.d.ts

@@ -22,7 +22,7 @@ import type { PhiThemePalette } from "./phi-theme-presets";
  * Who may still speak Ant Design directly is a separate question, and `scripts/validate-control-boundaries.mjs`
  * answers it: the alias resolver, the root adapter, the two font helpers and this file.
  */
-export declare const PHI_THEME_TOKEN_KEYS: readonly ["colorBgContainer", "colorBgElevated", "colorBgMask", "colorBgSpotlight", "colorBorder", "colorBorderSecondary", "colorSplit", "colorFillAlter", "colorFill", "colorBgLayout", "colorFillQuaternary", "colorFillSecondary", "colorFillTertiary", "colorText", "colorTextBase", "colorTextHeading", "colorTextSecondary", "colorTextTertiary", "colorTextQuaternary", "colorTextDescription", "colorTextDisabled", "colorTextLabel", "colorTextPlaceholder", "colorTextLightSolid", "colorPrimary", "colorPrimaryBg", "colorPrimaryBgHover", "colorPrimaryBorder", "colorPrimaryBorderHover", "colorPrimaryHover", "colorPrimaryActive", "colorPrimaryText", "colorPrimaryTextHover", "colorPrimaryTextActive", "colorInfo", "colorInfoBg", "colorInfoBgHover", "colorInfoBorder", "colorInfoBorderHover", "colorInfoText", "colorInfoTextHover", "colorSuccess", "colorSuccessBg", "colorSuccessBgHover", "colorSuccessBorder", "colorSuccessBorderHover", "colorSuccessText", "colorWarning", "colorWarningBg", "colorWarningBgHover", "colorWarningBorder", "colorWarningBorderHover", "colorWarningText", "colorError", "colorErrorBg", "colorErrorText", "colorErrorTextHover", "colorErrorTextActive", "colorLink", "colorLinkHover", "colorLinkActive", "padding", "paddingXXS", "paddingXS", "paddingSM", "paddingMD", "paddingLG", "paddingXL", "margin", "marginXXS", "marginXS", "marginSM", "marginMD", "marginLG", "marginXL", "marginXXL", "sizeXS", "sizeSM", "sizeMD", "sizeLG", "borderRadius", "borderRadiusXS", "borderRadiusSM", "borderRadiusLG", "borderRadiusOuter", "lineWidth", "lineType", "boxShadow", "boxShadowSecondary", "boxShadowTertiary", "controlHeight", "controlHeightXS", "controlHeightSM", "controlHeightLG", "fontFamily", "fontFamilyCode", "fontSize", "fontSizeSM", "fontSizeLG", "fontSizeXL", "fontSizeHeading1", "fontSizeHeading2", "fontSizeHeading3", "fontSizeHeading4", "fontSizeHeading5", "fontWeightStrong", "lineHeight", "lineHeightLG", "lineHeightHeading1", "lineHeightHeading2", "lineHeightHeading3", "lineHeightHeading4", "lineHeightHeading5", "motionDurationMid", "motionDurationSlow", "motionEaseInOut", "motionEaseOut"];
+export declare const PHI_THEME_TOKEN_KEYS: readonly ["colorBgContainer", "colorBgElevated", "colorBgMask", "colorBgSpotlight", "colorBorder", "colorBorderSecondary", "colorSplit", "colorFillAlter", "colorFill", "colorBgLayout", "colorFillQuaternary", "colorFillSecondary", "colorFillTertiary", "colorText", "colorTextBase", "colorTextHeading", "colorTextSecondary", "colorTextTertiary", "colorTextQuaternary", "colorTextDescription", "colorTextDisabled", "colorTextLabel", "colorTextPlaceholder", "colorTextLightSolid", "colorPrimary", "colorPrimaryBg", "colorPrimaryBgHover", "colorPrimaryBorder", "colorPrimaryBorderHover", "colorPrimaryHover", "colorPrimaryActive", "colorPrimaryText", "colorPrimaryTextHover", "colorPrimaryTextActive", "colorInfo", "colorInfoBg", "colorInfoBgHover", "colorInfoBorder", "colorInfoBorderHover", "colorInfoText", "colorInfoTextHover", "colorSuccess", "colorSuccessBg", "colorSuccessBgHover", "colorSuccessBorder", "colorSuccessBorderHover", "colorSuccessText", "colorWarning", "colorWarningBg", "colorWarningBgHover", "colorWarningBorder", "colorWarningBorderHover", "colorWarningText", "colorError", "colorErrorBg", "colorErrorText", "colorErrorTextHover", "colorErrorTextActive", "colorLink", "colorLinkHover", "colorLinkActive", "padding", "paddingXXS", "paddingXS", "paddingSM", "paddingMD", "paddingLG", "paddingXL", "margin", "marginXXS", "marginXS", "marginSM", "marginMD", "marginLG", "marginXL", "marginXXL", "sizeXS", "sizeSM", "sizeMD", "sizeLG", "borderRadius", "borderRadiusXS", "borderRadiusSM", "borderRadiusLG", "borderRadiusOuter", "lineWidth", "lineType", "boxShadow", "boxShadowSecondary", "boxShadowTertiary", "controlHeight", "controlHeightXS", "controlHeightSM", "controlHeightLG", "fontFamily", "fontFamilyCode", "fontSize", "fontSizeSM", "fontSizeLG", "fontSizeXL", "fontSizeHeading1", "fontSizeHeading2", "fontSizeHeading3", "fontSizeHeading4", "fontSizeHeading5", "fontWeightStrong", "lineHeight", "lineHeightSM", "lineHeightLG", "lineHeightHeading1", "lineHeightHeading2", "lineHeightHeading3", "lineHeightHeading4", "lineHeightHeading5", "motionDurationMid", "motionDurationSlow", "motionEaseInOut", "motionEaseOut"];
 /**
  * The names this house adds to Ant Design's set.
  *

package/theme/phi-theme-tokens.js

@@ -138,6 +138,7 @@ export const PHI_THEME_TOKEN_KEYS = [
     "fontSizeHeading5",
     "fontWeightStrong",
     "lineHeight",
+    "lineHeightSM",
     "lineHeightLG",
     "lineHeightHeading1",
     "lineHeightHeading2",

package/theme/phi-theme.d.ts

@@ -16,6 +16,11 @@ export type PhiComponentTokenOptions = {
         overrides?: Record<string, unknown>;
     };
     menu?: Record<string, unknown>;
+    /** The Theme's small size (`fontSizeSM`), for the parts that take it; absent, the scale's `sm`. */
+    fontSizeSM?: number;
+    /** The Theme's body size and line height (`fontSize`, `lineHeight`); absent, the scale's `base`. */
+    fontSize?: number;
+    lineHeight?: number;
     overrides?: Record<string, Record<string, unknown>>;
 };
 export type PhiThemeTokens = {

package/theme/phi-theme.js

@@ -65,6 +65,9 @@ export function buildPhiThemeStructuralTokens(options = {}) {
     return Object.fromEntries(Object.entries(buildPhiThemeTokens(options)).filter(([key]) => !key.startsWith("color")));
 }
 export function buildPhiComponentTokens(options = {}) {
+    const fontSizeSM = options.fontSizeSM ?? PHI_FONT_SIZES.sm;
+    const fontSize = options.fontSize ?? PHI_FONT_SIZES.base;
+    const lineHeight = options.lineHeight ?? lineHeightFor(PHI_FONT_SIZES.base);
     return {
         Layout: {
             headerHeight: PHI_LAYOUT.headerHeight,
@@ -81,6 +84,24 @@ export function buildPhiComponentTokens(options = {}) {
             itemMarginInline: PHI_SPACE.sm,
             ...options.menu,
         },
+        /*
+         * The parts that take the scale's small size rather than the body's. A table is read across, not down:
+         * its cells are small, as a plain table's are (controls.css). A compact control -- `size="small"` --
+         * is small in its words as well as its height; Ant Design gives it the body size unless told.
+         */
+        Table: { cellFontSize: fontSizeSM, cellFontSizeMD: fontSizeSM, cellFontSizeSM: fontSizeSM },
+        // A Tree lists rows like a Table and writes like one: its titles, and the switcher's icon with them.
+        Tree: { fontSize: fontSizeSM },
+        // A contents list beside a text is a list like a Tree's, and writes as small.
+        Anchor: { fontSize: fontSizeSM },
+        // A Divider's words label a section; Ant Design sets them at `lg`, which the scale made a heading's size.
+        Divider: { fontSizeLG: fontSize },
+        Input: { inputFontSizeSM: fontSizeSM },
+        InputNumber: { inputFontSizeSM: fontSizeSM },
+        DatePicker: { inputFontSizeSM: fontSizeSM },
+        Button: { contentFontSizeSM: fontSizeSM },
+        // An Overlay's title is a label over its body, in the body's size; Ant Design gives a Modal the h5's.
+        Modal: { titleFontSize: fontSize, titleLineHeight: lineHeight },
         ...options.overrides,
     };
 }

package/theme/phi-tokens.d.ts

@@ -19,28 +19,29 @@ export declare const PHI_PADDING: {
 /**
  * The type scale: one list for every size a Phi surface states.
  *
- * Two halves. Up to `lg` it climbs in steps of 2 px, because an interface needs its small sizes close
- * together -- a caption, a tag, a label, the text beside them. From `xl` it is the spacing sequence, where
- * the steps are meant to be far apart. Every size is set rather than left to Ant Design's curve, which
- * lands between the steps.
+ * A ladder of phi from the body size 16 -- the browser's own, and what reading text on the web is set in.
+ * `sm`, `lg`, `xxl` and `display` are the Fibonacci sizes around it (13, 21, 34, 55), `xl` is 16 x phi (26),
+ * between 21 and 34 where their geometric mean falls, and `xs` keeps the 9 a counter or a superscript needs.
+ * Every size is set rather than left to Ant Design's curve, which lands between the steps.
  *
  * `sm` to `xl` are handed to Ant Design as its tokens; `xs`, `xxl` and `display` have none and are read
- * from here, fixed until v1. The headings take their sizes from the same list: `h4` and `h5` are both the
- * body size and differ by weight and colour alone. `display` is no heading level but a size, for a hero's
- * or a landing's title, and is not offered beside the others.
+ * from here, fixed until v1. The headings take their sizes from the same list: `h1` the page's title at
+ * `xxl`, about twice the body, then `xl`, `lg`, and `h4` and `h5` at the body and `sm` sizes, set apart by
+ * weight and colour. `display` is no heading level but a size, for a hero's or a landing's title, and is
+ * not offered beside the others.
  */
 export declare const PHI_FONT_SIZES: {
     readonly xs: 9;
-    readonly sm: 11;
-    readonly base: 13;
-    readonly lg: 15;
-    readonly xl: 21;
+    readonly sm: 13;
+    readonly base: 16;
+    readonly lg: 21;
+    readonly xl: 26;
     readonly xxl: 34;
     readonly display: 55;
     readonly heading1: 34;
-    readonly heading2: 21;
-    readonly heading3: 15;
-    readonly heading4: 13;
+    readonly heading2: 26;
+    readonly heading3: 21;
+    readonly heading4: 16;
     readonly heading5: 13;
 };
 export declare const PHI_RADII: {
@@ -54,7 +55,7 @@ export declare const PHI_RADII: {
     readonly xxl: 89;
 };
 export declare const PHI_CONTROL_HEIGHTS: {
-    readonly sm: 21;
+    readonly sm: 26;
     readonly md: 34;
     readonly lg: 55;
 };

package/theme/phi-tokens.js

@@ -19,28 +19,29 @@ export const PHI_PADDING = {
 /**
  * The type scale: one list for every size a Phi surface states.
  *
- * Two halves. Up to `lg` it climbs in steps of 2 px, because an interface needs its small sizes close
- * together -- a caption, a tag, a label, the text beside them. From `xl` it is the spacing sequence, where
- * the steps are meant to be far apart. Every size is set rather than left to Ant Design's curve, which
- * lands between the steps.
+ * A ladder of phi from the body size 16 -- the browser's own, and what reading text on the web is set in.
+ * `sm`, `lg`, `xxl` and `display` are the Fibonacci sizes around it (13, 21, 34, 55), `xl` is 16 x phi (26),
+ * between 21 and 34 where their geometric mean falls, and `xs` keeps the 9 a counter or a superscript needs.
+ * Every size is set rather than left to Ant Design's curve, which lands between the steps.
  *
  * `sm` to `xl` are handed to Ant Design as its tokens; `xs`, `xxl` and `display` have none and are read
- * from here, fixed until v1. The headings take their sizes from the same list: `h4` and `h5` are both the
- * body size and differ by weight and colour alone. `display` is no heading level but a size, for a hero's
- * or a landing's title, and is not offered beside the others.
+ * from here, fixed until v1. The headings take their sizes from the same list: `h1` the page's title at
+ * `xxl`, about twice the body, then `xl`, `lg`, and `h4` and `h5` at the body and `sm` sizes, set apart by
+ * weight and colour. `display` is no heading level but a size, for a hero's or a landing's title, and is
+ * not offered beside the others.
  */
 export const PHI_FONT_SIZES = {
     xs: 9,
-    sm: 11,
-    base: 13,
-    lg: 15,
-    xl: 21,
+    sm: 13,
+    base: 16,
+    lg: 21,
+    xl: 26,
     xxl: 34,
     display: 55,
     heading1: 34,
-    heading2: 21,
-    heading3: 15,
-    heading4: 13,
+    heading2: 26,
+    heading3: 21,
+    heading4: 16,
     heading5: 13,
 };
 export const PHI_RADII = {
@@ -54,7 +55,7 @@ export const PHI_RADII = {
     xxl: 89,
 };
 export const PHI_CONTROL_HEIGHTS = {
-    sm: 21,
+    sm: 26,
     md: 34,
     lg: 55,
 };

package/types/cms-plugins.d.ts

@@ -114,6 +114,8 @@ export type PhiCmsConfigField = (PhiCmsConfigFieldBase & {
      * Button that is only its icon.
      */
     emptyValue?: "";
+    /** What an empty box shows: what an unset value means, such as `Auto`. Not stored. */
+    placeholder?: string;
 }) | (PhiCmsConfigFieldBase & {
     /**
      * One link, chosen rather than typed.

package/types/dashboard-cards.d.ts

@@ -31,15 +31,48 @@ export declare function createPhiDashboardCardId(moduleId: string, leaf: string)
  * `stat` is a figure, what it is, and where to go for more. `list` is a handful of entries -- what
  * changed, what is waiting -- each a line with an optional time and tone; the Builder's Dashboard is the
  * case that asked for it, because what a structure author looks for first is what is open rather than
- * how many. The form names a renderer and the payload fills it, and a form Core offers is a promise it
- * then keeps: a series card stays open until somebody has a series (DASHBOARD.md section 9).
+ * how many. `series` is a figure over time -- a day's views, clones or downloads for the last month --
+ * drawn as a line per series under its headline; the project-stats Add-on is the case that asked for it
+ * (DASHBOARD.md section 9). The form names a renderer and the payload fills it, and a form Core offers
+ * is a promise it then keeps.
  */
-export type PhiDashboardCardForm = "stat" | "list";
+export type PhiDashboardCardForm = "stat" | "list" | "series";
 /**
  * How many entries a `list` card draws. A card shows little and leads out (DASHBOARD.md section 2); a
  * provider that has more says so in `meta` and lets the card's target show the rest.
  */
 export declare const PHI_DASHBOARD_CARD_LIST_LIMIT = 5;
+/**
+ * How many series a `series` card draws. Two or three lines on a card's width still read as a comparison
+ * -- views and unique visitors -- and a fourth is a chart that wants a page of its own; a provider that has
+ * more puts them on separate cards or on the card's target.
+ */
+export declare const PHI_DASHBOARD_CARD_SERIES_LIMIT = 3;
+/**
+ * A `series` card's figures over time.
+ *
+ * Point by point, oldest first, because that is how a provider counts: one row per day, each with a value
+ * for every series. `labels` names the series in the order each point's `values` states them, so a point
+ * carries exactly one number per label -- a day nothing was counted on is a `0`, not a missing value,
+ * because a gap a line would have to bridge or break is a decision the card should not be making.
+ *
+ * `at` is when the point stands: an ISO date (`2026-11-05`) for a day, or an instant. The card formats it
+ * in the page's locale, a date as the calendar day it names. `unit` is a word for what is counted,
+ * already translated ("views", "downloads"), drawn after the figure in the chart's spoken label.
+ *
+ * The headline is the payload's `value`, as on a `stat` card: a figure the provider states -- a total
+ * over the period, which the points cannot add up to when the provider counts uniques. Absent, the card
+ * shows the latest point of the first series.
+ */
+export type PhiDashboardCardSeries = {
+    labels: string[];
+    points: PhiDashboardCardSeriesPoint[];
+    unit?: string;
+};
+export type PhiDashboardCardSeriesPoint = {
+    at: string;
+    values: number[];
+};
 export type PhiDashboardCardDescriptor = {
     cardId: PhiDashboardCardId;
     form: PhiDashboardCardForm;
@@ -96,7 +129,7 @@ export type PhiDashboardCardDescriptor = {
  */
 export type PhiDashboardCardPayload = {
     cardId: PhiDashboardCardId;
-    /** A `stat` card's figure, drawn under the descriptor's title. */
+    /** A `stat` card's figure, drawn under the descriptor's title, and a `series` card's headline. */
     value?: string;
     /**
      * A `list` card's entries, newest or most pressing first, at most `PHI_DASHBOARD_CARD_LIST_LIMIT` of
@@ -104,6 +137,8 @@ export type PhiDashboardCardPayload = {
      * card formats in the page's locale, or in words where words are what the provider has.
      */
     entries?: PhiTimelineEntry[];
+    /** A `series` card's points, drawn under the headline `value`. */
+    series?: PhiDashboardCardSeries;
     description?: string;
     meta?: string;
     error?: string | null;

package/types/dashboard-cards.js

@@ -18,3 +18,9 @@ export function createPhiDashboardCardId(moduleId, leaf) {
  * provider that has more says so in `meta` and lets the card's target show the rest.
  */
 export const PHI_DASHBOARD_CARD_LIST_LIMIT = 5;
+/**
+ * How many series a `series` card draws. Two or three lines on a card's width still read as a comparison
+ * -- views and unique visitors -- and a fourth is a chart that wants a page of its own; a provider that has
+ * more puts them on separate cards or on the card's target.
+ */
+export const PHI_DASHBOARD_CARD_SERIES_LIMIT = 3;

package/types/site-theme.d.ts

@@ -1,4 +1,5 @@
 import type { PhiShadow } from "./layout-style";
+import type { PhiLinkTarget } from "./references";
 import type { PhiCmsBackgroundWidgetConfig } from "../components/widgets/config/background";
 /**
  * The Theme Root Background (SHELL.md "Root Background and Shell Backdrop Layers"): painted once at
@@ -113,8 +114,15 @@ export type PhiSiteThemeBrandLine = {
  * decides is whether and how the Brand Widget appears; what it shows is decided here.
  */
 export type PhiSiteThemeBrand = {
-    /** Where the Brand Widget leads when it is clicked. The Site root where nothing says otherwise. */
-    homeHref?: string | null;
+    /**
+     * Where the Brand Widget leads when it is clicked. The Site root where nothing says otherwise.
+     *
+     * A link target like every other destination an author picks (`REFERENCES.md`): a Page by reference,
+     * resolved to its address per render, so a Page that is renamed or moved keeps the Brand leading to
+     * it. A Page that no longer resolves leads to the Site root rather than to a 404. The key ends in
+     * `LinkTarget`, which is what the reference collectors go by.
+     */
+    homeLinkTarget?: PhiLinkTarget | null;
     /** The small line above the Wordmark, for Sites whose name needs a word of context. */
     eyebrow?: string | null;
     /** The Logo, one picture per mode. A mode the record says nothing about wears the Theme Set's. */