@twentyfirstmedia/ui-core 0.2.1 → 0.3.0

package/src/format.ts

@@ -1,15 +1,16 @@
 /**
- * Numbers, money, percentages and dates, formatted with Intl in English (en-US). Money defaults
- * to euros; calendars start on Monday.
+ * Numbers, money, percentages and dates, formatted with Intl. English (en-US) by default; every
+ * helper takes an optional BCP 47 locale as its last argument, and components use the locale of
+ * the nearest `UIProvider` (see `useFormat`). Money defaults to euros; calendars start on Monday.
  */
 export const LOCALE = "en-US";
 export const CURRENCY = "EUR";
 /** First day of the week in calendars: 0 Sunday … 6 Saturday. */
 export const WEEK_START = 1;
 
-export function formatNumber(v: number, o?: Intl.NumberFormatOptions): string {
+export function formatNumber(v: number, o?: Intl.NumberFormatOptions, locale?: string): string {
   try {
-    return new Intl.NumberFormat(LOCALE, o).format(v);
+    return new Intl.NumberFormat(locale || LOCALE, o).format(v);
   } catch {
     return String(v);
   }
@@ -19,29 +20,121 @@ export function formatMoney(
   v: number,
   currency?: string | null,
   o?: Intl.NumberFormatOptions,
+  locale?: string,
 ): string {
-  return formatNumber(v, {
-    style: "currency",
-    currency: currency || CURRENCY,
-    minimumFractionDigits: v % 1 ? 2 : 0,
-    maximumFractionDigits: 2,
-    ...o,
-  });
+  return formatNumber(
+    v,
+    {
+      style: "currency",
+      currency: currency || CURRENCY,
+      minimumFractionDigits: v % 1 ? 2 : 0,
+      maximumFractionDigits: 2,
+      ...o,
+    },
+    locale,
+  );
 }
 
 /** A share in percent: `19` → "19%". */
-export function formatPercent(v: number, o?: Intl.NumberFormatOptions): string {
-  return formatNumber(v / 100, { style: "percent", maximumFractionDigits: 0, ...o });
+export function formatPercent(v: number, o?: Intl.NumberFormatOptions, locale?: string): string {
+  return formatNumber(v / 100, { style: "percent", maximumFractionDigits: 0, ...o }, locale);
 }
 
-export function formatDate(input: Date | string | number, o?: Intl.DateTimeFormatOptions): string {
+export function formatDate(
+  input: Date | string | number,
+  o?: Intl.DateTimeFormatOptions,
+  locale?: string,
+): string {
   const d = input instanceof Date ? input : new Date(input);
   try {
     return new Intl.DateTimeFormat(
-      LOCALE,
+      locale || LOCALE,
       o || { day: "2-digit", month: "2-digit", year: "numeric" },
     ).format(d);
   } catch {
     return d.toDateString();
   }
 }
+
+/** The group and decimal separators of a locale: `en-US` → `{ group: ",", decimal: "." }`. */
+export function numberSeparators(locale?: string): { group: string; decimal: string } {
+  let group = ",",
+    decimal = ".";
+  try {
+    for (const part of new Intl.NumberFormat(locale || LOCALE).formatToParts(12345.6)) {
+      if (part.type === "group") group = part.value;
+      else if (part.type === "decimal") decimal = part.value;
+    }
+  } catch {
+    // keep the English separators
+  }
+  return { group, decimal };
+}
+
+const escape = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/** A number inside a formatted string, as `parseFormatted` finds it. */
+export interface FormattedNumber {
+  /** Text before the number ("€", "+"). */
+  prefix: string;
+  value: number;
+  /** Digits after the decimal separator. */
+  decimals: number;
+  /** Whether the number used group separators ("1,305"). */
+  grouped: boolean;
+  /** Text after the number (" €/m²", "%"). */
+  suffix: string;
+}
+
+/**
+ * Finds the first number in a string formatted for `locale` and returns it with the text around
+ * it: `parseFormatted("13,05 €/m²", "de-DE")` → `{ prefix: "", value: 13.05, decimals: 2, … }`.
+ * Group separators are only taken between digits; a space or no-break space counts as a group
+ * separator for locales that group with one.
+ */
+export function parseFormatted(input: string | number, locale?: string): FormattedNumber | null {
+  if (typeof input === "number") {
+    if (!Number.isFinite(input)) return null;
+    const s = String(input);
+    if (/e/i.test(s)) return null;
+    return {
+      prefix: "",
+      value: input,
+      decimals: (s.split(".")[1] || "").length,
+      grouped: false,
+      suffix: "",
+    };
+  }
+  const { group, decimal } = numberSeparators(locale);
+  // narrow and regular no-break spaces both appear as group separators (fr, de-CH …)
+  const groups = /^\s$/.test(group) ? "[\\s\\u00a0\\u202f]" : escape(group);
+  const re = new RegExp(
+    `^([^0-9-]*)(-?[0-9](?:[0-9]|${groups}(?=[0-9]))*)(?:${escape(decimal)}([0-9]+))?(.*)$`,
+    "s",
+  );
+  const m = re.exec(input);
+  if (!m) return null;
+  const int = (m[2] as string).replace(new RegExp(groups, "g"), "");
+  const frac = m[3] ?? "";
+  return {
+    prefix: m[1] ?? "",
+    value: parseFloat(frac ? `${int}.${frac}` : int),
+    decimals: frac.length,
+    grouped: int.length !== (m[2] as string).length,
+    suffix: m[4] ?? "",
+  };
+}
+
+/** Writes a number back in the shape `parseFormatted` found it in (same decimals, grouping, text). */
+export function formatLike(v: number, shape: FormattedNumber, locale?: string): string {
+  const s = formatNumber(
+    v,
+    {
+      minimumFractionDigits: shape.decimals,
+      maximumFractionDigits: shape.decimals,
+      useGrouping: shape.grouped,
+    },
+    locale,
+  );
+  return shape.prefix + s + shape.suffix;
+}

package/src/index.ts

@@ -4,13 +4,56 @@ export {
   formatPercent,
   formatMoney,
   formatDate,
+  formatLike,
+  parseFormatted,
+  numberSeparators,
   LOCALE,
   CURRENCY,
   WEEK_START,
+  type FormattedNumber,
 } from "./format.js";
+export {
+  DEFAULT_STRINGS,
+  SHARED_STRINGS,
+  ADMIN_STRINGS,
+  AGENTS_STRINGS,
+  APP_CHROME_STRINGS,
+  APPROVALS_STRINGS,
+  BUILDING_BLOCKS_STRINGS,
+  CHARTS_STRINGS,
+  CHAT_STRINGS,
+  COMMERCE_STRINGS,
+  DATA_DISPLAY_STRINGS,
+  DATA_TABLE_STRINGS,
+  DEVELOPER_STRINGS,
+  FEEDBACK_STRINGS,
+  FORM_STRINGS,
+  FORMS_STRINGS,
+  MAIL_STRINGS,
+  MEDIA_STRINGS,
+  NAVIGATION_STRINGS,
+  OPERATIONS_STRINGS,
+  PREVIEWS_STRINGS,
+  PRIMITIVES_STRINGS,
+  REAL_ESTATE_STRINGS,
+  RICH_TEXT_EDITOR_STRINGS,
+  SELECT_MENU_STRINGS,
+  SHELL_STRINGS,
+  SITE_STRINGS,
+  WORKSPACE_STRINGS,
+  mergeStrings,
+  mergeMessages,
+  type UIStrings,
+  type UIMessages,
+} from "./strings.js";
 export {
   UIProvider,
   useUI,
+  useUIStrings,
+  useStrings,
+  useFormat,
+  formattersFor,
+  type Formatters,
   type UIProviderProps,
   type UIContextValue,
   type Kit,

package/src/provider.tsx

@@ -1,15 +1,18 @@
 "use client";
-import {
-  createContext,
-  useContext,
-  useEffect,
-  useMemo,
-  useRef,
-  useState,
-  type CSSProperties,
-  type ReactNode,
-} from "react";
+import { useEffect, useMemo, useRef, useState, type CSSProperties, type ReactNode } from "react";
+import { UIContext, useUI, type UIContextValue } from "./context.js";
+import { mergeMessages, type UIMessages } from "./strings.js";
 import { themeStyle, type ThemeInput, type ThemeValues } from "./theme.js";
+
+export {
+  useUI,
+  useUIStrings,
+  useStrings,
+  useFormat,
+  formattersFor,
+  type UIContextValue,
+  type Formatters,
+} from "./context.js";
 export type Kit = "halo" | "pro";
 export type Theme = "light" | "dark" | "system";
 export type Density = "compact" | "comfortable";
@@ -53,39 +56,23 @@ export interface UIProviderProps {
    * reduced-motion setting always turns motion off.
    */
   motion?: Motion;
+  /**
+   * BCP 47 locale for the numbers, money, percentages and dates components show (`"de-DE"`).
+   * Default `"en-US"`; a nested provider keeps its parent's locale unless it sets its own.
+   */
+  locale?: string;
+  /**
+   * Your own text for any built-in string: accessible names, button texts, placeholders, status
+   * words (`{ close: "Schließen", selectedCount: (n) => \`${n} ausgewählt\` }`). Partial: what you
+   * leave out stays English (or what an outer provider set). Props such as `title` or `label` on a
+   * component still win. See `DEFAULT_STRINGS` for every key.
+   */
+  messages?: UIMessages;
   className?: string;
   style?: CSSProperties;
   children?: ReactNode;
 }
 
-export interface UIContextValue {
-  kit: Kit | undefined;
-  theme: Theme | undefined;
-  density: Density | undefined;
-  surface: Surface | undefined;
-  motion: Motion | undefined;
-  /** Element portals render into (null: document.body). */
-  portalRoot: HTMLElement | null;
-}
-
-const UIContext = createContext<UIContextValue>({
-  kit: undefined,
-  theme: undefined,
-  density: undefined,
-  surface: undefined,
-  motion: undefined,
-  portalRoot: null,
-});
-
-/** Current kit, theme, density and portal target. */
-export function useUI(): UIContextValue {
-  return useContext(UIContext);
-}
-
-/**
- * Sets kit, theme and density for everything inside (they only change attributes, so switching
- * never re-mounts the subtree).
- */
 /** True while the colour scheme the page shows is dark (theme prop, kit default, system). */
 function useDarkMode(theme: Theme | undefined, kit: Kit | undefined, enabled: boolean): boolean {
   const [systemDark, setSystemDark] = useState(false);
@@ -106,6 +93,10 @@ function useDarkMode(theme: Theme | undefined, kit: Kit | undefined, enabled: bo
 const isThemeInput = (t: ThemeValues | ThemeInput): t is ThemeInput =>
   "light" in t || "dark" in t || "radius" in t;
 
+/**
+ * Sets kit, theme, density, locale and strings for everything inside (switching never re-mounts
+ * the subtree: kit, theme and density only change attributes, locale and strings re-render).
+ */
 export function UIProvider(p: UIProviderProps) {
   const parent = useUI();
   const scope = p.scope ?? "document";
@@ -115,6 +106,11 @@ export function UIProvider(p: UIProviderProps) {
   const density = p.density ?? parent.density;
   const surface = p.surface ?? parent.surface;
   const motion = p.motion ?? parent.motion;
+  const locale = p.locale || parent.locale;
+  const messages = useMemo(
+    () => (p.messages ? mergeMessages(parent.messages, p.messages) : parent.messages),
+    [parent.messages, p.messages],
+  );
   const perMode = !!p.tokens && isThemeInput(p.tokens);
   const dark = useDarkMode(theme, kit, perMode);
   const vars = useMemo(() => {
@@ -155,8 +151,8 @@ export function UIProvider(p: UIProviderProps) {
 
   const [portalRoot, setPortalRoot] = useState<HTMLElement | null>(null);
   const ctx = useMemo<UIContextValue>(
-    () => ({ kit, theme, density, surface, motion, portalRoot }),
-    [kit, theme, density, surface, motion, portalRoot],
+    () => ({ kit, theme, density, surface, motion, locale, messages, portalRoot }),
+    [kit, theme, density, surface, motion, locale, messages, portalRoot],
   );
   // Derived colours (glass, hover shades, Pro's scale) are worked out where data-theme sits. A
   // subtree with its own tokens needs data-theme too, or they would keep the outer values.