@multiplatform.one/theme 6.4.2 → 6.6.0

package/src/theme/radiusClass.ts

@@ -0,0 +1,51 @@
+/**
+ * Radius-class declarations (D-09 / LC-60).
+ *
+ * Most parts prove they obey the radius knob by simply going square at
+ * `borderRadius:none`. A few legitimately do not — an ornamental dot has no
+ * arc for the knob to move (R-PILL), and an avatar's circle is the object's
+ * identity rather than a style (R-IDENTITY). Those parts must SAY SO on the
+ * node, because the alternative — a probe that skips anything that looks
+ * round — silently exempts real KNOB-TOTALITY defects (LC-18).
+ *
+ * The declaration is only half the contract: the `radius:none` sweep
+ * validates it against the registry GENERATED from the spec's radius-class
+ * table (`scripts/radius-identity-registry.mjs`), so a class this file cannot
+ * spell, or an R-IDENTITY part the spec never adjudicated, still fails. This
+ * module is the writing end; `docs/theme-propagation-spec.md` is the registry.
+ */
+
+/**
+ * The radius classes whose parts stay round at `borderRadius:none`.
+ *
+ * - `R-PILL` — a pill/circle at every radius value (ornamental dots, badge
+ *   indicators, icon wells). Size still tracks the size knob.
+ * - `R-IDENTITY` — the shape IS the part's identity (Avatar, brand marks).
+ *   Membership is enumerated in the spec table and enforced per part.
+ */
+export type KnobImmuneRadiusClass = "R-PILL" | "R-IDENTITY";
+
+export interface RadiusClassDeclaration {
+  "data-radius-class": KnobImmuneRadiusClass;
+  "data-radius-part": string;
+}
+
+/**
+ * Declare a knob-immune shape so the `radius:none` sweep can license it.
+ *
+ * Spread onto the outermost node of the shape — a declaration covers its own
+ * anatomy, so inner painted parts (an avatar's image/fallback) inherit it.
+ *
+ * @param radiusClass the class the spec's Radius table assigns the part
+ * @param part the part name as the spec writes it (the R-IDENTITY registry
+ *   is matched by this name)
+ *
+ * @example
+ * <Frame {...radiusClassProps("R-IDENTITY", "Avatar")} circular />
+ */
+export function radiusClassProps(
+  radiusClass: KnobImmuneRadiusClass,
+  part: string,
+): RadiusClassDeclaration {
+  return { "data-radius-class": radiusClass, "data-radius-part": part };
+}

package/src/theme/readableColor.spec.ts

