@boostdev/design-system-components 2.8.0 → 2.11.0

package/src/components/ui/Calendar/Calendar.spec.tsx

@@ -2,8 +2,9 @@ import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { Calendar } from './Calendar';
 
-// Pin to a known date for deterministic tests
-const FIXED_DATE = new Date(2024, 0, 15); // January 15, 2024
+const FIXED_DATE = new Date(2024, 0, 15); // Monday, January 15, 2024
+const inMonthDays = () =>
+  screen.getAllByRole('button').filter(b => /^\d+$/.test(b.textContent ?? '') && !b.hasAttribute('data-outside'));
 
 describe('Calendar', () => {
   it('renders navigation buttons', () => {
@@ -17,48 +18,162 @@ describe('Calendar', () => {
     expect(screen.getByText('January 2024')).toBeInTheDocument();
   });
 
-  it('renders day buttons', () => {
+  it('renders one button per in-month day', () => {
     render(<Calendar value={FIXED_DATE} onChange={() => {}} />);
-    // January 2024 has 31 days
-    expect(screen.getAllByRole('button').filter(b => b.textContent?.match(/^\d+$/))).toHaveLength(31);
+    expect(inMonthDays()).toHaveLength(31); // January has 31 days
   });
 
-  it('navigates to next month', async () => {
+  it('renders localized weekday headers starting on Monday', () => {
     render(<Calendar value={FIXED_DATE} onChange={() => {}} />);
-    await userEvent.click(screen.getByRole('button', { name: 'Next month' }));
-    expect(screen.getByText('February 2024')).toBeInTheDocument();
+    const headers = screen.getAllByRole('columnheader').map(h => h.textContent);
+    expect(headers[0]).toBe('Mon');
+    expect(headers[6]).toBe('Sun');
   });
 
-  it('navigates to previous month', async () => {
+  it('navigates to next and previous month', async () => {
     render(<Calendar value={FIXED_DATE} onChange={() => {}} />);
+    await userEvent.click(screen.getByRole('button', { name: 'Next month' }));
+    expect(screen.getByText('February 2024')).toBeInTheDocument();
     await userEvent.click(screen.getByRole('button', { name: 'Previous month' }));
-    expect(screen.getByText('December 2023')).toBeInTheDocument();
+    expect(screen.getByText('January 2024')).toBeInTheDocument();
   });
 
   it('calls onChange when a date is selected', async () => {
     const onChange = vi.fn();
     render(<Calendar value={FIXED_DATE} onChange={onChange} />);
-    // Click on the 20th
-    const buttons = screen.getAllByRole('button').filter(b => b.textContent === '20');
-    await userEvent.click(buttons[0]);
+    await userEvent.click(screen.getByRole('button', { name: 'January 20, 2024' }));
     expect(onChange).toHaveBeenCalledOnce();
     const called = onChange.mock.calls[0][0] as Date;
     expect(called.getDate()).toBe(20);
-    expect(called.getMonth()).toBe(0); // January
+    expect(called.getMonth()).toBe(0);
   });
 
-  it('renders day-of-week headers', () => {
+  it('disables days outside min/max range', () => {
+    render(<Calendar value={FIXED_DATE} min={new Date(2024, 0, 10)} max={new Date(2024, 0, 20)} onChange={() => {}} />);
+    expect(screen.getByRole('button', { name: 'January 5, 2024' })).toBeDisabled();
+  });
+
+  it('disables arbitrary dates via isDateDisallowed', () => {
+    const noWeekends = (d: Date) => d.getDay() === 0 || d.getDay() === 6;
+    render(<Calendar value={FIXED_DATE} isDateDisallowed={noWeekends} onChange={() => {}} />);
+    expect(screen.getByRole('button', { name: 'January 13, 2024' })).toBeDisabled(); // Saturday
+    expect(screen.getByRole('button', { name: 'January 15, 2024' })).not.toBeDisabled(); // Monday
+  });
+
+  it('renders greyed, non-selectable outside days', () => {
     render(<Calendar value={FIXED_DATE} onChange={() => {}} />);
-    expect(screen.getByText('Mo')).toBeInTheDocument();
-    expect(screen.getByText('Su')).toBeInTheDocument();
+    const outside = screen.getAllByRole('button').filter(b => b.hasAttribute('data-outside'));
+    expect(outside.length).toBeGreaterThan(0);
+    expect(outside[0]).toBeDisabled();
   });
 
-  it('disables days outside min/max range', () => {
-    const min = new Date(2024, 0, 10);
-    const max = new Date(2024, 0, 20);
-    render(<Calendar value={FIXED_DATE} min={min} max={max} onChange={() => {}} />);
-    // Day 5 should be disabled
-    const day5 = screen.getAllByRole('button').find(b => b.textContent === '5' && b.hasAttribute('disabled'));
-    expect(day5).toBeDefined();
+  it('never marks an outside day as selected, even when it matches the selected date', async () => {
+    // value = Jan 31; navigate to February, where Jan 31 appears as a greyed
+    // leading outside day (Feb 1 2024 is a Thursday, Monday-first lead = Jan 29–31).
+    render(<Calendar value={new Date(2024, 0, 31)} onChange={() => {}} />);
+    await userEvent.click(screen.getByRole('button', { name: 'Next month' }));
+    const outsideJan31 = screen.getByRole('button', { name: 'January 31, 2024' });
+    expect(outsideJan31).toHaveAttribute('data-outside');
+    expect(outsideJan31).toBeDisabled();
+    expect(outsideJan31).not.toHaveAttribute('data-selected');
+    expect(outsideJan31.closest('[role="gridcell"]')).toHaveAttribute('aria-selected', 'false');
+  });
+
+  it('shows two months when months=2', () => {
+    render(<Calendar value={FIXED_DATE} months={2} onChange={() => {}} />);
+    expect(screen.getByText('January 2024')).toBeInTheDocument();
+    expect(screen.getByText('February 2024')).toBeInTheDocument();
+  });
+
+  it('honors a custom locale for month and weekday text', () => {
+    render(<Calendar value={FIXED_DATE} locale="nl-NL" onChange={() => {}} />);
+    expect(screen.getByText(/januari 2024/i)).toBeInTheDocument();
+    // Monday-first, Dutch short weekday for Monday is "ma"
+    expect(screen.getAllByRole('columnheader')[0]).toHaveTextContent('ma');
+  });
+
+  it('honors formatMonth / formatWeekday overrides', () => {
+    render(
+      <Calendar
+        value={FIXED_DATE}
+        onChange={() => {}}
+        formatMonth={() => 'CUSTOM'}
+        formatWeekday={d => String('SMTWTFS'[d.getDay()])}
+      />,
+    );
+    expect(screen.getByText('CUSTOM')).toBeInTheDocument();
+    expect(screen.getAllByRole('columnheader')[0]).toHaveTextContent('M'); // Monday-first
+  });
+
+  it('moves DOM focus with arrow keys', async () => {
+    render(<Calendar value={FIXED_DATE} onChange={() => {}} />);
+    screen.getByRole('button', { name: 'January 15, 2024' }).focus();
+    await userEvent.keyboard('{ArrowRight}');
+    expect(screen.getByRole('button', { name: 'January 16, 2024' })).toHaveFocus();
+  });
+
+  it('moves DOM focus across a month boundary with arrow keys', async () => {
+    render(<Calendar value={new Date(2024, 0, 31)} onChange={() => {}} />);
+    screen.getByRole('button', { name: 'January 31, 2024' }).focus();
+    await userEvent.keyboard('{ArrowRight}');
+    expect(screen.getByText('February 2024')).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'February 1, 2024' })).toHaveFocus();
+  });
+
+  it('pages by month with PageDown and by year with Shift+PageDown', async () => {
+    render(<Calendar value={FIXED_DATE} onChange={() => {}} />);
+    screen.getByRole('button', { name: 'January 15, 2024' }).focus();
+    await userEvent.keyboard('{PageDown}');
+    expect(screen.getByRole('button', { name: 'February 15, 2024' })).toHaveFocus();
+    await userEvent.keyboard('{Shift>}{PageDown}{/Shift}');
+    expect(screen.getByRole('button', { name: 'February 15, 2025' })).toHaveFocus();
+  });
+
+  it('selects the focused day with Enter', async () => {
+    const onChange = vi.fn();
+    render(<Calendar value={FIXED_DATE} onChange={onChange} />);
+    screen.getByRole('button', { name: 'January 15, 2024' }).focus();
+    await userEvent.keyboard('{ArrowRight}{Enter}');
+    expect(onChange).toHaveBeenCalledOnce();
+    expect((onChange.mock.calls[0][0] as Date).getDate()).toBe(16);
+  });
+
+  it('keeps exactly one tabbable day after navigating to a month with no selected/today date', async () => {
+    const now = new Date();
+    render(<Calendar value={new Date(now.getFullYear(), now.getMonth(), 15)} onChange={() => {}} />);
+    await userEvent.click(screen.getByRole('button', { name: 'Next month' }));
+    const tabbable = inMonthDays().filter(b => b.getAttribute('tabindex') === '0');
+    expect(tabbable).toHaveLength(1);
+    expect(tabbable[0]).toHaveTextContent('1');
+  });
+
+  it('puts aria-selected on the gridcell rather than the day button', () => {
+    render(<Calendar value={FIXED_DATE} onChange={() => {}} />);
+    const day15 = screen.getByRole('button', { name: 'January 15, 2024' });
+    expect(day15).not.toHaveAttribute('aria-selected');
+    expect(day15.closest('[role="gridcell"]')).toHaveAttribute('aria-selected', 'true');
+  });
+
+  it('renders a CSS-grid role hierarchy, not a table', () => {
+    const { container } = render(<Calendar value={FIXED_DATE} onChange={() => {}} />);
+    expect(container.querySelector('table')).toBeNull();
+    expect(container.querySelector('[role="grid"]')).not.toBeNull();
+    expect(container.querySelectorAll('[role="row"]').length).toBeGreaterThan(1);
+  });
+
+  it('syncs the displayed month when the controlled value changes', () => {
+    const { rerender } = render(<Calendar value={FIXED_DATE} onChange={() => {}} />);
+    expect(screen.getByText('January 2024')).toBeInTheDocument();
+    rerender(<Calendar value={new Date(2024, 5, 10)} onChange={() => {}} />);
+    expect(screen.getByText('June 2024')).toBeInTheDocument();
+  });
+
+  it('works uncontrolled via defaultValue', async () => {
+    const onChange = vi.fn();
+    render(<Calendar defaultValue={FIXED_DATE} onChange={onChange} />);
+    await userEvent.click(screen.getByRole('button', { name: 'January 20, 2024' }));
+    expect(onChange).toHaveBeenCalledOnce();
+    expect(screen.getByRole('button', { name: 'January 20, 2024' }).closest('[role="gridcell"]'))
+      .toHaveAttribute('aria-selected', 'true');
   });
 });

package/src/components/ui/Calendar/Calendar.stories.tsx

@@ -56,3 +56,17 @@ export const WithMinMax: Story = {
     );
   },
 };
+
+export const TwoMonths: Story = {
+  render: () => {
+    const [value, setValue] = useState<Date | undefined>();
+    return <Calendar value={value} months={2} onChange={setValue} />;
+  },
+};
+
+export const DutchLocale: Story = {
+  render: () => {
+    const [value, setValue] = useState<Date | undefined>();
+    return <Calendar value={value} locale="nl-NL" firstDayOfWeek={1} onChange={setValue} />;
+  },
+};

package/src/components/ui/Calendar/Calendar.tsx

@@ -1,193 +1,182 @@
-import { HTMLAttributes, useState, useId, KeyboardEvent } from 'react';
-import css from './Calendar.module.css';
+import { HTMLAttributes, useState, useId, useRef, useEffect, useCallback, KeyboardEvent } from 'react';
 import { cn } from '@boostdev/design-system-foundation';
 import type { WithClassName } from '../../../types';
+import css from './Calendar.module.css';
+import { MonthGrid, type DayState } from './MonthGrid';
+import {
+  isSameDay, isDisabled as coreIsDisabled, toISO, type ISODate,
+  getWeekdayNames, getMonthLabel, getDayLabel, nextFocusDate,
+} from './calendar-core';
+
+type PageBy = 'months' | 'single';
 
-const DAYS = ['Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa'];
-const DAY_LABELS: Record<string, string> = {
-  Su: 'Sunday', Mo: 'Monday', Tu: 'Tuesday', We: 'Wednesday',
-  Th: 'Thursday', Fr: 'Friday', Sa: 'Saturday',
-};
-const MONTHS = [
-  'January', 'February', 'March', 'April', 'May', 'June',
-  'July', 'August', 'September', 'October', 'November', 'December',
-];
-
-interface CalendarProps extends WithClassName, Omit<HTMLAttributes<HTMLDivElement>, 'defaultValue' | 'onChange'> {
+interface CalendarProps
+  extends WithClassName,
+    Omit<HTMLAttributes<HTMLDivElement>, 'defaultValue' | 'onChange'> {
   value?: Date;
   defaultValue?: Date;
   min?: Date;
   max?: Date;
+  months?: number;
+  pageBy?: PageBy;
+  firstDayOfWeek?: number;
+  locale?: string;
+  isDateDisallowed?: (date: Date) => boolean;
+  formatWeekday?: (date: Date) => string;
+  formatMonth?: (date: Date) => string;
+  formatDay?: (date: Date) => string;
+  labels?: { previousMonth?: string; nextMonth?: string };
   onChange?: (date: Date) => void;
 }
 
-function isSameDay(a: Date, b: Date): boolean {
-  return a.getFullYear() === b.getFullYear() &&
-    a.getMonth() === b.getMonth() &&
-    a.getDate() === b.getDate();
-}
-
-function toMidnight(date: Date): Date {
-  return new Date(date.getFullYear(), date.getMonth(), date.getDate());
+function monthIndex(d: Date): number {
+  return d.getFullYear() * 12 + d.getMonth();
 }
-
-function isOutOfRange(date: Date, min?: Date, max?: Date): boolean {
-  const d = toMidnight(date);
-  if (min && d < toMidnight(min)) return true;
-  return !!(max && d > toMidnight(max));
-
+function isMonthVisible(date: Date, viewYear: number, viewMonth: number, months: number): boolean {
+  const start = viewYear * 12 + viewMonth;
+  const idx = monthIndex(date);
+  return idx >= start && idx < start + months;
 }
-
-function getDaysInMonth(year: number, month: number): number {
-  return new Date(year, month + 1, 0).getDate();
-}
-
-function getFirstDayOfMonth(year: number, month: number): number {
-  return new Date(year, month, 1).getDay();
+function weekdayNamesFrom(fmt: (d: Date) => string, firstDayOfWeek: number): string[] {
+  return Array.from({ length: 7 }, (_, i) => fmt(new Date(2023, 0, 1 + ((firstDayOfWeek + i) % 7))));
 }
 
-export function Calendar({ value, defaultValue, min, max, onChange, className, ...rest }: Readonly<CalendarProps>) {
+export function Calendar({
+  value, defaultValue, min, max,
+  months = 1, pageBy = 'months', firstDayOfWeek = 1, locale,
+  isDateDisallowed, formatWeekday, formatMonth, formatDay, labels,
+  onChange, className, ...rest
+}: Readonly<CalendarProps>) {
   const today = new Date();
   const controlled = value !== undefined;
   const [internal, setInternal] = useState<Date | undefined>(defaultValue);
   const selected = controlled ? value : internal;
 
-  const [viewYear, setViewYear] = useState(selected?.getFullYear() ?? today.getFullYear());
-  const [viewMonth, setViewMonth] = useState(selected?.getMonth() ?? today.getMonth());
-  const [focusedDay, setFocusedDay] = useState<number | undefined>();
+  const base = selected ?? today;
+  const [viewYear, setViewYear] = useState(base.getFullYear());
+  const [viewMonth, setViewMonth] = useState(base.getMonth());
+  const [focusedIso, setFocusedIso] = useState<ISODate | undefined>();
+
+  const headingBaseId = useId();
+  const dayRefs = useRef<Map<ISODate, HTMLButtonElement>>(new Map());
+  const registerRef = useCallback((iso: ISODate, el: HTMLButtonElement | null) => {
+    if (el) dayRefs.current.set(iso, el);
+    else dayRefs.current.delete(iso);
+  }, []);
+
+  // Keep the shown month in sync when the controlled value moves out of view.
+  useEffect(() => {
+    if (!controlled || !value) return;
+    if (!isMonthVisible(value, viewYear, viewMonth, months)) {
+      setViewYear(value.getFullYear());
+      setViewMonth(value.getMonth());
+    }
+    // Intentionally re-syncs only on the controlled value itself, not on internal month navigation.
+  }, [controlled, value]);
+
+  // Move DOM focus onto the roving-tabindex day when it changes.
+  useEffect(() => {
+    if (focusedIso) dayRefs.current.get(focusedIso)?.focus();
+  }, [focusedIso, viewYear, viewMonth]);
 
-  const titleId = useId();
-  const daysInMonth = getDaysInMonth(viewYear, viewMonth);
-  const firstDay = getFirstDayOfMonth(viewYear, viewMonth);
+  const disabledFor = (date: Date) => coreIsDisabled(date, { min, max, isDateDisallowed });
 
-  const navigate = (delta: number) => {
-    const d = new Date(viewYear, viewMonth + delta, 1);
+  const page = (dir: number) => {
+    const step = pageBy === 'single' ? 1 : months;
+    const d = new Date(viewYear, viewMonth + dir * step, 1);
     setViewYear(d.getFullYear());
     setViewMonth(d.getMonth());
-    setFocusedDay(undefined);
+    setFocusedIso(undefined);
   };
 
-  const selectDay = (day: number) => {
-    const date = new Date(viewYear, viewMonth, day);
-    if (isOutOfRange(date, min, max)) return;
+  const select = (date: Date) => {
+    if (disabledFor(date)) return;
     if (!controlled) setInternal(date);
     onChange?.(date);
   };
 
-  const handleKeyDown = (e: KeyboardEvent<HTMLElement>, day: number) => {
-    const map: Record<string, number> = {
-      ArrowRight: 1, ArrowLeft: -1, ArrowDown: 7, ArrowUp: -7,
-    };
-    if (e.key in map) {
-      e.preventDefault();
-      const current = new Date(viewYear, viewMonth, day);
-      const next = new Date(current);
-      next.setDate(next.getDate() + map[e.key]);
-      setViewYear(next.getFullYear());
-      setViewMonth(next.getMonth());
-      setFocusedDay(next.getDate());
-    } else if (e.key === 'Home') {
-      e.preventDefault();
-      setFocusedDay(1);
-    } else if (e.key === 'End') {
-      e.preventDefault();
-      setFocusedDay(daysInMonth);
-    } else if (e.key === 'Enter' || e.key === ' ') {
+  const moveFocus = (target: Date) => {
+    setFocusedIso(toISO(target));
+    if (!isMonthVisible(target, viewYear, viewMonth, months)) {
+      setViewYear(target.getFullYear());
+      setViewMonth(target.getMonth());
+    }
+  };
+
+  const onKeyDown = (e: KeyboardEvent<HTMLElement>, date: Date) => {
+    if (e.key === 'Enter' || e.key === ' ') {
       e.preventDefault();
-      selectDay(day);
+      select(date);
+      return;
     }
+    const next = nextFocusDate(date, e.key, { shiftKey: e.shiftKey, firstDayOfWeek });
+    if (!next) return;
+    e.preventDefault();
+    moveFocus(next);
   };
 
-  // Build grid: leading empty cells, then day cells
-  const cells: Array<{ day: number } | null> = [
-    ...Array.from({ length: firstDay }, () => null),
-    ...Array.from({ length: daysInMonth }, (_, i) => ({ day: i + 1 })),
-  ];
-  // Pad to complete last row
-  while (cells.length % 7 !== 0) cells.push(null);
+  // Roving tabindex: exactly one tabbable day.
+  const selectedVisible = selected && isMonthVisible(selected, viewYear, viewMonth, months) ? selected : undefined;
+  const todayVisible = isMonthVisible(today, viewYear, viewMonth, months) ? today : undefined;
+  const tabbableIso = focusedIso
+    ?? (selectedVisible && toISO(selectedVisible))
+    ?? (todayVisible && toISO(todayVisible))
+    ?? toISO(new Date(viewYear, viewMonth, 1));
+
+  const classifyDay = (date: Date): DayState => ({
+    today: isSameDay(date, today),
+    selected: !!selected && isSameDay(date, selected),
+    rangeStart: false,
+    rangeEnd: false,
+    inRange: false,
+    disabled: disabledFor(date),
+    tabbable: toISO(date) === tabbableIso,
+  });
+
+  const weekdayNames = formatWeekday
+    ? weekdayNamesFrom(formatWeekday, firstDayOfWeek)
+    : getWeekdayNames(locale, firstDayOfWeek);
+  const labelOfMonth = (y: number, m: number) =>
+    formatMonth ? formatMonth(new Date(y, m, 1)) : getMonthLabel(y, m, locale);
+  const labelOfDay = (d: Date) => (formatDay ? formatDay(d) : getDayLabel(d, locale));
+  const prevLabel = labels?.previousMonth ?? 'Previous month';
+  const nextLabel = labels?.nextMonth ?? 'Next month';
+  const count = Math.max(1, months);
+  // Name every visible month in the group label, not just the first (matters for months > 1).
+  const groupLabel = Array.from({ length: count }, (_, i) => {
+    const d = new Date(viewYear, viewMonth + i, 1);
+    return labelOfMonth(d.getFullYear(), d.getMonth());
+  }).join(', ');
 
   return (
-    <div {...rest} className={cn(css.calendar, className)} role="group" aria-labelledby={titleId}>
-      <div className={css.header}>
-        <button
-          type="button"
-          className={css.navBtn}
-          aria-label="Previous month"
-          onClick={() => navigate(-1)}
-        >
-          <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5">
-            <path strokeLinecap="round" strokeLinejoin="round" d="M15 19l-7-7 7-7" />
-          </svg>
-        </button>
-        <span id={titleId} className={css.monthYear} aria-live="polite">
-          {MONTHS[viewMonth]} {viewYear}
-        </span>
-        <button
-          type="button"
-          className={css.navBtn}
-          aria-label="Next month"
-          onClick={() => navigate(1)}
-        >
-          <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5">
-            <path strokeLinecap="round" strokeLinejoin="round" d="M9 5l7 7-7 7" />
-          </svg>
-        </button>
+    <div {...rest} className={cn(css.calendar, className)} role="group" aria-label={groupLabel}>
+      <div className={css.months}>
+        {Array.from({ length: count }, (_, i) => {
+          const d = new Date(viewYear, viewMonth + i, 1);
+          return (
+            <MonthGrid
+              key={i}
+              year={d.getFullYear()}
+              month={d.getMonth()}
+              firstDayOfWeek={firstDayOfWeek}
+              weekdayNames={weekdayNames}
+              monthLabel={labelOfMonth(d.getFullYear(), d.getMonth())}
+              headingId={`${headingBaseId}-${i}`}
+              showPrev={i === 0}
+              showNext={i === count - 1}
+              onPrev={() => page(-1)}
+              onNext={() => page(1)}
+              prevLabel={prevLabel}
+              nextLabel={nextLabel}
+              classifyDay={classifyDay}
+              formatDay={labelOfDay}
+              registerRef={registerRef}
+              onSelect={select}
+              onKeyDown={onKeyDown}
+            />
+          );
+        })}
       </div>
-
-      <table
-        className={css.grid}
-        role="grid"
-        aria-labelledby={titleId}
-      >
-        <thead>
-          <tr>
-            {DAYS.map(d => (
-              <th key={d} scope="col" aria-label={DAY_LABELS[d] ?? d} className={css.weekday}>
-                {d}
-              </th>
-            ))}
-          </tr>
-        </thead>
-        <tbody>
-          {Array.from({ length: cells.length / 7 }, (_, row) => (
-            <tr key={row}>
-              {cells.slice(row * 7, row * 7 + 7).map((cell, col) => {
-                if (!cell) return <td key={col} className={css.empty} aria-hidden="true" />;
-
-                const date = new Date(viewYear, viewMonth, cell.day);
-                const isSelected = selected ? isSameDay(date, selected) : false;
-                const isToday = isSameDay(date, today);
-                const disabled = isOutOfRange(date, min, max);
-                const isFocused = focusedDay === cell.day;
-
-                return (
-                  <td key={col} role="gridcell">
-                    <button
-                      type="button"
-                      className={cn(
-                        css.day,
-                        isSelected && css.selected,
-                        isToday && !isSelected && css.today,
-                        disabled && css.disabled,
-                      )}
-                      aria-label={date.toLocaleDateString('en', { month: 'long', day: 'numeric', year: 'numeric' })}
-                      aria-selected={isSelected}
-                      aria-current={isToday ? 'date' : undefined}
-                      aria-disabled={disabled}
-                      disabled={disabled}
-                      tabIndex={isFocused || (!focusedDay && isSelected) || (!focusedDay && !selected && isToday) ? 0 : -1}
-                      onClick={() => selectDay(cell.day)}
-                      onKeyDown={e => handleKeyDown(e, cell.day)}
-                    >
-                      {cell.day}
-                    </button>
-                  </td>
-                );
-              })}
-            </tr>
-          ))}
-        </tbody>
-      </table>
     </div>
   );
 }

package/src/components/ui/Calendar/CalendarRange.mdx

@@ -0,0 +1,39 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './CalendarRange.stories';
+
+<Meta of={Stories} />
+
+# CalendarRange
+
+Two-click date-range picker built on the same grid and date core as `Calendar`.
+Click a start date, then an end date; the days between preview on hover and while
+navigating with the keyboard. The pair is always returned earliest-first.
+
+## When to use
+- Booking flows, reporting windows, or any "from / to" date selection
+- Pair with `months={2}` to show consecutive months side by side
+
+## Examples
+
+### Default (uncontrolled)
+<Canvas of={Stories.Default} />
+
+### Two months
+<Canvas of={Stories.TwoMonths} />
+
+### With min/max constraints
+<Canvas of={Stories.WithMinMax} />
+
+## Props
+
+> Shares all configuration props with `Calendar` (`min`, `max`, `months`, `pageBy`,
+> `firstDayOfWeek`, `locale`, `isDateDisallowed`, `formatWeekday`, `formatMonth`,
+> `formatDay`, `labels`). `value` and `onChange` operate on a `[Date, Date]` pair.
+
+<ArgTypes of={Stories} />
+
+## Accessibility
+
+- Same WAI-ARIA grid pattern as `Calendar`: `role="grid"` / `row` / `columnheader` / `gridcell`, roving tabindex, arrow-key navigation, `Enter`/`Space` to pick
+- The start and end days carry `aria-selected="true"` on their gridcell
+- `Escape` cancels an in-progress selection