@eocrm/design-system 0.0.0-stage → 0.6.18

package/src/_meta/manifest.ts

@@ -0,0 +1,293 @@
+/**
+ * Build-time helper that derives a dependency graph of every component
+ * directory in `src/components/`. Output is committed as
+ * `src/components.manifest.json` and consumed by:
+ *
+ * - the drift-detection Vitest test alongside this file
+ * - the playground's `/components/dependencies` page
+ * - (future) AI-PRIMER.md auto-generated architecture section
+ *
+ * The graph is computed from import statements — no per-component
+ * metadata to maintain. A component is a "primitive" if it imports no
+ * other components in this directory; "composition" otherwise.
+ */
+
+import { readdirSync, readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const COMPONENTS_DIR = join(__dirname, '..', 'components');
+
+export type ComponentTier = 'primitive' | 'composition';
+
+export interface ComponentManifestEntry {
+  /** `'primitive'` if no other library components are imported; `'composition'` otherwise. */
+  tier: ComponentTier;
+  /** Functional cluster — derived from `CLUSTERS` map below. `null` if not classified. */
+  cluster: string | null;
+  /** Sorted list of library components this one imports. Empty for primitives. */
+  composes: string[];
+  /** Sorted inverse — components that import this one. */
+  composedBy: string[];
+}
+
+export type ComponentManifest = Record<string, ComponentManifestEntry>;
+
+/**
+ * Functional-cluster table. Mirrors the AI-PRIMER.md and AppShell sidebar
+ * grouping. Update this when adding a component to keep the cluster
+ * column accurate; the test alongside this file fails if a component is
+ * unclassified.
+ */
+const CLUSTERS: Record<string, string> = {
+  // Layout
+  Stack: 'Layout',
+  Cluster: 'Layout',
+  Constrain: 'Layout',
+  Indent: 'Layout',
+  AppLayout: 'Layout',
+  Divider: 'Layout',
+  Grid: 'Layout',
+  Split: 'Layout',
+  Sticky: 'Layout',
+  Masonry: 'Layout',
+  Card: 'Layout',
+  ScrollArea: 'Layout',
+  Page: 'Layout',
+  Screen: 'Layout',
+  PageHeader: 'Layout',
+
+  // Forms
+  Button: 'Forms',
+  SocialButton: 'Forms',
+  ButtonGroup: 'Forms',
+  Checkbox: 'Forms',
+  ColorPicker: 'Forms',
+  DatePicker: 'Forms',
+  DatePickers: 'Forms',
+  RelativeDateInput: 'Forms',
+  DateStrip: 'Forms',
+  SlotGrid: 'Forms',
+  DateRangePicker: 'Forms',
+  Field: 'Forms',
+  SettingRow: 'Forms',
+  FormRow: 'Forms',
+  FormSection: 'Forms',
+  FileUpload: 'Forms',
+  IconPicker: 'Forms',
+  ImageCrop: 'Forms',
+  Input: 'Forms',
+  Kanban: 'Forms',
+  LiquidEditor: 'Forms',
+  OtpInput: 'Forms',
+  PasswordInput: 'Forms',
+  PasswordStrengthMeter: 'Forms',
+  CurrencySelect: 'Forms',
+  MoneyInput: 'Forms',
+  PhoneInput: 'Forms',
+  Radio: 'Forms',
+  OptionsPicker: 'Forms',
+  EmojiPicker: 'Forms',
+  Select: 'Forms',
+  Slider: 'Forms',
+  Sortable: 'Forms',
+  SortableGroup: 'Forms',
+  CatalogPicker: 'Forms',
+  PillMenu: 'Forms',
+  Switch: 'Forms',
+  RichTextEditor: 'Forms',
+  Textarea: 'Forms',
+  TimeField: 'Forms',
+
+  // Display
+  Avatar: 'Display',
+  AgentAvatar: 'Display',
+  Image: 'Display',
+  QrCode: 'Display',
+  MediaTile: 'Display',
+  WidgetPreview: 'Display',
+  Badge: 'Display',
+  Dot: 'Display',
+  EntityChip: 'Display',
+  Timeline: 'Display',
+  StagePath: 'Display',
+  Thread: 'Display',
+  BrandIcon: 'Display',
+  Logo: 'Display',
+  DefinitionList: 'Display',
+  List: 'Display',
+  Calendar: 'Display',
+  CircularProgress: 'Display',
+  Code: 'Display',
+  CodeBlock: 'Display',
+  HighlightedText: 'Display',
+  CursorPagination: 'Display',
+  DashboardCanvas: 'Display',
+  DashboardWidget: 'Display',
+  StatGroup: 'Display',
+  Chart: 'Display',
+  Sparkline: 'Display',
+  TreeView: 'Display',
+  DataTable: 'Display',
+  EmptyState: 'Display',
+  ErrorState: 'Display',
+  IconTile: 'Display',
+  FilterChip: 'Display',
+  FlowCanvas: 'Display',
+  Kbd: 'Display',
+  Pagination: 'Display',
+  PersonDisplay: 'Display',
+  Progress: 'Display',
+  Skeleton: 'Display',
+  Table: 'Display',
+  RichText: 'Display',
+  Text: 'Display',
+  Title: 'Display',
+
+  // Feedback
+  Alert: 'Feedback',
+  Banner: 'Feedback',
+  ChatBubble: 'Feedback',
+  ChatLauncher: 'Feedback',
+  Highlight: 'Feedback',
+  Toast: 'Feedback',
+
+  // Navigation
+  Accordion: 'Navigation',
+  Breadcrumb: 'Navigation',
+  Link: 'Navigation',
+  LinkCard: 'Navigation',
+  Rail: 'Navigation',
+  TableOfContents: 'Navigation',
+  Tabs: 'Navigation',
+  TopBar: 'Navigation',
+
+  // Overlays
+  ConfirmationPopover: 'Overlays',
+  Drawer: 'Overlays',
+  DropdownMenu: 'Overlays',
+  Lightbox: 'Overlays',
+  Modal: 'Overlays',
+  Popover: 'Overlays',
+  Tooltip: 'Overlays',
+  Tour: 'Overlays',
+
+  // Accessibility
+  VisuallyHidden: 'Accessibility',
+  LiveRegion: 'Accessibility',
+};
+
+// `(?:\.\./)+`, not a single `../`, since #509 — the other half of the flat-walk
+// bug. Once nested files are read, their imports are one level deeper, so
+// `from '../../RichTextEditor/…'` inside RichText/engine/ has to match too.
+// Widening the walk without widening this pattern still sees nothing.
+const FROM_PARENT_PATH = /from\s+['"](?:\.\.\/)+([A-Z][a-zA-Z0-9]+)(?:\/[^'"]*)?['"]/g;
+
+function listComponentDirs(): string[] {
+  return readdirSync(COMPONENTS_DIR, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .filter((entry) => !entry.name.startsWith('_'))
+    .map((entry) => entry.name)
+    .sort();
+}
+
+function collectSourceText(componentDir: string): string {
+  // Concatenate every non-test .tsx + .ts file UNDER the component dir so that
+  // sub-files (e.g. SVSquare.tsx inside ColorPicker/) contribute their imports
+  // to the parent component's dependency set.
+  //
+  // Recursive since #509. It said "every" and read one level, so nothing in a
+  // nested directory counted — RichText/engine/ holds 20 modules and none of
+  // them were ever parsed. That hid a real bidirectional dependency between
+  // RichText and RichTextEditor for as long as the acyclic gate has been green;
+  // the gate was not wrong, it was being fed half the source. Fixing the walk
+  // without first breaking that cycle turns the gate red.
+  const out: string[] = [];
+  const walk = (dir: string) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const path = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(path);
+      } else if (
+        (entry.name.endsWith('.tsx') || entry.name.endsWith('.ts')) &&
+        !entry.name.endsWith('.test.tsx') &&
+        !entry.name.endsWith('.test.ts')
+      ) {
+        out.push(readFileSync(path, 'utf-8'));
+      }
+    }
+  };
+  walk(componentDir);
+  return out.join('\n');
+}
+
+/**
+ * The import-matching half of the walk, exposed so it can be asserted directly.
+ *
+ * The pattern has to accept more than one `../` (#509). Nothing in the tree
+ * currently exercises that — the only nested directory, RichText/engine, had
+ * its single upward import removed when the RichText <-> RichTextEditor cycle
+ * was broken — so the manifest looks the same whether the pattern is right or
+ * wrong. That is exactly the condition under which a fix rots.
+ */
+export function collectImportsFrom(lines: string[]): string[] {
+  return extractParentImports(lines.join('\n'));
+}
+
+function extractParentImports(source: string): string[] {
+  const deps = new Set<string>();
+  for (const match of source.matchAll(FROM_PARENT_PATH)) {
+    deps.add(match[1]);
+  }
+  return [...deps];
+}
+
+/**
+ * Build the full component manifest by walking every directory under
+ * `src/components/` and parsing its source-file imports. Output is sorted
+ * (component keys + composes / composedBy arrays) so the JSON is stable
+ * across runs.
+ */
+export function buildManifest(): ComponentManifest {
+  const names = listComponentDirs();
+  const knownComponents = new Set(names);
+  const manifest: ComponentManifest = {};
+
+  // First pass: populate `composes` for each component.
+  for (const name of names) {
+    const dir = join(COMPONENTS_DIR, name);
+    const src = collectSourceText(dir);
+    const imports = extractParentImports(src).filter((n) => knownComponents.has(n) && n !== name);
+    imports.sort();
+    manifest[name] = {
+      tier: imports.length === 0 ? 'primitive' : 'composition',
+      cluster: CLUSTERS[name] ?? null,
+      composes: imports,
+      composedBy: [],
+    };
+  }
+
+  // Second pass: invert the graph for `composedBy`.
+  for (const [name, entry] of Object.entries(manifest)) {
+    for (const dep of entry.composes) {
+      const target = manifest[dep];
+      if (target) {
+        target.composedBy.push(name);
+      }
+    }
+  }
+
+  // Sort composedBy lists for stable output.
+  for (const entry of Object.values(manifest)) {
+    entry.composedBy.sort();
+  }
+
+  // Return a key-sorted object so JSON.stringify gives deterministic output.
+  return Object.fromEntries(
+    Object.entries(manifest).sort(([a], [b]) => a.localeCompare(b)),
+  ) as ComponentManifest;
+}
+
+/** Path to the committed manifest JSON (relative to the design-system root). */
+export const MANIFEST_PATH = join(__dirname, '..', 'components.manifest.json');