@@ -0,0 +1,115 @@
+import { describe, expect, it } from "vitest";
+import { resolveAccentTintedSurface } from "./readableColor";
+import { contrastRatio, normalizeToHex, relativeLuminance } from "./colorRules";
+
+// The stock accent ramp (defaults/accent.ts) as the theme resolves it.
+const lightAccent = [
+  "hsla(250, 50%, 62%, 1)",
+  "hsla(250, 50%, 58%, 1)",
+  "hsla(250, 50%, 54%, 1)",
+  "hsla(250, 50%, 48%, 1)",
+  "hsla(250, 50%, 46%, 1)",
+  "hsla(250, 50%, 44%, 1)",
+  "hsla(250, 50%, 42%, 1)",
+  "hsla(250, 50%, 40%, 1)",
+  "hsla(250, 50%, 38%, 1)",
+  "hsla(250, 50%, 36%, 1)",
+  "hsla(250, 50%, 95%, 1)",
+  "hsla(250, 50%, 98%, 1)",
+];
+const darkAccent = [
+  "hsla(250, 50%, 35%, 1)",
+  "hsla(250, 50%, 38%, 1)",
+  "hsla(250, 50%, 41%, 1)",
+  "hsla(250, 50%, 43%, 1)",
+  "hsla(250, 50%, 46%, 1)",
+  "hsla(250, 50%, 49%, 1)",
+  "hsla(250, 50%, 52%, 1)",
+  "hsla(250, 50%, 54%, 1)",
+  "hsla(250, 50%, 57%, 1)",
+  "hsla(250, 50%, 60%, 1)",
+  "hsla(250, 50%, 90%, 1)",
+  "hsla(250, 50%, 95%, 1)",
+];
+
+const lightPaper = "#ffffff";
+const lightInk = "#242226";
+const darkPaper = "#161519";
+const darkInk = "#f0eff1";
+
+const lum = (raw: string) => relativeLuminance(normalizeToHex(raw)!);
+
+describe("resolveAccentTintedSurface", () => {
+  it("takes the ramp's pale surface end in a light scheme", () => {
+    const tint = resolveAccentTintedSurface({
+      steps: lightAccent,
+      paper: lightPaper,
+      ink: lightInk,
+    });
+    expect(tint).toBe(lightAccent[10]);
+  });
+
+  it("takes the ramp's deep surface end in a dark scheme", () => {
+    const tint = resolveAccentTintedSurface({ steps: darkAccent, paper: darkPaper, ink: darkInk });
+    expect(tint).toBe(darkAccent[0]);
+  });
+
+  // The bug this rule replaced: keying the pick off a SURFACE token let a tint
+  // sub-theme (which re-ramps surfaces) slide the chip a step per tint. Scheme
+  // polarity comes from the paper/ink anchors, which a tint leaves alone.
+  it("does not drift when surrounding surfaces are re-ramped by a tint", () => {
+    const untinted = resolveAccentTintedSurface({
+      steps: lightAccent,
+      paper: lightPaper,
+      ink: lightInk,
+    });
+    for (const tintedPaper of ["#fffce8", "#fff8f8", "#f2fbf5"]) {
+      expect(
+        resolveAccentTintedSurface({ steps: lightAccent, paper: tintedPaper, ink: lightInk }),
+      ).toBe(untinted);
+    }
+  });
+
+  it("stays a SURFACE tier — never the solid an accent CTA takes", () => {
+    // The solid is accentBackground (= the ramp's mid, palette-shape solid).
+    const lightSolid = lightAccent[2];
+    const darkSolid = darkAccent[9];
+    expect(
+      resolveAccentTintedSurface({ steps: lightAccent, paper: lightPaper, ink: lightInk }),
+    ).not.toBe(lightSolid);
+    expect(
+      resolveAccentTintedSurface({ steps: darkAccent, paper: darkPaper, ink: darkInk }),
+    ).not.toBe(darkSolid);
+  });
+
+  it("keeps a luminance-picked label readable on the tint in both schemes", () => {
+    const cases = [
+      { steps: lightAccent, paper: lightPaper, ink: lightInk },
+      { steps: darkAccent, paper: darkPaper, ink: darkInk },
+    ];
+    for (const c of cases) {
+      const tint = resolveAccentTintedSurface(c)!;
+      const best = Math.max(
+        contrastRatio(lum(tint), lum(c.paper)),
+        contrastRatio(lum(tint), lum(c.ink)),
+      );
+      expect(best).toBeGreaterThanOrEqual(4.5);
+    }
+  });
+
+  it("returns undefined when the accent ramp or an anchor is missing", () => {
+    expect(
+      resolveAccentTintedSurface({ steps: [], paper: lightPaper, ink: lightInk }),
+    ).toBeUndefined();
+    expect(
+      resolveAccentTintedSurface({ steps: lightAccent, paper: undefined, ink: lightInk }),
+    ).toBeUndefined();
+    expect(
+      resolveAccentTintedSurface({
+        steps: Array.from({ length: 12 }, () => "var(--nope)"),
+        paper: lightPaper,
+        ink: lightInk,
+      }),
+    ).toBeUndefined();
+  });
+});

package/src/theme/readableColor.ts

