@astryxdesign/core 0.1.9 → 0.2.0-canary.068bda9

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/reset.css

@@ -360,32 +360,6 @@
     -webkit-tap-highlight-color: transparent;
   }
 
-  /* ===========================================================================
-     Touch Devices
-     =========================================================================== */
-
-  /*
-   * Suppress focus-visible outlines on touch-only devices.
-   *
-   * Focus rings exist to show keyboard users where focus is. On devices
-   * with no hover capability and a coarse pointer (phones, tablets),
-   * there's no keyboard navigation — focus rings are visual noise that
-   * can flash on tap, on dialog open (showModal auto-focus), or on
-   * programmatic focus.
-   *
-   * This targets touch-only devices specifically:
-   * - (hover: none) — no hover capability (not a mouse)
-   * - (pointer: coarse) — imprecise pointer (finger, not stylus)
-   *
-   * Hybrid devices (laptop with touchscreen) are NOT affected because
-   * their primary pointer is fine (trackpad/mouse) and hover is available.
-   */
-  @media (hover: none) and (pointer: coarse) {
-    :where(:focus-visible) {
-      outline: none;
-    }
-  }
-
   /* ===========================================================================
      Color Scheme
      =========================================================================== */

package/src/reset.test.ts

@@ -0,0 +1,60 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Tests for reset.css invariants that components rely on.
+ *
+ * reset.css is a plain stylesheet, so these tests assert on its source
+ * text (same approach as the reset.css baseline checks in
+ * theme/onMediaTokens.test.ts and AspectRatio/AspectRatio.test.tsx).
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+import {beforeAll, describe, expect, it} from 'vitest';
+
+describe('reset.css accessibility invariants', () => {
+  let ruleBlocks: {selector: string; body: string}[];
+
+  beforeAll(() => {
+    const resetCSS = fs.readFileSync(
+      path.resolve(__dirname, './reset.css'),
+      'utf-8',
+    );
+    // Strip comments, then collect every innermost `selector { body }`
+    // block. `[^{}]` keeps at-rule preludes (@media, @layer) out of the
+    // selector capture, since their own `{` terminates any earlier match.
+    const stripped = resetCSS.replace(/\/\*[\s\S]*?\*\//g, '');
+    ruleBlocks = [...stripped.matchAll(/([^{}]+)\{([^{}]*)\}/g)].map(
+      ([, selector, body]) => ({selector: selector.trim(), body}),
+    );
+  });
+
+  it('parses rule blocks out of reset.css', () => {
+    // Guards the WCAG assertion below against silently passing if the
+    // block parsing ever breaks.
+    expect(ruleBlocks.length).toBeGreaterThan(20);
+    expect(
+      ruleBlocks.some(({body}) => body.includes('box-sizing: border-box')),
+    ).toBe(true);
+  });
+
+  /**
+   * WCAG 2.4.7 (Focus Visible, Level AA): keyboard focus indicators must
+   * not be suppressed. `:focus-visible` only matches keyboard-style focus,
+   * so any `outline: none` on it removes the focus indicator for keyboard
+   * users — and a `@media (hover: none) and (pointer: coarse)` guard does
+   * not exempt keyboard users on coarse-pointer devices (iPad/phone with a
+   * Bluetooth keyboard, switch-control users).
+   */
+  it('does not suppress :focus-visible outlines (WCAG 2.4.7)', () => {
+    const focusVisibleBlocks = ruleBlocks.filter(({selector}) =>
+      selector.includes(':focus-visible'),
+    );
+    for (const {selector, body} of focusVisibleBlocks) {
+      expect
+        .soft(body, `":focus-visible" rule "${selector}" must keep the outline`)
+        .not.toMatch(/outline(?:-style|-width)?\s*:\s*(?:none|0)/);
+    }
+  });
+});

package/src/theme/derivedVarRegistry.test.ts

@@ -186,6 +186,7 @@ function discoverComponents(): ComponentInfo[] {
 // ---------------------------------------------------------------------------
 
 const DIR_TO_REGISTRY_KEY: Record<string, string> = {
+  Avatar: 'avatar',
   Banner: 'banner',
   Button: 'button',
   Card: 'card',

package/src/theme/derivedVarRegistry.ts

@@ -35,6 +35,12 @@ export interface DerivedVarEntry {
  * entries share the same property.
  */
 export const derivedVarRegistry: Record<string, DerivedVarEntry[]> = {
+  avatar: [
+    {property: 'fontSize', vars: ['--_avatar-fallback-font-size']},
+    {property: 'fontWeight', vars: ['--_avatar-fallback-font-weight']},
+    {property: 'color', vars: ['--_avatar-fallback-color']},
+    {property: 'backgroundColor', vars: ['--_avatar-fallback-background']},
+  ],
   banner: [{property: 'borderRadius', vars: ['--_banner-radius']}],
   button: [{property: 'borderRadius', vars: ['--_button-radius']}],
   card: [

package/src/theme/generateThemeRules.test.ts

@@ -385,6 +385,48 @@ describe('derived var expansion', () => {
     expect(rule).toContain('--_button-radius: 8px');
   });
 
+  it('emits internal vars for avatar fallback typography (base)', () => {
+    const theme = defineTheme({
+      name: 'test-derived-avatar',
+      components: {
+        avatar: {
+          base: {
+            fontWeight: 'var(--font-weight-normal)',
+            color: 'var(--color-text-secondary)',
+            backgroundColor: 'var(--color-accent-muted)',
+          },
+        },
+      },
+    });
+    const rules = generateThemeRules(theme);
+    const rule = rules.find(r => r.includes('.astryx-avatar'));
+    expect(rule).toBeDefined();
+    expect(rule).toContain(
+      '--_avatar-fallback-font-weight: var(--font-weight-normal)',
+    );
+    expect(rule).toContain(
+      '--_avatar-fallback-color: var(--color-text-secondary)',
+    );
+    expect(rule).toContain(
+      '--_avatar-fallback-background: var(--color-accent-muted)',
+    );
+  });
+
+  it('emits a per-size fallback font-size for avatar (size:sm)', () => {
+    const theme = defineTheme({
+      name: 'test-derived-avatar-size',
+      components: {
+        avatar: {
+          'size:sm': {fontSize: '9px'},
+        },
+      },
+    });
+    const rules = generateThemeRules(theme);
+    const rule = rules.find(r => r.includes('.astryx-avatar.sm'));
+    expect(rule).toBeDefined();
+    expect(rule).toContain('--_avatar-fallback-font-size: 9px');
+  });
+
   it('does not emit derived vars for components without registry entries', () => {
     const theme = defineTheme({
       name: 'test-no-derived',

package/src/theme/index.ts

@@ -71,19 +71,13 @@ export {expandTypeScale, generateTypeScaleComponents} from './expandTypeScale';
 export type {TypeScaleConfig, TypeScaleTokens} from './expandTypeScale';
 
 export {expandRadiusScale} from './expandRadiusScale';
-export type {
-  RadiusScaleConfig,
-  RadiusScaleTokens,
-} from './expandRadiusScale';
+export type {RadiusScaleConfig, RadiusScaleTokens} from './expandRadiusScale';
 
 export {expandColorScale} from './expandColorScale';
 export type {ColorScaleConfig, ColorScaleTokens} from './expandColorScale';
 
 export {expandMotionScale} from './expandMotionScale';
-export type {
-  MotionScaleConfig,
-  MotionScaleTokens,
-} from './expandMotionScale';
+export type {MotionScaleConfig, MotionScaleTokens} from './expandMotionScale';
 
 // Export token defaults and vars for use in custom components and themes
 export {
@@ -155,6 +149,8 @@ export type {
   TextSize,
   TextWeight,
   TextColor,
+  BuiltinTextColor,
+  TextColorMap,
   TypographyConfig,
   TypographyRole,
   FontWeight,

package/src/theme/types.ts

@@ -15,11 +15,7 @@
  * Raw CSS values (e.g. '800') are accepted as an escape hatch.
  */
 export type FontWeight =
-  | 'normal'
-  | 'medium'
-  | 'semibold'
-  | 'bold'
-  | (string & {});
+  'normal' | 'medium' | 'semibold' | 'bold' | (string & {});
 
 /**
  * A typography role declaration (body, heading, or code).
@@ -155,15 +151,49 @@ export type TextSize =
 export type TextWeight = 'normal' | 'medium' | 'semibold' | 'bold';
 
 /**
- * Text color variants for Text/Heading
+ * Extensible map of text color variants for Text/Heading.
+ *
+ * Themes add custom colors via component overrides in defineTheme; a custom
+ * color renders with the `primary` baseline color from StyleX and receives its
+ * actual color from theme CSS (`.astryx-text.<color>` / `.astryx-heading.<color>`),
+ * exactly like custom text `type`s.
+ *
+ * To add type-safe custom colors, use module augmentation — the same technique
+ * as `ButtonVariantMap` etc.:
+ * ```ts
+ * declare module '@astryxdesign/core/Text' {
+ *   interface TextColorMap {
+ *     brand: true;
+ *     danger: true;
+ *   }
+ * }
+ * ```
+ *
+ * `astryx theme build` generates these augmentations automatically when it
+ * detects new `color:*` values in a theme's Text/Heading component overrides.
  */
-export type TextColor =
-  | 'primary'
-  | 'secondary'
-  | 'disabled'
-  | 'placeholder'
-  | 'accent'
-  | 'inherit';
+export interface TextColorMap {
+  primary: true;
+  secondary: true;
+  disabled: true;
+  placeholder: true;
+  accent: true;
+  inherit: true;
+}
+
+/**
+ * Built-in text color variants for Text/Heading. The concrete keys that ship
+ * with the design system, independent of theme augmentation — used where a
+ * value must be one of the real StyleX color styles (see `resolveStyleColor`).
+ */
+export type BuiltinTextColor =
+  'primary' | 'secondary' | 'disabled' | 'placeholder' | 'accent' | 'inherit';
+
+/**
+ * Text color variants for Text/Heading. Extensible via module augmentation of
+ * `TextColorMap`.
+ */
+export type TextColor = keyof TextColorMap;
 
 /**
  * Display mode for Text/Heading

package/src/utils/index.ts

@@ -98,3 +98,5 @@ export {
 export type {RGBA} from './color';
 
 export {devWarn, devError, warnOnce, formatDevMessage} from './devWarning';
+
+export {rtlStyles} from './rtlStyles';

package/src/utils/plainDate.test.ts

@@ -235,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,
     });
   });
 });

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 {
@@ -83,7 +88,16 @@ export function plainDateAddDays(pd: PlainDate, n: number): PlainDate {
   return plainDateFromDate(d);
 }
 
-function getTimeZoneParts(
+/**
+ * The wall-clock fields an instant reads as in a given zone.
+ *
+ * A fixed `'en-US'` locale with `hourCycle: 'h23'` keeps the parts numeric and
+ * stable whatever locale the viewer has, so callers can assemble machine
+ * shapes (`YYYY-MM-DD`, `HH:mm:ss`) from them. Exported for Timestamp, whose
+ * `system_*` formats are built from these fields rather than through `Intl`
+ * formatting.
+ */
+export function getTimeZoneParts(
   instant: number,
   timezoneID: string,
 ): {

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/dist/Thumbnail/thumbnail.markers.stylex.d.ts

@@ -1,9 +0,0 @@
-import * as stylex from '@stylexjs/stylex';
-/**
- * Scoped marker for Thumbnail ancestor selectors. Applied to the image
- * container so the remove button's hover/focus reveal (`showRemoveOn="hover"`)
- * responds only to this thumbnail — not to hover/focus state from an outer
- * container the thumbnail happens to sit inside.
- */
-export declare const thumbnailScope: ReturnType<typeof stylex.defineMarker>;
-//# sourceMappingURL=thumbnail.markers.stylex.d.ts.map

package/dist/Thumbnail/thumbnail.markers.stylex.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"thumbnail.markers.stylex.d.ts","sourceRoot":"","sources":["../../src/Thumbnail/thumbnail.markers.stylex.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAE3C;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,UAAU,CAAC,OAAO,MAAM,CAAC,YAAY,CAC3C,CAAC"}

package/dist/Thumbnail/thumbnail.markers.stylex.js

@@ -1,14 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-import * as stylex from '@stylexjs/stylex';
-
-/**
- * Scoped marker for Thumbnail ancestor selectors. Applied to the image
- * container so the remove button's hover/focus reveal (`showRemoveOn="hover"`)
- * responds only to this thumbnail — not to hover/focus state from an outer
- * container the thumbnail happens to sit inside.
- */
-export const thumbnailScope = {
-  x9jk0ni: "x9jk0ni",
-  $$css: true
-};

package/src/Thumbnail/thumbnail.markers.stylex.ts

@@ -1,12 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-import * as stylex from '@stylexjs/stylex';
-
-/**
- * Scoped marker for Thumbnail ancestor selectors. Applied to the image
- * container so the remove button's hover/focus reveal (`showRemoveOn="hover"`)
- * responds only to this thumbnail — not to hover/focus state from an outer
- * container the thumbnail happens to sit inside.
- */
-export const thumbnailScope: ReturnType<typeof stylex.defineMarker> =
-  stylex.defineMarker();