package/src/app/AppProvider.tsx

@@ -0,0 +1,78 @@
+import { type ReactNode, useMemo } from 'react';
+import {
+  LocaleProvider,
+  I18nProvider,
+  type DeepPartial,
+  type Locale,
+  type Messages,
+} from '../i18n';
+import { ToastViewport, type ToastViewportProps } from '../components/Toast';
+import { buildThemeTokenCss, type TokenMap } from './themeTokens';
+
+export interface AppProviderProps {
+  /**
+   * UI-string locale — selects the built-in message bundle. v1 ships `'en'`
+   * and `'ru'`. Drives every design-system component's copy via `useTranslation`.
+   */
+  locale: Locale;
+  /**
+   * BCP-47 locale for Intl-facing formatting (Calendar, dates, numbers), read
+   * by components via `useLocale`. Optional — defaults to `locale` verbatim
+   * (`'en'` / `'ru'` are valid language tags). Set it for a region, e.g.
+   * `'en-US'` / `'ru-RU'` / `'en-GB'`.
+   */
+  intlLocale?: string;
+  /**
+   * Deep-partial overrides deep-merged over the built-in messages for `locale`.
+   * Supply only the keys you rebrand/retext; the rest fall back to the shipped
+   * defaults. Memoize this object — passing a fresh literal every render
+   * rebuilds the merged messages each time.
+   */
+  translations?: DeepPartial<Messages>;
+  /**
+   * Toast viewport configuration (`position`, `duration`, …), or `false` to
+   * NOT mount a viewport (place `<ToastViewport>` yourself). Omitted ⇒ a
+   * viewport is mounted with the library defaults.
+   */
+  toast?: ToastViewportProps | false;
+  /**
+   * CSS design-token overrides applied in BOTH light and dark — a flat map of
+   * token name → value (`{ '--color-accent': '#7c3aed', '--radius-md': '6px' }`).
+   * Rebrands the design system globally (reaches portaled Modal/Tooltip/Toast).
+   * Emitted as a declarative `<style>`; layers over the dark theme correctly.
+   * **Memoize this object** — a fresh literal each render rebuilds the CSS.
+   */
+  tokens?: TokenMap;
+  /**
+   * Token overrides applied ONLY in dark (forced `data-theme="dark"` and system
+   * `prefers-color-scheme: dark`), merged over `tokens` — use it to tune a token
+   * for dark surfaces (e.g. a lighter accent). **Memoize this object.**
+   */
+  darkTokens?: TokenMap;
+  children: ReactNode;
+}
+
+/**
+ * App root: composes `LocaleProvider` + `I18nProvider` and mounts the toast viewport.
+ * @see docs/setup.md
+ */
+export function AppProvider({
+  locale,
+  intlLocale,
+  translations,
+  toast,
+  tokens,
+  darkTokens,
+  children,
+}: AppProviderProps) {
+  const tokenCss = useMemo(() => buildThemeTokenCss(tokens, darkTokens), [tokens, darkTokens]);
+  return (
+    <LocaleProvider locale={intlLocale ?? locale}>
+      <I18nProvider locale={locale} overrides={translations}>
+        {tokenCss && <style data-eocrm-tokens>{tokenCss}</style>}
+        {children}
+        {toast !== false && <ToastViewport {...(toast ?? {})} />}
+      </I18nProvider>
+    </LocaleProvider>
+  );
+}

