@astryxdesign/core 0.1.8 → 0.1.9-canary.75d2d03

package/src/i18n/getLocaleDirection.ts

@@ -0,0 +1,29 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file getLocaleDirection.ts
+ * @input BCP 47 locale tag
+ * @output 'ltr' | 'rtl'
+ * @position Server-safe helper for computing text direction from a locale.
+ *   Callable in React Server Components / Next.js layouts to set <html dir>.
+ *
+ * Uses Intl.Locale.getTextInfo() (CLDR-backed) with a try/catch fallback to
+ * 'ltr'. React 19 baseline covers all target browsers + Node ≥20; the older
+ * accessor form (`.textInfo`) is handled as a fallback for defensive parity.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/i18n/InternationalizationProvider.tsx (uses this to derive default)
+ * - /packages/core/src/i18n/useDirection.ts (client-side hook counterpart)
+ * - /packages/core/src/i18n/index.ts (public export)
+ */
+
+export function getLocaleDirection(locale: string): 'ltr' | 'rtl' {
+  try {
+    const loc = new Intl.Locale(locale);
+    // @ts-expect-error — older engines expose accessor form `.textInfo`
+    const info = typeof loc.getTextInfo === 'function' ? loc.getTextInfo() : loc.textInfo;
+    return info?.direction === 'rtl' ? 'rtl' : 'ltr';
+  } catch {
+    return 'ltr';
+  }
+}

package/src/i18n/index.ts

@@ -10,10 +10,14 @@
  * The public API is deliberately small:
  *   - InternationalizationProvider — provider component
  *   - useTranslator               — hook returning a translator function
+ *   - useDirection                — hook returning the ambient text direction
+ *   - getLocaleDirection          — server-safe locale → direction helper
  *   - Translator                  — interface for consumer-injected runtimes
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/index.ts
+ * - /packages/core/src/i18n/useDirection.ts
+ * - /packages/core/src/i18n/getLocaleDirection.ts
  */
 
 export {InternationalizationProvider} from './InternationalizationProvider';
@@ -22,6 +26,8 @@ export {InternationalizationContext} from './InternationalizationContext';
 export type {InternationalizationContextValue} from './InternationalizationContext';
 export {useTranslator} from './useTranslator';
 export type {TranslatorFn} from './useTranslator';
