@astryxdesign/core 0.5.0 → 0.5.1-canary.046f6ea

package/src/utils/dateParser.ts

@@ -23,10 +23,10 @@ export {
  * Detects if the locale uses day-first date format (DD/MM/YYYY).
  * US and a few others use month-first (MM/DD/YYYY).
  */
-export function isLocaleDayFirst(locale?: Locale): boolean {
-  const parts = new Intl.DateTimeFormat(locale).formatToParts(
-    new Date(2000, 0, 15),
-  );
+export function isLocaleDayFirst(locale: Locale = 'en'): boolean {
+  const parts = new Intl.DateTimeFormat(locale, {
+    calendar: 'gregory',
+  }).formatToParts(new Date(2000, 0, 15));
   const dayIndex = parts.findIndex(p => p.type === 'day');
   const monthIndex = parts.findIndex(p => p.type === 'month');
   return dayIndex < monthIndex;
@@ -35,20 +35,17 @@ export function isLocaleDayFirst(locale?: Locale): boolean {
 /**
  * Parses user input into a PlainDate.
  *
- * Supports:
- * - ISO format: "2026-01-25"
- * - Full month names: "January 25, 2026", "25 January 2026"
- * - Full month names without year: "January 25", "25 January" (defaults to current year)
- * - Numeric formats: "1/25/2026", "25/1/2026" (locale-aware with heuristics)
- * - Numeric formats without year: "1/25", "25/1" (defaults to current year)
- *
- * For ambiguous numeric formats (both numbers ≤ 12), uses locale preference.
+ * Supports ISO dates, English month names, and ASCII numeric dates with or
+ * without a year. For ambiguous ASCII numeric input where both fields are at
+ * most 12, `locale` selects month-first versus day-first order. It does not
+ * localize month-name parsing, accept non-ASCII digits, or provide a general
+ * locale-aware parser.
  *
  * @returns PlainDate if valid, null if unparseable
  */
 export function parseDateInput(
   input: string,
-  locale?: Locale,
+  locale: Locale = 'en',
 ): PlainDate | null {
   const trimmed = input.trim();
   if (!trimmed) {
@@ -157,7 +154,7 @@ function parseNumericDate(
   first: number,
   second: number,
   year: number,
-  locale?: Locale,
+  locale: Locale,
 ): PlainDate | null {
   let day: number;
   let month: number;

package/src/utils/focusOutline.stylex.ts

@@ -124,6 +124,52 @@ export const focusOutlineStyles = stylex.create({
     },
     outlineOffset: {default: '0', ':has(:focus-visible)': FOCUS_OUTLINE_OFFSET},
   },
+  /**
+   * Like {@link focusOutlineStyles.focusWithin}, but only for the element's
+   * FIRST child — for a wrapper that paints the ring on behalf of one primary
+   * control while its siblings ring themselves.
+   *
+   * `focusWithin` matches any descendant, so a row holding more than one tab
+   * stop lights the whole row *on top of* the focused control's own ring: two
+   * outlines for one tab stop. Scoping to `> :first-child` keeps the ring the
+   * primary's, and leaves every sibling control ringing itself.
+   *
+   * The wrapper owns the coupling: the primary has to be its first child, and
+   * the wrapper must not be a tab stop (its own `:focus-visible` would never
+   * match). Pair it with {@link focusOutlineStyles.suppressed} on the primary.
+   */
+  focusWithinFirstChild: {
+    outlineWidth: {
+      default: '0',
+      ':has(> :first-child:focus-visible)': focusOutlineLonghands.outlineWidth,
+    },
+    outlineStyle: {
+      default: 'none',
+      ':has(> :first-child:focus-visible)': focusOutlineLonghands.outlineStyle,
+    },
+    outlineColor: {
+      default: null,
+      ':has(> :first-child:focus-visible)': focusOutlineLonghands.outlineColor,
+    },
+    outlineOffset: {
+      default: '0',
+      ':has(> :first-child:focus-visible)': FOCUS_OUTLINE_OFFSET,
+    },
+  },
+  /**
+   * Draws no ring, and keeps the UA's own off — for an element whose ring an
+   * ancestor paints.
+   *
+   * The reset is not optional. Every other style here suppresses the browser
+   * default through its `default` branch, so dropping the ring from a control
+   * drops that suppression with it, and a bare `<a>` or `<button>` goes back
+   * to the UA focus ring — painted *inside* the ancestor's.
+   */
+  suppressed: {
+    outlineWidth: '0',
+    outlineStyle: 'none',
+    outlineOffset: '0',
+  },
   publishFocusVisibleVars: {
     '--_focus-outline': {
       default: 'none',
@@ -168,6 +214,10 @@ function makeFocusOutlineProps(style: StyleXPropsArg) {
 export const focusOutlineProps = {
   focusVisible: makeFocusOutlineProps(focusOutlineStyles.focusVisible),
   focusWithin: makeFocusOutlineProps(focusOutlineStyles.focusWithin),
+  focusWithinFirstChild: makeFocusOutlineProps(
+    focusOutlineStyles.focusWithinFirstChild,
+  ),
+  suppressed: makeFocusOutlineProps(focusOutlineStyles.suppressed),
   publishFocusVisibleVars: makeFocusOutlineProps(
     focusOutlineStyles.publishFocusVisibleVars,
   ),

package/src/utils/interactionOverlay.stylex.ts

@@ -0,0 +1,74 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/* eslint-disable @astryx/no-hover-on-disabled -- Every hover branch is
+ * nested beneath ENABLED below. Keeping that shared guard outside the media
+ * branch is what gives hover and active matching generated specificity. */
+
+/**
+ * @file Shared hover and pressed overlay states
+ * @input Uses StyleX and the semantic interaction-overlay color tokens
+ * @output Exports reusable background-color and background-image state styles
+ * @position Internal styling utility for interactive core surfaces
+ *
+ * Keep the enabled guard outside the individual states. StyleX assigns an
+ * extra priority bucket (and generated selector specificity) to media-nested
+ * rules. Repeating `:active` inside the hover-capable branch gives hover and
+ * press the same generated specificity; StyleX's native pseudo-state ordering
+ * then emits `:active` last. The bare `:active` branch remains the touch
+ * fallback, where `(hover: hover)` does not match.
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import {colorVars} from '../theme/tokens.stylex';
+
+const ENABLED = ':where(:not(:disabled,[aria-disabled="true"]))';
+const HOVER_HOVER = '@media (hover: hover)';
+
+const hoverImage = `linear-gradient(${colorVars['--color-overlay-hover']}, ${colorVars['--color-overlay-hover']})`;
+const pressedImage = `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`;
+const neutralImage = `linear-gradient(${colorVars['--color-neutral']}, ${colorVars['--color-neutral']})`;
+
+export const interactionOverlayStyles = stylex.create({
+  backgroundColor: {
+    backgroundColor: {
+      default: 'transparent',
+      [ENABLED]: {
+        default: null,
+        ':active': colorVars['--color-overlay-pressed'],
+        [HOVER_HOVER]: {
+          default: null,
+          ':hover': colorVars['--color-overlay-hover'],
+          ':active': colorVars['--color-overlay-pressed'],
+        },
+      },
+    },
+  },
+  backgroundImage: {
+    backgroundImage: {
+      default: null,
+      [ENABLED]: {
+        default: null,
+        ':active': pressedImage,
+        [HOVER_HOVER]: {
+          default: null,
+          ':hover': hoverImage,
+          ':active': pressedImage,
+        },
+      },
+    },
+  },
+  backgroundImageOnNeutral: {
+    backgroundImage: {
+      default: neutralImage,
+      [ENABLED]: {
+        default: null,
+        ':active': `${pressedImage}, ${neutralImage}`,
+        [HOVER_HOVER]: {
+          default: null,
+          ':hover': `${hoverImage}, ${neutralImage}`,
+          ':active': `${pressedImage}, ${neutralImage}`,
+        },
+      },
+    },
+  },
+});

package/src/utils/isApplePlatform.test.ts

@@ -0,0 +1,61 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file isApplePlatform.test.ts
+ * @input Uses vitest, isApplePlatform
+ * @output Unit tests for isApplePlatform
+ * @position Testing; validates isApplePlatform.ts implementation
+ */
+
+import {describe, it, expect, vi, afterEach} from 'vitest';
+import {isApplePlatform} from './isApplePlatform';
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe('isApplePlatform', () => {
+  it('trusts a client-hints platform that names one', () => {
+    vi.stubGlobal('navigator', {
+      userAgentData: {platform: 'macOS'},
+      platform: 'Win32',
+    });
+    expect(isApplePlatform()).toBe(true);
+
+    vi.stubGlobal('navigator', {
+      userAgentData: {platform: 'Windows'},
+      platform: 'MacIntel',
+    });
+    expect(isApplePlatform()).toBe(false);
+  });
+
+  it.each([
+    ['blank', ''],
+    ['whitespace', '   '],
+    ['the spec Unknown sentinel', 'Unknown'],
+    ['unknown in any case', 'UNKNOWN'],
+    ['a non-string', null],
+  ])('falls through to navigator.platform on %s', (_label, platform) => {
+    vi.stubGlobal('navigator', {
+      userAgentData: {platform},
+      platform: 'MacIntel',
+    });
+    expect(isApplePlatform()).toBe(true);
+
+    vi.stubGlobal('navigator', {userAgentData: {platform}, platform: 'Win32'});
+    expect(isApplePlatform()).toBe(false);
+  });
+
+  it('falls back to navigator.platform when client hints are absent', () => {
+    vi.stubGlobal('navigator', {platform: 'iPhone'});
+    expect(isApplePlatform()).toBe(true);
+
+    vi.stubGlobal('navigator', {platform: 'Linux x86_64'});
+    expect(isApplePlatform()).toBe(false);
+  });
+
+  it('answers false when there is no navigator at all', () => {
+    vi.stubGlobal('navigator', undefined);
+    expect(isApplePlatform()).toBe(false);
+  });
+});

package/src/utils/isApplePlatform.ts

@@ -0,0 +1,37 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file isApplePlatform.ts
+ * @input Reads navigator.userAgentData.platform and navigator.platform
+ * @output Exports isApplePlatform
+ * @position Internal util; the single platform detection behind useHotkeys and Kbd
+ *
+ * Deliberately absent from utils/index.ts: packages/core/src/index.ts does
+ * `export * from './utils'`, so naming it there would publish it as API.
+ * Import it by path, as interactionModality is imported.
+ */
+
+/**
+ * Detects whether the current platform is macOS/iOS.
+ * Prefers the User-Agent Client Hints API when it names a platform (modern
+ * Chrome/Edge), falls back to navigator.platform (deprecated but universally
+ * supported) when it names none.
+ */
+export function isApplePlatform(): boolean {
+  if (typeof navigator === 'undefined') {
+    return false;
+  }
+  const uaData = 'userAgentData' in navigator ? navigator.userAgentData : null;
+  if (uaData && typeof uaData === 'object' && 'platform' in uaData) {
+    const uaPlatform = (uaData as {platform?: unknown}).platform;
+    const named = typeof uaPlatform === 'string' ? uaPlatform.trim() : '';
+    // A value that names nothing is no answer, not a negative one: builds that
+    // rewrite their client-hints identity ship '', and 'Unknown' is the spec's
+    // own sentinel for "cannot say". Both fall through rather than reading as
+    // "not Apple".
+    if (named !== '' && named.toLowerCase() !== 'unknown') {
+      return /mac/i.test(named);
+    }
+  }
+  return /Mac|iPhone|iPad|iPod/.test(navigator.platform ?? '');
+}

package/src/utils/plainDate.test.ts

@@ -29,6 +29,7 @@ import {
   plainDateFormat,
   formatSharedDate,
   DATE_FORMAT_WITH_WEEKDAY,
+  DATE_FORMAT_MONTH_YEAR,
 } from './plainDate';
 import type {ISODateString} from './dateTypes';
 
@@ -589,6 +590,51 @@ describe('plainDateFormat', () => {
     expect(result).toContain('2026');
     expect(result).toContain('25');
   });
+
+  it('defaults to en when the locale is omitted', () => {
+    expect(
+      plainDateFormat({year: 2026, month: 8, day: 22}, DATE_FORMAT_MONTH_YEAR),
+    ).toBe('August 2026');
+  });
+
+  it('honors an explicit locale', () => {
+    expect(
+      plainDateFormat(
+        {year: 2026, month: 8, day: 22},
+        DATE_FORMAT_MONTH_YEAR,
+        'fr',
+      ),
+    ).toBe('août 2026');
+  });
+
+  it('matches an explicit en locale when the locale is omitted', () => {
+    const pd: PlainDate = {year: 2026, month: 8, day: 22};
+    for (const options of [DATE_FORMAT_MONTH_YEAR, DATE_FORMAT_WITH_WEEKDAY]) {
+      expect(plainDateFormat(pd, options)).toBe(
+        plainDateFormat(pd, options, 'en'),
+      );
+    }
+  });
+
+  it('uses Gregorian fields for a non-Gregorian locale extension', () => {
+    expect(
+      plainDateFormat(
+        {year: 2026, month: 8, day: 22},
+        {year: 'numeric'},
+        'en-US-u-ca-buddhist',
+      ),
+    ).toBe('2026');
+  });
+
+  it('honors an explicitly requested calendar for compatibility', () => {
+    expect(
+      plainDateFormat(
+        {year: 2026, month: 8, day: 22},
+        {year: 'numeric', calendar: 'buddhist'},
+        'en-US',
+      ),
+    ).toBe('2569 BE');
+  });
 });
 
 describe('formatSharedDate', () => {

package/src/utils/plainDate.ts

@@ -130,6 +130,7 @@ export function getTimeZoneParts(
     minute: '2-digit',
     second: '2-digit',
     hourCycle: 'h23',
+    calendar: 'gregory',
   }).formatToParts(new Date(instant));
 
   const lookup = Object.fromEntries(
@@ -307,12 +308,26 @@ export const DATE_FORMAT_SHORT_WITH_YEAR: Intl.DateTimeFormatOptions = {
   year: 'numeric',
 };
 
+/**
+ * Format a `PlainDate` for display.
+ *
+ * The locale defaults to the same `'en'` fallback as `useLocale()`, avoiding
+ * runtime-dependent output when no provider locale is available. Astryx date
+ * APIs currently model Gregorian dates, so this helper defaults to Gregorian
+ * when `options.calendar` is omitted. The explicit option remains supported for
+ * compatibility with the public `Intl.DateTimeFormatOptions` signature; it is a
+ * display-only escape hatch and does not change PlainDate arithmetic, parsing,
+ * serialization, or any Astryx component's calendar semantics.
+ */
 export function plainDateFormat(
   pd: PlainDate,
   options: Intl.DateTimeFormatOptions,
-  locale?: Locale,
+  locale: Locale = 'en',
 ): string {
-  return new Intl.DateTimeFormat(locale, options).format(plainDateToDate(pd));
+  return new Intl.DateTimeFormat(locale, {
+    ...options,
+    calendar: options.calendar ?? 'gregory',
+  }).format(plainDateToDate(pd));
 }
 
 // =============================================================================
@@ -360,7 +375,7 @@ export const SHARED_DATE_FORMAT_OPTIONS: Record<
 export function formatSharedDate(
   pd: PlainDate,
   format: SharedDateFormat,
-  locale?: Locale,
+  locale: Locale = 'en',
 ): string {
   if (format === 'system_date') {
     return plainDateToISO(pd);