package/src/app/index.ts

@@ -0,0 +1,3 @@
+export { AppProvider } from './AppProvider';
+export type { AppProviderProps } from './AppProvider';
+export type { TokenMap } from './themeTokens';

package/src/app/themeTokens.ts

@@ -0,0 +1,95 @@
+/**
+ * A flat map of CSS design-token overrides: custom-property name → value.
+ * Keys must start with `--` (e.g. `--color-accent`, `--radius-md`,
+ * `--font-family-sans`). Consumed by `<AppProvider tokens>` / `darkTokens`.
+ */
+export type TokenMap = Partial<Record<`--${string}`, string>>;
+
+// Read NODE_ENV defensively so the library never throws at module init
+// (mirrors components/Tabs/Tabs.tsx).
+const IS_DEV = typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production';
+
+// A valid CSS custom-property name: `--` followed by word chars / dashes.
+const KEY_RE = /^--[\w-]+$/;
+// Characters that could break out of a CSS declaration or the <style> element.
+const UNSAFE_VALUE_RE = /[{}<>]/;
+
+function warn(message: string): void {
+  if (IS_DEV) console.warn(`[AppProvider] ${message}`);
+}
+
+/**
+ * Keep only entries whose key is a valid custom-property name and whose value
+ * cannot break out of a CSS declaration / the <style> element. Rejected
+ * entries are dropped with a dev warning (the consumer is trusted — this is
+ * defensive, not a security boundary). Preserves the map's own key order.
+ */
+function sanitizeEntries(map: TokenMap | undefined): Array<[string, string]> {
+  if (!map) return [];
+  const out: Array<[string, string]> = [];
+  for (const [key, value] of Object.entries(map)) {
+    if (value == null) continue;
+    if (!KEY_RE.test(key)) {
+      warn(`ignoring override with invalid key ${JSON.stringify(key)} (must match --name)`);
+      continue;
+    }
+    if (UNSAFE_VALUE_RE.test(value)) {
+      warn(`ignoring override ${key}: value contains an unsafe character ({ } < >)`);
+      continue;
+    }
+    out.push([key, value]);
+  }
+  return out;
+}
+
+function declarations(entries: Array<[string, string]>, indent: string): string {
+  return entries.map(([key, value]) => `${indent}${key}: ${value};`).join('\n');
+}
+
+// Each scope also lists an accent-aware selector (`:root:root[data-accent]`) that
+// STRICTLY out-specifies the matching generated `data-accent` block, so overrides
+// win over an accent regardless of <style> order. Specificity: light (0,3,0) >
+// accent light (0,2,0); dark/OS-dark (0,4,0) > accent dark (0,3,0). Dark (0,4,0)
+// also beats light (0,3,0), so `darkTokens` still win in dark with an accent set.
+const LIGHT_SELECTOR = ':root, :root:root[data-accent]';
+const DARK_SELECTOR = ":root[data-theme='dark'], :root:root[data-accent][data-theme='dark']";
+const OS_DARK_SELECTOR =
+  ":root:not([data-theme='light']), :root:root[data-accent]:not([data-theme='light'])";
+
+/**
+ * Build the CSS for consumer token overrides, mirroring `dark.scss`'s scopes so
+ * the cascade resolves correctly:
+ * - `tokens` → `:root {}` plus accent-aware twins (`:root:root[data-accent]`) that
+ *   win over the generated `data-accent` blocks by specificity, AND re-emitted
+ *   into the dark scopes so a single map applies in both themes.
+ * - `darkTokens` → layered AFTER `tokens` inside the dark scopes only.
+ *
+ * Returns `null` when there is nothing to emit, so `<AppProvider>` renders no
+ * `<style>` for the no-override case (preserving its zero-side-effect default).
+ */
+export function buildThemeTokenCss(tokens?: TokenMap, darkTokens?: TokenMap): string | null {
+  const base = sanitizeEntries(tokens);
+  const dark = sanitizeEntries(darkTokens);
+  if (base.length === 0 && dark.length === 0) return null;
+
+  const blocks: string[] = [];
+
+  if (base.length > 0) {
+    blocks.push(`${LIGHT_SELECTOR} {\n${declarations(base, '  ')}\n}`);
+  }
+
+  // tokens re-emitted into dark so a single map applies in dark too; darkTokens
+  // layered after so they win.
+  const darkScope = [...base, ...dark];
+  if (darkScope.length > 0) {
+    blocks.push(`${DARK_SELECTOR} {\n${declarations(darkScope, '  ')}\n}`);
+    blocks.push(
+      `@media (prefers-color-scheme: dark) {\n` +
+        `  ${OS_DARK_SELECTOR} {\n` +
+        `${declarations(darkScope, '    ')}\n` +
+        `  }\n}`,
+    );
+  }
+
+  return blocks.join('\n');
+}

