@astryxdesign/core 0.4.4 → 0.4.5-canary.013e728

package/src/Breadcrumbs/BreadcrumbItem.tsx

@@ -158,7 +158,7 @@ const itemStyles = stylex.create({
     paddingBlock: spacingVars['--spacing-1'],
     textDecoration: {
       default: 'none',
-      ':hover': {
+      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
         '@media (hover: hover)': 'underline',
       },
     },

package/src/Button/Button.tsx

@@ -107,11 +107,11 @@ const styles = stylex.create({
     },
   },
   ariaDisabled: {
+    // The variants' hover treatment already steps aside for
+    // `[aria-disabled]`; `:active` still matches a press on an aria-disabled
+    // button, so that one is suppressed here.
     backgroundImage: {
       default: 'none',
-      ':hover': {
-        '@media (hover: hover)': 'none',
-      },
       ':active': 'none',
     },
   },
@@ -198,7 +198,7 @@ const variants = stylex.create({
     color: colorVars['--color-on-accent'],
     backgroundImage: {
       default: null,
-      ':hover': {
+      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
         '@media (hover: hover)': `linear-gradient(${colorVars['--color-overlay-hover']}, ${colorVars['--color-overlay-hover']})`,
       },
       ':active': `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`,
@@ -209,7 +209,7 @@ const variants = stylex.create({
     color: colorVars['--color-text-primary'],
     backgroundImage: {
       default: null,
-      ':hover': {
+      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
         '@media (hover: hover)': `linear-gradient(${colorVars['--color-overlay-hover']}, ${colorVars['--color-overlay-hover']})`,
       },
       ':active': `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`,
@@ -220,7 +220,7 @@ const variants = stylex.create({
     color: colorVars['--color-text-primary'],
     backgroundImage: {
       default: null,
-      ':hover': {
+      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
         '@media (hover: hover)': `linear-gradient(${colorVars['--color-overlay-hover']}, ${colorVars['--color-overlay-hover']})`,
       },
       ':active': `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`,
@@ -235,7 +235,7 @@ const variants = stylex.create({
     outlineColor: {default: null, ':focus-visible': colorVars['--color-error']},
     backgroundImage: {
       default: null,
-      ':hover': {
+      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
         '@media (hover: hover)': `linear-gradient(${colorVars['--color-overlay-hover']}, ${colorVars['--color-overlay-hover']})`,
       },
       ':active': `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`,

package/src/Calendar/Calendar.doc.mjs

@@ -68,6 +68,18 @@ export const docs = {
       type: 'Array<(date: Date) => boolean>',
       description: 'Custom constraint functions.',
     },
+    {
+      name: 'maxRangeSpan',
+      type: 'number',
+      description:
+        'Range mode: max days a range may span, both endpoints counted (7 = a 7-day window). Caps the window from the picked start; before a start is picked every day stays selectable.',
+    },
+    {
+      name: 'minRangeSpan',
+      type: 'number',
+      description:
+        'Range mode: min days a range must span, both endpoints counted (2 forbids a single-day range). Default 1.',
+    },
     {
       name: 'focusDate',
       type: 'ISODateString',
@@ -142,6 +154,8 @@ export const docsZh = {
     {name: 'min', type: 'ISODateString', description: '可选择的最早日期。'},
     {name: 'max', type: 'ISODateString', description: '可选择的最晚日期。'},
     {name: 'dateConstraints', type: 'Array<(date: Date) => boolean>', description: '自定义约束函数。'},
+    {name: 'maxRangeSpan', type: 'number', description: '范围模式：范围最多可跨越的天数，含首尾两端（7 = 7 天窗口）。选定起始日后限制窗口大小。'},
+    {name: 'minRangeSpan', type: 'number', description: '范围模式：范围最少需跨越的天数，含首尾两端（2 表示禁止单日范围）。默认为 1。'},
     {name: 'focusDate', type: 'ISODateString', description: '受控可见月份。'},
     {name: 'onFocusDateChange', type: '(focusDate: ISODateString) => void', description: '导航回调函数。'},
     {name: 'handleRef', type: 'React.Ref<CalendarHandle>', description: '日历导航的命令式句柄，包括 navigateTo()。'},
@@ -205,6 +219,8 @@ export const docsDense = {
     min: 'minimum selectable date',
     max: 'maximum selectable date',
     dateConstraints: 'custom constraint fns',
+    maxRangeSpan: 'range mode: max days a range may span, both ends counted (7 = 7-day window)',
+    minRangeSpan: 'range mode: min days a range must span, both ends counted (default 1)',
     focusDate: 'controlled visible month',
     onFocusDateChange: 'navigation callback',
     handleRef: 'imperative navigation handle',

package/src/Calendar/Calendar.test.tsx

@@ -21,6 +21,8 @@ import {calendarStyles} from './styles';
 import {defineTheme} from '../theme/defineTheme';
 import {generateThemeCSS} from '../theme/generateThemeRules';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
+import {InternationalizationProvider} from '../i18n/InternationalizationProvider';
+import {standaloneShortWeekdayNamesByLocale} from './standaloneShortWeekdayNames.generated';
 
 function generateThemeTestCSS(theme: Parameters<typeof generateThemeCSS>[0]) {
   const {prose, component} = generateThemeCSS(theme);
@@ -120,6 +122,45 @@ describe('Calendar', () => {
     expect(screen.getByText('Sa')).toBeInTheDocument();
   });
 
+  it('uses the provider locale for stand-alone short day names', () => {
+    const localizedNames = standaloneShortWeekdayNamesByLocale.es;
+    const englishNames = standaloneShortWeekdayNamesByLocale.en;
+    expect(localizedNames).not.toEqual(englishNames);
+
+    const {rerender} = render(
+      <InternationalizationProvider locale="es-ES">
+        <Calendar />
+      </InternationalizationProvider>,
+    );
+
+    expect(
+      screen.getAllByRole('columnheader').map(header => header.textContent),
+    ).toEqual(localizedNames);
+
+    rerender(
+      <InternationalizationProvider locale="en">
+        <Calendar />
+      </InternationalizationProvider>,
+    );
+    expect(
+      screen.getAllByRole('columnheader').map(header => header.textContent),
+    ).toEqual(englishNames);
+  });
+
+  it('rotates localized day names by numeric weekday index', () => {
+    const localizedNames = standaloneShortWeekdayNamesByLocale.es;
+
+    render(
+      <InternationalizationProvider locale="es-ES">
+        <Calendar weekStartsOn={1} />
+      </InternationalizationProvider>,
+    );
+
+    expect(
+      screen.getAllByRole('columnheader').map(header => header.textContent),
+    ).toEqual([...localizedNames.slice(1), localizedNames[0]]);
+  });
+
   it('displays correct number of day cells', () => {
     render(<Calendar />);
 
@@ -236,6 +277,102 @@ describe('Calendar', () => {
     expect(sunday).toBeDisabled();
   });
 
+  it('caps the end date to maxRangeSpan once a start is picked', async () => {
+    const user = userEvent.setup();
+
+    render(<Calendar mode="range" focusDate="2026-01-01" maxRangeSpan={7} />);
+
+    // Before a start is picked every day is selectable.
+    expect(getDayButton(20)).not.toBeDisabled();
+
+    // Pick Jan 10 as the start. A 7-day window spans Jan 4–16 (start ± 6).
+    await user.click(getDayButton(10));
+
+    expect(getDayButton(16)).not.toBeDisabled(); // 6 days after — the edge
+    expect(getDayButton(17)).toBeDisabled(); // 7 days after — beyond the cap
+    expect(getDayButton(4)).not.toBeDisabled(); // 6 days before — symmetric
+    expect(getDayButton(3)).toBeDisabled(); // 7 days before — beyond the cap
+  });
+
+  it('enforces minRangeSpan once a start is picked', async () => {
+    const user = userEvent.setup();
+
+    render(<Calendar mode="range" focusDate="2026-01-01" minRangeSpan={3} />);
+
+    // Pick Jan 10. A 3-day minimum forbids ends closer than 2 days away.
+    await user.click(getDayButton(10));
+
+    // The picked start itself stays enabled — it is the active selection
+    // anchor, not an unreachable end.
+    expect(getDayButton(10)).not.toBeDisabled();
+    expect(getDayButton(11)).toBeDisabled(); // 1 day apart — too short
+    expect(getDayButton(12)).not.toBeDisabled(); // 3-day span — allowed
+    expect(getDayButton(8)).not.toBeDisabled(); // 3-day span the other way
+    expect(getDayButton(9)).toBeDisabled(); // 2-day span — too short
+  });
+
+  it('clears the in-progress start when the anchor is clicked again', async () => {
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+
+    render(
+      <Calendar
+        mode="range"
+        focusDate="2026-01-01"
+        onChange={handleChange}
+        minRangeSpan={3}
+      />,
+    );
+
+    // Pick Jan 10 as the start, then click it again.
+    await user.click(getDayButton(10));
+    await user.click(getDayButton(10));
+
+    // No zero-length range is committed…
+    expect(handleChange).not.toHaveBeenCalled();
+
+    // …and the start is cleared: the days that minRangeSpan disabled around
+    // the old anchor are selectable again, so a new start can be placed there.
+    expect(getDayButton(11)).not.toBeDisabled();
+    expect(getDayButton(9)).not.toBeDisabled();
+  });
+
+  it('does not apply range-span constraints in single mode', async () => {
+    const user = userEvent.setup();
+
+    render(<Calendar focusDate="2026-01-01" maxRangeSpan={7} />);
+
+    // A picked single date must not disable far-away days.
+    await user.click(getDayButton(10));
+    expect(getDayButton(25)).not.toBeDisabled();
+  });
+
+  it('keeps a controlled value that is wider than maxRangeSpan (selection-only)', () => {
+    // The span constraint governs which days are pickable, not validation of
+    // an already-set value — so a 15-day value under a 7-day cap stays
+    // rendered and is never silently rewritten.
+    render(
+      <Calendar
+        mode="range"
+        value={{start: '2026-01-05', end: '2026-01-20'}}
+        focusDate="2026-01-01"
+        maxRangeSpan={7}
+      />,
+    );
+
+    // No selection is in progress (both endpoints are set), so no anchor →
+    // every day is pickable and both endpoints render selected.
+    expect(getDayButton(20)).not.toBeDisabled();
+    expect(getDayButton(5).closest('[role="gridcell"]')).toHaveAttribute(
+      'aria-selected',
+      'true',
+    );
+    expect(getDayButton(20).closest('[role="gridcell"]')).toHaveAttribute(
+      'aria-selected',
+      'true',
+    );
+  });
+
   // ─── Multi-Month ─────────────────────────────────────────────
 
   it('renders two months when numberOfMonths={2}', () => {

package/src/Calendar/Calendar.tsx

@@ -18,6 +18,7 @@
  */
 
 import {
+  use,
   useState,
   useMemo,
   useCallback,
@@ -86,7 +87,7 @@ import type {
 } from '../utils/dateTypes';
 import {normalizeDayOfWeek} from '../utils/dateTypes';
 import {themeProps} from '../utils/themeProps';
-import {useTranslator} from '../i18n';
+import {useTranslator, InternationalizationContext} from '../i18n';
 
 /** Imperative handle for Calendar handleRef */
 
@@ -120,6 +121,25 @@ interface CalendarBaseProps extends Omit<
    */
   dateConstraints?: ReadonlyArray<(date: Date) => boolean>;
 
+  /**
+   * Range mode only. Maximum number of days a selected range may span,
+   * counting both endpoints — `maxRangeSpan={7}` allows a 7-day window
+   * (start + 6 days). Once a start date is picked, days beyond this distance
+   * from it are disabled in either direction; before a start is picked every
+   * otherwise-valid day stays selectable. Use for rolling windows like "at
+   * most a week from the chosen day". For fixed calendar bounds use min/max.
+   */
+  maxRangeSpan?: number;
+
+  /**
+   * Range mode only. Minimum number of days a selected range must span,
+   * counting both endpoints — `minRangeSpan={2}` forbids a single-day range.
+   * Once a start date is picked, days closer than this to it are disabled —
+   * except the start itself, which stays selectable as the active anchor.
+   * Defaults to 1 (a same-day start and end is allowed).
+   */
+  minRangeSpan?: number;
+
   /**
    * Controlled focus date (which month is visible).
    * If not provided, defaults to selected date or today.
@@ -201,6 +221,7 @@ export type CalendarProps = CalendarSingleProps | CalendarRangeProps;
  */
 export function Calendar({ref, ...props}: CalendarProps) {
   const t = useTranslator();
+  const {locale} = use(InternationalizationContext);
   const {
     handleRef,
     mode = 'single',
@@ -211,6 +232,8 @@ export function Calendar({ref, ...props}: CalendarProps) {
     min,
     max,
     dateConstraints,
+    maxRangeSpan,
+    minRangeSpan,
     focusDate: focusDateProp,
     onFocusDateChange,
     hasOutsideDays = true,
@@ -306,12 +329,12 @@ export function Calendar({ref, ...props}: CalendarProps) {
   // Format month header
   const monthYearLabel = useMemo(() => {
     if (numberOfMonths === 1) {
-      return plainDateFormat(visibleMonths[0], DATE_FORMAT_MONTH_YEAR);
+      return plainDateFormat(visibleMonths[0], DATE_FORMAT_MONTH_YEAR, locale);
     }
     return visibleMonths
-      .map(m => plainDateFormat(m, DATE_FORMAT_MONTH_YEAR))
+      .map(m => plainDateFormat(m, DATE_FORMAT_MONTH_YEAR, locale))
       .join(' – ');
-  }, [visibleMonths, numberOfMonths]);
+  }, [visibleMonths, numberOfMonths, locale]);
 
   // Announce the newly visible month to screen readers whenever it changes.
   // The visible month label (`<span>`) carries no live semantics, so paging the
@@ -419,12 +442,29 @@ export function Calendar({ref, ...props}: CalendarProps) {
           setRangeSelectionStart(iso);
           announce(
             t('@astryx.calendar.rangeStartAnnounce', {
-              date: plainDateFormat(date, DATE_FORMAT_WITH_WEEKDAY),
+              date: plainDateFormat(date, DATE_FORMAT_WITH_WEEKDAY, locale),
             }),
           );
         } else {
           // Second click - complete the range
           const startPd = plainDateFromISO(rangeSelectionStart);
+
+          // Clicking the anchor again clears the in-progress start rather than
+          // committing a zero-length range. This is also the escape hatch when
+          // `minRangeSpan` disables the days around the anchor: without it the
+          // anchor would be the only clickable day left and the start could
+          // never be moved. `minRangeSpan` leaves the anchor itself enabled
+          // precisely so this toggle stays reachable.
+          if (plainDateIsEqual(date, startPd)) {
+            setRangeSelectionStart(null);
+            announce(
+              t('@astryx.calendar.rangeClearedAnnounce', {
+                date: plainDateFormat(date, DATE_FORMAT_WITH_WEEKDAY),
+              }),
+            );
+            return;
+          }
+
           let start: ISODateString;
           let end: ISODateString;
 
@@ -448,17 +488,19 @@ export function Calendar({ref, ...props}: CalendarProps) {
               start: plainDateFormat(
                 plainDateFromISO(start),
                 DATE_FORMAT_WITH_WEEKDAY,
+                locale,
               ),
               end: plainDateFormat(
                 plainDateFromISO(end),
                 DATE_FORMAT_WITH_WEEKDAY,
+                locale,
               ),
             }),
           );
         }
       }
     },
-    [mode, onChange, rangeSelectionStart, announce, t],
+    [mode, onChange, rangeSelectionStart, announce, t, locale],
   );
 
   return (
@@ -528,6 +570,8 @@ export function Calendar({ref, ...props}: CalendarProps) {
             min={min}
             max={max}
             dateConstraints={dateConstraints}
+            maxRangeSpan={maxRangeSpan}
+            minRangeSpan={minRangeSpan}
             hasOutsideDays={hasOutsideDays}
             hasWeekNumbers={hasWeekNumbers}
             hasVariableRowCount={hasVariableRowCount}
@@ -567,6 +611,8 @@ interface MonthGridProps {
   min?: ISODateString;
   max?: ISODateString;
   dateConstraints?: ReadonlyArray<(date: Date) => boolean>;
+  maxRangeSpan?: number;
+  minRangeSpan?: number;
   hasOutsideDays: boolean;
   hasWeekNumbers: boolean;
   hasVariableRowCount: boolean;
@@ -589,6 +635,8 @@ function MonthGrid({
   min,
   max,
   dateConstraints,
+  maxRangeSpan,
+  minRangeSpan,
   hasOutsideDays,
   hasWeekNumbers,
   hasVariableRowCount,
@@ -601,6 +649,7 @@ function MonthGrid({
   pendingFocus,
   onPendingFocusHandled,
 }: MonthGridProps) {
+  const {locale} = use(InternationalizationContext);
   const year = month.year;
 
   // Use hooks for days generation and constraints
@@ -610,11 +659,30 @@ function MonthGrid({
     weekStartsOn,
     hasVariableRowCount,
   });
+  const dayNameHeaders = useMemo(
+    () =>
+      dayNames.map((name, offset) => ({
+        dayOfWeek: ((weekStartsOn + offset) % 7) as DayOfWeek,
+        name,
+      })),
+    [dayNames, weekStartsOn],
+  );
+
+  const rangeAnchor = useMemo(
+    () =>
+      mode === 'range' && rangeSelectionStart
+        ? plainDateFromISO(rangeSelectionStart)
+        : null,
+    [mode, rangeSelectionStart],
+  );
 
   const {isDateDisabled} = useCalendarConstraints({
     min,
     max,
     dateConstraints,
+    maxRangeSpan,
+    minRangeSpan,
+    rangeAnchor,
   });
 
   // Parse selected date for roving tabindex priority
@@ -803,8 +871,8 @@ function MonthGrid({
 
   // Month label for announcements
   const monthLabel = useMemo(() => {
-    return plainDateFormat(month, DATE_FORMAT_MONTH_YEAR);
-  }, [month]);
+    return plainDateFormat(month, DATE_FORMAT_MONTH_YEAR, locale);
+  }, [month, locale]);
 
   return (
     <div {...stylex.props(monthGridStyles.monthGrid)}>
@@ -833,9 +901,9 @@ function MonthGrid({
               )}
             />
           )}
-          {dayNames.map(name => (
+          {dayNameHeaders.map(({dayOfWeek, name}) => (
             <div
-              key={name}
+              key={dayOfWeek}
               role="columnheader"
               {...stylex.props(monthGridStyles.dayName)}>
               {name}
@@ -962,6 +1030,7 @@ function DayCell({
   onDayHover,
 }: DayCellProps) {
   const t = useTranslator();
+  const {locale} = use(InternationalizationContext);
   const {date, isOutside, dayNumber} = day;
 
   if (isOutside && !hasOutsideDays) {
@@ -1007,7 +1076,7 @@ function DayCell({
   // params rather than string concatenation. A mid-flight first pick (where
   // rangeStart === rangeEnd) reads as "range start" only; a completed one-day
   // range reads as both start and end.
-  const dateLabel = plainDateFormat(date, DATE_FORMAT_WITH_WEEKDAY);
+  const dateLabel = plainDateFormat(date, DATE_FORMAT_WITH_WEEKDAY, locale);
   const dayLabel = state.isSelected
     ? t('@astryx.calendar.daySelected', {date: dateLabel})
     : state.isRangeStart && state.isRangeEnd

package/src/Calendar/getStandaloneShortWeekdayNames.test.ts

@@ -0,0 +1,54 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file getStandaloneShortWeekdayNames.test.ts
+ * @input Private Calendar weekday locale resolver and generated CLDR data
+ * @output Regression coverage for exact, language, extension, and safe fallback
+ * @position Tests for getStandaloneShortWeekdayNames.ts
+ */
+
+import {describe, expect, it} from 'vitest';
+import {getStandaloneShortWeekdayNames} from './getStandaloneShortWeekdayNames';
+import {standaloneShortWeekdayNamesByLocale} from './standaloneShortWeekdayNames.generated';
+
+describe('getStandaloneShortWeekdayNames', () => {
+  it('preserves the default English weekday names', () => {
+    expect(getStandaloneShortWeekdayNames('en')).toEqual([
+      'Su',
+      'Mo',
+      'Tu',
+      'We',
+      'Th',
+      'Fr',
+      'Sa',
+    ]);
+  });
+
+  it('returns an exact generated locale entry', () => {
+    expect(getStandaloneShortWeekdayNames('ar-SA')).toBe(
+      standaloneShortWeekdayNamesByLocale['ar-SA'],
+    );
+  });
+
+  it('ignores Unicode extensions when resolving an exact locale', () => {
+    const expected = standaloneShortWeekdayNamesByLocale['zh-TW'];
+
+    expect(getStandaloneShortWeekdayNames('zh-TW')).toBe(expected);
+    expect(getStandaloneShortWeekdayNames('zh-TW-u-ca-chinese')).toBe(expected);
+  });
+
+  it('falls back from a regional locale to its base language', () => {
+    expect(getStandaloneShortWeekdayNames('es-ES')).toBe(
+      standaloneShortWeekdayNamesByLocale.es,
+    );
+  });
+
+  it('safely falls back to English for malformed and unsupported locales', () => {
+    expect(getStandaloneShortWeekdayNames('not_a_locale')).toBe(
+      standaloneShortWeekdayNamesByLocale.en,
+    );
+    expect(getStandaloneShortWeekdayNames('xx-ZZ')).toBe(
+      standaloneShortWeekdayNamesByLocale.en,
+    );
+  });
+});

package/src/Calendar/getStandaloneShortWeekdayNames.ts

@@ -0,0 +1,38 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file getStandaloneShortWeekdayNames.ts
+ * @input Generated CLDR stand-alone-short weekday table
+ * @output Private locale resolver for Calendar weekday headers
+ * @position Calendar-internal pure utility; not exported from the package
+ */
+
+import {
+  standaloneShortWeekdayNamesByLocale,
+  type StandaloneShortWeekdayNames,
+} from './standaloneShortWeekdayNames.generated';
+
+const weekdayNamesByLocale: Readonly<
+  Record<string, StandaloneShortWeekdayNames>
+> = standaloneShortWeekdayNamesByLocale;
+const englishWeekdayNames = weekdayNamesByLocale.en;
+
+/**
+ * Resolve generated weekday reference data as exact locale -> language -> English.
+ * Unicode extensions are ignored through Intl.Locale.baseName. Invalid tags and
+ * valid but unsupported languages safely use English.
+ */
+export function getStandaloneShortWeekdayNames(
+  locale: string,
+): StandaloneShortWeekdayNames {
+  try {
+    const parsed = new Intl.Locale(locale);
+    return (
+      weekdayNamesByLocale[parsed.baseName] ??
+      weekdayNamesByLocale[parsed.language] ??
+      englishWeekdayNames
+    );
+  } catch {
+    return englishWeekdayNames;
+  }
+}

package/src/Calendar/hooks/useCalendarConstraints.ts

@@ -20,6 +20,7 @@ import {
   plainDateToDate,
   plainDateIsBefore,
   plainDateIsAfter,
+  plainDateDiffDays,
 } from '../../utils/plainDate';
 
 /**
@@ -35,6 +36,25 @@ export interface UseCalendarConstraintsOptions {
    * Date is disabled if ANY function returns false.
    */
   dateConstraints?: ReadonlyArray<(date: Date) => boolean>;
+  /**
+   * Maximum number of days a range may span, counting both endpoints
+   * (a value of 7 allows a 7-day window). In range mode, once a start is
+   * picked, dates further than this from it are disabled. No effect until a
+   * range anchor exists.
+   */
+  maxRangeSpan?: number;
+  /**
+   * Minimum number of days a range must span, counting both endpoints
+   * (a value of 2 forbids a single-day range). In range mode, once a start
+   * is picked, dates closer than this to it are disabled.
+   */
+  minRangeSpan?: number;
+  /**
+   * The in-progress range start (first click, awaiting the second). Span
+   * constraints are measured from this date. Null when no selection is
+   * underway.
+   */
+  rangeAnchor?: PlainDate | null;
 }
 
 /**
@@ -53,13 +73,15 @@ export interface UseCalendarConstraintsReturn {
  * Hook for managing calendar date validation constraints.
  *
  * Provides a function to check if a date is disabled based on
- * min/max bounds and custom constraint functions.
+ * min/max bounds, range-span bounds, and custom constraint functions.
  *
  * @example
  * ```
  * const {isDateDisabled} = useCalendarConstraints({
  *   min: '2026-01-01',
  *   max: '2026-12-31',
+ *   maxRangeSpan: 7, // once a start is picked, cap the window at 7 days
+ *   rangeAnchor, // the in-progress start (null before the first click)
  *   dateConstraints: [
  *     (date) => date.getDay() !== 0, // No Sundays (receives native Date)
  *   ],
@@ -74,7 +96,8 @@ export interface UseCalendarConstraintsReturn {
 export function useCalendarConstraints(
   options: UseCalendarConstraintsOptions,
 ): UseCalendarConstraintsReturn {
-  const {min, max, dateConstraints} = options;
+  const {min, max, dateConstraints, maxRangeSpan, minRangeSpan, rangeAnchor} =
+    options;
 
   // Parse min/max dates
   const minDate = useMemo(() => (min ? plainDateFromISO(min) : null), [min]);
@@ -93,6 +116,27 @@ export function useCalendarConstraints(
         return true;
       }
 
+      // Range-span bounds, measured from the in-progress start. Spans count
+      // both endpoints (a span of 7 spans a 7-day window), so the reachable
+      // distance from the anchor is `span - 1` days in either direction. Only
+      // active once a start is picked — before that, every day stays pickable.
+      if (rangeAnchor) {
+        const distance = Math.abs(plainDateDiffDays(rangeAnchor, date));
+        if (maxRangeSpan != null && distance > maxRangeSpan - 1) {
+          return true;
+        }
+        // The anchor itself (distance 0) is never disabled by minRangeSpan —
+        // it is the picked start, and disabling it would render the active
+        // selection start as aria-disabled to keyboard and screen-reader users.
+        if (
+          minRangeSpan != null &&
+          distance > 0 &&
+          distance < minRangeSpan - 1
+        ) {
+          return true;
+        }
+      }
+
       // Check custom constraints (convert to Date for public API compatibility)
       if (dateConstraints) {
         for (const constraint of dateConstraints) {
@@ -104,7 +148,14 @@ export function useCalendarConstraints(
 
       return false;
     },
-    [minDate, maxDate, dateConstraints],
+    [
+      minDate,
+      maxDate,
+      dateConstraints,
+      maxRangeSpan,
+      minRangeSpan,
+      rangeAnchor,
+    ],
   );
 
   return {