@astryxdesign/core 0.4.3 → 0.4.4-canary.0e8af82

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

@@ -236,6 +236,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

@@ -120,6 +120,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.
@@ -211,6 +230,8 @@ export function Calendar({ref, ...props}: CalendarProps) {
     min,
     max,
     dateConstraints,
+    maxRangeSpan,
+    minRangeSpan,
     focusDate: focusDateProp,
     onFocusDateChange,
     hasOutsideDays = true,
@@ -425,6 +446,23 @@ export function Calendar({ref, ...props}: CalendarProps) {
         } 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;
 
@@ -528,6 +566,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 +607,8 @@ interface MonthGridProps {
   min?: ISODateString;
   max?: ISODateString;
   dateConstraints?: ReadonlyArray<(date: Date) => boolean>;
+  maxRangeSpan?: number;
+  minRangeSpan?: number;
   hasOutsideDays: boolean;
   hasWeekNumbers: boolean;
   hasVariableRowCount: boolean;
@@ -589,6 +631,8 @@ function MonthGrid({
   min,
   max,
   dateConstraints,
+  maxRangeSpan,
+  minRangeSpan,
   hasOutsideDays,
   hasWeekNumbers,
   hasVariableRowCount,
@@ -611,10 +655,21 @@ function MonthGrid({
     hasVariableRowCount,
   });
 
+  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

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 {

package/src/Chat/ChatComposerInput.tsx

@@ -43,7 +43,7 @@ import {
   typeScaleVars,
   typographyVars,
 } from '../theme/tokens.stylex';
-import {mergeProps} from '../utils';
+import {mergeProps, isImeKeyEvent} from '../utils';
 import {useTriggerMenu} from './useTriggerMenu';
 import {useChatComposerTokens, isCustomToken} from './useChatComposerTokens';
 import {ensureCaretInside, insertTextAtCursor} from './chatComposerSelection';
@@ -559,9 +559,8 @@ export function ChatComposerInput(props: ChatComposerInputProps) {
 
       if (e.key === 'Enter' && !e.shiftKey) {
         // Never submit mid-composition — an IME uses Enter to commit a
-        // candidate (e.g. Japanese/Chinese/Korean input), and browsers may
-        // also surface the legacy keyCode 229 for composing keystrokes.
-        if (e.nativeEvent.isComposing || e.nativeEvent.keyCode === 229) {
+        // candidate. See utils/ime.ts for the full rationale.
+        if (isImeKeyEvent(e.nativeEvent)) {
           return;
         }
 

package/src/CheckboxInput/CheckboxInput.tsx

@@ -47,6 +47,7 @@ import {useTooltip} from '../Tooltip';
 import {mergeProps, mergeRefs} from '../utils';
 import {indicatorScope} from '../Indicator/indicator.markers.stylex';
 import {useIndicatorFocusRing} from '../hooks/useIndicatorFocusRing';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
 import {useIndicator} from '../Indicator';
 import {themeProps} from '../utils/themeProps';
 import {CheckboxListContext} from '../CheckboxList/CheckboxListContext';
@@ -301,6 +302,10 @@ export function CheckboxInput({
   const id = useId();
   const descriptionID = useId();
   const statusMessageID = useId();
+  // Announce the effective required state (form default included) while the
+  // native `required` stays bound to the explicit `isRequired` so a layout
+  // default never switches on browser validation.
+  const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
 
   const [, startTransition] = useTransition();
   const [optimisticValue, setOptimisticValue] = useOptimistic(value);
@@ -421,6 +426,7 @@ export function CheckboxInput({
             form={isFocusableDisabled ? '' : undefined}
             readOnly={isReadOnly}
             required={isRequired}
+            aria-required={isEffectivelyRequired ? 'true' : undefined}
             onChange={e => {
               if (isDisabled || isBusy || isReadOnly) {
                 return;

package/src/ComplexSelector/ComplexSelector.tsx

@@ -35,6 +35,7 @@ import {useTranslator} from '../i18n';
 import {layerAnimations} from '../Layer/layerAnimations.stylex';
 import type {LayerAlignment, LayerPlacement} from '../Layer/useLayer';
 import {usePopover} from '../Popover/usePopover';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
 import {
   colorVars,
   durationVars,
@@ -46,7 +47,7 @@ import {
   typographyVars,
   typeScaleVars,
 } from '../theme/tokens.stylex';
-import {mergeProps} from '../utils';
+import {isRenderable, mergeProps} from '../utils';
 import {composeEventHandlers} from '../utils/composeEventHandlers';
 import {focusOutlineStyles} from '../utils/focusOutline.stylex';
 import type {SizeValue} from '../utils/types';
@@ -344,6 +345,7 @@ export function ComplexSelector<Value>({
   ...props
 }: ComplexSelectorProps<Value>) {
   const t = useTranslator();
+  const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
   const placeholder = placeholderFromProps ?? t('@astryx.selector.placeholder');
   const effectiveStatusVariant =
     variant === 'ghost' && statusVariant === 'attached'
@@ -439,6 +441,11 @@ export function ComplexSelector<Value>({
 
   const triggerContent = triggerLabel ?? placeholder;
 
+  const startIconSlot = renderIconSlot(startIcon, {
+    size: 'sm',
+    color: 'secondary',
+  });
+
   const content = (
     <div id={contentId} {...stylex.props(styles.content, contentXstyle)}>
       {children(optimisticValue, commitValue, close, {
@@ -467,9 +474,12 @@ export function ComplexSelector<Value>({
             inputWrapperStyles.base,
             styles.triggerContainer,
             styles[size],
-            variant === 'input' && focusOutlineStyles.focusWithin,
+            // The ring belongs to the wrapper (the focusable `<button>` sits
+            // inside it), but it must still be a KEYBOARD ring: `:focus-within`
+            // matched a mouse click on the trigger and drew the outline for
+            // pointer users too. `focusWithin` here is `:has(:focus-visible)`.
+            focusOutlineStyles.focusWithin,
             variant === 'ghost' && styles.triggerGhost,
-            variant === 'ghost' && focusOutlineStyles.focusWithin,
             isDisabled && inputWrapperStyles.disabled,
             variant === 'ghost' && isDisabled && styles.triggerGhostDisabled,
             isDisabled && styles.disabled,
@@ -479,8 +489,7 @@ export function ComplexSelector<Value>({
           className,
           style,
         )}>
-        {startIcon &&
-          renderIconSlot(startIcon, {size: 'sm', color: 'secondary'})}
+        {isRenderable(startIconSlot) && startIconSlot}
         <button
           ref={triggerRef}
           id={triggerId}
@@ -490,7 +499,7 @@ export function ComplexSelector<Value>({
           aria-controls={contentId}
           aria-describedby={ariaDescribedBy}
           aria-labelledby={labelId}
-          aria-required={isRequired ? 'true' : undefined}
+          aria-required={isEffectivelyRequired ? 'true' : undefined}
           aria-invalid={status?.type === 'error' ? 'true' : undefined}
           aria-busy={isBusy || undefined}
           disabled={isDisabled}

package/src/ContextMenu/ContextMenu.tsx

@@ -63,7 +63,7 @@ import {
   easeVars,
   shadowVars,
 } from '../theme/tokens.stylex';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps, mergeRefs, isImeKeyEvent} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import type {StyleXStyles} from '../theme/types';
 import {themeProps} from '../utils/themeProps';
@@ -334,7 +334,9 @@ export function ContextMenu({
       if (e.key !== 'Escape') {
         return;
       }
-      if (e.isComposing || e.keyCode === 229) {
+      if (isImeKeyEvent(e)) {
+        // Ignore Escape that is committing/cancelling an IME composition;
+        // see utils/ime.ts for why.
         return;
       }
       e.preventDefault();

package/src/DateInput/DateInput.test.tsx

@@ -536,6 +536,27 @@ describe('DateInput', () => {
     expect(onChange).toHaveBeenCalledWith('2026-03-15');
   });
 
+  it('does not commit on a composing Enter (IME)', () => {
+    const onChange = vi.fn();
+    render(<DateInput label="Date" onChange={onChange} />);
+
+    const input = screen.getByRole('combobox');
+    fireEvent.change(input, {target: {value: '03/15/2026'}});
+    onChange.mockClear();
+
+    // The composing keydown (isComposing / legacy keyCode 229) that commits an
+    // IME candidate fires before compositionend; it must not be read as
+    // "commit the typed date".
+    fireEvent.keyDown(input, {key: 'Enter', isComposing: true});
+    expect(onChange).not.toHaveBeenCalled();
+    fireEvent.keyDown(input, {key: 'Enter', keyCode: 229});
+    expect(onChange).not.toHaveBeenCalled();
+
+    // A real, non-composing Enter still commits.
+    fireEvent.keyDown(input, {key: 'Enter'});
+    expect(onChange).toHaveBeenCalledWith('2026-03-15');
+  });
+
   // --- Arrow-down opens calendar popover ---
 
   // Note: Tests involving popover rendering (show/hide with calendar)

package/src/DateInput/DateInput.tsx

@@ -58,9 +58,10 @@ import {
 } from '../Calendar';
 import {useCalendarConstraints} from '../Calendar/hooks';
 import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
 import {usePopover} from '../Popover';
 import {useTooltip} from '../Tooltip';
-import {getInputARIA, parseDateInput} from '../utils';
+import {getInputARIA, isImeKeyEvent, parseDateInput} from '../utils';
 import {
   plainDateFromISO,
   plainDateToISO,
@@ -399,6 +400,7 @@ export function DateInput({
   ...rest
 }: DateInputProps) {
   const t = useTranslator();
+  const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
   const placeholder =
     placeholderFromProps ?? t('@astryx.dateInput.placeholder');
   const size = useSize(sizeProp, 'md');
@@ -627,6 +629,14 @@ export function DateInput({
   // Handle keyboard events on input
   const handleInputKeyDown = useCallback(
     (e: React.KeyboardEvent) => {
+      // An in-progress IME composition uses Enter to commit the candidate and
+      // Escape to cancel it; that composing keydown fires before
+      // compositionend, so without this guard a Korean/Japanese/Chinese user
+      // committing a syllable with Enter would instead commit the pending date
+      // (or Escape would close the calendar mid-composition). See utils/ime.ts.
+      if (isImeKeyEvent(e.nativeEvent)) {
+        return;
+      }
       if (e.key === 'Escape' && popover.isOpen) {
         e.preventDefault();
         popover.hide();
@@ -729,7 +739,7 @@ export function DateInput({
         readOnly={showsDisabledMessage || undefined}
         aria-labelledby={ariaLabelledBy}
         aria-describedby={ariaDescribedBy}
-        aria-required={isRequired === true ? 'true' : undefined}
+        aria-required={isEffectivelyRequired ? 'true' : undefined}
         aria-invalid={
           status?.type === 'error' || !isInputValid ? 'true' : undefined
         }

package/src/DateRangeInput/DateRangeInput.doc.mjs

@@ -98,6 +98,18 @@ export const docs = {
       type: 'Array<(date: Date) => boolean>',
       description: 'Custom constraint functions to disable specific dates.',
     },
+    {
+      name: 'maxRangeSpan',
+      type: 'number',
+      description:
+        'Maximum days a selected range may span, counting both endpoints (`7` = a 7-day window, start + 6). Once a start is picked, days beyond this distance are disabled so the range cannot stretch past the cap. Rolling window relative to the start — for fixed calendar bounds use `min`/`max`. Constrains selection only; it never rewrites a `value` already wider than the cap (flag that with `status`).',
+    },
+    {
+      name: 'minRangeSpan',
+      type: 'number',
+      description:
+        'Minimum days a selected range must span, counting both endpoints (`2` forbids a single-day range). Once a start is picked, days closer than this are disabled. Defaults to 1 (same-day start and end allowed).',
+    },
     {
       name: 'presets',
       type: 'Array<DateRangePreset>',
@@ -313,6 +325,10 @@ export const docsDense = {
     min: 'min selectable date: ISODateString template literal type (YYYY-MM-DD); use string literal or cast `as ISODateString`',
     max: 'max selectable date: ISODateString template literal type (YYYY-MM-DD); use string literal or cast `as ISODateString`',
     dateConstraints: 'custom constraint fns to disable dates',
+    maxRangeSpan:
+      'max days a range may span, both endpoints counted (7 = a 7-day window); caps the window from the picked start. Selection-only; does not rewrite an over-wide value',
+    minRangeSpan:
+      'min days a range must span, both endpoints counted (2 forbids a single-day range); default 1',
     presets: 'preset ranges as quick-select options',
     hasClear: 'clear button when range is set (default true)',
     placeholder: 'placeholder when empty',