package/src/calendar/dateMath.ts

@@ -0,0 +1,114 @@
+const MS_PER_DAY = 86_400_000;
+
+/** Return a new Date `n` days after `date`. Local-time anchored. Does not mutate `date`. */
+export function addDays(date: Date, n: number): Date {
+  const result = new Date(date);
+  result.setDate(result.getDate() + n);
+  return result;
+}
+
+/**
+ * Return a new Date `n` months after `date`. Clamps day-of-month onto shorter
+ * target months (Jan 31 + 1 month → Feb 28/29). Does not mutate `date`.
+ */
+export function addMonths(date: Date, n: number): Date {
+  const result = new Date(date);
+  const originalDay = result.getDate();
+  result.setDate(1);
+  result.setMonth(result.getMonth() + n);
+  // Clamp day to the target month's last day (handles Jan 31 + 1m → Feb 28/29)
+  const lastDay = new Date(result.getFullYear(), result.getMonth() + 1, 0).getDate();
+  result.setDate(Math.min(originalDay, lastDay));
+  return result;
+}
+
+/** Return a new Date `n` weeks after `date` (sugar for `addDays(date, n * 7)`). */
+export function addWeeks(date: Date, n: number): Date {
+  return addDays(date, n * 7);
+}
+
+/** Return a new Date with the same calendar day at local 00:00:00.000. */
+export function startOfDay(date: Date): Date {
+  const result = new Date(date);
+  result.setHours(0, 0, 0, 0);
+  return result;
+}
+
+/**
+ * Return the local-midnight start of the week containing `date`. `weekStartsOn`
+ * is the column index of the locale's first-day-of-week (0 = Sunday, 1 = Monday).
+ */
+export function startOfWeek(date: Date, weekStartsOn: 0 | 1 | 2 | 3 | 4 | 5 | 6): Date {
+  const result = startOfDay(date);
+  const delta = (result.getDay() - weekStartsOn + 7) % 7;
+  result.setDate(result.getDate() - delta);
+  return result;
+}
+
+/** Return the 1st of `date`'s month at local midnight. */
+export function startOfMonth(date: Date): Date {
+  const result = new Date(date.getFullYear(), date.getMonth(), 1);
+  return result;
+}
+
+/** Return the last day of `date`'s month at local midnight (e.g., Jan 31, Feb 28/29). */
+export function endOfMonth(date: Date): Date {
+  // Day 0 of next month = last day of current month.
+  return new Date(date.getFullYear(), date.getMonth() + 1, 0);
+}
+
+/** True when `a` and `b` fall on the same calendar day (ignores time component). */
+export function isSameDay(a: Date, b: Date): boolean {
+  return (
+    a.getFullYear() === b.getFullYear() &&
+    a.getMonth() === b.getMonth() &&
+    a.getDate() === b.getDate()
+  );
+}
+
+/** True when `a` and `b` fall in the same calendar month and year. */
+export function isSameMonth(a: Date, b: Date): boolean {
+  return a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth();
+}
+
+/**
+ * True when `date` is today. Pass an explicit `now` for deterministic tests;
+ * defaults to `new Date()`.
+ */
+export function isToday(date: Date, now: Date = new Date()): boolean {
+  return isSameDay(date, now);
+}
+
+/**
+ * True when `date.getDay()` is in `weekendDays` (e.g., `[0, 6]` for Sat/Sun
+ * in most locales; `[5, 6]` for Fri/Sat in ar-SA / he-IL). Use
+ * `getWeekendDays(locale)` to derive the array.
+ */
+export function isWeekend(date: Date, weekendDays: readonly number[]): boolean {
+  return weekendDays.includes(date.getDay());
+}
+
+/**
+ * Calendar-day difference between `a` and `b`. DST-safe — rounds to whole
+ * days so the ±1 hour offset across a DST boundary doesn't shift the count.
+ * Positive when `b` is after `a`.
+ */
+export function daysBetween(a: Date, b: Date): number {
+  const startA = startOfDay(a).getTime();
+  const startB = startOfDay(b).getTime();
+  return Math.round((startB - startA) / MS_PER_DAY);
+}
+
+/** Return `'YYYY-MM-DD'` in local time. Zero-padded month and day. */
+export function toDateKey(date: Date): string {
+  const yyyy = String(date.getFullYear()).padStart(4, '0');
+  const mm = String(date.getMonth() + 1).padStart(2, '0');
+  const dd = String(date.getDate()).padStart(2, '0');
+  return `${yyyy}-${mm}-${dd}`;
+}
+
+/** Parse a `'YYYY-MM-DD'` key (as produced by `toDateKey`) to a local-midnight Date. */
+export function fromDateKey(key: string): Date {
+  const [yyyy, mm, dd] = key.split('-').map(Number);
+  return new Date(yyyy, mm - 1, dd);
+}

