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

package/src/Calendar/hooks/useCalendarDays.ts

@@ -4,7 +4,7 @@
 
 /**
  * @file useCalendarDays.ts
- * @input Uses React context via use(), useMemo, PlainDate utilities, generated CLDR weekday data
+ * @input Uses React useMemo, useLocale, PlainDate utilities, generated CLDR weekday data
  * @output Exports useCalendarDays hook for generating calendar day grids
  * @position Calendar-specific hook; used by Calendar
  *
@@ -12,7 +12,7 @@
  * - /packages/core/src/Calendar/hooks/index.ts
  */
 
-import {use, useMemo} from 'react';
+import {useMemo} from 'react';
 import type {DayOfWeek, ISODateString} from '../../utils/dateTypes';
 import {
   type PlainDate,
@@ -21,7 +21,7 @@ import {
   plainDateDayOfWeek,
   plainDateAddDays,
 } from '../../utils/plainDate';
-import {InternationalizationContext} from '../../i18n/InternationalizationContext';
+import {useLocale} from '../../i18n';
 import {getStandaloneShortWeekdayNames} from '../getStandaloneShortWeekdayNames';
 
 /**
@@ -86,7 +86,7 @@ export function useCalendarDays(
   options: UseCalendarDaysOptions,
 ): UseCalendarDaysReturn {
   const {year, month, weekStartsOn = 0, hasVariableRowCount = false} = options;
-  const {locale} = use(InternationalizationContext);
+  const locale = useLocale();
 
   // Calculate grid structure
   const gridInfo = useMemo(() => {

package/src/Calendar/hooks/useCalendarNavigation.ts

@@ -4,7 +4,7 @@
 
 /**
  * @file useCalendarNavigation.ts
- * @input Uses React useState, useMemo, useCallback, PlainDate utilities
+ * @input Uses React useState, useMemo, useCallback, useLocale, PlainDate utilities
  * @output Exports useCalendarNavigation hook for month navigation
  * @position Calendar-specific hook; used by Calendar
  *
@@ -12,7 +12,7 @@
  * - /packages/core/src/Calendar/hooks/index.ts
  */
 
-import {use, useState, useMemo, useCallback} from 'react';
+import {useState, useMemo, useCallback} from 'react';
 import type {ISODateString} from '../../utils/dateTypes';
 import {
   type PlainDate,
@@ -25,7 +25,7 @@ import {
   plainDateFormat,
   DATE_FORMAT_MONTH_YEAR,
 } from '../../utils/plainDate';
-import {InternationalizationContext} from '../../i18n';
+import {useLocale} from '../../i18n';
 
 /**
  * Configuration for calendar navigation
@@ -99,7 +99,7 @@ export function useCalendarNavigation(
     onFocusDateChange,
     numberOfMonths = 1,
   } = options;
-  const {locale} = use(InternationalizationContext);
+  const locale = useLocale();
 
   // Pending focus target after month navigation
   const [pendingFocus, setPendingFocus] = useState<ISODateString | null>(null);

package/src/Calendar/styles.ts

@@ -51,19 +51,12 @@ export const calendarStyles = stylex.create({
   },
   monthsContainer: {
     display: 'flex',
+    // Wraps rather than overflowing: two months side by side need ~488px, so
+    // an unwrapped row scrolls the document sideways below that and puts the
+    // next-month button off-viewport (WCAG 1.4.10). Above 488px nothing moves.
+    flexWrap: 'wrap',
     gap: spacingVars['--spacing-4'],
   },
-  srOnly: {
-    position: 'absolute',
-    width: '1px',
-    height: '1px',
-    padding: 0,
-    margin: '-1px',
-    overflow: 'hidden',
-    clip: 'rect(0, 0, 0, 0)',
-    whiteSpace: 'nowrap',
-    borderWidth: 0,
-  },
   /**
    * Wrapper for the month nav chevrons. RTL mirroring is applied by
    * composing the shared `rtlStyles.mirror` transform onto this wrapper
@@ -123,6 +116,17 @@ export const monthGridStyles = stylex.create({
 // Day Cell Styles - Structural (layout, sizing, positioning)
 // =============================================================================
 
+// Half the gap between the day button and its cell — (--size-element-md minus
+// --size-element-sm) / 2 — so the band's rounded caps line up with the button
+// and the button's ::before bleeds out to meet its neighbour's. Deliberately a
+// literal and NOT a spacing token: this is a layout value derived from the two
+// size tokens, and pinning it to --spacing-0-5 desynchronises it from them
+// (matcha sets that step to 3px, which overlaps adjacent days' hit targets by
+// 2px). Deriving it with calc() from the size tokens would be better still and
+// would close butter's 4px dead gap; that needs its own measured change.
+const BAND_INSET = '2px';
+const HIT_BLEED = '-2px';
+
 export const dayCellStyles = stylex.create({
   // Cell container
   cell: {
@@ -137,53 +141,53 @@ export const dayCellStyles = stylex.create({
   // Range background - structural positioning
   rangeBg: {
     position: 'absolute',
-    top: '2px',
-    bottom: '2px',
+    top: BAND_INSET,
+    bottom: BAND_INSET,
     insetInlineStart: 0,
     insetInlineEnd: 0,
   },
   rangeBgRadiusStart: {
-    insetInlineStart: '2px',
+    insetInlineStart: BAND_INSET,
     borderStartStartRadius: radiusVars['--radius-full'],
     borderEndStartRadius: radiusVars['--radius-full'],
   },
   rangeBgRadiusEnd: {
-    insetInlineEnd: '2px',
+    insetInlineEnd: BAND_INSET,
     borderStartEndRadius: radiusVars['--radius-full'],
     borderEndEndRadius: radiusVars['--radius-full'],
   },
   rangeInsetStart: {
-    insetInlineStart: '2px',
+    insetInlineStart: BAND_INSET,
   },
   rangeInsetEnd: {
-    insetInlineEnd: '2px',
+    insetInlineEnd: BAND_INSET,
   },
 
   // Preview background - structural positioning
   previewBg: {
     position: 'absolute',
-    top: '2px',
-    bottom: '2px',
+    top: BAND_INSET,
+    bottom: BAND_INSET,
     insetInlineStart: 0,
     insetInlineEnd: 0,
   },
   previewBgRadiusStart: {
-    insetInlineStart: '2px',
+    insetInlineStart: BAND_INSET,
     borderStartStartRadius: radiusVars['--radius-full'],
     borderEndStartRadius: radiusVars['--radius-full'],
   },
   previewBgRadiusEnd: {
-    insetInlineEnd: '2px',
+    insetInlineEnd: BAND_INSET,
     borderStartEndRadius: radiusVars['--radius-full'],
     borderEndEndRadius: radiusVars['--radius-full'],
   },
   previewStart: {
-    insetInlineStart: '2px',
+    insetInlineStart: BAND_INSET,
     borderStartStartRadius: radiusVars['--radius-full'],
     borderEndStartRadius: radiusVars['--radius-full'],
   },
   previewEnd: {
-    insetInlineEnd: '2px',
+    insetInlineEnd: BAND_INSET,
     borderStartEndRadius: radiusVars['--radius-full'],
     borderEndEndRadius: radiusVars['--radius-full'],
   },
@@ -195,7 +199,7 @@ export const dayCellStyles = stylex.create({
     display: 'flex',
     alignItems: 'center',
     justifyContent: 'center',
-    borderRadius: '50%',
+    borderRadius: radiusVars['--radius-full'],
     borderWidth: 0,
     borderStyle: 'none',
     cursor: {
@@ -213,14 +217,14 @@ export const dayCellStyles = stylex.create({
     },
     transitionDuration: durationVars['--duration-fast'],
     transitionTimingFunction: easeVars['--ease-standard'],
-    // Expand hit target by 2px on each side to prevent gaps
+    // Expand hit target so adjacent days meet with no gap
     '::before': {
       content: '""',
       position: 'absolute',
-      top: '-2px',
-      insetInlineEnd: '-2px',
-      bottom: '-2px',
-      insetInlineStart: '-2px',
+      top: HIT_BLEED,
+      insetInlineEnd: HIT_BLEED,
+      bottom: HIT_BLEED,
+      insetInlineStart: HIT_BLEED,
     },
   },
 
@@ -255,12 +259,6 @@ export const dayCellTheme = stylex.create({
   day: {
     color: colorVars['--color-text-primary'],
     backgroundColor: 'transparent',
-    backgroundImage: {
-      default: null,
-      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
-        '@media (hover: hover)': `linear-gradient(${colorVars['--color-overlay-hover']}, ${colorVars['--color-overlay-hover']})`,
-      },
-    },
   },
 
   // Outside days (adjacent months)
@@ -280,13 +278,21 @@ export const dayCellTheme = stylex.create({
 
   // Selected state (single selection or range endpoints)
   daySelected: {
-    backgroundColor: colorVars['--color-accent'],
-    color: colorVars['--color-on-accent'],
-    backgroundImage: {
-      default: null,
-      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
-        '@media (hover: hover)': `linear-gradient(${colorVars['--color-overlay-hover']}, ${colorVars['--color-overlay-hover']})`,
-      },
+    // Forced colors (Windows High Contrast) strips the accent fill, which
+    // leaves the selected date looking exactly like every other day.
+    // Highlight/HighlightText is the platform convention for a selected
+    // control (WCAG 1.4.11), and `forced-color-adjust: none` is required
+    // because this is a <button>: the UA otherwise keeps the native
+    // ButtonFace surface and ignores the authored fill, the same trap
+    // ToggleButton documents.
+    forcedColorAdjust: 'none',
+    backgroundColor: {
+      default: colorVars['--color-accent'],
+      '@media (forced-colors: active)': 'Highlight',
+    },
+    color: {
+      default: colorVars['--color-on-accent'],
+      '@media (forced-colors: active)': 'HighlightText',
     },
   },
 

package/src/Card/Card.doc.mjs

@@ -57,8 +57,9 @@ export const docs = {
     {
       name: 'padding',
       type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
-      description: 'Internal padding using the spacing scale.',
-      default: '4',
+      description:
+        "Internal padding using the spacing scale. Omit it and the card takes the theme's card padding rather than a step, so passing a step is a decision to override the theme, not a way to restate the default.",
+      default: "the theme's card padding (spacing step 4 with no theme)",
     },
     {
       name: 'variant',
@@ -77,7 +78,6 @@ export const docs = {
   ],
   playground: {
     defaults: {
-      padding: 4,
       children: {
         __element: 'VStack',
         props: {gap: 2},
@@ -91,7 +91,7 @@ export const docs = {
   theming: {
     container: true,
     targets: [
-      {className: 'astryx-card', visualProps: ['variant']},
+      {className: 'astryx-card', visualProps: ['variant', 'elevation']},
     ],
     vars: [
       {name: '--_card-radius', description: 'Border radius of the card', default: 'var(--radius-container)', private: true},
@@ -135,16 +135,19 @@ export const docsZh = {
     {name: 'maxWidth', type: 'SizeValue', description: '卡片最大宽度。'},
     {name: 'minHeight', type: 'SizeValue', description: '卡片最小高度。'},
     {name: 'children', type: 'ReactNode', description: '在卡片内部渲染的内容。'},
-    {name: 'padding', type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10', description: '使用间距比例的内边距。', default: '4'},
+    {name: 'padding', type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10', description: '使用间距比例的内边距。省略时，卡片采用主题的卡片内边距，而不是某个步进值；传入步进值意味着覆盖主题，而不是复述默认值。', default: "the theme's card padding (spacing step 4 with no theme)"},
+    {name: 'variant', type: "'default' | 'transparent' | 'muted' | 'blue' | 'cyan' | 'gray' | 'green' | 'orange' | 'pink' | 'purple' | 'red' | 'teal' | 'yellow'", description: '背景颜色变体。`default` 使用标准卡片背景；`transparent` 完全去掉背景；`muted` 使用弱化卡片的柔和背景。非语义变体使用对应的 `--color-background-<name>` 令牌。', default: "'default'"},
     {name: 'elevation', type: "'none' | 'low' | 'med' | 'high'", description: '静止阴影深度。`none` 为扁平；`low`/`med`/`high` 对应阴影令牌比例。', default: "'none'"},
   ],
   theming: {
     container: true,
     targets: [
-      {className: 'astryx-card', visualProps: ['variant']},
+      {className: 'astryx-card', visualProps: ['variant', 'elevation']},
     ],
     vars: [
       {name: '--_card-radius', description: 'Border radius of the card', default: 'var(--radius-container)', private: true},
+      {name: '--_card-elevation', description: 'Resting shadow of the card, set from the elevation prop.', default: '0 0 transparent', private: true},
+      {name: '--_card-ring', description: 'Inset ring drawn in the card box-shadow list.', default: '0 0 transparent', private: true},
     ],
     derived: [
       {property: 'borderRadius', vars: ['--_card-radius']},
@@ -178,7 +181,7 @@ export const docsDense = {
     maxWidth: 'max card width',
     minHeight: 'min card height',
     children: 'content inside card',
-    padding: 'internal padding via spacing scale',
+    padding: "internal padding via spacing scale; omitted = the theme's card padding, NOT a fixed step. Passing a step overrides the theme.",
     variant: 'background color variant; `default` = standard card bg, `transparent` = no background at all, `muted` = muted bg for de-emphasised cards; non-semantic variants use the corresponding `--color-background-<name>` token',
     elevation: 'resting shadow depth: none (flat) | low | med | high (shadow token scale). Raise only to float above content.',
   },

package/src/Card/Card.test.tsx

@@ -1,8 +1,10 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+import {createRef} from 'react';
 import {describe, it, expect} from 'vitest';
 import {render} from '@testing-library/react';
 import {Card} from './Card';
+import type {CardVariant} from './Card';
 
 describe('Card', () => {
   it('renders children', () => {
@@ -10,17 +12,52 @@ describe('Card', () => {
     expect(getByText('Hello')).toBeInTheDocument();
   });
 
-  it('renders astryx-* class names for theme targeting', () => {
-    const {container} = render(<Card>Content</Card>);
-    const root = container.firstElementChild!;
+  it('forwards ref to the rendered element', () => {
+    const ref = createRef<HTMLDivElement>();
+    const {container} = render(<Card ref={ref}>C</Card>);
+    expect(ref.current).toBe(container.firstElementChild);
+  });
+
+  it('spreads unknown props onto the same element that carries the theme target', () => {
+    const {getByTestId} = render(
+      <Card data-testid="card" id="promo" aria-label="Promotion">
+        C
+      </Card>,
+    );
+    const root = getByTestId('card');
+    expect(root).toHaveAttribute('id', 'promo');
+    expect(root).toHaveAttribute('aria-label', 'Promotion');
     expect(root.className).toContain('astryx-card');
   });
 
-  it('renders transparent variant with variant class', () => {
-    const {container} = render(<Card variant="transparent">Content</Card>);
+  it('merges a consumer className instead of replacing the theme target', () => {
+    const {container} = render(<Card className="promo">C</Card>);
     const root = container.firstElementChild!;
     expect(root.className).toContain('astryx-card');
-    expect(root.className).toContain('transparent');
+    expect(root.className).toContain('promo');
+  });
+
+  it('reflects variant as a theme data attribute', () => {
+    const {container} = render(<Card variant="muted">C</Card>);
+    expect(container.firstElementChild).toHaveAttribute(
+      'data-variant',
+      'muted',
+    );
+  });
+
+  it('reflects elevation as a theme data attribute', () => {
+    const {container} = render(<Card elevation="high">C</Card>);
+    expect(container.firstElementChild).toHaveAttribute(
+      'data-elevation',
+      'high',
+    );
+  });
+
+  it('defaults to the default variant at rest elevation', () => {
+    const {container} = render(<Card>C</Card>);
+    const root = container.firstElementChild!;
+    expect(root).toHaveAttribute('data-variant', 'default');
+    expect(root).toHaveAttribute('data-elevation', 'none');
   });
 
   it('applies a distinct class for each elevation level', () => {
@@ -28,18 +65,75 @@ describe('Card', () => {
       const {container} = render(<Card elevation={elevation}>C</Card>);
       return container.firstElementChild!.className;
     };
-    const none = classFor('none');
-    const low = classFor('low');
-    const med = classFor('med');
-    const high = classFor('high');
-    expect(new Set([none, low, med, high]).size).toBe(4);
-  });
-
-  it('defaults to flat (elevation none) — same class as explicit none', () => {
-    const {container: defaultContainer} = render(<Card>C</Card>);
-    const {container: noneContainer} = render(<Card elevation="none">C</Card>);
-    expect(defaultContainer.firstElementChild!.className).toBe(
-      noneContainer.firstElementChild!.className,
-    );
+    const classes = (['none', 'low', 'med', 'high'] as const).map(classFor);
+    expect(new Set(classes).size).toBe(4);
+  });
+
+  // Deriving the prop from CardVariantMap must not change which values it
+  // accepts. A key added to or dropped from the map fails to type-check here:
+  // a missing one against Record<CardVariant, true>, an extra one as an excess
+  // property.
+  const builtInVariants: Record<CardVariant, true> = {
+    default: true,
+    transparent: true,
+    muted: true,
+    blue: true,
+    cyan: true,
+    gray: true,
+    green: true,
+    orange: true,
+    pink: true,
+    purple: true,
+    red: true,
+    teal: true,
+    yellow: true,
+  };
+
+  it('accepts exactly the thirteen built-in variants, each reflected', () => {
+    const variants = Object.keys(builtInVariants) as CardVariant[];
+    expect(variants).toHaveLength(13);
+    for (const variant of variants) {
+      const {container} = render(<Card variant={variant}>C</Card>);
+      expect(container.firstElementChild).toHaveAttribute(
+        'data-variant',
+        variant,
+      );
+    }
+  });
+
+  describe('a variant a theme added', () => {
+    // The cast stands in for the module augmentation `astryx theme build`
+    // emits; that the augmentation itself widens the prop is covered by
+    // packages/cli/clients/cli/commands/build-theme.variants.test.mjs.
+    const themeAdded = 'brand' as CardVariant;
+
+    const classesFor = (variant: CardVariant) => {
+      const {container} = render(<Card variant={variant}>C</Card>);
+      return new Set(container.firstElementChild!.className.split(' '));
+    };
+
+    it('renders the selector a theme rule needs', () => {
+      const {container} = render(<Card variant={themeAdded}>C</Card>);
+      const root = container.firstElementChild!;
+      expect(root).toHaveAttribute('data-variant', 'brand');
+      expect(root.className).toContain('astryx-card');
+      expect(root.className).toContain('brand');
+    });
+
+    it('falls through to base styles instead of another variant', () => {
+      const muted = classesFor('muted');
+      const blue = classesFor('blue');
+      const brand = classesFor(themeAdded);
+
+      const variantOwned = [
+        ...[...muted].filter(c => !blue.has(c)),
+        ...[...blue].filter(c => !muted.has(c)),
+      ];
+      const shared = [...muted].filter(c => blue.has(c));
+
+      expect(variantOwned.length).toBeGreaterThan(0);
+      expect(variantOwned.filter(c => brand.has(c))).toEqual([]);
+      expect(shared.filter(c => !brand.has(c))).toEqual([]);
+    });
   });
 });