+export {useDirection} from './useDirection';
+export {getLocaleDirection} from './getLocaleDirection';
 export type {Translator} from './translator';
 export type {
   Locale,

package/src/i18n/resolve.ts

@@ -22,6 +22,7 @@
 import IntlMessageFormat from 'intl-messageformat';
 import type {Catalog, Locale, MessagesByLocale, Overrides} from './types';
 import enSource from '../../locales/en.json' with {type: 'json'};
+import {warnOnce, __resetDevWarnings} from '../utils/devWarning';
 
 const EN_CATALOG = enSource as Catalog;
 
@@ -72,23 +73,6 @@ export function resolveLocaleChain(locale: Locale): Locale[] {
   return chain;
 }
 
-/**
- * Missing-key warn-once tracking. Fires ONLY when a key is missing from
- * every source including the shipped `en` catalog — that's a real bug
- * (typo, stale catalog, deleted key). Fallback to `en` from a non-en
- * locale is expected and silent, matching the FormatJS / i18next default
- * of not spamming the console when a translation simply hasn't been
- * written yet.
- */
-const warnedMissing = new Set<string>();
-
-function warnOnce(bucket: Set<string>, key: string, message: string): void {
-  if (!bucket.has(key)) {
-    bucket.add(key);
-    console.warn(message);
-  }
-}
-
 function lookup(
   key: string,
   locale: Locale,
@@ -135,10 +119,14 @@ export function resolve(
   const result = lookup(key, locale, messages, overrides);
 
   if (result === null) {
+    // Fires ONLY when a key is missing from every source including the
+    // shipped `en` catalog — a real bug (typo, stale catalog, deleted key).
+    // Fallback to `en` from a non-en locale is expected and stays silent,
+    // matching the FormatJS / i18next default.
     warnOnce(
-      warnedMissing,
-      `${locale}::${key}`,
-      `[astryx-i18n] missing key: ${key} (locale: ${locale})`,
+      `astryx-i18n:${locale}::${key}`,
+      'astryx-i18n',
+      `missing key: ${key} (locale: ${locale})`,
     );
     return key;
   }
@@ -161,5 +149,5 @@ export function resolve(
  */
 export function __resetForTests(): void {
   formatterCache.clear();
-  warnedMissing.clear();
+  __resetDevWarnings();
 }

package/src/i18n/useDirection.ts

@@ -0,0 +1,29 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useDirection.ts
+ * @input InternationalizationContext (via use())
+ * @output 'ltr' | 'rtl'
+ * @position Client hook for reading the ambient text direction. Returns 'ltr'
+ *   when called outside a provider (matches the silent-en-fallback pattern of
+ *   useTranslator).
+ *
+ * Use this in components that need to swap directional icons, mirror
+ * behavioral logic (slider math, keyboard nav), or apply direction-specific
+ * styling that CSS logical properties can't express.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/i18n/InternationalizationContext.ts
+ * - /packages/core/src/i18n/getLocaleDirection.ts (server-safe counterpart)
+ * - /packages/core/src/i18n/index.ts
+ */
+
+import {use} from 'react';
+import {InternationalizationContext} from './InternationalizationContext';
+
+export function useDirection(): 'ltr' | 'rtl' {
+  const ctx = use(InternationalizationContext);
+  return ctx.direction;
+}

package/src/theme/Theme.tsx

@@ -45,6 +45,7 @@ import {registerIcons} from '../Icon/globalIconRegistry';
 import {generateThemeCSS, type DefinedTheme} from './defineTheme';
 import {dataAttr} from '../naming';
 import {ThemeContext} from './useTheme';
+import {warnOnce} from '../utils/devWarning';
 
 /**
  * Theme provider props
@@ -97,9 +98,6 @@ ThemeNestingContext.displayName = 'ThemeNestingContext';
 /** Track which themes have already been injected */
 const injectedThemes = new Set<string>();
 
-/** Track which themes have already logged the perf warning */
-const warnedThemes = new Set<string>();
-
 /**
  * Hook to inject theme CSS into the document.
  * Built themes (from `astryx theme build`) skip injection — their CSS
@@ -120,17 +118,16 @@ function useThemeStyleInjection(theme: DefinedTheme): void {
     }
 
     // One-time perf hint per theme
-    if (!warnedThemes.has(theme.name)) {
-      warnedThemes.add(theme.name);
-      console.warn(
-        `[Astryx] Theme "${theme.name}" is using runtime style injection. ` +
-          `For better performance, use the pre-built theme:\n\n` +
-          `  import {${theme.name}Theme} from '@astryxdesign/theme-${theme.name}/built';\n` +
-          `  import '@astryxdesign/theme-${theme.name}/theme.css';\n\n` +
-          `For custom themes, run \`npx @astryxdesign/cli theme build <file>\` to generate ` +
-          `the built artifacts.`,
-      );
-    }
+    warnOnce(
+      `theme-injection:${theme.name}`,
+      'Theme',
+      `"${theme.name}" is using runtime style injection. ` +
+        `For better performance, use the pre-built theme:\n\n` +
+        `  import {${theme.name}Theme} from '@astryxdesign/theme-${theme.name}/built';\n` +
+        `  import '@astryxdesign/theme-${theme.name}/theme.css';\n\n` +
+        `For custom themes, run \`npx @astryxdesign/cli theme build <file>\` to generate ` +
+        `the built artifacts.`,
+    );
 
     const {prose, component} = generateThemeCSS(theme);
     if (!prose && !component) {

package/src/theme/generateThemeRules.test.ts

@@ -190,6 +190,61 @@ describe('generateThemeRules', () => {
     expect(rules.some(r => r.includes('.astryx-text.accent'))).toBe(true);
   });
 
+  // --- Size-prop overrides (so `size` beats a themed `type`) ---
+
+  it('emits Text size-prop font-size overrides in the same layer as type rules', () => {
+    // Digit-leading sizes are prefixed (size-2xs); word sizes stay bare.
+    const sizeRule = rules.find(
+      r => r.includes('.astryx-text.size-2xs') && r.includes('font-size'),
+    );
+    expect(sizeRule).toBeDefined();
+    expect(sizeRule).toContain('var(--font-size-2xs)');
+
+    // `xsm` maps to the --font-size-xs token (matches sizeStyles).
+    const xsmRule = rules.find(r => r.includes('.astryx-text.xsm'));
+    expect(xsmRule).toBeDefined();
+    expect(xsmRule).toContain('var(--font-size-xs)');
+
+    // Overrides set only font-size — line-height/family come from `type`.
+    expect(xsmRule).not.toContain('line-height');
+  });
+
+  it('emits a size override for every TextSize value', () => {
+    const sizes = [
+      'size-4xs',
+      'size-3xs',
+      'size-2xs',
+      'xsm',
+      'sm',
+      'base',
+      'lg',
+      'xl',
+      'size-2xl',
+      'size-3xl',
+      'size-4xl',
+    ];
+    for (const cls of sizes) {
+      expect(
+        rules.some(
+          r => r.includes(`.astryx-text.${cls}`) && r.includes('font-size'),
+        ),
+      ).toBe(true);
+    }
+  });
+
+  it('orders size overrides after the themed type font-size rules', () => {
+    // Source order breaks specificity ties within a layer, so the size
+    // override must come after the `.astryx-text.<type>` type rule.
+    const typeIdx = rules.findIndex(
+      r => r.includes('.astryx-text.supporting') && r.includes('font-size'),
+    );
+    const sizeIdx = rules.findIndex(
+      r => r.includes('.astryx-text.size-2xs') && r.includes('font-size'),
+    );
+    expect(typeIdx).toBeGreaterThanOrEqual(0);
+    expect(sizeIdx).toBeGreaterThan(typeIdx);
+  });
+
   // --- Consistency ---
 
   it('generateThemeCSS returns prose and component blocks with @scope', () => {
@@ -202,6 +257,16 @@ describe('generateThemeRules', () => {
       expect(combined).toContain(rule);
     }
   });
+
+  it('routes Text size overrides into the component (astryx-theme) block', () => {
+    // The size override only beats a themed type if it lands in the same
+    // layer as the type rules (astryx-theme / component block), not the
+    // reset-tier prose block.
+    const {prose, component} = generateThemeCSS(theme);
+    expect(component).toContain('.astryx-text.size-2xs');
+    expect(component).toContain('.astryx-text.xsm');
+    expect(prose).not.toContain('.astryx-text.size-2xs');
+  });
 });
 
 describe('generateThemeRules with weight overrides', () => {

package/src/theme/generateThemeRules.ts

@@ -301,6 +301,10 @@ export function generateThemeRules(theme: DefinedTheme): string[] {
   // 4. Prop-level color overrides (for text/heading/link specificity)
   generateColorOverrides(theme.components || {}, parts);
 
+  // 5. Text `size`-prop font-size overrides (so an explicit size beats a
+  //    themed type's font-size across the astryx-base → astryx-theme layers)
+  generateSizeOverrides(theme.components || {}, parts);
+
   // (on-media rules are generated separately — see generateOnMediaCSS)
 
   return parts;
@@ -500,6 +504,58 @@ function generateColorOverrides(
   }
 }
 
+/**
+ * Map a Text `size` prop value to its raw font-size token.
+ * Mirrors `sizeStyles` in `Text/text.stylex.ts` (note `xsm` → `--font-size-xs`).
+ * <!-- SYNC: packages/core/src/Text/text.stylex.ts (sizeStyles) -->
+ */
+const TEXT_SIZE_TOKEN_MAP: Record<string, string> = {
+  '4xs': 'var(--font-size-4xs)',
+  '3xs': 'var(--font-size-3xs)',
+  '2xs': 'var(--font-size-2xs)',
+  xsm: 'var(--font-size-xs)',
+  sm: 'var(--font-size-sm)',
+  base: 'var(--font-size-base)',
+  lg: 'var(--font-size-lg)',
+  xl: 'var(--font-size-xl)',
+  '2xl': 'var(--font-size-2xl)',
+  '3xl': 'var(--font-size-3xl)',
+  '4xl': 'var(--font-size-4xl)',
+};
+
+/**
+ * Generate `size`-prop font-size overrides for the Text component.
+ *
+ * The `size` prop is documented as a font-size override that wins over the
+ * size implied by `type`. Its StyleX class lives in `@layer astryx-base`, but a
+ * theme's per-type font-size rule (`.astryx-text.<type>`) lives in the higher
+ * `@layer astryx-theme`, so the layer cascade let the theme silently shadow
+ * `size` for any `type` the theme styled. Re-emitting the size classes here —
+ * same layer as the type rules, same `.astryx-text.<x>` specificity, later in
+ * source — restores `size` as a real override.
+ *
+ * Only `font-size` is overridden; line-height and other type properties are
+ * intentionally preserved, matching the prop's documented contract.
+ *
+ * Gated on the theme touching `text` (which includes the auto-generated
+ * type-scale rules) — with no theme type rule to beat, the base-layer StyleX
+ * class already wins and no override is needed.
+ */
+function generateSizeOverrides(
+  components: Record<string, unknown>,
+  parts: string[],
+): void {
+  if (!('text' in components)) {
+    return;
+  }
+  for (const [sizeName, sizeValue] of Object.entries(TEXT_SIZE_TOKEN_MAP)) {
+    const suffix = parseStyleKey(`size:${sizeName}`);
+    parts.push(
+      `  ${componentClassSelector('text', suffix)} { font-size: ${sizeValue}; }`,
+    );
+  }
+}
+
 /**
  * Generate theme rules split into component and prose groups.
  *

package/src/theme/hct.ts

@@ -110,7 +110,7 @@ function labToXyz(L: number, a: number, b: number): [number, number, number] {
 // Tone <-> Y (CIE Luminance)
 // =============================================================================
 
-export function toneToY(tone: number): number {
+function toneToY(tone: number): number {
   return labFInv((tone + 16) / 116);
 }
 

package/src/theme/syntax/defineSyntaxTheme.ts

@@ -12,6 +12,7 @@
  */
 
 import {syntaxTokenDefaults, type SyntaxTokenName} from './tokens';
+import {devWarn} from '../../utils/devWarning';
 
 // =============================================================================
 // Types
@@ -139,12 +140,10 @@ export function defineSyntaxTheme(
 ): SyntaxThemeDefinition {
   const missing = ALL_SYNTAX_KEYS.filter(key => !(key in input.tokens));
   if (missing.length > 0) {
-    console.warn(
-      '[Astryx] defineSyntaxTheme("' +
-        input.name +
-        '"): missing tokens: ' +
-        missing.join(', ') +
-        '. All 14 syntax tokens are required.',
+    devWarn(
+      'defineSyntaxTheme',
+      `"${input.name}": missing tokens: ${missing.join(', ')}. ` +
+        `All 14 syntax tokens are required.`,
     );
   }
 

package/src/utils/devWarning.test.ts

@@ -0,0 +1,56 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {afterEach, describe, expect, it, vi} from 'vitest';
+import {
+  devWarn,
+  devError,
+  warnOnce,
+  formatDevMessage,
+  __resetDevWarnings,
+} from './devWarning';
+
+afterEach(() => {
+  __resetDevWarnings();
+  vi.restoreAllMocks();
+});
+
+describe('formatDevMessage', () => {
+  it('formats as "Component: message"', () => {
+    expect(formatDevMessage('Field', 'oops')).toBe('Field: oops');
+  });
+});
+
+describe('devWarn', () => {
+  it('warns in the standardized format and forwards extra args', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const detail = {a: 1};
+    devWarn('Popover', 'no button', detail);
+    expect(warn).toHaveBeenCalledWith('Popover: no button', detail);
+  });
+});
+
+describe('devError', () => {
+  it('errors in the standardized format', () => {
+    const error = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const err = new Error('boom');
+    devError('Table', 'plugin threw:', err);
+    expect(error).toHaveBeenCalledWith('Table: plugin threw:', err);
+  });
+});
+
+describe('warnOnce', () => {
+  it('fires at most once per key', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    warnOnce('k', 'Theme', 'runtime injection');
+    warnOnce('k', 'Theme', 'runtime injection');
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(warn).toHaveBeenCalledWith('Theme: runtime injection');
+  });
+
+  it('fires again for a different key', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    warnOnce('a', 'Theme', 'one');
+    warnOnce('b', 'Theme', 'two');
+    expect(warn).toHaveBeenCalledTimes(2);
+  });
+});

package/src/utils/devWarning.ts

@@ -0,0 +1,102 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file devWarning.ts
+ * @input A component/hook name and a message
+ * @output Standardized `Component: message` console warnings and errors
+ * @position Shared dev-logging utility used across components and hooks
+ *
+ * Standardizes how the design system surfaces information to the builder:
+ * every message reads `Component: message` (e.g. `Field: isOptional and
+ * isRequired are mutually exclusive.`), so the source is always obvious in
+ * the console.
+ *
+ * Prefer the `useDevWarning` hook inside components — it guards against
+ * repeating a warning on every render. These imperative helpers exist for
+ * the non-render contexts a hook can't cover: plain functions, module
+ * initialization, and inside effects.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/utils/index.ts
+ * - /packages/core/src/hooks/useDevWarning.ts (the render-path counterpart)
+ */
+
+const isDev = process.env.NODE_ENV !== 'production';
+
+/** Format a message as `Component: message`. */
+export function formatDevMessage(component: string, message: string): string {
+  return `${component}: ${message}`;
+}
+
+/**
+ * Dev-only `console.warn` in the standardized `Component: message` format.
+ * A no-op in production — warnings are builder guardrails, not shipped noise.
+ * Extra args (e.g. an offending value) are forwarded to `console.warn`.
+ *
+ * @example
+ * ```
+ * devWarn('Popover', 'children must contain a <button>.');
+ * ```
+ */
+export function devWarn(
+  component: string,
+  message: string,
+  ...args: unknown[]
+): void {
+  if (!isDev) {
+    return;
+  }
+  console.warn(formatDevMessage(component, message), ...args);
+}
+
+/**
+ * `console.error` in the standardized `Component: message` format. Unlike
+ * {@link devWarn}, this runs in production too: it reports real runtime
+ * failures (e.g. a thrown callback) that should reach error telemetry.
+ *
+ * @example
+ * ```
+ * devError('Table', 'Plugin at index 0 threw in transform:', error);
+ * ```
+ */
+export function devError(
+  component: string,
+  message: string,
+  ...args: unknown[]
+): void {
+  console.error(formatDevMessage(component, message), ...args);
+}
+
+const warnedKeys = new Set<string>();
+
+/**
+ * Dev-only warning that fires at most once per `key` for the lifetime of the
+ * app. Use for singleton warnings that aren't tied to a component instance —
+ * a missing translation key, a per-theme perf hint, a one-time fallback.
+ * For per-component-instance warnings, use the `useDevWarning` hook instead.
+ *
+ * @example
+ * ```
+ * warnOnce(`theme:${name}`, 'Theme', `"${name}" uses runtime injection.`);
+ * ```
+ */
+export function warnOnce(
+  key: string,
+  component: string,
+  message: string,
+  ...args: unknown[]
+): void {
+  if (!isDev || warnedKeys.has(key)) {
+    return;
+  }
+  warnedKeys.add(key);
+  console.warn(formatDevMessage(component, message), ...args);
+}
+
+/**
+ * Clear `warnOnce` dedup state. Test-only.
+ * @internal
+ */
+export function __resetDevWarnings(): void {
+  warnedKeys.clear();
+}

package/src/utils/index.ts

@@ -42,12 +42,16 @@ export {
   plainDateSetEndOfWeekExclusive,
   plainDateGetWeekNumber,
   plainDateFormat,
+  formatSharedDate,
   DATE_FORMAT_WITH_WEEKDAY,
+  DATE_FORMAT_SHORT_WITH_WEEKDAY,
   DATE_FORMAT_LONG,
   DATE_FORMAT_MONTH_YEAR,
   DATE_FORMAT_SHORT,
   DATE_FORMAT_SHORT_WITH_YEAR,
+  SHARED_DATE_FORMAT_OPTIONS,
 } from './plainDate';
+export type {SharedDateFormat} from './plainDate';
 
 export {
   parseISOTime,
@@ -92,3 +96,5 @@ export {
   toGLFloats,
 } from './color';
 export type {RGBA} from './color';
+
+export {devWarn, devError, warnOnce, formatDevMessage} from './devWarning';

package/src/utils/plainDate.test.ts

@@ -26,6 +26,7 @@ import {
   plainDateSetEndOfWeekExclusive,
   plainDateGetWeekNumber,
   plainDateFormat,
+  formatSharedDate,
   DATE_FORMAT_WITH_WEEKDAY,
 } from './plainDate';
 import type {ISODateString} from './dateTypes';
@@ -521,3 +522,24 @@ describe('plainDateFormat', () => {
     expect(result).toContain('25');
   });
 });
+
+describe('formatSharedDate', () => {
+  const pd: PlainDate = {year: 2026, month: 1, day: 25};
+
+  it('formats the short-month "date" shape', () => {
+    expect(formatSharedDate(pd, 'date')).toBe('Jan 25, 2026');
+  });
+
+  it('formats the long-month "date_long" shape', () => {
+    expect(formatSharedDate(pd, 'date_long')).toBe('January 25, 2026');
+  });
+
+  it('formats the weekday "date_weekday" shape', () => {
+    // 2026-01-25 is a Sunday.
+    expect(formatSharedDate(pd, 'date_weekday')).toBe('Sun, Jan 25, 2026');
+  });
+
+  it('formats the ISO "system_date" shape', () => {
+    expect(formatSharedDate(pd, 'system_date')).toBe('2026-01-25');
+  });
+});

package/src/utils/plainDate.ts

@@ -229,6 +229,15 @@ export const DATE_FORMAT_WITH_WEEKDAY: Intl.DateTimeFormatOptions = {
   day: 'numeric',
 };
 
+// e.g. "Wed, May 21, 2026" (locale-dependent) — short weekday + short month.
+// Backs the shared `date_weekday` format used by both Timestamp and DateInput.
+export const DATE_FORMAT_SHORT_WITH_WEEKDAY: Intl.DateTimeFormatOptions = {
+  weekday: 'short',
+  month: 'short',
+  day: 'numeric',
+  year: 'numeric',
+};
+
 // e.g. "May 21, 2026" (locale-dependent)
 export const DATE_FORMAT_LONG: Intl.DateTimeFormatOptions = {
   year: 'numeric',
@@ -263,3 +272,55 @@ export function plainDateFormat(
     plainDateToDate(pd),
   );
 }
+
+// =============================================================================
+// Shared date-only format vocabulary
+// =============================================================================
+
+/**
+ * The date-only members of Timestamp's `format` vocabulary that a
+ * calendar-date field (no time-of-day) can render. Both Timestamp and
+ * DateInput share these string literals and the mapping below so that the same
+ * literal renders the same date shape in either component.
+ *
+ * - `date`: locale short-month date, e.g. "Mar 21, 2026"
+ * - `date_long`: locale long-month date, e.g. "March 21, 2026"
+ * - `date_weekday`: short weekday + short-month date, e.g. "Wed, Mar 21, 2026"
+ * - `system_date`: ISO 8601 calendar date, e.g. "2026-03-21"
+ */
+export type SharedDateFormat =
+  'date' | 'date_long' | 'date_weekday' | 'system_date';
+
+/**
+ * Intl option bags for the locale-aware shared date members. `system_date` is
+ * intentionally absent — it is emitted as a fixed ISO `YYYY-MM-DD` string, not
+ * via `Intl` — and is handled directly by {@link formatSharedDate}.
+ *
+ * This is the single source of truth consumed by both Timestamp's
+ * `formatTimestamp` switch and DateInput's display path, so the two never
+ * drift for the members they share.
+ */
+export const SHARED_DATE_FORMAT_OPTIONS: Record<
+  Exclude<SharedDateFormat, 'system_date'>,
+  Intl.DateTimeFormatOptions
+> = {
+  date: DATE_FORMAT_SHORT_WITH_YEAR,
+  date_long: DATE_FORMAT_LONG,
+  date_weekday: DATE_FORMAT_SHORT_WITH_WEEKDAY,
+};
+
+/**
+ * Renders a {@link PlainDate} using one of the {@link SharedDateFormat}
+ * members. The shared entry point DateInput uses for the named-format path;
+ * Timestamp maps the same members onto {@link SHARED_DATE_FORMAT_OPTIONS} in
+ * its own `formatTimestamp` switch (its input is a `Date`, not a `PlainDate`).
+ */
+export function formatSharedDate(
+  pd: PlainDate,
+  format: SharedDateFormat,
+): string {
+  if (format === 'system_date') {
+    return plainDateToISO(pd);
+  }
+  return plainDateFormat(pd, SHARED_DATE_FORMAT_OPTIONS[format]);
+}

package/src/utils/types.ts

@@ -12,6 +12,20 @@
  */
 export type SizeValue = number | string;
 
+/**
+ * Resting elevation level for configurable surfaces.
+ *
+ * Maps to the shadow token scale:
+ * - `none` = flat (`box-shadow: none`)
+ * - `low`  = `--shadow-low`
+ * - `med`  = `--shadow-med`
+ * - `high` = `--shadow-high`
+ *
+ * Components narrow this union to the steps they actually need — e.g. Card
+ * exposes all four, while ChatComposer exposes only `'none' | 'low'`.
+ */
+export type Elevation = 'none' | 'low' | 'med' | 'high';
+
 /**
  * Numeric spacing step from the Astryx spacing scale.
  *