@phis/ui 0.2.0 → 0.3.0

package/theme/phi-published-root-style.d.ts

@@ -6,10 +6,9 @@ export type PhiPublishedRootStyle = CSSProperties & Record<`--${string}`, string
 export type PhiPublishedRootTheme = {
     style: PhiPublishedRootStyle;
 };
-export declare function resolvePhiPublishedRootTheme({ siteTheme, mode, remRootValue, themePresets, }: {
+export declare function resolvePhiPublishedRootTheme({ siteTheme, mode, themePresets, }: {
     siteTheme: PhiSiteTheme;
     /** The resolved projection; the Site record itself may still say `system`. */
     mode: PhiThemeMode;
-    remRootValue: number;
     themePresets?: readonly PhiThemePresetPlugin[];
 }): PhiPublishedRootTheme;

package/theme/phi-published-root-style.js

@@ -2,17 +2,15 @@ import "server-only";
 import { buildPhiCssVars, buildPhiShellCssVars } from "./phi-css-vars";
 import { resolvePhiServerThemeTokens } from "./phi-server-tokens";
 import { PHI_CORE_THEME_PRESET_PLUGINS, } from "./phi-theme-presets";
-export function resolvePhiPublishedRootTheme({ siteTheme, mode, remRootValue, themePresets = PHI_CORE_THEME_PRESET_PLUGINS, }) {
+export function resolvePhiPublishedRootTheme({ siteTheme, mode, themePresets = PHI_CORE_THEME_PRESET_PLUGINS, }) {
     const themeTokens = resolvePhiServerThemeTokens({ siteTheme, mode, themePresets });
     return {
         style: {
-            ...buildPhiCssVars(remRootValue, themeTokens),
+            ...buildPhiCssVars(themeTokens),
             ...buildPhiShellCssVars({
-                rootValue: remRootValue,
                 shellTheme: siteTheme.shell,
                 themeTokens,
             }),
-            "--phi-rem-root-value": String(remRootValue),
         },
     };
 }

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

@@ -10,9 +10,6 @@ import type { PhiControlShapeCorners } from "./phi-control-shape";
  * it, because there is nothing to be independent of.
  */
 export declare function isPhiCoreThemeGround(ground: Pick<PhiThemeGroundBlock, "key">): boolean;
-export declare function isPhiCoreThemePalette(palette: Pick<PhiThemePresetPlugin, "key">): boolean;
-export declare function isPhiCoreThemeStyle(style: Pick<PhiThemeStyleBlock, "key">): boolean;
-export declare function isPhiCoreThemeFonts(fonts: Pick<PhiThemeFontsBlock, "key">): boolean;
 export declare function isPhiCoreThemeSet(set: Pick<PhiThemeSetBlock, "key">): boolean;
 /** The slice of a Site Theme the adoption reads and writes. */
 export type PhiThemeAdoptionSource = {

package/theme/phi-theme-adoption.js

@@ -10,13 +10,13 @@ import { mergePhiThemePalettes, PHI_CORE_THEME_PRESET_PLUGINS } from "./phi-them
 export function isPhiCoreThemeGround(ground) {
     return PHI_CORE_THEME_GROUND_BLOCKS.some((block) => block.key === ground.key);
 }
-export function isPhiCoreThemePalette(palette) {
+function isPhiCoreThemePalette(palette) {
     return PHI_CORE_THEME_PRESET_PLUGINS.some((block) => block.key === palette.key);
 }
-export function isPhiCoreThemeStyle(style) {
+function isPhiCoreThemeStyle(style) {
     return PHI_CORE_THEME_STYLE_BLOCKS.some((block) => block.key === style.key);
 }
-export function isPhiCoreThemeFonts(fonts) {
+function isPhiCoreThemeFonts(fonts) {
     return PHI_CORE_THEME_FONTS_BLOCKS.some((block) => block.key === fonts.key);
 }
 export function isPhiCoreThemeSet(set) {

package/theme/phi-theme-blocks.js

@@ -53,7 +53,7 @@ export const PHI_CORE_THEME_GROUND_BLOCKS = [
                         repeat: "no-repeat",
                     },
                     overlay: null,
-                    effect: null,
+                    filter: null,
                     motion: { mode: "fixed" },
                 },
                 dark: {
@@ -65,7 +65,7 @@ export const PHI_CORE_THEME_GROUND_BLOCKS = [
                         repeat: "no-repeat",
                     },
                     overlay: null,
-                    effect: null,
+                    filter: null,
                     motion: { mode: "fixed" },
                 },
             },
@@ -73,13 +73,13 @@ export const PHI_CORE_THEME_GROUND_BLOCKS = [
                 light: {
                     base: { kind: "color", color: "rgba(255, 255, 255, 0.55)" },
                     overlay: null,
-                    effect: "glass",
+                    filter: "glass",
                     motion: null,
                 },
                 dark: {
                     base: { kind: "color", color: "rgba(9, 14, 26, 0.55)" },
                     overlay: null,
-                    effect: "glass",
+                    filter: "glass",
                     motion: null,
                 },
                 shadow: { header: "soft", sider: "soft", footer: "soft" },

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

@@ -11,7 +11,6 @@ export declare function buildPhiThemeCustomColorPalette(seedColor: string): PhiT
  * generated from its primary colour, the sixth step being the seed itself.
  */
 export declare function resolvePhiThemePaletteCustomColors(palette: PhiThemePalette | null | undefined, mode: PhiThemeMode): PhiThemeCustomColorPalette;
-export declare function resolvePhiThemePresetCustomColors(preset: PhiThemePresetPlugin, mode: PhiThemeMode): PhiThemeCustomColorPalette;
 /** The custom colours a Site renders: the palette it follows with the Site's own palette on top. */
 export declare function resolvePhiPublishedThemeCustomColors(siteTheme: PhiThemeCustomColorSource, mode: PhiThemeMode, presets: readonly PhiThemePresetPlugin[]): PhiThemeCustomColorPalette;
 export {};

package/theme/phi-theme-palette.js

@@ -25,9 +25,6 @@ export function resolvePhiThemePaletteCustomColors(palette, mode) {
         ...(modeConfig?.customColors ?? {}),
     };
 }
-export function resolvePhiThemePresetCustomColors(preset, mode) {
-    return resolvePhiThemePaletteCustomColors(preset.palette, mode);
-}
 /** The custom colours a Site renders: the palette it follows with the Site's own palette on top. */
 export function resolvePhiPublishedThemeCustomColors(siteTheme, mode, presets) {
     const preset = resolvePhiThemePresetPlugin(presets, siteTheme.preset);

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

@@ -36,15 +36,6 @@ export type PhiThemeDerivation = {
     };
 };
 export declare function createPhiThemeDerivation(set: Pick<PhiThemeSetBlock, "key" | "version" | "title">): PhiThemeDerivation;
-/**
- * The derivation a Theme states, or the core Set for a Theme that states none.
- *
- * A Theme from before the Sets has no record until its first draft writes one, and that draft writes
- * the core Set; naming the core Set here says the same thing ahead of time.
- */
-export declare function resolvePhiThemeDerivation(theme: {
-    derivedFrom?: unknown;
-} | null | undefined): PhiThemeDerivation;
 export declare function ensurePhiThemeDerivation<T extends {
     derivedFrom?: PhiThemeDerivation | null;
 }>(theme: T): T;

package/theme/phi-theme-selection.js

@@ -1,3 +1,4 @@
+import { isPhiRecord } from "../helpers/is-record";
 import { PHI_CORE_THEME_SET_KEY, PHI_CORE_THEME_SETS } from "./phi-theme-blocks";
 import { PHI_DEFAULT_THEME_PRESET_KEY } from "./phi-theme-presets";
 const PHI_SITE_THEME_SELECTION_PREFIX = "site:";
@@ -32,11 +33,11 @@ export function createPhiThemeDerivation(set) {
     return { set: { key: set.key, version: set.version, title: set.title } };
 }
 function readPhiThemeDerivation(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
+    if (!isPhiRecord(value)) {
         return null;
     }
     const set = value.set;
-    if (!set || typeof set !== "object" || Array.isArray(set)) {
+    if (!isPhiRecord(set)) {
         return null;
     }
     const { key, version, title } = set;
@@ -53,7 +54,7 @@ function readPhiThemeDerivation(value) {
  * A Theme from before the Sets has no record until its first draft writes one, and that draft writes
  * the core Set; naming the core Set here says the same thing ahead of time.
  */
-export function resolvePhiThemeDerivation(theme) {
+function resolvePhiThemeDerivation(theme) {
     const stated = readPhiThemeDerivation(theme?.derivedFrom);
     if (stated) {
         return stated;

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", "colorSuccessBorderHover", "colorSuccessText", "colorWarning", "colorWarningBg", "colorWarningBgHover", "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", "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", "lineHeightLG", "lineHeightHeading1", "lineHeightHeading2", "lineHeightHeading3", "lineHeightHeading4", "lineHeightHeading5", "motionDurationMid", "motionDurationSlow", "motionEaseInOut", "motionEaseOut"];
 /**
  * The names this house adds to Ant Design's set.
  *
@@ -44,21 +44,6 @@ export type PhiThemeTokenKey = (typeof PHI_THEME_TOKEN_KEYS)[number];
  * is cut from, so both sides read one list rather than two that drift.
  */
 export type PhiThemeTokens = Pick<GlobalToken, PhiThemeTokenKey>;
-/**
- * The colours a palette seeds, shared by both modes.
- *
- * Ant Design derives the rest from these six. Everything else a palette wants to say outright is an
- * override, which is held to the vocabulary above -- the difference matters, because a seed is an
- * input to the derivation and an override is a result of it stated by hand.
- */
-export declare const PHI_THEME_PALETTE_SEED_KEYS: readonly ["colorPrimary", "colorInfo", "colorSuccess", "colorWarning", "colorError", "colorLink"];
-/**
- * What `style.token` may hold beyond the vocabulary: Ant Design's own seed flags.
- *
- * `wireframe` is not a token with a value on the page, it is the switch that decides how Ant Design
- * derives the rest. The Theme workspace writes it, so a Site has it stored, so it is said here.
- */
-export declare const PHI_THEME_STYLE_SEED_KEYS: readonly ["wireframe"];
 /**
  * A stored Theme, held to the vocabulary before anything is derived from it.
  *

package/theme/phi-theme-tokens.js

@@ -69,11 +69,13 @@ export const PHI_THEME_TOKEN_KEYS = [
     "colorSuccess",
     "colorSuccessBg",
     "colorSuccessBgHover",
+    "colorSuccessBorder",
     "colorSuccessBorderHover",
     "colorSuccessText",
     "colorWarning",
     "colorWarningBg",
     "colorWarningBgHover",
+    "colorWarningBorder",
     "colorWarningBorderHover",
     "colorWarningText",
     "colorError",
@@ -118,6 +120,7 @@ export const PHI_THEME_TOKEN_KEYS = [
     "boxShadowTertiary",
     // The height a Control stands at.
     "controlHeight",
+    "controlHeightXS",
     "controlHeightSM",
     "controlHeightLG",
     // Type.
@@ -169,7 +172,7 @@ export const PHI_THEME_OWN_TOKEN_KEYS = [
  * override, which is held to the vocabulary above -- the difference matters, because a seed is an
  * input to the derivation and an override is a result of it stated by hand.
  */
-export const PHI_THEME_PALETTE_SEED_KEYS = [
+const PHI_THEME_PALETTE_SEED_KEYS = [
     "colorPrimary",
     "colorInfo",
     "colorSuccess",
@@ -183,7 +186,7 @@ export const PHI_THEME_PALETTE_SEED_KEYS = [
  * `wireframe` is not a token with a value on the page, it is the switch that decides how Ant Design
  * derives the rest. The Theme workspace writes it, so a Site has it stored, so it is said here.
  */
-export const PHI_THEME_STYLE_SEED_KEYS = [
+const PHI_THEME_STYLE_SEED_KEYS = [
     "wireframe",
 ];
 function readPhiThemeVocabularyViolations(record, allowed, source, slot) {

package/theme/phi-theme.d.ts

@@ -54,7 +54,5 @@ export type PhiThemeTokens = {
     [key: string]: unknown;
 };
 export type PhiComponentTokens = Record<string, Record<string, unknown>>;
-export declare const PHI_DEFAULT_ANTD_FONT_SIZE = 12;
-export declare function buildPhiThemeTokens(options?: PhiThemeTokenOptions): PhiThemeTokens;
 export declare function buildPhiThemeStructuralTokens(options?: PhiThemeTokenOptions): Record<string, unknown>;
 export declare function buildPhiComponentTokens(options?: PhiComponentTokenOptions): PhiComponentTokens;

package/theme/phi-theme.js

@@ -1,7 +1,13 @@
-import { PHI_CONTROL_HEIGHTS, PHI_LAYOUT, PHI_RADII, PHI_PADDING as PHI_PADDING_VALUES, PHI_MARGIN as PHI_MARGIN_VALUES, } from "./phi-tokens";
-import { PHI_CONTROL, PHI_MARGIN, PHI_SPACE } from "./antd-css-var-contract";
-export const PHI_DEFAULT_ANTD_FONT_SIZE = 12;
-export function buildPhiThemeTokens(options = {}) {
+import { PHI_CONTROL_HEIGHTS, PHI_LAYOUT, PHI_FONT_SIZES, PHI_RADII, PHI_PADDING as PHI_PADDING_VALUES, } from "./phi-tokens";
+import { PHI_CONTROL, PHI_SPACE } from "./antd-css-var-contract";
+/*
+ * A line height for a size, by Ant Design's own rule: the size and 8 px. Set beside each size because
+ * Ant Design derives line heights from its sizes, not from ones it is handed -- 13 keeps its 21.
+ */
+function lineHeightFor(size) {
+    return (size + 8) / size;
+}
+function buildPhiThemeTokens(options = {}) {
     return {
         paddingXXS: PHI_PADDING_VALUES.xxs,
         paddingXS: PHI_PADDING_VALUES.xs,
@@ -11,21 +17,38 @@ export function buildPhiThemeTokens(options = {}) {
         paddingLG: PHI_PADDING_VALUES.lg,
         paddingXL: PHI_PADDING_VALUES.xl,
         paddingXXL: PHI_PADDING_VALUES.xxl,
-        marginXXS: PHI_MARGIN_VALUES.xxs,
-        marginXS: PHI_MARGIN_VALUES.xs,
-        marginSM: PHI_MARGIN_VALUES.sm,
-        margin: PHI_MARGIN_VALUES.base,
-        marginMD: PHI_MARGIN_VALUES.md,
-        marginLG: PHI_MARGIN_VALUES.lg,
-        marginXL: PHI_MARGIN_VALUES.xl,
-        marginXXL: PHI_MARGIN_VALUES.xxl,
+        // Ant Design's second family, on the same scale: its own components read it (phi-tokens.ts).
+        marginXXS: PHI_PADDING_VALUES.xxs,
+        marginXS: PHI_PADDING_VALUES.xs,
+        marginSM: PHI_PADDING_VALUES.sm,
+        margin: PHI_PADDING_VALUES.base,
+        marginMD: PHI_PADDING_VALUES.md,
+        marginLG: PHI_PADDING_VALUES.lg,
+        marginXL: PHI_PADDING_VALUES.xl,
+        marginXXL: PHI_PADDING_VALUES.xxl,
         borderRadiusSM: PHI_RADII.xs,
         borderRadius: PHI_RADII.sm,
         borderRadiusLG: PHI_RADII.base,
         controlHeightSM: PHI_CONTROL_HEIGHTS.sm,
         controlHeight: PHI_CONTROL_HEIGHTS.md,
         controlHeightLG: PHI_CONTROL_HEIGHTS.lg,
-        fontSize: PHI_DEFAULT_ANTD_FONT_SIZE,
+        fontSize: PHI_FONT_SIZES.base,
+        fontSizeSM: PHI_FONT_SIZES.sm,
+        fontSizeLG: PHI_FONT_SIZES.lg,
+        fontSizeXL: PHI_FONT_SIZES.xl,
+        fontSizeHeading1: PHI_FONT_SIZES.heading1,
+        fontSizeHeading2: PHI_FONT_SIZES.heading2,
+        fontSizeHeading3: PHI_FONT_SIZES.heading3,
+        fontSizeHeading4: PHI_FONT_SIZES.heading4,
+        fontSizeHeading5: PHI_FONT_SIZES.heading5,
+        lineHeight: lineHeightFor(PHI_FONT_SIZES.base),
+        lineHeightSM: lineHeightFor(PHI_FONT_SIZES.sm),
+        lineHeightLG: lineHeightFor(PHI_FONT_SIZES.lg),
+        lineHeightHeading1: lineHeightFor(PHI_FONT_SIZES.heading1),
+        lineHeightHeading2: lineHeightFor(PHI_FONT_SIZES.heading2),
+        lineHeightHeading3: lineHeightFor(PHI_FONT_SIZES.heading3),
+        lineHeightHeading4: lineHeightFor(PHI_FONT_SIZES.heading4),
+        lineHeightHeading5: lineHeightFor(PHI_FONT_SIZES.heading5),
         fontFamily: options.fontFamily,
         colorPrimary: options.colorPrimary ?? "#E05A2A",
         colorLink: "#7088BA",
@@ -54,8 +77,8 @@ export function buildPhiComponentTokens(options = {}) {
         Menu: {
             itemHeight: PHI_CONTROL.md,
             itemPaddingInline: PHI_SPACE.base,
-            itemMarginBlock: PHI_MARGIN.sm,
-            itemMarginInline: PHI_MARGIN.sm,
+            itemMarginBlock: PHI_SPACE.sm,
+            itemMarginInline: PHI_SPACE.sm,
             ...options.menu,
         },
         ...options.overrides,

package/theme/phi-tokens.d.ts

@@ -1,3 +1,11 @@
+/**
+ * The one spacing scale: the distance inside a frame and the distance between two things alike.
+ *
+ * Ant Design has two families for it, `padding*` and `margin*`, and its own components read both. Here
+ * they are seeded from this one sequence and nothing sets them apart -- no Theme field, no stored Theme,
+ * no block -- so a second scale only meant a second way to write the same distance, and the two were
+ * mixed: a gap written on one scale was not recognized by the field that offered the other.
+ */
 export declare const PHI_PADDING: {
     readonly xxs: 3;
     readonly xs: 8;
@@ -6,17 +14,34 @@ export declare const PHI_PADDING: {
     readonly md: 34;
     readonly lg: 55;
     readonly xl: 89;
-    readonly xxl: 155;
+    readonly xxl: 144;
 };
-export declare const PHI_MARGIN: {
-    readonly xxs: 3;
-    readonly xs: 8;
-    readonly sm: 13;
-    readonly base: 21;
-    readonly md: 34;
-    readonly lg: 55;
-    readonly xl: 89;
-    readonly xxl: 155;
+/**
+ * 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.
+ *
+ * `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.
+ */
+export declare const PHI_FONT_SIZES: {
+    readonly xs: 9;
+    readonly sm: 11;
+    readonly base: 13;
+    readonly lg: 15;
+    readonly xl: 21;
+    readonly xxl: 34;
+    readonly display: 55;
+    readonly heading1: 34;
+    readonly heading2: 21;
+    readonly heading3: 15;
+    readonly heading4: 13;
+    readonly heading5: 13;
 };
 export declare const PHI_RADII: {
     readonly xxs: 3;
@@ -57,5 +82,6 @@ export declare const PHI_LAYOUT: {
     readonly contentMaxNarrow: 377;
     readonly contentMax: 610;
     readonly contentMaxWide: 987;
+    readonly readingMax: 754;
     readonly heroHeight: 377;
 };

package/theme/phi-tokens.js

@@ -1,3 +1,11 @@
+/**
+ * The one spacing scale: the distance inside a frame and the distance between two things alike.
+ *
+ * Ant Design has two families for it, `padding*` and `margin*`, and its own components read both. Here
+ * they are seeded from this one sequence and nothing sets them apart -- no Theme field, no stored Theme,
+ * no block -- so a second scale only meant a second way to write the same distance, and the two were
+ * mixed: a gap written on one scale was not recognized by the field that offered the other.
+ */
 export const PHI_PADDING = {
     xxs: 3,
     xs: 8,
@@ -6,9 +14,35 @@ export const PHI_PADDING = {
     md: 34,
     lg: 55,
     xl: 89,
-    xxl: 155,
+    xxl: 144,
+};
+/**
+ * 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.
+ *
+ * `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.
+ */
+export const PHI_FONT_SIZES = {
+    xs: 9,
+    sm: 11,
+    base: 13,
+    lg: 15,
+    xl: 21,
+    xxl: 34,
+    display: 55,
+    heading1: 34,
+    heading2: 21,
+    heading3: 15,
+    heading4: 13,
+    heading5: 13,
 };
-export const PHI_MARGIN = PHI_PADDING;
 export const PHI_RADII = {
     xxs: 3,
     xs: 5,
@@ -84,5 +118,13 @@ export const PHI_LAYOUT = {
     contentMaxNarrow: 377,
     contentMax: 610,
     contentMaxWide: 987,
+    /*
+     * How wide a column of prose is allowed to get: an article, an entry and what stands around it.
+     *
+     * Off the three steps above on purpose, because a text is measured in characters and not in Controls.
+     * Twice `contentMaxNarrow`: with a frame's padding taken off it leaves a line of roughly seventy
+     * characters at body size, which is where reading stops being comfortable. A maximum, like the others.
+     */
+    readingMax: 754,
     heroHeight: 377,
 };

package/types/builder.d.ts

@@ -1,3 +1,4 @@
+import type { PhiSurfacePolicy } from "./surface";
 import type { PhiCmsBuilderWidgetPlugin, PhiCmsConfigField, PhiCmsLayoutPluginDefinition, PhiCmsLayoutPlugin, PhiCmsLayoutSlotDefinition, PhiCmsWidgetContentBinding, PhiCmsWidgetPlugin, PhiCmsWidgetPluginDefinition, PhiCmsWidgetSignalSubcontrolCollection } from "./cms-plugins";
 import type { PhiRenderableBlockAnchor } from "./renderable-block";
 import type { PhiCmsRegionOwnership } from "../helpers/cms-region-keys";
@@ -29,6 +30,9 @@ export type PhiBuilderContainerMeta = PhiBuilderPluginMetaBase & {
     slotMode?: "named" | "sequential" | "single";
     allowReorder?: true;
     defaultAnchor?: PhiRenderableBlockAnchor | null;
+    /** What a new node is written with, where the Layout says more than its `defaultConfig`. */
+    creationConfig?: Record<string, unknown> | null;
+    translatesOwnText?: true;
     fields: readonly PhiCmsConfigField[];
 };
 export type PhiBuilderWidgetMeta = PhiBuilderPluginMetaBase & {
@@ -39,6 +43,10 @@ export type PhiBuilderWidgetMeta = PhiBuilderPluginMetaBase & {
     contentBinding?: PhiCmsWidgetContentBinding | null;
     translatesOwnText?: true;
     signalSubcontrols?: readonly PhiCmsWidgetSignalSubcontrolCollection[];
+    /** Who draws the Widget's Surface; the Inspector offers no Surface section under `none`. */
+    surface?: PhiSurfacePolicy | null;
+    /** What a new placement is written with, where the Widget says more than its `defaultConfig`. */
+    creationConfig?: Record<string, unknown> | null;
     fields: readonly PhiCmsConfigField[];
 };
 export type PhiBuilderPluginMeta = PhiBuilderContainerMeta | PhiBuilderWidgetMeta;

package/types/calendar.d.ts

@@ -139,6 +139,11 @@ export type PhiCalendarAdapterDatePickerProps = {
     rangePlaceholders?: readonly [string, string];
     controlSize?: PhiControlSize;
     variant?: PhiControlVariant;
+    /**
+     * The id of the element that names the picker, for its input's `aria-labelledby`. The label is drawn
+     * by the Control around the picker, so the adapter cannot know it otherwise.
+     */
+    ariaLabelledBy?: string;
     onChange?: (selection: PhiTemporalSelection) => void;
 };
 export type PhiCalendarAdapterCalendarProps = {

package/types/calendar.js

@@ -1,3 +1,4 @@
+import { isPhiRecord } from "../helpers/is-record";
 export function isPhiCalendarAdapterKey(value) {
     return typeof value === "string" && /^@[^/]+\/[^/]+(?:\/modules\/[^/]+)?\/calendars\/[^/]+$/.test(value);
 }
@@ -9,13 +10,13 @@ export function isPhiIsoTime(value) {
         /^(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d{1,9})?)?$/.test(value);
 }
 export function isPhiCalendarDate(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
+    if (!isPhiRecord(value))
         return false;
     const candidate = value;
     return typeof candidate.calendar === "string" && candidate.calendar.length > 0 && isPhiIsoDate(candidate.isoDate);
 }
 export function isPhiCalendarDisabledDateRule(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
+    if (!isPhiRecord(value))
         return false;
     const candidate = value;
     if (candidate.kind === "before" || candidate.kind === "after" || candidate.kind === "date") {
@@ -28,7 +29,7 @@ export function isPhiCalendarDisabledDateRule(value) {
         candidate.weekdays.every((weekday) => Number.isInteger(weekday) && weekday >= 0 && weekday <= 6);
 }
 export function isPhiTemporalSelection(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
+    if (!isPhiRecord(value))
         return false;
     const candidate = value;
     if (candidate.mode === "single")
@@ -40,7 +41,7 @@ export function isPhiTemporalSelection(value) {
     return candidate.mode === "multiple" && Array.isArray(candidate.values) && candidate.values.every(isPhiTemporalValue);
 }
 export function isPhiCalendarViewport(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
+    if (!isPhiRecord(value))
         return false;
     const candidate = value;
     return typeof candidate.calendar === "string" && candidate.calendar.length > 0 &&
@@ -50,7 +51,7 @@ export function isPhiCalendarViewport(value) {
         isPhiIsoDate(candidate.isoStart) && isPhiIsoDate(candidate.isoEndExclusive);
 }
 export function isPhiCalendarEvent(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
+    if (!isPhiRecord(value))
         return false;
     const candidate = value;
     if (typeof candidate.id !== "string" || !candidate.id ||
@@ -66,7 +67,7 @@ export function isPhiCalendarEvent(value) {
         typeof end.instant === "string" && !Number.isNaN(Date.parse(end.instant));
 }
 export function isPhiTemporalValue(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
+    if (!isPhiRecord(value))
         return false;
     const candidate = value;
     if (candidate.kind === "date")

package/types/cms-border-config.js

@@ -1,3 +1,4 @@
+import { isPhiRecord } from "../helpers/is-record";
 import { readCssSize, readNumber, readString, } from "../components/widgets/config/parser-primitives";
 /*
  * The border reader, apart from the CMS config it belongs to. The Overlay container reads an Overlay's
@@ -5,7 +6,7 @@ import { readCssSize, readNumber, readString, } from "../components/widgets/conf
  * something every page should download for it.
  */
 export function readPhiCmsBorderWidgetConfig(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
+    if (!isPhiRecord(value)) {
         const border = readString(value);
         if (border == null) {
             return undefined;