@astryxdesign/core 0.1.8 → 0.1.9-canary.02ef052

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,7 @@ export {
   toGLFloats,
 } from './color';
 export type {RGBA} from './color';
+
+export {devWarn, devError, warnOnce, formatDevMessage} from './devWarning';
+
+export {rtlStyles} from './rtlStyles';

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';
@@ -234,19 +235,37 @@ describe('plainDateAddMonths', () => {
     });
   });
 
-  it('overflows day into next month when target month is shorter', () => {
+  it('clamps to the last day when the target month is shorter', () => {
+    // Jan 31 + 1 month lands in February (clamped), not overflowed into
+    // March — matching Temporal.PlainDate.add and date-fns addMonths.
     expect(plainDateAddMonths({year: 2026, month: 1, day: 31}, 1)).toEqual({
       year: 2026,
-      month: 3,
-      day: 3,
+      month: 2,
+      day: 28,
     });
   });
 
-  it('overflows Jan 31 + 1 month in leap year', () => {
+  it('clamps to Feb 29 in a leap year', () => {
     expect(plainDateAddMonths({year: 2024, month: 1, day: 31}, 1)).toEqual({
       year: 2024,
-      month: 3,
-      day: 2,
+      month: 2,
+      day: 29,
+    });
+  });
+
+  it('clamps when subtracting into a shorter month', () => {
+    expect(plainDateAddMonths({year: 2026, month: 3, day: 31}, -1)).toEqual({
+      year: 2026,
+      month: 2,
+      day: 28,
+    });
+  });
+
+  it('clamps a 31st onto a 30-day month', () => {
+    expect(plainDateAddMonths({year: 2026, month: 5, day: 31}, 1)).toEqual({
+      year: 2026,
+      month: 6,
+      day: 30,
     });
   });
 });
@@ -521,3 +540,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

@@ -72,9 +72,14 @@ export function plainDateDayOfWeek(pd: PlainDate): number {
 }
 
 export function plainDateAddMonths(pd: PlainDate, n: number): PlainDate {
-  const d = plainDateToDate(pd);
-  d.setMonth(d.getMonth() + n);
-  return plainDateFromDate(d);
+  // Pure month arithmetic with day clamping (Temporal.PlainDate.add
+  // semantics): Jan 31 + 1 month is Feb 28/29, not Mar 2/3. Date#setMonth
+  // would overflow the excess days into the following month instead.
+  const totalMonths = pd.year * 12 + (pd.month - 1) + n;
+  const year = Math.floor(totalMonths / 12);
+  const month = (((totalMonths % 12) + 12) % 12) + 1;
+  const day = Math.min(pd.day, getDaysInMonth(year, month));
+  return {year, month, day};
 }
 
 export function plainDateAddDays(pd: PlainDate, n: number): PlainDate {
@@ -229,6 +234,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 +277,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/rtlStyles.ts

@@ -0,0 +1,27 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file rtlStyles.ts
+ * @input None
+ * @output Shared StyleX style that horizontally mirrors an element under RTL
+ * @position Core utility; applied to directional-icon wrappers in Calendar,
+ *   Lightbox, and the Table expand/disclosure plugins
+ *
+ * `mirror` flips its element on the horizontal axis only when an ancestor
+ * carries `dir="rtl"`. Using `scaleX(-1)` (not `scale(-1, -1)`) keeps the
+ * vertical axis intact, and applying it OUTSIDE any state-driven rotation lets
+ * it compose correctly — e.g. a Table disclosure chevron still rotates to point
+ * down when expanded under RTL. The `:is([dir="rtl"] *)` selector matches the
+ * MobileNav drawer convention; a bare `direction: rtl` alone won't trigger it.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/utils/index.ts
+ */
+
+import * as stylex from '@stylexjs/stylex';
+
+export const rtlStyles = stylex.create({
+  mirror: {
+    transform: {default: null, ':is([dir="rtl"] *)': 'scaleX(-1)'},
+  },
+});

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.
  *