@@ -102,41 +102,62 @@ export function useAccentOnSurface(): string {
 }
 
 /**
- * Accent-TINTED surface step — the accent-ramp analogue of a neutral surface
- * tier, for selected/current chips that carry the accent language at surface
- * strength rather than as a solid fill (LC-05: selected state is accent; the
- * ViewSwitcher rider pins segmented-control strength at "tinted", not solid).
+ * Accent SURFACE tier of the accent ramp, mirrored by scheme — the fill for a
+ * selected/current chip that must carry the accent language at SURFACE
+ * strength rather than as a solid (LC-05: selection is accent; the ViewSwitcher
+ * rider pins segmented-control strength at "tinted", not the solid an accent
+ * CTA takes).
  *
- * Picks the accent step whose relative luminance sits closest to the neutral
- * tier it replaces, so the chip stays a surface in BOTH schemes without a
- * per-component light/dark fork: against this repo's stock accent ramp that
- * resolves to a pale violet in light and a deep violet in dark, because the
- * accent ramp flips with the scheme exactly as the neutral ramp does.
+ * The step is a declared ramp POSITION, the same way the neutral ramp declares
+ * its tiers (surface `$color2`, UI background `$color3`-`$color5`, text
+ * `$color11`-`$color12`): the accent ramp's surface end is its palest step in a
+ * light scheme and its deepest in a dark one, so the chip reads as a tinted
+ * surface on either page. Scheme polarity comes from the paper/ink ANCHORS,
+ * never from a surface token — a tint re-ramps surfaces, and keying off one
+ * made this pick drift a step per tint (measured: the chip slid from the pale
+ * accent to the palest accent under a yellow tint).
  *
- * Returns `undefined` when the accent ramp is absent or unparseable — callers
- * keep their neutral default rather than render an unthemed chip.
+ * Returns `undefined` when the accent ramp is absent or unparseable (tint
+ * sub-themes without an accent ramp) — callers keep their neutral default
+ * rather than render an unthemed chip.
  */
