@boostdev/design-system-components 2.8.0 → 2.11.0

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

@@ -0,0 +1,119 @@
+import { render, screen, fireEvent } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { CalendarRange } from './CalendarRange';
+
+const JAN = (d: number) => new Date(2024, 0, d);
+const day = (n: number) => screen.getByRole('button', { name: `January ${n}, 2024` });
+
+describe('CalendarRange', () => {
+  it('selects a range across two clicks and calls onChange with a sorted pair', async () => {
+    const onChange = vi.fn();
+    render(<CalendarRange value={[JAN(10), JAN(12)]} onChange={onChange} />);
+    await userEvent.click(day(5));
+    await userEvent.click(day(8));
+    expect(onChange).toHaveBeenCalledOnce();
+    const [start, end] = onChange.mock.calls[0][0] as [Date, Date];
+    expect(start.getDate()).toBe(5);
+    expect(end.getDate()).toBe(8);
+  });
+
+  it('auto-sorts when the second click precedes the first', async () => {
+    const onChange = vi.fn();
+    render(<CalendarRange value={[JAN(10), JAN(12)]} onChange={onChange} />);
+    await userEvent.click(day(8));
+    await userEvent.click(day(5));
+    const [start, end] = onChange.mock.calls[0][0] as [Date, Date];
+    expect(start.getDate()).toBe(5);
+    expect(end.getDate()).toBe(8);
+  });
+
+  it('sorts an externally reversed value pair for painting', () => {
+    render(<CalendarRange value={[JAN(12), JAN(10)]} onChange={() => {}} />);
+    expect(day(10)).toHaveAttribute('data-range-start');
+    expect(day(12)).toHaveAttribute('data-range-end');
+    expect(day(11)).toHaveAttribute('data-in-range');
+  });
+
+  it('marks a committed range with start/end/in-range hooks', () => {
+    render(<CalendarRange value={[JAN(10), JAN(12)]} onChange={() => {}} />);
+    expect(day(10)).toHaveAttribute('data-range-start');
+    expect(day(12)).toHaveAttribute('data-range-end');
+    expect(day(11)).toHaveAttribute('data-in-range');
+    expect(day(10).closest('[role="gridcell"]')).toHaveAttribute('aria-selected', 'true');
+  });
+
+  it('previews the range on hover after the first click', () => {
+    render(<CalendarRange value={[JAN(10), JAN(12)]} onChange={() => {}} />);
+    fireEvent.click(day(5));            // anchor
+    fireEvent.pointerEnter(day(8));     // hover preview
+    expect(day(5)).toHaveAttribute('data-range-start');
+    expect(day(8)).toHaveAttribute('data-range-end');
+    expect(day(6)).toHaveAttribute('data-in-range');
+    expect(day(7)).toHaveAttribute('data-in-range');
+  });
+
+  it('selects a range with the keyboard', async () => {
+    const onChange = vi.fn();
+    render(<CalendarRange value={[JAN(10), JAN(12)]} onChange={onChange} />);
+    day(10).focus();                    // committed start is tabbable
+    await userEvent.keyboard('{Enter}'); // anchor at Jan 10
+    await userEvent.keyboard('{ArrowRight}{Enter}'); // end at Jan 11
+    const [start, end] = onChange.mock.calls[0][0] as [Date, Date];
+    expect(start.getDate()).toBe(10);
+    expect(end.getDate()).toBe(11);
+  });
+
+  it('does not select disallowed dates', async () => {
+    const onChange = vi.fn();
+    render(<CalendarRange value={[JAN(10), JAN(12)]} min={JAN(6)} onChange={onChange} />);
+    expect(day(4)).toBeDisabled();
+    await userEvent.click(day(4));
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it('commits into internal state when uncontrolled', async () => {
+    render(<CalendarRange defaultValue={[JAN(10), JAN(12)]} onChange={() => {}} />);
+    await userEvent.click(day(5));
+    await userEvent.click(day(8));
+    expect(day(5)).toHaveAttribute('data-range-start');
+    expect(day(8)).toHaveAttribute('data-range-end');
+  });
+
+  it('shows two months when months=2', () => {
+    render(<CalendarRange value={[JAN(10), JAN(12)]} months={2} onChange={() => {}} />);
+    expect(screen.getByText('January 2024')).toBeInTheDocument();
+    expect(screen.getByText('February 2024')).toBeInTheDocument();
+  });
+
+  it('previews the range while navigating with the keyboard', async () => {
+    render(<CalendarRange value={[JAN(10), JAN(12)]} onChange={() => {}} />);
+    day(10).focus();
+    await userEvent.keyboard('{Enter}');                 // anchor at Jan 10
+    await userEvent.keyboard('{ArrowRight}{ArrowRight}'); // focus moves to Jan 12
+    expect(day(10)).toHaveAttribute('data-range-start');
+    expect(day(11)).toHaveAttribute('data-in-range');
+    expect(day(12)).toHaveAttribute('data-range-end');
+  });
+
+  it('cancels an in-progress selection on Escape', async () => {
+    const onChange = vi.fn();
+    render(<CalendarRange value={[JAN(10), JAN(12)]} onChange={onChange} />);
+    day(5).focus();
+    await userEvent.keyboard('{Enter}');   // anchor at Jan 5 (starts a new selection)
+    expect(day(5)).toHaveAttribute('data-range-start');
+    await userEvent.keyboard('{Escape}');  // cancel — committed range is restored
+    expect(onChange).not.toHaveBeenCalled();
+    expect(day(5)).not.toHaveAttribute('data-range-start');
+    expect(day(10)).toHaveAttribute('data-range-start');
+    expect(day(12)).toHaveAttribute('data-range-end');
+  });
+
+  it('does not end a range on a disallowed date', async () => {
+    const onChange = vi.fn();
+    render(<CalendarRange value={[JAN(10), JAN(12)]} min={JAN(6)} onChange={onChange} />);
+    await userEvent.click(day(8));  // anchor at Jan 8 (valid)
+    expect(day(4)).toBeDisabled();
+    await userEvent.click(day(4));  // Jan 4 < min → disabled, cannot end the range
+    expect(onChange).not.toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,51 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { CalendarRange } from './CalendarRange';
+
+const meta = {
+  title: 'React/UI/CalendarRange',
+  component: CalendarRange,
+  decorators: [
+    Story => (
+      <div style={{ display: 'flex', justifyContent: 'center', padding: '2rem' }}>
+        <Story />
+      </div>
+    ),
+  ],
+} satisfies Meta<typeof CalendarRange>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => {
+    const [range, setRange] = useState<[Date, Date] | undefined>();
+    return (
+      <div>
+        <CalendarRange value={range} onChange={setRange} />
+        {range && (
+          <p style={{ marginTop: '1rem', textAlign: 'center', fontSize: '0.875rem' }}>
+            {range[0].toLocaleDateString()} — {range[1].toLocaleDateString()}
+          </p>
+        )}
+      </div>
+    );
+  },
+};
+
+export const TwoMonths: Story = {
+  render: () => {
+    const [range, setRange] = useState<[Date, Date] | undefined>();
+    return <CalendarRange value={range} months={2} onChange={setRange} />;
+  },
+};
+
+export const WithMinMax: Story = {
+  render: () => {
+    const today = new Date();
+    const min = new Date(today.getFullYear(), today.getMonth(), 1);
+    const max = new Date(today.getFullYear(), today.getMonth() + 2, 0);
+    const [range, setRange] = useState<[Date, Date] | undefined>();
+    return <CalendarRange value={range} min={min} max={max} months={2} onChange={setRange} />;
+  },
+};

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

@@ -0,0 +1,213 @@
+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, isInRange, sortRange, isDisabled as coreIsDisabled,
+  toISO, parseISO, type ISODate, getWeekdayNames, getMonthLabel, getDayLabel, nextFocusDate,
+} from './calendar-core';
+
+type PageBy = 'months' | 'single';
+
+interface CalendarRangeProps
+  extends WithClassName,
+    Omit<HTMLAttributes<HTMLDivElement>, 'defaultValue' | 'onChange'> {
+  value?: [Date, Date];
+  defaultValue?: [Date, 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?: (range: [Date, Date]) => void;
+  onRangeStart?: (date: Date) => void;
+}
+
+function isMonthVisible(date: Date, viewYear: number, viewMonth: number, months: number): boolean {
+  const start = viewYear * 12 + viewMonth;
+  const idx = date.getFullYear() * 12 + date.getMonth();
+  return idx >= start && idx < start + months;
+}
+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 CalendarRange({
+  value, defaultValue, min, max,
+  months = 1, pageBy = 'months', firstDayOfWeek = 1, locale,
+  isDateDisallowed, formatWeekday, formatMonth, formatDay, labels,
+  onChange, onRangeStart, className, ...rest
+}: Readonly<CalendarRangeProps>) {
+  const today = new Date();
+  const controlled = value !== undefined;
+  const [internal, setInternal] = useState<[Date, Date] | undefined>(defaultValue);
+  const committed = controlled ? value : internal;
+
+  const [anchor, setAnchor] = useState<Date | undefined>();
+  const [hover, setHover] = useState<Date | undefined>();
+
+  const base = committed ? committed[0] : 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);
+  }, []);
+
+  useEffect(() => {
+    if (!controlled || !value) return;
+    if (!isMonthVisible(value[0], viewYear, viewMonth, months)) {
+      setViewYear(value[0].getFullYear());
+      setViewMonth(value[0].getMonth());
+    }
+    // Only re-sync when the controlled value itself changes, not on internal navigation.
+  }, [controlled, value]);
+
+  useEffect(() => {
+    if (focusedIso) dayRefs.current.get(focusedIso)?.focus();
+  }, [focusedIso, viewYear, viewMonth]);
+
+  const disabledFor = (date: Date) => coreIsDisabled(date, { min, max, isDateDisallowed });
+
+  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());
+    setFocusedIso(undefined);
+  };
+
+  const select = (date: Date) => {
+    if (disabledFor(date)) return;
+    if (!anchor) {
+      setAnchor(date);
+      setHover(undefined);
+      onRangeStart?.(date);
+    } else {
+      const pair = sortRange(anchor, date);
+      if (!controlled) setInternal(pair);
+      onChange?.(pair);
+      setAnchor(undefined);
+      setHover(undefined);
+    }
+  };
+
+  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();
+      select(date);
+      return;
+    }
+    if (e.key === 'Escape') {
+      if (anchor) { setAnchor(undefined); setHover(undefined); }
+      return;
+    }
+    const next = nextFocusDate(date, e.key, { shiftKey: e.shiftKey, firstDayOfWeek });
+    if (!next) return;
+    e.preventDefault();
+    moveFocus(next);
+  };
+
+  // Resolve the effective [start, end] used for painting: the in-progress
+  // selection (anchor + hover/focus preview) if anchoring, else the committed range.
+  let paintStart: Date | undefined;
+  let paintEnd: Date | undefined;
+  if (anchor) {
+    const previewEnd = hover ?? (focusedIso ? parseISO(focusedIso) ?? anchor : anchor);
+    [paintStart, paintEnd] = sortRange(anchor, previewEnd);
+  } else if (committed) {
+    // Sort so an externally-set out-of-order value pair still paints correctly.
+    [paintStart, paintEnd] = sortRange(committed[0], committed[1]);
+  }
+
+  const anchorVisible = anchor && isMonthVisible(anchor, viewYear, viewMonth, months) ? anchor : undefined;
+  const committedStartVisible = committed && isMonthVisible(committed[0], viewYear, viewMonth, months) ? committed[0] : undefined;
+  const todayVisible = isMonthVisible(today, viewYear, viewMonth, months) ? today : undefined;
+  const tabbableIso = focusedIso
+    ?? (anchorVisible && toISO(anchorVisible))
+    ?? (committedStartVisible && toISO(committedStartVisible))
+    ?? (todayVisible && toISO(todayVisible))
+    ?? toISO(new Date(viewYear, viewMonth, 1));
+
+  const classifyDay = (date: Date): DayState => {
+    const isStart = !!paintStart && isSameDay(date, paintStart);
+    const isEnd = !!paintEnd && isSameDay(date, paintEnd);
+    const inRange = !!paintStart && !!paintEnd && !isStart && !isEnd && isInRange(date, paintStart, paintEnd);
+    return {
+      today: isSameDay(date, today),
+      selected: false,
+      rangeStart: isStart,
+      rangeEnd: isEnd,
+      inRange,
+      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-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}
+              onDayPointerEnter={anchor ? (date => setHover(date)) : undefined}
+            />
+          );
+        })}
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,141 @@
+import { KeyboardEvent } from 'react';
+import { cn } from '@boostdev/design-system-foundation';
+import css from './Calendar.module.css';
+import { buildMonthGrid, type ISODate } from './calendar-core';
+
+export interface DayState {
+  today: boolean;
+  selected: boolean;
+  rangeStart: boolean;
+  rangeEnd: boolean;
+  inRange: boolean;
+  disabled: boolean;
+  tabbable: boolean;
+}
+
+export interface MonthGridProps {
+  year: number;
+  month: number;
+  firstDayOfWeek: number;
+  weekdayNames: string[];
+  monthLabel: string;
+  headingId: string;
+  showPrev: boolean;
+  showNext: boolean;
+  onPrev: () => void;
+  onNext: () => void;
+  prevLabel: string;
+  nextLabel: string;
+  classifyDay: (date: Date) => DayState;
+  formatDay: (date: Date) => string;
+  registerRef: (iso: ISODate, el: HTMLButtonElement | null) => void;
+  onSelect: (date: Date) => void;
+  onKeyDown: (e: KeyboardEvent<HTMLElement>, date: Date) => void;
+  onDayPointerEnter?: (date: Date) => void;
+}
+
+const ChevronLeft = () => (
+  <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>
+);
+const ChevronRight = () => (
+  <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>
+);
+
+export function MonthGrid(props: Readonly<MonthGridProps>) {
+  const {
+    year, month, firstDayOfWeek, weekdayNames, monthLabel, headingId,
+    showPrev, showNext, onPrev, onNext, prevLabel, nextLabel,
+    classifyDay, formatDay, registerRef, onSelect, onKeyDown, onDayPointerEnter,
+  } = props;
+
+  const cells = buildMonthGrid(year, month, firstDayOfWeek);
+  const rows = Array.from({ length: 6 }, (_, r) => cells.slice(r * 7, r * 7 + 7));
+
+  return (
+    <div className={css.month}>
+      <div className={css.monthHeader}>
+        <span className={css.navSlot}>
+          {showPrev && (
+            <button type="button" className={css.navBtn} aria-label={prevLabel} onClick={onPrev}>
+              <ChevronLeft />
+            </button>
+          )}
+        </span>
+        <span id={headingId} className={css.monthYear} aria-live="polite">{monthLabel}</span>
+        <span className={css.navSlot}>
+          {showNext && (
+            <button type="button" className={css.navBtn} aria-label={nextLabel} onClick={onNext}>
+              <ChevronRight />
+            </button>
+          )}
+        </span>
+      </div>
+
+      <div className={css.grid} role="grid" aria-labelledby={headingId}>
+        <div className={css.row} role="row">
+          {weekdayNames.map((name, i) => (
+            <span key={i} role="columnheader" className={css.weekday} aria-label={name}>{name}</span>
+          ))}
+        </div>
+        {rows.map((week, r) => (
+          <div key={r} className={css.row} role="row">
+            {week.map(cell => {
+              // Outside days (from adjacent months) are inert: greyed, disabled,
+              // and never carry selected/range/today state — classifyDay keys off
+              // the Date alone and can't tell an in-month cell from an outside cell
+              // sharing the same date, so gate the state here.
+              const s: DayState = cell.outside
+                ? { today: false, selected: false, rangeStart: false, rangeEnd: false, inRange: false, disabled: true, tabbable: false }
+                : classifyDay(cell.date);
+              const isEndpoint = s.selected || s.rangeStart || s.rangeEnd;
+              return (
+                <span
+                  key={cell.iso}
+                  role="gridcell"
+                  aria-selected={isEndpoint}
+                  className={css.cell}
+                >
+                  <button
+                    ref={el => registerRef(cell.iso, el)}
+                    type="button"
+                    data-date={cell.iso}
+                    data-outside={cell.outside || undefined}
+                    data-today={s.today || undefined}
+                    data-selected={s.selected || undefined}
+                    data-range-start={s.rangeStart || undefined}
+                    data-range-end={s.rangeEnd || undefined}
+                    data-in-range={s.inRange || undefined}
+                    className={cn(
+                      css.day,
+                      cell.outside && css.outside,
+                      s.today && !isEndpoint && css.today,
+                      s.selected && css.selected,
+                      s.rangeStart && css.rangeStart,
+                      s.rangeEnd && css.rangeEnd,
+                      s.inRange && css.inRange,
+                      s.disabled && css.disabled,
+                    )}
+                    aria-label={formatDay(cell.date)}
+                    aria-current={s.today ? 'date' : undefined}
+                    aria-disabled={s.disabled || undefined}
+                    disabled={s.disabled || cell.outside}
+                    tabIndex={s.tabbable ? 0 : -1}
+                    onClick={() => onSelect(cell.date)}
+                    onKeyDown={e => onKeyDown(e, cell.date)}
+                    onPointerEnter={onDayPointerEnter ? () => onDayPointerEnter(cell.date) : undefined}
+                  >
+                    {cell.day}
+                  </button>
+                </span>
+              );
+            })}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}