package/src/calendar/formatters.ts

@@ -0,0 +1,75 @@
+const cache = new Map<string, Intl.DateTimeFormat>();
+
+function getFormatter(locale: string, options: Intl.DateTimeFormatOptions): Intl.DateTimeFormat {
+  const key = `${locale}|${JSON.stringify(options)}`;
+  let f = cache.get(key);
+  if (!f) {
+    f = new Intl.DateTimeFormat(locale, options);
+    cache.set(key, f);
+  }
+  return f;
+}
+
+/**
+ * "May 2026" / "Май 2026" — capitalized standalone month name + numeric year,
+ * without the locale's era suffix.
+ *
+ * `Intl.DateTimeFormat(locale, { year: 'numeric', month: 'long' })` in some
+ * locales (notably `ru-RU`) yields "май 2026 г." — lowercase genitive month
+ * with an era marker. For calendar headers we want a nominative-cased
+ * standalone month, so we format month and year separately and uppercase the
+ * first character of the month with locale-aware casing.
+ */
+export function formatMonth(date: Date, locale: string): string {
+  const month = getFormatter(locale, { month: 'long' }).format(date);
+  const year = date.getFullYear();
+  const capitalized = month.charAt(0).toLocaleUpperCase(locale) + month.slice(1);
+  return `${capitalized} ${year}`;
+}
+
+/** "Mon" (Intl 'short' weekday). */
+export function formatWeekdayShort(date: Date, locale: string): string {
+  return getFormatter(locale, { weekday: 'short' }).format(date);
+}
+
+/** "M" (Intl 'narrow' weekday — for tight column headers). */
+export function formatWeekdayNarrow(date: Date, locale: string): string {
+  return getFormatter(locale, { weekday: 'narrow' }).format(date);
+}
+
+/** "Wed 20" */
+export function formatDayShort(date: Date, locale: string): string {
+  return getFormatter(locale, { weekday: 'short', day: 'numeric' }).format(date);
+}
+
+/** "Wednesday, May 20" */
+export function formatDayLong(date: Date, locale: string): string {
+  return getFormatter(locale, { weekday: 'long', month: 'long', day: 'numeric' }).format(date);
+}
+
+/** "May 18 – 24, 2026" via Intl.DateTimeFormat#formatRange. */
+export function formatRange(from: Date, to: Date, locale: string): string {
+  return getFormatter(locale, { year: 'numeric', month: 'long', day: 'numeric' }).formatRange(
+    from,
+    to,
+  );
+}
+
+/** "9 AM" / "09:00" — hour only, 12/24-hour determined by locale default. */
+export function formatHour(hour: number, locale: string): string {
+  const date = new Date(2000, 0, 1, hour);
+  return getFormatter(locale, { hour: 'numeric' }).format(date);
+}
+
+/**
+ * "9:00 AM" / "09:00" — hour + minute, suitable for event start times.
+ * 12/24-hour determined by locale default.
+ */
+export function formatTime(date: Date, locale: string): string {
+  return getFormatter(locale, { hour: 'numeric', minute: '2-digit' }).format(date);
+}
+
+/** Test-only helper. Resets the formatter cache between tests. */
+export function _resetFormatterCacheForTests(): void {
+  cache.clear();
+}