-export function useAccentTintedSurface(neutralToken = "$color4"): string | undefined {
+// Ramp positions (1-based) of the accent surface tier per scheme.
+const ACCENT_SURFACE_STEP_LIGHT = 11;
+const ACCENT_SURFACE_STEP_DARK = 1;
+
+export interface ResolveAccentTintedSurfaceInput {
+  /** Accent ramp steps 1..12, as raw color values; holes allowed. */
+  steps: (string | undefined)[];
+  /** Scheme paper anchor (`$color1`). */
+  paper?: string;
+  /** Scheme ink anchor (`$color12`). */
+  ink?: string;
+}
+
+/** Pure resolver behind {@link useAccentTintedSurface} — see its docs. */
+export function resolveAccentTintedSurface({
+  steps,
+  paper,
+  ink,
+}: ResolveAccentTintedSurfaceInput): string | undefined {
+  const paperHex = paper ? normalizeToHex(paper) : null;
+  const inkHex = ink ? normalizeToHex(ink) : null;
+  if (!paperHex || !inkHex) return undefined;
+  const isLight = relativeLuminance(paperHex) > relativeLuminance(inkHex);
+  const step = steps[(isLight ? ACCENT_SURFACE_STEP_LIGHT : ACCENT_SURFACE_STEP_DARK) - 1];
+  if (!step || !normalizeToHex(step)) return undefined;
+  return step;
+}
+
+export function useAccentTintedSurface(): string | undefined {
   const theme = useTamaguiTheme() as unknown as Record<string, { val?: unknown } | undefined>;
-  const neutral = resolveTokenValue(theme, neutralToken);
+  const paper = resolveTokenValue(theme, "color1");
+  const ink = resolveTokenValue(theme, "color12");
   const steps: (string | undefined)[] = [];
   for (let i = 1; i <= 12; i++) steps.push(resolveTokenValue(theme, `accent${i}`));
   // eslint-disable-next-line react-hooks/exhaustive-deps
-  return useMemo(() => {
-    const neutralHex = neutral ? normalizeToHex(neutral) : null;
-    if (!neutralHex) return undefined;
-    const target = relativeLuminance(neutralHex);
-    let best: string | undefined;
-    let bestDelta = Number.POSITIVE_INFINITY;
-    for (const step of steps) {
-      const hex = step ? normalizeToHex(step) : null;
-      if (!step || !hex) continue;
-      const delta = Math.abs(relativeLuminance(hex) - target);
-      if (delta < bestDelta) {
-        bestDelta = delta;
-        best = step;
-      }
-    }
-    return best;
-  }, [neutral, steps.join("|")]);
+  return useMemo(
+    () => resolveAccentTintedSurface({ steps, paper, ink }),
+    [paper, ink, steps.join("|")],
+  );
 }

package/src/theme/resolveKnobs.spec.ts

@@ -18,8 +18,13 @@ import {
 import type { Knobs } from "./knobs";
 import type { KnobProps } from "./recipes";
 import { cornerSmoothClassName } from "./cornerSmoothing";
-import { defaultPreset, boldPreset } from "./presets";
-import { applyDensity, capContainerRadius, resolveKnobs } from "./resolveKnobs";
+import { defaultPreset, boldPreset, heroPreset } from "./presets";
+import {
+  applyDensity,
+  capContainerRadius,
+  resolveKnobs,
+  resolvePageTitleScale,
+} from "./resolveKnobs";
 import {
   normalizeToHex,
   relativeLuminance,
@@ -47,6 +52,7 @@ const expectedKnobPropKeys: (keyof KnobProps)[] = [
   "gapLg",
   "sizeToken",
   "heading",
+  "pageTitle",
   "body",
   "textWeight",
   "transition",
@@ -731,6 +737,44 @@ describe("resolveKnobs", () => {
     });
   });
 
+  // ── pageTitleScale (D-11 hero-H1 dial) ──────────────────────
+
+  describe("pageTitleScale knob", () => {
+    it("defaults to the moderate page-title step ($8 = 32px)", () => {
+      expect(resolveKnobs(defaultKnobs).knobProps.pageTitle).toEqual({ size: "$8" });
+    });
+
+    it('"display" re-opens the hero step ($10 = 64px)', () => {
+      expect(resolveKnobs(knobsWith({ pageTitleScale: "display" })).knobProps.pageTitle).toEqual({
+        size: "$10",
+      });
+    });
+
+    it("an omitted knob still resolves moderate (preset constructions predate the dial)", () => {
+      const { pageTitleScale: _omitted, ...withoutDial } = defaultKnobs;
+      expect(resolveKnobs(withoutDial as Knobs).knobProps.pageTitle).toEqual({ size: "$8" });
+    });
+
+    it("resolvePageTitleScale is the one table both channels read", () => {
+      expect(resolvePageTitleScale("moderate")).toEqual({ size: "$8" });
+      expect(resolvePageTitleScale("display")).toEqual({ size: "$10" });
+    });
+
+    it("product presets ship moderate; `hero` is the only display opt-in", () => {
+      expect(defaultPreset.knobs.pageTitleScale).toBe("moderate");
+      expect(boldPreset.knobs.pageTitleScale).toBe("moderate");
+      expect(heroPreset.knobs.pageTitleScale).toBe("display");
+      expect(resolveKnobs(heroPreset.knobs).knobProps.pageTitle).toEqual({ size: "$10" });
+    });
+
+    it("`hero` differs from the default preset in nothing but the title step", () => {
+      const { pageTitleScale: _hero, ...heroRest } = heroPreset.knobs;
+      const { pageTitleScale: _default, ...defaultRest } = defaultPreset.knobs;
+      expect(heroRest).toEqual(defaultRest);
+      expect(heroPreset.theme).toBe(defaultPreset.theme);
+    });
+  });
+
   // ── animation ─────────────────────────────────────────────
 
   describe("animation knob", () => {

package/types/dates.d.ts

@@ -12,6 +12,11 @@
  *                          current year elided (`year: "auto"`)
  *   - editing surfaces   → compact absolute with the year always shown
  *                          ("Jul 1, 2026") — pickers are precision contexts
+ *   - calendar chrome    → the day/month/time-of-day registers below
+ *                          (weekday and month names, "2 PM" hour ticks,
+ *                          "2:00 PM" times, "Tuesday, March 10" day names)
+ *   - date axis ticks    → compact absolute with `year: "never"`, because
+ *                          the surrounding chrome already states the year
  * No default may emit verbose locale output with seconds.
  */
 export type DateInput = Date | string | number | null | undefined;
@@ -19,9 +24,11 @@ export interface AbsoluteDateFormatOptions {
     /**
      * `"auto"` (default) elides the current year — the display register for
      * tables, feeds, and system events. `"always"` keeps it — the editing
-     * register for picker display values.
+     * register for picker display values. `"never"` drops it — the axis-tick
+     * register, where a wider label would collide with its neighbours and the
+     * period header carries the year.
      */
-    year?: "auto" | "always";
+    year?: "auto" | "always" | "never";
     /** Include the time component ("Aug 9, 3:30 PM"). Default false. */
     withTime?: boolean;
     /** BCP-47 locale forwarded to Intl. Default: system locale. */
@@ -31,6 +38,24 @@ export interface AbsoluteDateFormatOptions {
 }
 /** ISO date-only shape ("YYYY-MM-DD"). */
 export declare const ISO_DATE_ONLY: RegExp;
+/**
+ * Parse a date value onto the LOCAL calendar day it names — the canonical
+ * parse for anything that will be positioned on a day grid (calendar cells,
+ * Gantt bars, date axes) rather than merely formatted.
+ *
+ * A date-only string ("YYYY-MM-DD") is a calendar date carrying no timezone,
+ * which is how Frappe sends `Date` fields. ECMA-262 parses that form as UTC
+ * midnight, so every zone west of UTC reads it as the *previous* local day,
+ * and no zone but UTC lands it on the local midnight that day-grid math tests
+ * for. Those are built from local parts instead.
+ *
+ * Values that carry a time ("YYYY-MM-DD HH:MM:SS", ISO with an offset, epoch
+ * millis) are genuine instants and keep the timezone-aware parse untouched.
+ *
+ * Returns null for empty and unparseable input, and for out-of-range parts
+ * ("2026-13-45") rather than silently rolling them into the next month.
+ */
+export declare function parseCalendarDate(value: DateInput): Date | null;
 /**
  * Compact absolute date — the house register for every absolute date.
  * "Jul 1" / "Jul 1, 2025" (year auto-elided when current), or with
@@ -49,4 +74,59 @@ export declare function formatAbsoluteDateTime(value: DateInput, options?: Omit<
  * feed/social register (LC-12), selected by `timestampStyle: "relative"`.
  */
 export declare function formatRelativeTimestamp(value: DateInput, now?: number): string;
+/** Clock-time shape ("HH:MM" / "HH:MM:SS") — how Frappe `Time` values arrive. */
+export declare const CLOCK_TIME: RegExp;
+export interface TimeOfDayFormatOptions {
+    /** BCP-47 locale forwarded to Intl. Default: system locale. */
+    locale?: string;
+    /** Minutes ride along by default; `false` is the hour-tick register. */
+    minutes?: boolean;
+    /** Pin the 12/24-hour clock. Default: whatever the locale uses. */
+    hour12?: boolean;
+}
+/**
+ * Time-of-day register ("2:00 PM", or "2 PM" with `minutes: false` for
+ * hour ticks) — calendar time grids, Frappe `Time` fields, and
+ * "last updated" chrome. Accepts a clock-time string as well as a date,
+ * and never emits seconds.
+ */
+export declare function formatTimeOfDay(value: DateInput, options?: TimeOfDayFormatOptions): string;
+export interface DayLongFormatOptions {
+    locale?: string;
+    /** Lead with the weekday ("Tuesday, March 10"). Default true. */
+    weekday?: boolean;
+    /** Append the year ("Tuesday, March 10, 2026"). Default false. */
+    year?: boolean;
+}
+/**
+ * Long day register ("Tuesday, March 10") — calendar day headers and the
+ * accessible names that read a date aloud, where the compact absolute
+ * register is too terse to speak.
+ */
+export declare function formatDayLong(value: DateInput, options?: DayLongFormatOptions): string;
+export interface MonthYearFormatOptions {
+    locale?: string;
+    /** `"short"` ("Mar 2026", the tick register) or `"long"` ("March 2026"). */
+    month?: "short" | "long";
+}
+/** Month-year register ("Mar 2026") — period headers and month axis ticks. */
+export declare function formatMonthYear(value: DateInput, options?: MonthYearFormatOptions): string;
+/** Day-of-month register ("10") — the densest date axis tick. */
+export declare function formatDayOfMonth(value: DateInput, options?: {
+    locale?: string;
+}): string;
+export interface WeekdayNamesOptions {
+    locale?: string;
+    /** `"short"` ("Mon"), `"long"` ("Monday") or `"narrow"` ("M"). */
+    style?: "short" | "long" | "narrow";
+    /** Week start, 0 = Sunday (default) — the index base callers rely on. */
+    firstDay?: number;
+}
+/** Weekday names for calendar chrome, in week order from `firstDay`. */
+export declare function getWeekdayNames(options?: WeekdayNamesOptions): string[];
+/** Month names for calendar chrome and picker headers, January first. */
+export declare function getMonthNames(options?: {
+    locale?: string;
+    style?: "long" | "short";
+}): string[];
 //# sourceMappingURL=dates.d.ts.map

package/types/dates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dates.d.ts","sourceRoot":"","sources":["../src/dates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AAElE,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IACzB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,0CAA0C;AAC1C,eAAO,MAAM,aAAa,QAAwB,CAAC;AAyBnD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,SAAS,EAChB,OAAO,GAAE,yBAA8B,GACtC,MAAM,CA0BR;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,SAAS,EAChB,OAAO,GAAE,IAAI,CAAC,yBAAyB,EAAE,UAAU,CAAM,GACxD,MAAM,CAER;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,CAgB1F"}
+{"version":3,"file":"dates.d.ts","sourceRoot":"","sources":["../src/dates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AAElE,MAAM,WAAW,yBAAyB;IACxC;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;IACnC,oEAAoE;IACpE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,0CAA0C;AAC1C,eAAO,MAAM,aAAa,QAAwB,CAAC;AAyBnD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,GAAG,IAAI,CAkB/D;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,SAAS,EAChB,OAAO,GAAE,yBAA8B,GACtC,MAAM,CA0BR;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,SAAS,EAChB,OAAO,GAAE,IAAI,CAAC,yBAAyB,EAAE,UAAU,CAAM,GACxD,MAAM,CAER;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,CAgB1F;AAED,iFAAiF;AACjF,eAAO,MAAM,UAAU,QAAqC,CAAC;AAE7D,MAAM,WAAW,sBAAsB;IACrC,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,mEAAmE;IACnE,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,GAAE,sBAA2B,GAAG,MAAM,CAuB9F;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,kEAAkE;IAClE,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,GAAE,oBAAyB,GAAG,MAAM,CAa1F;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CAC1B;AAED,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,GAAE,sBAA2B,GAAG,MAAM,CAW9F;AAED,iEAAiE;AACjE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,MAAM,CAU5F;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;IACpC,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wEAAwE;AACxE,wBAAgB,eAAe,CAAC,OAAO,GAAE,mBAAwB,GAAG,MAAM,EAAE,CAO3E;AAED,yEAAyE;AACzE,wBAAgB,aAAa,CAC3B,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAAO,GAC1D,MAAM,EAAE,CAIV"}

package/types/devWarn.d.ts

@@ -16,6 +16,41 @@ export type DevWarnDetail = {
     region?: string;
     [key: string]: unknown;
 };
+/**
+ * LC-57 GUARDRAIL-CLEAN-STORIES allowlist entry, declared as a Storybook story
+ * parameter (`parameters.guardrailSpecimen`).
+ *
+ * Catalog stories emit zero `[theme]` guardrail warnings at rest. A story whose
+ * whole purpose is to demonstrate the warned state (a disabled-dial specimen, a
+ * pager boundary case) is allowlisted by declaring itself:
+ *
+ * ```ts
+ * export const Disabled: Story = {
+ *   parameters: {
+ *     guardrailSpecimen: {
+ *       warns: ["bare-disabled"],
+ *       reason: "Demonstrates the disabled dial; Stepper has no disabledReason plumbing.",
+ *     } satisfies GuardrailSpecimenParameter,
+ *   },
+ * };
+ * ```
+ *
+ * Semantics, pinned:
+ * - `warns` is the CLOSED set of codes the story may emit at rest. An emitted
+ *   code outside the set still FAILs the story.
+ * - A declared code that happens not to fire passes — component improvements
+ *   must never break an allowlist entry.
+ * - The declaration NEVER suppresses the console warning — the warn still
+ *   fires; only the warn-harvester tolerates it (explicit, never tacit).
+ * - Harvesters (`p-results/story-hygiene/verify.mjs`) read this parameter off
+ *   the rendered story and fail CLOSED when parameters cannot be read at all.
+ */
+export type GuardrailSpecimenParameter = {
+    /** Warn codes this story may emit at rest — a closed set, not a wildcard. */
+    warns: DevWarnCode[];
+    /** Why the warned state is the story's subject (recorded per LC-57). */
+    reason: string;
+};
 /**
  * Emit a once-per-key console warning in non-production builds.
  */

package/types/devWarn.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"devWarn.d.ts","sourceRoot":"","sources":["../src/devWarn.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"devWarn.d.ts","sourceRoot":"","sources":["../src/devWarn.ts"],"names":[],"mappings":"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"}

package/types/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./theme/index";
 export * from "./dates";
+export * from "./numbers";
 export * from "./devWarn";
 export * from "./keyboardFocusRing";
 export * from "./menuRow";

package/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,qBAAqB,CAAC;AACpC,cAAc,WAAW,CAAC;AAC1B,cAAc,QAAQ,CAAC;AACvB,cAAc,eAAe,CAAC;AAG9B,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,qBAAqB,CAAC;AACpC,cAAc,WAAW,CAAC;AAC1B,cAAc,QAAQ,CAAC;AACvB,cAAc,eAAe,CAAC;AAG9B,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC"}

package/types/numbers.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Canonical number / currency registers (LC-12 render channel, Axiom 9).
+ *
+ * One formatter owns every number the catalog renders — table aggregates,
+ * KPI values, report cells, chart value labels — so the same data class
+ * never speaks in two voices ("15400" in a group header beside "15,400" in
+ * the cell two rows below).
+ *
+ * Content class picks the register:
+ *   - cardinal / aggregate → `formatNumber` (grouped, ≤2 fraction digits)
+ *   - money                → `formatCurrency` (grouped, 2 fraction digits;
+ *                            `fractionDigits: "auto"` elides a whole-value
+ *                            `.00` for summary tiles)
+ *   - rate                 → `formatPercent` (value already carries percent
+ *                            units: 94.2 → "94.2%")
+ *
+ * Not covered (declared exemptions): chart AXIS tick labels, whose
+ * density-driven register is owned by `charts/math.ts#formatAxisTick`;
+ * app-land `useFormatNumber` / `useFormatCurrency` (i18n package), which
+ * bind the active UI language outside the catalog; and machine formats
+ * (export/serialization).
+ */
+export type NumberInput = number | string | null | undefined;
+export interface NumberFormatOptions {
+    /** BCP-47 locale forwarded to Intl. Default: system locale. */
+    locale?: string;
+    /** Pins min and max fraction digits together (fixed-precision columns). */
+    precision?: number;
+    minimumFractionDigits?: number;
+    /** House cap for the cardinal register. Default 2. */
+    maximumFractionDigits?: number;
+    /** Thousands grouping. Default true. */
+    grouping?: boolean;
+}
+export interface CurrencyFormatOptions extends NumberFormatOptions {
+    /** ISO 4217 code, e.g. "USD" — renders through Intl's currency style. */
+    currency?: string;
+    /**
+     * Currency symbol as handed over by Frappe-style adapters. Resolved to an
+     * ISO code when known, otherwise prefixed literally.
+     */
+    symbol?: string;
+    /**
+     * `"always"` (default) pins 2 fraction digits — the money register that
+     * keeps columns aligned. `"auto"` drops them for whole values — the
+     * summary-tile register (KPI cards read "$48,250", not "$48,250.00")
+     * while still showing cents when a value has them.
+     */
+    fractionDigits?: "always" | "auto";
+}
+export type PercentFormatOptions = NumberFormatOptions;
+/**
+ * ISO 4217 code for a currency symbol (or a code passed straight through).
+ * `undefined` when the symbol has no known code — callers prefix it.
+ */
+export declare function resolveCurrencyCode(symbol: string | undefined): string | undefined;
+/**
+ * Cardinal / aggregate register — grouped digits, at most two fraction
+ * digits ("15,400", "5,133.33"). Empty input renders "" and an unparseable
+ * string passes through unchanged (honest passthrough — never invents).
+ */
+export declare function formatNumber(value: NumberInput, options?: NumberFormatOptions): string;
+/**
+ * Money register — grouped digits with two fraction digits, rendered with
+ * the currency's own symbol placement when the code is known ("$15,400.00",
+ * "₹15,400.00") and symbol-prefixed otherwise.
+ */
+export declare function formatCurrency(value: NumberInput, options?: CurrencyFormatOptions): string;
+/**
+ * Rate register — the value already carries percent units (94.2 → "94.2%"),
+ * never a 0..1 ratio; ratios are converted by the caller that owns the unit.
+ */
+export declare function formatPercent(value: NumberInput, options?: PercentFormatOptions): string;
+//# sourceMappingURL=numbers.d.ts.map

package/types/numbers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"numbers.d.ts","sourceRoot":"","sources":["../src/numbers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AAE7D,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,sDAAsD;IACtD,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,wCAAwC;IACxC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,qBAAsB,SAAQ,mBAAmB;IAChE,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;CACpC;AAED,MAAM,MAAM,oBAAoB,GAAG,mBAAmB,CAAC;AAcvD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAIlF;AAyCD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,GAAE,mBAAwB,GAAG,MAAM,CAQ1F;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,GAAE,qBAA0B,GAAG,MAAM,CA8B9F;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,GAAE,oBAAyB,GAAG,MAAM,CAK5F"}

package/types/theme/colorRules.d.ts

@@ -55,7 +55,7 @@ export interface ButtonColorConfig extends ComponentColorConfig {
 }
 export declare const buttonColors: ButtonColorConfig;
 export declare const inputColors: ComponentColorConfig;
-export declare function $color(step: ColorStep): "$color1" | "$color12" | "$color5" | "$color2" | "$color11" | "$color3" | "$color4" | "$color6" | "$color7" | "$color8" | "$color9" | "$color10";
+export declare function $color(step: ColorStep): "$color3" | "$color1" | "$color2" | "$color12" | "$color7" | "$color4" | "$color5" | "$color11" | "$color6" | "$color8" | "$color9" | "$color10";
 export interface SemanticGroup {
     key: string;
     label: string;

package/types/theme/cookies.d.ts

@@ -26,13 +26,27 @@ export declare function splitCookieValue(value: string): string[];
 export declare function joinSplitCookieValues(chunks: string[]): string;
 /**
  * Read the overrides cookie value, handling chunked cookies.
- * Accepts the cookies object from `useCookies()`.
+ *
+ * Accepts BOTH value shapes a cookie jar can deliver:
+ *   - already-parsed OBJECTS — react-cookie's `useCookies()` jar
+ *     (universal-cookie) auto-JSON-parses every cookie value it can (its
+ *     `readCookie` tries `JSON.parse` unless `doNotParse` is set), so a
+ *     single-chunk overrides cookie arrives here as an object, not a string;
+ *   - raw JSON STRINGS — direct `document.cookie` / SSR cookie-header reads
+ *     (`loadPresetOverrides`), and multi-chunk payloads on every path (a
+ *     fragment of a split JSON document does not parse on its own, so even
+ *     universal-cookie leaves those chunks as strings).
+ *
+ * Anything else (numbers, arrays, mixed chunk types, malformed JSON) reads
+ * as no overrides, and every parsed payload is shape-validated before use.
  */
-export declare function readOverridesCookie(cookies: Record<string, string | undefined>): Partial<Knobs>;
+export declare function readOverridesCookie(cookies: Record<string, unknown>): Partial<Knobs>;
 /**
- * Read the preset name from the cookie.
+ * Read the preset name from the cookie. universal-cookie auto-JSON-parses
+ * jar values, so a numeric-looking name would arrive as a number — preset
+ * names are strings by contract, anything else reads as no preset.
  */
-export declare function readPresetCookie(cookies: Record<string, string | undefined>): string | undefined;
+export declare function readPresetCookie(cookies: Record<string, unknown>): string | undefined;
 /**
  * Write the preset name cookie.
  * Returns the cookie key and value for the caller to pass to setCookie.

package/types/theme/cookies.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cookies.d.ts","sourceRoot":"","sources":["../../src/theme/cookies.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAMrC,6CAA6C;AAC7C,eAAO,MAAM,YAAY,cAAc,CAAC;AAExC,sDAAsD;AACtD,eAAO,MAAM,qBAAqB,UAAU,CAAC;AAY7C;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CASxD;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAE9D;AAeD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAiB/F;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,MAAM,GAAG,SAAS,CAEhG;AAMD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAEpF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG;IAC/D,KAAK,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7C,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAgBA;AAMD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAQ5E;AAMD;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,EAAE,CAM7C;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,IAAI,CAQtE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAC9C,OAAO,CAAC,KAAK,CAAC,CAGhB"}
+{"version":3,"file":"cookies.d.ts","sourceRoot":"","sources":["../../src/theme/cookies.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAMrC,6CAA6C;AAC7C,eAAO,MAAM,YAAY,cAAc,CAAC;AAExC,sDAAsD;AACtD,eAAO,MAAM,qBAAqB,UAAU,CAAC;AAY7C;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CASxD;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAE9D;AAyCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAwBpF;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,SAAS,CAGrF;AAMD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAEpF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG;IAC/D,KAAK,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7C,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAgBA;AAMD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAQ5E;AAMD;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,EAAE,CAM7C;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,IAAI,CAQtE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAC9C,OAAO,CAAC,KAAK,CAAC,CAGhB"}