@multiplatform.one/theme 6.4.0 → 6.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiplatform.one/theme",
-  "version": "6.4.0",
+  "version": "6.4.1",
   "description": "Tamagui theme system for multiplatform.one",
   "keywords": [
     "multiplatform",
@@ -53,8 +53,8 @@
     "@tamagui/toast": "2.0.0-rc.41",
     "@tamagui/web": "2.0.0-rc.41",
     "react-cookie": "^8.1.2",
-    "@multiplatform.one/store": "6.4.0",
-    "@multiplatform.one/platform": "6.4.0"
+    "@multiplatform.one/platform": "6.4.1",
+    "@multiplatform.one/store": "6.4.1"
   },
   "devDependencies": {
     "@tamagui/animations-css": "2.0.0-rc.41",
@@ -69,8 +69,8 @@
     "tamagui": "2.0.0-rc.41",
     "typescript": "~5.9.3",
     "vitest": "^4.1.5",
-    "@multiplatform.one/config": "6.4.0",
-    "@multiplatform.one/test-utils": "6.4.0"
+    "@multiplatform.one/test-utils": "6.4.1",
+    "@multiplatform.one/config": "6.4.1"
   },
   "peerDependencies": {
     "@tamagui/animations-css": "^2.0.0-rc",

package/src/dates.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.
  */
 
@@ -21,9 +26,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. */
@@ -78,7 +85,7 @@ export function formatAbsoluteDate(
     month: "short",
     day: "numeric",
   };
-  if (year === "always" || displayYear !== referenceYear) {
+  if (year === "always" || (year !== "never" && displayYear !== referenceYear)) {
     intlOptions.year = "numeric";
   }
   if (withTime) {
@@ -128,3 +135,134 @@ export function formatRelativeTimestamp(value: DateInput, now: number = Date.now
   const yr = Math.floor(day / 365);
   return `${Math.max(1, yr)}y ago`;
 }
+
+/** Clock-time shape ("HH:MM" / "HH:MM:SS") — how Frappe `Time` values arrive. */
+export const CLOCK_TIME = /^(\d{1,2}):(\d{2})(?::(\d{2}))?$/;
+
+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 function formatTimeOfDay(value: DateInput, options: TimeOfDayFormatOptions = {}): string {
+  const { locale, minutes = true, hour12 } = options;
+  let date: Date | null = null;
+  if (typeof value === "string") {
+    const clock = value.trim().match(CLOCK_TIME);
+    if (clock) {
+      const parsed = new Date(2000, 0, 1, Number(clock[1]), Number(clock[2]));
+      if (!Number.isNaN(parsed.getTime())) date = parsed;
+    }
+  }
+  if (!date) {
+    const coerced = coerceDateInput(value);
+    if (!coerced) return typeof value === "string" ? value : "";
+    date = coerced.date;
+  }
+  const intlOptions: Intl.DateTimeFormatOptions = { hour: "numeric" };
+  if (minutes) intlOptions.minute = "2-digit";
+  if (hour12 !== undefined) intlOptions.hour12 = hour12;
+  try {
+    return date.toLocaleTimeString(locale, intlOptions);
+  } catch {
+    return typeof value === "string" ? value : "";
+  }
+}
+
+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 function formatDayLong(value: DateInput, options: DayLongFormatOptions = {}): string {
+  const coerced = coerceDateInput(value);
+  if (!coerced) return typeof value === "string" ? value : "";
+  const { locale, weekday = true, year = false } = options;
+  const intlOptions: Intl.DateTimeFormatOptions = { month: "long", day: "numeric" };
+  if (weekday) intlOptions.weekday = "long";
+  if (year) intlOptions.year = "numeric";
+  if (coerced.dateOnly) intlOptions.timeZone = "UTC";
+  try {
+    return coerced.date.toLocaleDateString(locale, intlOptions);
+  } catch {
+    return typeof value === "string" ? value : "";
+  }
+}
+
+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 function formatMonthYear(value: DateInput, options: MonthYearFormatOptions = {}): string {
+  const coerced = coerceDateInput(value);
+  if (!coerced) return typeof value === "string" ? value : "";
+  const { locale, month = "short" } = options;
+  const intlOptions: Intl.DateTimeFormatOptions = { month, year: "numeric" };
+  if (coerced.dateOnly) intlOptions.timeZone = "UTC";
+  try {
+    return coerced.date.toLocaleDateString(locale, intlOptions);
+  } catch {
+    return typeof value === "string" ? value : "";
+  }
+}
+
+/** Day-of-month register ("10") — the densest date axis tick. */
+export function formatDayOfMonth(value: DateInput, options: { locale?: string } = {}): string {
+  const coerced = coerceDateInput(value);
+  if (!coerced) return typeof value === "string" ? value : "";
+  const intlOptions: Intl.DateTimeFormatOptions = { day: "numeric" };
+  if (coerced.dateOnly) intlOptions.timeZone = "UTC";
+  try {
+    return coerced.date.toLocaleDateString(options.locale, intlOptions);
+  } catch {
+    return String(coerced.date.getDate());
+  }
+}
+
+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 function getWeekdayNames(options: WeekdayNamesOptions = {}): string[] {
+  const { locale, style = "short", firstDay = 0 } = options;
+  const formatter = new Intl.DateTimeFormat(locale, { weekday: style, timeZone: "UTC" });
+  // 2004-01-04 is a Sunday, so day-of-week and offset line up.
+  return Array.from({ length: 7 }, (_, i) =>
+    formatter.format(new Date(Date.UTC(2004, 0, 4 + ((firstDay + i) % 7)))),
+  );
+}
+
+/** Month names for calendar chrome and picker headers, January first. */
+export function getMonthNames(
+  options: { locale?: string; style?: "long" | "short" } = {},
+): string[] {
+  const { locale, style = "long" } = options;
+  const formatter = new Intl.DateTimeFormat(locale, { month: style, timeZone: "UTC" });
+  return Array.from({ length: 12 }, (_, i) => formatter.format(new Date(Date.UTC(2000, i, 1))));
+}

package/src/index.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/src/numbers.ts

@@ -0,0 +1,161 @@
+/**
+ * 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;
+
+/** Frappe adapters hand over a symbol; Intl's currency style wants a code. */
+const CURRENCY_SYMBOL_TO_CODE: Record<string, string> = {
+  $: "USD",
+  "€": "EUR",
+  "£": "GBP",
+  "¥": "JPY",
+  "₹": "INR",
+  "₩": "KRW",
+};
+
+/**
+ * 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 function resolveCurrencyCode(symbol: string | undefined): string | undefined {
+  if (!symbol) return undefined;
+  if (/^[A-Za-z]{3}$/.test(symbol)) return symbol.toUpperCase();
+  return CURRENCY_SYMBOL_TO_CODE[symbol];
+}
+
+interface CoercedNumber {
+  num: number;
+}
+
+function coerceNumberInput(value: NumberInput): CoercedNumber | null {
+  if (value == null || value === "") return null;
+  if (typeof value === "number") return Number.isFinite(value) ? { num: value } : null;
+  const num = Number(value);
+  return Number.isFinite(num) ? { num } : null;
+}
+
+function resolveDigits(options: NumberFormatOptions): Pick<
+  Intl.NumberFormatOptions,
+  "minimumFractionDigits" | "maximumFractionDigits"
+> {
+  const { precision, minimumFractionDigits, maximumFractionDigits } = options;
+  if (precision != null) {
+    return { minimumFractionDigits: precision, maximumFractionDigits: precision };
+  }
+  const max = maximumFractionDigits ?? 2;
+  const min = minimumFractionDigits ?? 0;
+  return { minimumFractionDigits: min, maximumFractionDigits: Math.max(min, max) };
+}
+
+function formatWith(num: number, options: Intl.NumberFormatOptions, locale?: string): string {
+  try {
+    return new Intl.NumberFormat(locale, options).format(num);
+  } catch {
+    return String(num);
+  }
+}
+
+/**
+ * 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 function formatNumber(value: NumberInput, options: NumberFormatOptions = {}): string {
+  const coerced = coerceNumberInput(value);
+  if (!coerced) return typeof value === "string" ? value : "";
+  return formatWith(
+    coerced.num,
+    { ...resolveDigits(options), useGrouping: options.grouping ?? true },
+    options.locale,
+  );
+}
+
+/**
+ * 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 function formatCurrency(value: NumberInput, options: CurrencyFormatOptions = {}): string {
+  const coerced = coerceNumberInput(value);
+  if (!coerced) return typeof value === "string" ? value : "";
+  const { currency, symbol, fractionDigits = "always", locale, grouping } = options;
+  const hasExplicitDigits =
+    options.precision != null ||
+    options.minimumFractionDigits != null ||
+    options.maximumFractionDigits != null;
+  const wholeValue = Number.isInteger(coerced.num);
+  const digits = hasExplicitDigits
+    ? resolveDigits(options)
+    : fractionDigits === "auto" && wholeValue
+      ? { minimumFractionDigits: 0, maximumFractionDigits: 0 }
+      : { minimumFractionDigits: 2, maximumFractionDigits: 2 };
+  const code = currency ?? resolveCurrencyCode(symbol);
+  const useGrouping = grouping ?? true;
+  if (code) {
+    return formatWith(coerced.num, { ...digits, useGrouping, style: "currency", currency: code }, locale);
+  }
+  const amount = formatWith(coerced.num, { ...digits, useGrouping }, locale);
+  return symbol ? `${symbol}${amount}` : amount;
+}
+
+/**
+ * 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 function formatPercent(value: NumberInput, options: PercentFormatOptions = {}): string {
+  const formatted = formatNumber(value, options);
+  if (formatted === "") return "";
+  const coerced = coerceNumberInput(value);
+  return coerced ? `${formatted}%` : formatted;
+}

package/src/theme/readableColor.ts

@@ -43,15 +43,16 @@ function resolveTokenValue(
 }
 
 /**
- * Readable text/glyph color to sit ON `fillToken` (e.g. "$accentBackground",
- * "$color8"): the scheme's paper (`$color1`) or ink (`$color12`) anchor,
- * whichever contrasts more on the resolved fill, returned as a concrete value
- * so no nested sub-theme can flip it. Returns `undefined` when any color fails
- * to resolve/parse — callers keep their own default in that case.
+ * Readable text/glyph color to sit ON `fill` (a token like "$accentBackground"
+ * / "$color8", or an already-resolved color value — e.g. the step returned by
+ * `useAccentTintedSurface`): the scheme's paper (`$color1`) or ink (`$color12`)
+ * anchor, whichever contrasts more on the resolved fill, returned as a concrete
+ * value so no nested sub-theme can flip it. Returns `undefined` when any color
+ * fails to resolve/parse — callers keep their own default in that case.
  */
-export function useReadableTextOn(fillToken: string): string | undefined {
+export function useReadableTextOn(fill_: string | undefined): string | undefined {
   const theme = useTamaguiTheme() as unknown as Record<string, { val?: unknown } | undefined>;
-  const fill = resolveTokenValue(theme, fillToken);
+  const fill = fill_?.startsWith("$") ? resolveTokenValue(theme, fill_) : fill_;
   const paper = resolveTokenValue(theme, "color1");
   const ink = resolveTokenValue(theme, "color12");
   return useMemo(() => {
@@ -99,3 +100,43 @@ export function useAccentOnSurface(): string {
     return best ?? ink;
   }, [c1, c2, ink, steps.join("|")]);
 }
+
+/**
+ * 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).
+ *
+ * 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.
+ *
+ * Returns `undefined` when the accent ramp is absent or unparseable — callers
+ * keep their neutral default rather than render an unthemed chip.
+ */
+export function useAccentTintedSurface(neutralToken = "$color4"): string | undefined {
+  const theme = useTamaguiTheme() as unknown as Record<string, { val?: unknown } | undefined>;
+  const neutral = resolveTokenValue(theme, neutralToken);
+  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("|")]);
+}