@astryxdesign/core 0.7.1-canary.ff40b78 → 0.7.1

package/src/Calendar/Calendar.tsx

@@ -51,10 +51,14 @@ import {
   plainDateSetFirstOfMonth,
   plainDateAddMonths,
   plainDateAddDays,
+  plainDateDiffDays,
+  getDaysInMonth,
+  plainDateIsAfter,
   plainDateIsBefore,
   plainDateIsEqual,
   plainDateGetWeekNumber,
   plainDateFormat,
+  plainDateWeekFieldName,
   DATE_FORMAT_WITH_WEEKDAY,
   DATE_FORMAT_MONTH_YEAR,
 } from '../utils/plainDate';
@@ -91,9 +95,12 @@ import type {
 import {normalizeDayOfWeek} from '../utils/dateTypes';
 import {themeProps} from '../utils/themeProps';
 import {useLocale, useTranslator} from '../i18n';
+import {VisuallyHidden} from '../VisuallyHidden';
 
-/** Imperative handle for Calendar handleRef */
+/** How a month navigation moves the focused day: by its row offset in days, or by whole months. */
+type NavigationUnit = 'days' | 'months';
 
+/** Imperative handle for Calendar handleRef */
 export interface CalendarHandle {
   /** Navigate the calendar to show the month containing the given date */
   navigateTo: (date: ISODateString) => void;
@@ -214,6 +221,21 @@ interface CalendarRangeProps extends CalendarBaseProps {
 
 export type CalendarProps = CalendarSingleProps | CalendarRangeProps;
 
+/** The first day of `month`'s month that `isDisabled` allows, or null. */
+function firstEnabledDayOfMonth(
+  month: PlainDate,
+  isDisabled: (pd: PlainDate) => boolean,
+): PlainDate | null {
+  const days = getDaysInMonth(month.year, month.month);
+  for (let day = 1; day <= days; day += 1) {
+    const pd = {year: month.year, month: month.month, day};
+    if (!isDisabled(pd)) {
+      return pd;
+    }
+  }
+  return null;
+}
+
 // =============================================================================
 // Main Component
 // =============================================================================
@@ -333,6 +355,39 @@ export function Calendar({ref, ...props}: CalendarProps) {
     });
   }, [baseMonth, numberOfMonths]);
 
