@astryxdesign/core 0.0.0-bootstrap.0 → 0.1.0-canary.08d4cf4

package/src/Calendar/Calendar.doc.mjs

@@ -0,0 +1,205 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'Calendar',
+  displayName: 'Calendar',
+  category: 'Data Input',
+  keywords: ["calendar","datepicker","date picker","rangepicker","date range","monthview","daypicker"],
+  usage: {
+    description:
+      'Calendar lets the user pick a date or date range from a month grid. Use it in booking flows, scheduling UIs, date filters, or anywhere the user needs to see surrounding dates for context.',
+    bestPractices: [
+      {guidance: true, description: 'Set min and max dates to limit selection to a valid window, like only future dates for a booking or the current quarter for a report.'},
+      {guidance: true, description: 'Use range mode when the user needs to pick a start and end date, like a trip or a time-off request.'},
+      {guidance: true, description: 'Use dateConstraints to disable specific dates like weekends or holidays, and explain why they are unavailable.'},
+      {guidance: true, description: 'Show two months side by side when the user frequently selects dates that span a month boundary.'},
+      {guidance: false, description: 'Use a calendar for dates far in the past or future like a birth date. A text input is faster for open-ended entry.'},
+      {guidance: false, description: 'Disable large blocks of dates without context. The user should understand why dates are unavailable.'},
+    ],
+    anatomy: [
+      {name: 'Month header', required: true, description: 'The month name and year with navigation arrows to move between months.'},
+      {name: 'Day grid', required: true, description: 'A 7-column grid of days with column headers for the day names.'},
+      {name: 'Selected day', required: false, description: 'The currently selected date, highlighted. In range mode, the start and end dates plus the days between them.'},
+      {name: 'Today marker', required: false, description: 'A subtle indicator on the current date for orientation.'},
+    ],
+  },
+  props: [
+    {
+      name: 'mode',
+      type: "'single' | 'range'",
+      description: 'Selection mode.',
+      default: "'single'",
+    },
+    {
+      name: 'value',
+      type: 'ISODateString | DateRange',
+      description: 'Controlled selected value.',
+    },
+    {
+      name: 'defaultValue',
+      type: 'ISODateString | DateRange',
+      description: 'Uncontrolled default value.',
+    },
+    {
+      name: 'onChange',
+      type: 'Function',
+      description: 'Selection callback.',
+    },
+    {
+      name: 'numberOfMonths',
+      type: '1 | 2',
+      description: 'Number of months to display.',
+      default: '1',
+    },
+    {
+      name: 'min',
+      type: 'ISODateString',
+      description: 'Minimum selectable date.',
+    },
+    {
+      name: 'max',
+      type: 'ISODateString',
+      description: 'Maximum selectable date.',
+    },
+    {
+      name: 'dateConstraints',
+      type: 'Array<(date: Date) => boolean>',
+      description: 'Custom constraint functions.',
+    },
+    {
+      name: 'focusDate',
+      type: 'ISODateString',
+      description: 'Controlled visible month.',
+    },
+    {
+      name: 'onFocusDateChange',
+      type: '(focusDate: ISODateString) => void',
+      description: 'Navigation callback.',
+    },
+    {
+      name: 'handleRef',
+      type: 'React.Ref<CalendarHandle>',
+      description: 'Imperative handle for calendar navigation, including navigateTo().',
+    },
+    {
+      name: 'hasOutsideDays',
+      type: 'boolean',
+      description: 'Show days from adjacent months.',
+      default: 'true',
+    },
+    {
+      name: 'hasWeekNumbers',
+      type: 'boolean',
+      description: 'Show ISO week numbers.',
+      default: 'false',
+    },
+    {
+      name: 'hasVariableRowCount',
+      type: 'boolean',
+      description: 'Variable vs fixed 6-row grid.',
+      default: 'false',
+    },
+    {
+      name: 'weekStartsOn',
+      type: '0 | 1 | 2 | 3 | 4 | 5 | 6',
+      description: 'First day of week (0=Sunday).',
+      default: '0',
+    },
+  ],
+  theming: {
+    targets: [
+      {className: 'astryx-calendar', visualProps: ['mode']},
+      {className: 'astryx-calendar-day', states: ['selected', 'today', 'disabled', 'in-range']},
+    ],
+  },
+};
+
+/** @type {import('../docs-types').ComponentDoc} */
+export const docsZh = {
+  name: 'Calendar',
+  displayName: 'Calendar',
+  usage: {
+    description:
+      'Calendar lets the user pick a date or date range from a month grid. Use it in booking flows, scheduling UIs, date filters, or anywhere the user needs to see surrounding dates for context.',
+    bestPractices: [
+      {guidance: true, description: 'Set min and max dates to limit selection to a valid window, like only future dates for a booking or the current quarter for a report.'},
+      {guidance: true, description: 'Use range mode when the user needs to pick a start and end date, like a trip or a time-off request.'},
+      {guidance: true, description: 'Use dateConstraints to disable specific dates like weekends or holidays, and explain why they are unavailable.'},
+      {guidance: true, description: 'Show two months side by side when the user frequently selects dates that span a month boundary.'},
+      {guidance: false, description: 'Use a calendar for dates far in the past or future like a birth date. A text input is faster for open-ended entry.'},
+      {guidance: false, description: 'Disable large blocks of dates without context. The user should understand why dates are unavailable.'},
+    ],
+  },
+  props: [
+    {name: 'mode', type: "'single' | 'range'", description: '选择模式。', default: "'single'"},
+    {name: 'value', type: 'ISODateString | DateRange', description: '受控选中值。'},
+    {name: 'defaultValue', type: 'ISODateString | DateRange', description: '非受控默认值。'},
+    {name: 'onChange', type: 'Function', description: '选择回调函数。'},
+    {name: 'numberOfMonths', type: '1 | 2', description: '显示的月份数量。', default: '1'},
+    {name: 'min', type: 'ISODateString', description: '可选择的最早日期。'},
+    {name: 'max', type: 'ISODateString', description: '可选择的最晚日期。'},
+    {name: 'dateConstraints', type: 'Array<(date: Date) => boolean>', description: '自定义约束函数。'},
+    {name: 'focusDate', type: 'ISODateString', description: '受控可见月份。'},
+    {name: 'onFocusDateChange', type: '(focusDate: ISODateString) => void', description: '导航回调函数。'},
+    {name: 'handleRef', type: 'React.Ref<CalendarHandle>', description: '日历导航的命令式句柄，包括 navigateTo()。'},
+    {name: 'hasOutsideDays', type: 'boolean', description: '显示相邻月份的日期。', default: 'true'},
+    {name: 'hasWeekNumbers', type: 'boolean', description: '显示 ISO 周数。', default: 'false'},
+    {name: 'hasVariableRowCount', type: 'boolean', description: '可变行数与固定 6 行网格。', default: 'false'},
+    {name: 'weekStartsOn', type: '0 | 1 | 2 | 3 | 4 | 5 | 6', description: '每周起始日（0=周日）。', default: '0'},
+  ],
+  theming: {
+    targets: [
+      {
+        className: 'astryx-calendar',
+        visualProps: [
+          'mode',
+        ],
+      },
+      {
+        className: 'astryx-calendar-day',
+        states: [
+          'selected',
+          'today',
+          'disabled',
+          'in-range',
+        ],
+      },
+    ],
+  },
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+  description: 'month grid for picking a date or date range',
+  usage: {
+    description:
+      'Calendar lets the user pick a date or date range from a month grid. Use in booking, scheduling, date filters.',
+    bestPractices: [
+      {guidance: true, description: 'Set min/max to limit selection to a valid window: only future dates for booking, current quarter for a report.'},
+      {guidance: true, description: 'Use range mode when user picks start + end dates: trip, time-off request.'},
+      {guidance: true, description: 'Use dateConstraints to disable specific dates (weekends/holidays); explain why unavailable.'},
+      {guidance: true, description: 'Show two months side by side when user frequently selects dates spanning a month boundary.'},
+      {guidance: false, description: 'Use for dates far in the past/future; text input is faster.'},
+      {guidance: false, description: 'Disable dates without explaining why.'},
+    ],
+  },
+  propDescriptions: {
+    mode: 'selection mode',
+    value: 'controlled selected value',
+    defaultValue: 'uncontrolled default value',
+    onChange: 'selection callback',
+    numberOfMonths: 'months to display',
+    min: 'minimum selectable date',
+    max: 'maximum selectable date',
+    dateConstraints: 'custom constraint fns',
+    focusDate: 'controlled visible month',
+    onFocusDateChange: 'navigation callback',
+    handleRef: 'imperative navigation handle',
+    hasOutsideDays: 'show days from adjacent months',
+    hasWeekNumbers: 'show ISO week numbers',
+    hasVariableRowCount: 'variable vs fixed 6-row grid',
+    weekStartsOn: 'first day of week (0=Sunday)',
+  },
+};