+  // A pending target is claimed by the grid that shows its month, or dropped
+  // by the next focus move that is not onto the target day: when a controlled
+  // owner refuses the month change, no grid shows the target's month, and a
+  // stale target would later steal focus (and Enter) when that month does
+  // appear. Only a grid showing the target's month receives it; any other
+  // focus change (an arrow to another day, the month header's buttons, or out
+  // of the calendar) drops it (see onBlur below).
+  const claimablePendingFocus = useMemo(() => {
+    if (pendingFocus == null) {
+      return null;
+    }
+    const target = plainDateFromISO(pendingFocus);
+    return visibleMonths.some(
+      pd => pd.year === target.year && pd.month === target.month,
+    )
+      ? pendingFocus
+      : null;
+  }, [pendingFocus, visibleMonths]);
+  const handleRootBlur = useCallback(
+    (e: React.FocusEvent<HTMLDivElement>) => {
+      // Only the move onto the target day itself keeps the target: an arrow
+      // to any other day, a move to the header buttons, or focus leaving the
+      // calendar all drop it.
+      const movesToTarget =
+        e.relatedTarget instanceof Element &&
+        e.relatedTarget.getAttribute('data-date') === pendingFocus;
+      if (pendingFocus != null && !movesToTarget) {
+        setPendingFocus(null);
+      }
+    },
+    [pendingFocus],
+  );
+
   // Format month header
   const monthYearLabel = useMemo(() => {
     if (numberOfMonths === 1) {
@@ -363,6 +418,15 @@ export function Calendar({ref, ...props}: CalendarProps) {
   }, [monthYearLabel, announce]);
 
   // Determine if prev/next navigation is possible based on min/max
+  const minDateForKeys = useMemo(
+    () => (min ? plainDateFromISO(min) : null),
+    [min],
+  );
+  const maxDateForKeys = useMemo(
+    () => (max ? plainDateFromISO(max) : null),
+    [max],
+  );
+
   const canNavigatePrevious = useMemo(() => {
     if (!min) {
       return true;
@@ -390,26 +454,137 @@ export function Calendar({ref, ...props}: CalendarProps) {
   }, [max, baseMonth, numberOfMonths]);
 
   // Navigation handlers
+  // The same constraint view the grids use, so a key can resolve its target
+  // before the month changes.
+  const rootRangeAnchor = useMemo(
+    () =>
+      mode === 'range' && rangeSelectionStart
+        ? plainDateFromISO(rangeSelectionStart)
+        : null,
+    [mode, rangeSelectionStart],
+  );
+  const {isDateDisabled: isRootDateDisabled} = useCalendarConstraints({
+    min,
+    max,
+    dateConstraints,
+    maxRangeSpan,
+    minRangeSpan,
+    rangeAnchor: rootRangeAnchor,
+  });
+
   const navigateMonth = useCallback(
-    (delta: number, focusedDate?: ISODateString, offset?: number) => {
-      const newPd = plainDateAddMonths(baseMonth, delta);
-      const newISO = plainDateToISO(newPd);
+    (
+      delta: number,
+      focusedDate?: ISODateString,
+      offset?: number,
+      unit: NavigationUnit = 'days',
+    ) => {
+      const monthIndex = (pd: PlainDate) => pd.year * 12 + pd.month;
+      const firstShown = monthIndex(baseMonth);
+      const lastShown = firstShown + numberOfMonths - 1;
+
+      // The Previous/Next buttons move the month with no focused day.
+      if (!focusedDate) {
+        if (
+          (delta < 0 && !canNavigatePrevious) ||
+          (delta > 0 && !canNavigateNext)
+        ) {
+          return;
+        }
+        const newPd = plainDateAddMonths(baseMonth, delta);
+        if (onFocusDateChange) {
+          onFocusDateChange(plainDateToISO(newPd));
+        } else {
+          setInternalFocusDate(newPd);
+        }
+        return;
+      }
 
-      // Calculate target focus date if a focused date was provided
-      if (focusedDate) {
-        const currentPd = plainDateFromISO(focusedDate);
-        const daysToMove = offset ?? 7;
-        const targetPd = plainDateAddDays(currentPd, delta * daysToMove);
-        setPendingFocus(plainDateToISO(targetPd));
+      // A key resolves its TARGET day first and decides by that, so a
+      // boundary blocks only out-of-range targets, never the month movement
+      // itself (ArrowUp from February 3 reaches January 27 at a January
+      // minimum), and a direction with no enabled day left changes nothing
+      // rather than dropping focus.
+      const currentPd = plainDateFromISO(focusedDate);
+      const inRange = (pd: PlainDate) =>
+        !(minDateForKeys && plainDateIsBefore(pd, minDateForKeys)) &&
+        !(maxDateForKeys && plainDateIsAfter(pd, maxDateForKeys));
+      let targetPd: PlainDate;
+      if (unit === 'months') {
+        // A page targets the same day of the month a month away (clamped to
+        // that month's length). Past `min`/`max` nothing moves; a month with
+        // no enabled day is no destination either, the same as an arrow with
+        // no enabled day in its direction; a target disabled by a constraint
+        // lands on that month's first enabled day instead.
+        const candidate = plainDateAddMonths(currentPd, delta);
+        if (!inRange(candidate)) {
+          return;
+        }
+        if (isRootDateDisabled(candidate)) {
+          const firstEnabled = firstEnabledDayOfMonth(
+            candidate,
+            isRootDateDisabled,
+          );
+          if (firstEnabled == null) {
+            return;
+          }
+          targetPd = firstEnabled;
+        } else {
+          targetPd = candidate;
+        }
+      } else {
+        // Walk the arrow's direction to the first enabled day, up to a year
+        // away; past `min`/`max` or with every day disabled, nothing moves.
+        const step = delta * (offset ?? 7);
+        let candidate = plainDateAddDays(currentPd, step);
+        let found: PlainDate | null = null;
+        while (Math.abs(plainDateDiffDays(currentPd, candidate)) <= 366) {
+          if (!inRange(candidate)) {
+            return;
+          }
+          if (!isRootDateDisabled(candidate)) {
+            found = candidate;
+            break;
+          }
+          candidate = plainDateAddDays(candidate, step);
+        }
+        if (found == null) {
+          return;
+        }
+        targetPd = found;
       }
 
+      // Focus moves to the target; the months change only when the target's
+      // month is not already shown. The view shifts the least it can in the
+      // key's direction, so the target month becomes the first (backwards)
+      // or last (forwards) month shown.
+      const resolved: PlainDate = targetPd;
+      const targetMonth = monthIndex(resolved);
+      setPendingFocus(plainDateToISO(resolved));
+      if (targetMonth >= firstShown && targetMonth <= lastShown) {
+        return;
+      }
+      const targetFirst = {year: resolved.year, month: resolved.month, day: 1};
+      const newPd =
+        targetMonth < firstShown
+          ? targetFirst
+          : plainDateAddMonths(targetFirst, -(numberOfMonths - 1));
       if (onFocusDateChange) {
-        onFocusDateChange(newISO);
+        onFocusDateChange(plainDateToISO(newPd));
       } else {
         setInternalFocusDate(newPd);
       }
     },
-    [baseMonth, onFocusDateChange],
+    [
+      baseMonth,
+      canNavigateNext,
+      canNavigatePrevious,
+      isRootDateDisabled,
+      maxDateForKeys,
+      minDateForKeys,
+      numberOfMonths,
+      onFocusDateChange,
+    ],
   );
 
   // Escape key handler to cancel range selection
@@ -513,6 +688,7 @@ export function Calendar({ref, ...props}: CalendarProps) {
     <div
       ref={ref}
       {...rest}
+      onBlur={composeEventHandlers(rest.onBlur, handleRootBlur)}
       {...mergeProps(
         themeProps('calendar', {mode}),
         stylex.props(calendarStyles.calendar, xstyle),
@@ -587,13 +763,13 @@ export function Calendar({ref, ...props}: CalendarProps) {
               setHoveredDate(date ? plainDateToISO(date) : null)
             }
             today={today}
-            onNavigatePrevious={(focusedDate, offset) =>
-              navigateMonth(-1, focusedDate, offset)
+            onNavigatePrevious={(focusedDate, offset, unit) =>
+              navigateMonth(-1, focusedDate, offset, unit)
             }
-            onNavigateNext={(focusedDate, offset) =>
-              navigateMonth(1, focusedDate, offset)
+            onNavigateNext={(focusedDate, offset, unit) =>
+              navigateMonth(1, focusedDate, offset, unit)
             }
-            pendingFocus={pendingFocus}
+            pendingFocus={claimablePendingFocus}
             onPendingFocusHandled={() => setPendingFocus(null)}
           />
         ))}
@@ -626,8 +802,16 @@ interface MonthGridProps {
   onDayClick: (date: PlainDate) => void;
   onDayHover: (date: PlainDate | null) => void;
   today: PlainDate;
-  onNavigatePrevious?: (focusedDate: ISODateString, offset: number) => void;
-  onNavigateNext?: (focusedDate: ISODateString, offset: number) => void;
+  onNavigatePrevious?: (
+    focusedDate: ISODateString,
+    offset: number,
+    unit?: NavigationUnit,
+  ) => void;
+  onNavigateNext?: (
+    focusedDate: ISODateString,
+    offset: number,
+    unit?: NavigationUnit,
+  ) => void;
   pendingFocus?: ISODateString | null;
   onPendingFocusHandled?: () => void;
 }
@@ -773,14 +957,14 @@ function MonthGrid({
   const handlePageUp = useCallback(() => {
     const focusedDate = getFocusedDate();
     if (focusedDate) {
-      onNavigatePrevious?.(focusedDate, 7);
+      onNavigatePrevious?.(focusedDate, 1, 'months');
     }
   }, [getFocusedDate, onNavigatePrevious]);
 
   const handlePageDown = useCallback(() => {
     const focusedDate = getFocusedDate();
     if (focusedDate) {
-      onNavigateNext?.(focusedDate, 7);
+      onNavigateNext?.(focusedDate, 1, 'months');
     }
   }, [getFocusedDate, onNavigateNext]);
 
@@ -800,8 +984,15 @@ function MonthGrid({
   } = useGridFocus<HTMLDivElement>({
     columns: 7,
     cellSelector: '[role="gridcell"]',
+    // A borrowed adjacent-month day is exposed aria-disabled (its click does
+    // nothing, but it can still take pointer focus) and may also be natively
+    // disabled by bounds or a constraint; the keyboard skips it either way
+    // and crosses into that month through the grid edge instead, so focus
+    // lands on the real day in the month now shown (FR5).
     isCellFocusable: cell =>
-      cell.querySelector('button:not([disabled])') !== null,
+      cell.querySelector(
+        'button:not([disabled]):not([aria-disabled="true"])',
+      ) !== null,
     getFocusTarget: cell => cell.querySelector<HTMLElement>('button'),
     hasRovingTabIndex: true,
     onNavigateBefore: handleNavigatePrevious,
@@ -810,34 +1001,53 @@ function MonthGrid({
     onPageDown: handlePageDown,
   });
 
-  // Handle pending focus after month navigation
+  // Handle pending focus after month navigation. Every mounted month grid
+  // sees the same pending date; only the grid showing that date's month acts,
+  // so a neighbouring grid's fallback never overrides the right target. The
+  // target is the real day in this month, never an outside-day copy; when it
+  // is disabled, the month's first enabled day takes focus instead.
   useEffect(() => {
     if (!pendingFocus || !gridRef.current) {
       return;
     }
 
-    const buttons = gridRef.current.querySelectorAll<HTMLElement>(
-      'button:not([disabled])',
-    );
-
     const targetPd = plainDateFromISO(pendingFocus);
+    if (targetPd.year !== year || targetPd.month !== month.month) {
+      return;
+    }
     const targetIso = plainDateToISO(targetPd);
 
-    let targetButton: HTMLElement | null = null;
-    for (const button of buttons) {
-      if (button.getAttribute('data-date') === targetIso) {
-        targetButton = button;
-        break;
-      }
-    }
+    const buttons = Array.from(
+      gridRef.current.querySelectorAll<HTMLElement>(
+        'button[data-date]:not([disabled]):not([aria-disabled="true"])',
+      ),
+    );
 
-    if (!targetButton && buttons.length > 0) {
-      targetButton = buttons[0];
+    // The real target day, else the month's first enabled day, else — in a
+    // month with no enabled day — the first day button that can still take
+    // focus (a borrowed adjacent-month day), so focus stays in the grid
+    // rather than dropping to the page.
+    const targetButton =
+      buttons.find(button => button.getAttribute('data-date') === targetIso) ??
+      buttons[0] ??
+      gridRef.current.querySelector<HTMLElement>(
+        'button[data-date]:not([disabled])',
+      ) ??
+      null;
+
+    if (targetButton != null) {
+      // The target becomes this grid's one Tab stop before it takes focus,
+      // the way the hook's own arrow moves do (FR2): a programmatic focus
+      // alone would leave the stop on the day the grid mounted with.
+      for (const button of gridRef.current.querySelectorAll<HTMLElement>(
+        'button[data-date]',
+      )) {
+        button.tabIndex = button === targetButton ? 0 : -1;
+      }
+      targetButton.focus();
     }
-
-    targetButton?.focus();
     onPendingFocusHandled?.();
-  }, [pendingFocus, gridRef, onPendingFocusHandled]);
+  }, [pendingFocus, gridRef, month.month, onPendingFocusHandled, year]);
 
   // Parse selection
   let selectedDate: PlainDate | null = null;
@@ -900,12 +1110,19 @@ function MonthGrid({
             same display:contents row so its cells align to the grid columns. */}
         <div role="row" {...stylex.props(monthGridStyles.weekRow)}>
           {hasWeekNumbers && (
+            // The corner above the week-number column is a header cell like
+            // the weekday names beside it (APG grid: every cell in a row is a
+            // gridcell, columnheader or rowheader). Its name is the locale's
+            // own word for the week field, as visually hidden text so the
+            // column stays blank and the header is not empty to axe.
             <div
+              role="columnheader"
               {...stylex.props(
                 monthGridStyles.dayName,
                 monthGridStyles.weekNumberHeader,
-              )}
-            />
+              )}>
+              <VisuallyHidden>{plainDateWeekFieldName(locale)}</VisuallyHidden>
+            </div>
           )}
           {dayNameHeaders.map(({dayOfWeek, name}) => (
             <div

package/src/Calendar/__tests__/Calendar.a11y.chromium.spec.ts

@@ -0,0 +1,126 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Calendar.a11y.chromium.spec.ts
+ * @input Built Calendar stories and GRID_PATTERN in real Chromium
+ * @output Browser evidence for every grid expectation across the binding's states (role and name, arrows in reading order, Home/End, Enter)
+ * @position Chromium lane of the Calendar grid binding (component:Calendar AR1)
+ */
+
+import {
+  expect,
+  test,
+  type CDPSession,
+  type Locator,
+  type Page,
+} from '@playwright/test';
+import {
+  GRID_PATTERN,
+  blockingResults,
+  checkAccessibilitySpec,
+  formatFailures,
+  neverExercised,
+  unmatchedKnownFailures,
+  summarize,
+  type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {
+  createChromiumHarness,
+  holdMotionStill,
+} from '@astryxdesign/a11y-spec/chromium';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+import {
+  CALENDAR_BINDING_STATES,
+  NEIGHBOURHOOD,
+  START_ISO,
+  type CalendarBindingState,
+} from './Calendar.a11y.states';
+import {CALENDAR_KNOWN_FAILURES} from './Calendar.a11y.known-failures';
+
+let storybook: StaticServer;
+
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+function storyUrl(storyId: string): string {
+  return `${storybook.origin}/iframe.html?id=${storyId}&viewMode=story`;
+}
+
+async function mountState(
+  page: Page,
+  state: CalendarBindingState,
+): Promise<{subject: Locator; related: Record<string, Locator>}> {
+  await page.goto(storyUrl(state.storyId), {waitUntil: 'load'});
+  await holdMotionStill(page);
+  const root = page.locator('#storybook-root');
+  const subject = root.getByRole('grid', {name: state.gridName});
+  await subject.waitFor({state: 'attached'});
+  const day = (iso: string) => root.locator(`button[data-date="${iso}"]`);
+  const start = day(START_ISO);
+  return {
+    subject,
+    related: {
+      start,
+      startCell: root.locator(
+        `[role="gridcell"]:has(> button[data-date="${START_ISO}"])`,
+      ),
+      ...Object.fromEntries(
+        Object.entries(NEIGHBOURHOOD).map(([name, iso]) => [name, day(iso)]),
+      ),
+    },
+  };
+}
+
+async function runState(
+  page: Page,
+  cdp: CDPSession,
+  state: CalendarBindingState,
+): Promise<BindingResult> {
+  return checkAccessibilitySpec({
+    spec: GRID_PATTERN,
+    binding: 'Calendar',
+    state: state.id,
+    facts: state.facts,
+    knownFailures: CALENDAR_KNOWN_FAILURES,
+    mount: async () => {
+      const {subject, related} = await mountState(page, state);
+      return createChromiumHarness({page, cdp, subject, related});
+    },
+  });
+}
+
+test('every grid expectation is exercised by a Calendar state', async ({
+  page,
+}) => {
+  const cdp = await page.context().newCDPSession(page);
+  const results: BindingResult[] = [];
+  for (const state of CALENDAR_BINDING_STATES) {
+    results.push(await runState(page, cdp, state));
+  }
+  expect(neverExercised(results)).toEqual([]);
+  expect(unmatchedKnownFailures(CALENDAR_KNOWN_FAILURES, results)).toEqual([]);
+});
+
+for (const state of CALENDAR_BINDING_STATES) {
+  test(`Calendar [${state.id}] — ${state.summary}`, async ({page}) => {
+    const cdp = await page.context().newCDPSession(page);
+    const result = await runState(page, cdp, state);
+    const report = summarize(GRID_PATTERN, [result]);
+    // Required rows block (AST-020 FR9); advisory rows and exact known
+    // failures report.
+    expect(formatFailures(blockingResults([result]))).toBe('');
+    expect(report.unrunLayers).toEqual([]);
+    expect(report.counts.unexpectedPass).toBe(0);
+  });
+}

package/src/Calendar/__tests__/Calendar.a11y.known-failures.ts

@@ -0,0 +1,12 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Calendar.a11y.known-failures.ts
+ * @input The exact grid-contract failures the shipped Calendar produces today
+ * @output CALENDAR_KNOWN_FAILURES — records both lanes reconcile against, so a fix shows up as an unexpected pass and any other failure stays a failure
+ * @position Known-failure ledger for the Calendar binding
+ */
+
+import type {KnownFailure} from '@astryxdesign/a11y-spec';
+
+export const CALENDAR_KNOWN_FAILURES: ReadonlyArray<KnownFailure> = [];

package/src/Calendar/__tests__/Calendar.a11y.renders.tsx

@@ -0,0 +1,57 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file Calendar.a11y.renders.tsx
+ * @input One Calendar binding state
+ * @output The React tree every lane renders for that state (the jsdom test directly, the story through Storybook)
+ * @position Shared fixture for the Calendar grid binding
+ */
+
+import {useState, type ReactElement} from 'react';
+import {Calendar} from '../Calendar';
+import type {DateRange, ISODateString} from '../Calendar';
+import {START_ISO, type CalendarBindingState} from './Calendar.a11y.states';
+
+function BoundCalendar({state}: {state: CalendarBindingState}) {
+  const [single, setSingle] = useState<ISODateString | null>(
+    state.mode === 'single' && typeof state.value === 'string'
+      ? state.value
+      : null,
+  );
+  const [range, setRange] = useState<DateRange | null>(
+    state.mode === 'range' && typeof state.value === 'object'
+      ? state.value
+      : null,
+  );
+  if (state.mode === 'range') {
+    return (
+      <Calendar
+        mode="range"
+        value={range}
+        onChange={setRange}
+        focusDate={START_ISO}
+        numberOfMonths={state.numberOfMonths ?? 1}
+      />
+    );
+  }
+  return (
+    <Calendar
+      mode="single"
+      value={single}
+      onChange={setSingle}
+      focusDate={START_ISO}
+      numberOfMonths={state.numberOfMonths ?? 1}
+      hasWeekNumbers={state.hasWeekNumbers}
+    />
+  );
+}
+
+export function renderCalendarState(state: CalendarBindingState): ReactElement {
+  return (
+    <div dir={state.rtl ? 'rtl' : 'ltr'} style={{padding: 16}}>
+      <BoundCalendar state={state} />
+    </div>
+  );
+}