package/src/Calendar/Calendar.test.tsx

@@ -0,0 +1,461 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Calendar.test.tsx
+ * @input Uses vitest, @testing-library/react
+ * @output Test suite for Calendar component
+ * @position Tests for Calendar.tsx
+ *
+ * SYNC: When Calendar.tsx changes, update tests accordingly
+ */
+
+import {describe, it, expect, vi} from 'vitest';
+import {act, render, screen} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import {Calendar} from './Calendar';
+import type {CalendarHandle} from './Calendar';
+
+/**
+ * Helper to find a day button by its day number.
+ * Day buttons have aria-labels like "Thursday, January 15, 2026".
+ */
+function getDayButton(day: number, month = 'January', year = 2026) {
+  // Match the full date pattern with the day number
+  const pattern = new RegExp(`${month}\\s+${day},\\s+${year}`);
+  return screen.getByRole('gridcell', {name: pattern});
+}
+
+describe('Calendar', () => {
+  // ─── Basic Rendering ─────────────────────────────────────────
+  it('forwards ref to the calendar root element', () => {
+    let root: HTMLDivElement | null = null;
+    render(
+      <Calendar
+        ref={el => {
+          root = el;
+        }}
+      />,
+    );
+    expect(root).toBeInstanceOf(HTMLDivElement);
+  });
+
+  it('exposes navigation through handleRef', () => {
+    let handle: CalendarHandle | null = null;
+    render(
+      <Calendar
+        handleRef={h => {
+          handle = h;
+        }}
+      />,
+    );
+
+    act(() => {
+      handle?.navigateTo('2026-03-01');
+    });
+
+    expect(screen.getByText('March 2026')).toBeInTheDocument();
+  });
+
+  it('renders current month by default', () => {
+    render(<Calendar />);
+
+    const today = new Date();
+    const formatter = new Intl.DateTimeFormat(undefined, {
+      year: 'numeric',
+      month: 'long',
+    });
+    const expectedLabel = formatter.format(today);
+
+    expect(screen.getByText(expectedLabel)).toBeInTheDocument();
+  });
+
+  it('displays day names', () => {
+    render(<Calendar />);
+
+    expect(screen.getByText('Su')).toBeInTheDocument();
+    expect(screen.getByText('Mo')).toBeInTheDocument();
+    expect(screen.getByText('Tu')).toBeInTheDocument();
+    expect(screen.getByText('We')).toBeInTheDocument();
+    expect(screen.getByText('Th')).toBeInTheDocument();
+    expect(screen.getByText('Fr')).toBeInTheDocument();
+    expect(screen.getByText('Sa')).toBeInTheDocument();
+  });
+
+  it('displays correct number of day cells', () => {
+    render(<Calendar />);
+
+    // 6 rows * 7 days = 42 cells (default fixed row count)
+    const buttons = screen.getAllByRole('gridcell');
+    expect(buttons.length).toBe(42);
+  });
+
+  // ─── Selection ───────────────────────────────────────────────
+
+  it('highlights selected date', () => {
+    render(<Calendar value="2026-01-15" focusDate="2026-01-01" />);
+
+    const day15 = getDayButton(15);
+    expect(day15).toHaveAttribute('aria-selected', 'true');
+  });
+
+  it('calls onChange when date is selected', async () => {
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+
+    render(<Calendar onChange={handleChange} focusDate="2026-01-01" />);
+
+    const day15 = getDayButton(15);
+    await user.click(day15);
+
+    expect(handleChange).toHaveBeenCalledTimes(1);
+    expect(handleChange).toHaveBeenCalledWith('2026-01-15', expect.any(Date));
+  });
+
+  // ─── Navigation ──────────────────────────────────────────────
+
+  it('navigates to previous month', async () => {
+    const user = userEvent.setup();
+
+    render(<Calendar focusDate="2026-02-01" />);
+
+    // Verify we start on February
+    expect(screen.getByText('February 2026')).toBeInTheDocument();
+
+    const prevButton = screen.getByRole('button', {name: 'Previous month'});
+    await user.click(prevButton);
+
+    expect(screen.getByText('January 2026')).toBeInTheDocument();
+  });
+
+  it('navigates to next month', async () => {
+    const user = userEvent.setup();
+
+    render(<Calendar focusDate="2026-01-01" />);
+
+    // Verify we start on January
+    expect(screen.getByText('January 2026')).toBeInTheDocument();
+
+    const nextButton = screen.getByRole('button', {name: 'Next month'});
+    await user.click(nextButton);
+
+    expect(screen.getByText('February 2026')).toBeInTheDocument();
+  });
+
+  it('calls onFocusDateChange when navigating', async () => {
+    const user = userEvent.setup();
+    const handleFocusChange = vi.fn();
+
+    render(
+      <Calendar
+        focusDate="2026-01-01"
+        onFocusDateChange={handleFocusChange}
+      />,
+    );
+
+    const nextButton = screen.getByRole('button', {name: 'Next month'});
+    await user.click(nextButton);
+
+    expect(handleFocusChange).toHaveBeenCalledWith('2026-02-01');
+  });
+
+  // ─── Date Constraints ────────────────────────────────────────
+
+  it('respects min date constraint', () => {
+    render(<Calendar focusDate="2026-01-01" min="2026-01-10" />);
+
+    // Day 5 should be disabled (before min)
+    const day5 = getDayButton(5);
+    expect(day5).toBeDisabled();
+
+    // Day 15 should be enabled (after min)
+    const day15 = getDayButton(15);
+    expect(day15).not.toBeDisabled();
+  });
+
+  it('respects max date constraint', () => {
+    render(<Calendar focusDate="2026-01-01" max="2026-01-20" />);
+
+    const day25 = getDayButton(25);
+    expect(day25).toBeDisabled();
+
+    const day15 = getDayButton(15);
+    expect(day15).not.toBeDisabled();
+  });
+
+  it('respects custom dateConstraints', () => {
+    // Only allow weekdays
+    const isWeekday = (date: Date) => {
+      const day = date.getDay();
+      return day !== 0 && day !== 6;
+    };
+
+    render(
+      <Calendar focusDate="2026-01-01" dateConstraints={[isWeekday]} />,
+    );
+
+    // January 4, 2026 is a Sunday - should be disabled
+    const sunday = getDayButton(4);
+    expect(sunday).toBeDisabled();
+  });
+
+  // ─── Multi-Month ─────────────────────────────────────────────
+
+  it('renders two months when numberOfMonths={2}', () => {
+    render(<Calendar numberOfMonths={2} focusDate="2026-01-01" />);
+
+    // The header shows both months
+    expect(screen.getByText(/January 2026.*February 2026/)).toBeInTheDocument();
+  });
+
+  it('navigation advances both months together', async () => {
+    const user = userEvent.setup();
+
+    render(<Calendar numberOfMonths={2} focusDate="2026-01-01" />);
+
+    const nextButton = screen.getByRole('button', {name: 'Next month'});
+    await user.click(nextButton);
+
+    expect(screen.getByText(/February 2026.*March 2026/)).toBeInTheDocument();
+  });
+
+  // ─── Display Options ─────────────────────────────────────────
+
+  it('shows week numbers when hasWeekNumbers is true', () => {
+    render(<Calendar hasWeekNumbers focusDate="2026-01-01" />);
+
+    // Look for week number cells - they should be in the grid but not buttons
+    // Week numbers for January 2026 include week 1, 2, 3, 4, 5
+    const weekNumberCells = screen.getAllByText(/^[1-5]$/);
+    // Should have more than just day numbers (week numbers add extra cells)
+    expect(weekNumberCells.length).toBeGreaterThan(5);
+  });
+
+  it('respects weekStartsOn option', () => {
+    render(<Calendar weekStartsOn={1} />);
+
+    // First day name should be Monday
+    const dayNames = screen.getAllByText(/^(Mo|Tu|We|Th|Fr|Sa|Su)$/);
+    expect(dayNames[0]).toHaveTextContent('Mo');
+  });
+
+  // ─── Range Mode ──────────────────────────────────────────────
+
+  it('supports range selection mode', async () => {
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+
+    render(
+      <Calendar
+        mode="range"
+        onChange={handleChange}
+        focusDate="2026-01-01"
+      />,
+    );
+
+    // Click start date
+    const day10 = getDayButton(10);
+    await user.click(day10);
+
+    // Click end date
+    const day15 = getDayButton(15);
+    await user.click(day15);
+
+    expect(handleChange).toHaveBeenCalledWith({
+      start: '2026-01-10',
+      end: '2026-01-15',
+    });
+  });
+
+  it('handles reverse range selection (end before start)', async () => {
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+
+    render(
+      <Calendar
+        mode="range"
+        onChange={handleChange}
+        focusDate="2026-01-01"
+      />,
+    );
+
+    // Click later date first
+    const day20 = getDayButton(20);
+    await user.click(day20);
+
+    // Click earlier date
+    const day10 = getDayButton(10);
+    await user.click(day10);
+
+    // Should swap to ensure start <= end
+    expect(handleChange).toHaveBeenCalledWith({
+      start: '2026-01-10',
+      end: '2026-01-20',
+    });
+  });
+
+  it('highlights range when value is provided', () => {
+    render(
+      <Calendar
+        mode="range"
+        value={{start: '2026-01-10', end: '2026-01-15'}}
+        focusDate="2026-01-01"
+      />,
+    );
+
+    const day10 = getDayButton(10);
+    const day12 = getDayButton(12);
+    const day15 = getDayButton(15);
+
+    expect(day10).toHaveAttribute('aria-selected', 'true');
+    expect(day12).toHaveAttribute('aria-selected', 'true');
+    expect(day15).toHaveAttribute('aria-selected', 'true');
+  });
+
+  // ─── Accessibility ───────────────────────────────────────────
+
+  it('has accessible grid structure', () => {
+    render(<Calendar focusDate="2026-01-01" />);
+
+    expect(screen.getByRole('grid')).toBeInTheDocument();
+    expect(screen.getAllByRole('row').length).toBeGreaterThan(0);
+    expect(screen.getAllByRole('gridcell').length).toBeGreaterThan(0);
+  });
+
+  it('has navigation buttons with accessible labels', () => {
+    render(<Calendar />);
+
+    expect(
+      screen.getByRole('button', {name: 'Previous month'}),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole('button', {name: 'Next month'}),
+    ).toBeInTheDocument();
+  });
+
+  // ─── Bug Regression Tests ───────────────────────────────────
+
+  it('day buttons have data-date attribute with ISO string', () => {
+    render(<Calendar focusDate="2026-01-01" />);
+
+    const day15 = getDayButton(15);
+    expect(day15).toHaveAttribute('data-date', '2026-01-15');
+  });
+
+  it('ArrowDown moves focus +7 days, not to same day in next month', async () => {
+    const user = userEvent.setup();
+    const handleFocusChange = vi.fn();
+
+    render(
+      <Calendar
+        focusDate="2026-01-01"
+        onFocusDateChange={handleFocusChange}
+      />,
+    );
+
+    // Focus Jan 28
+    const day28 = getDayButton(28);
+    await user.click(day28);
+    day28.querySelector('button')?.focus();
+
+    // Press ArrowDown — should move to Feb 4 (+7 days), not Feb 28
+    await user.keyboard('{ArrowDown}');
+
+    // After navigation, Feb 4 should be focused
+    const focusedElement = document.activeElement;
+    expect(focusedElement).toHaveAttribute('data-date', '2026-02-04');
+  });
+
+  it('prev button is disabled when focusDate month contains min', () => {
+    render(<Calendar focusDate="2026-01-01" min="2026-01-15" />);
+
+    const prevButton = screen.getByRole('button', {name: 'Previous month'});
+    expect(prevButton).toBeDisabled();
+  });
+
+  it('next button is disabled when focusDate month contains max', () => {
+    render(<Calendar focusDate="2026-01-01" max="2026-01-15" />);
+
+    const nextButton = screen.getByRole('button', {name: 'Next month'});
+    expect(nextButton).toBeDisabled();
+  });
+
+  it('outside days are not clickable when hasOutsideDays is true', async () => {
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+
+    render(
+      <Calendar
+        focusDate="2026-01-01"
+        hasOutsideDays
+        onChange={handleChange}
+      />,
+    );
+
+    // January 2026 starts on Thursday, so Dec 28-31 are outside days
+    // Find an outside day button (December day visible in January grid)
+    const outsideDays = screen.getAllByRole('gridcell').filter(cell => {
+      const button = cell.querySelector('button');
+      return button?.getAttribute('aria-disabled') === 'true';
+    });
+
+    // Click the first outside day
+    if (outsideDays[0]) {
+      const button = outsideDays[0].querySelector('button');
+      if (button) {
+        await user.click(button);
+      }
+    }
+
+    expect(handleChange).not.toHaveBeenCalled();
+  });
+
+  it('Escape cancels range selection in progress', async () => {
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+
+    render(
+      <Calendar
+        mode="range"
+        onChange={handleChange}
+        focusDate="2026-01-01"
+      />,
+    );
+
+    // Click start date to begin range selection
+    const day10 = getDayButton(10);
+    await user.click(day10);
+
+    // Press Escape to cancel
+    await user.keyboard('{Escape}');
+
+    // Click another date — should start a NEW range, not complete the old one
+    const day20 = getDayButton(20);
+    await user.click(day20);
+
+    // onChange should NOT have been called (no range completed)
+    expect(handleChange).not.toHaveBeenCalled();
+  });
+
+  it('day name headers have role="columnheader"', () => {
+    render(<Calendar focusDate="2026-01-01" />);
+
+    const columnHeaders = screen.getAllByRole('columnheader');
+    expect(columnHeaders.length).toBe(7);
+
+    // Verify they contain day name abbreviations
+    const dayNames = columnHeaders.map(h => h.textContent);
+    expect(dayNames).toEqual(['Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa']);
+  });
+
+  it('button inside gridcell does not duplicate role="gridcell"', () => {
+    render(<Calendar focusDate="2026-01-01" />);
+
+    const gridcells = screen.getAllByRole('gridcell');
+    for (const cell of gridcells) {
+      const button = cell.querySelector('button');
+      if (button) {
+        expect(button).not.toHaveAttribute('role', 'gridcell');
+      }
+    }
+  });
+});