@astryxdesign/core 0.4.5 → 0.4.6-canary.cea9ecd

package/src/DateInput/useOwnScrollGesture.ts

@@ -0,0 +1,227 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useOwnScrollGesture.ts
+ * @input A scroll container ref and which axis it owns
+ * @output Stops touch gestures on that container from reaching an ancestor
+ * @position Internal behavior hook; consumed by Wheel.tsx and MonthScroller.tsx
+ *
+ * Lets a nested scroller keep the finger that lands on it.
+ *
+ * ## The conflict
+ *
+ * `BottomSheet` implements swipe-to-dismiss by watching touches on its
+ * scrolling body: at the body's scroll top, a downward pull stops being a
+ * scroll and becomes a sheet drag. The test is `body.scrollTop`, and the body
+ * of a sheet sized to hug its content never scrolls, so it reads as "at the
+ * top" forever — every downward-ish drag anywhere inside promotes to a drag.
+ *
+ * `touch-action` does NOT protect against this. It governs what the BROWSER
+ * will pan natively; the sheet's listener is JavaScript, and its
+ * `preventDefault()` cancels the native scroll whatever `touch-action` says.
+ * Measured: with `touch-action: pan-x` on the month scroller, a swipe just 9°
+ * off horizontal (120px across, 20px down — an ordinary thumb arc) had every
+ * `touchmove` cancelled by the sheet, so the calendar did not move at all and
+ * the sheet sprang back. The month simply would not change.
+ *
+ * ## Two ways to own a gesture
+ *
+ * - `'all'` — the wheels. They scroll vertically, exactly the axis the sheet
+ *   wants, so there is no way to share: the scroller takes every touch that
+ *   lands on it and the sheet is dismissed from the handle, the header or the
+ *   scrim instead.
+ *
+ * - `'inline'` — the month scroller. It pages sideways, so the two CAN share
+ *   by direction: lock the axis on the first significant move, claim the
+ *   gesture only when it is horizontal, and let vertical ones through so
+ *   swipe-to-dismiss still works on the calendar.
+ *
+ * ## Where the line falls, and the gestures that fall past it
+ *
+ * A thumb swiping sideways travels in an arc, not a line — a "horizontal"
+ * swipe routinely drifts 10-30° down, and sometimes further. So an `'inline'`
+ * scroller claims generously: vertical has to beat horizontal by
+ * {@link VERTICAL_DOMINANCE} before the sheet gets the gesture, which puts the
+ * split near 63° rather than at the diagonal.
+ *
+ * That is wider than the browser will pan. `touch-action: pan-x` pans only
+ * while `|dx| > |dy|` and refuses the moment a gesture tips past 45°, so the
+ * band between the two lines used to be the worst outcome available: measured
+ * on an iPhone 15 profile, a 200px swipe at 45-60° neither paged a month nor
+ * dismissed the sheet, because we had told the sheet to keep off a gesture the
+ * compositor then declined to pan. Nothing moved at all.
+ *
+ * {@link OwnScrollGestureOptions.onSwipe} closes that band, and it does not
+ * need to know where the browser's line is: if the element's scroll offset
+ * never changed across a claimed gesture, the browser declined it, and a
+ * swipe that cleared {@link SWIPE_DISTANCE} is reported so the caller can page
+ * itself. Native pans keep their momentum and snapping and report nothing.
+ *
+ * The remaining asymmetry is deliberate and in the direction the scroller
+ * needs: it is generous about distance too, paging on a 30px flick where the
+ * sheet asks for ~200px of pull before it dismisses.
+ *
+ * ## Why native listeners
+ *
+ * React delegates its events at the root container, which is an ANCESTOR of
+ * the sheet body — so a React `onTouchStart` would run after the body's own
+ * listener had already claimed the gesture. `stopPropagation` has to happen on
+ * a listener attached to the element itself, during the real bubble phase,
+ * before the event ever reaches the body.
+ *
+ * Nothing here calls `preventDefault`, so the listeners stay passive and the
+ * scroller keeps native momentum, snapping and rubber-banding.
+ *
+ * SYNC: When modified, update DateInputTouch.test.tsx.
+ */
+
+import {useEffect, useRef} from 'react';
+
+/**
+ * How much a gesture's vertical travel must exceed its horizontal travel
+ * before an `'inline'` scroller gives it up. Above 1, so horizontal wins the
+ * ambiguous middle; see the file header for why the split is deliberately
+ * unfair, and how the gestures past the browser's own 45° line are handled.
+ */
+export const VERTICAL_DOMINANCE = 2;
+
+/** Movement below this is noise, not a direction. */
+const AXIS_LOCK_SLOP = 6;
+
+/**
+ * Horizontal travel a claimed-but-unpanned gesture needs before it counts as
+ * a swipe. Roughly the shortest flick the browser itself will page on.
+ */
+export const SWIPE_DISTANCE = 32;
+
+export type OwnedAxis = 'all' | 'inline';
+
+export type OwnScrollGestureOptions = {
+  /** Skip while the scroller is hidden; a hidden panel keeps its layout box,
+   * so its listeners would otherwise still be live. */
+  isEnabled?: boolean;
+  /**
+   * Called when a claimed gesture ended without the browser having scrolled
+   * the element at all — the diagonal swipes `touch-action: pan-x` refuses.
+   *
+   * `direction` is the sign to move the scroll offset by, so it composes
+   * directly: `scrollBy({left: direction * pageWidth})`. It is physical, and
+   * therefore correct in both directions of writing.
+   *
+   * Only fires for `'inline'`. A gesture the browser panned reports nothing,
+   * so momentum and snapping are never second-guessed.
+   */
+  onSwipe?: (direction: 1 | -1) => void;
+};
+
+/**
+ * Claim touch gestures that start on `ref`'s element, so an ancestor cannot
+ * reinterpret them as its own drag.
+ *
+ * @param ref - the scroll container
+ * @param axis - `'all'` to take every touch, `'inline'` to take only the
+ *   horizontal ones and leave vertical drags to the sheet
+ * @param options - see {@link OwnScrollGestureOptions}
+ */
+export function useOwnScrollGesture(
+  ref: React.RefObject<HTMLElement | null>,
+  axis: OwnedAxis = 'all',
+  options: OwnScrollGestureOptions = {},
+): void {
+  const {isEnabled = true, onSwipe} = options;
+
+  // Read through a ref so a caller need not memoize the callback: re-running
+  // this effect would tear the listeners off mid-gesture.
+  const onSwipeRef = useRef(onSwipe);
+  onSwipeRef.current = onSwipe;
+
+  useEffect(() => {
+    const element = ref.current;
+    if (element == null || !isEnabled) {
+      return;
+    }
+
+    // null = not yet decided; true = ours for the rest of this gesture.
+    let claimed: boolean | null = null;
+    let originX = 0;
+    let originY = 0;
+    let lastX = 0;
+    let offsetAtStart = 0;
+    // Whether the browser actually panned the element during this gesture.
+    // Sampled per move rather than compared once at the end, because a short
+    // pan that snaps back finishes at the offset it started from.
+    let didPan = false;
+
+    const onStart = (event: TouchEvent) => {
+      const touch = event.touches[0];
+      originX = touch?.clientX ?? 0;
+      originY = touch?.clientY ?? 0;
+      lastX = originX;
+      offsetAtStart = element.scrollLeft;
+      didPan = false;
+      // 'all' decides at touchstart, before the sheet's own touchstart
+      // listener records an armed edge. 'inline' cannot decide yet — a touch
+      // has no direction until it moves — so it lets touchstart through and
+      // locks on the first move that clears the slop.
+      claimed = axis === 'all' ? true : null;
+      if (claimed) {
+        event.stopPropagation();
+      }
+    };
+
+    const onMove = (event: TouchEvent) => {
+      if (claimed === false) {
+        return;
+      }
+      const touch = event.touches[0];
+      if (touch == null) {
+        return;
+      }
+      if (claimed == null) {
+        const dx = Math.abs(touch.clientX - originX);
+        const dy = Math.abs(touch.clientY - originY);
+        if (Math.max(dx, dy) < AXIS_LOCK_SLOP) {
+          return;
+        }
+        claimed = dy <= dx * VERTICAL_DOMINANCE;
+        if (!claimed) {
+          return;
+        }
+      }
+      lastX = touch.clientX;
+      didPan ||= Math.abs(element.scrollLeft - offsetAtStart) >= 1;
+      event.stopPropagation();
+    };
+
+    const onEnd = () => {
+      // A gesture we claimed that the browser then refused to pan: the sheet
+      // was told to keep off it, so unless it is acted on here it does
+      // nothing at all. See the file header.
+      if (
+        claimed === true &&
+        axis === 'inline' &&
+        !didPan &&
+        Math.abs(lastX - originX) >= SWIPE_DISTANCE
+      ) {
+        onSwipeRef.current?.(lastX < originX ? 1 : -1);
+      }
+      // touchend/touchcancel deliberately propagate: they carry no
+      // interpretation, and letting them through is what resets the sheet's
+      // bookkeeping.
+      claimed = null;
+    };
+
+    element.addEventListener('touchstart', onStart, {passive: true});
+    element.addEventListener('touchmove', onMove, {passive: true});
+    element.addEventListener('touchend', onEnd, {passive: true});
+    element.addEventListener('touchcancel', onEnd, {passive: true});
+    return () => {
+      element.removeEventListener('touchstart', onStart);
+      element.removeEventListener('touchmove', onMove);
+      element.removeEventListener('touchend', onEnd);
+      element.removeEventListener('touchcancel', onEnd);
+    };
+  }, [ref, axis, isEnabled]);
+}

package/src/DateInput/usePointerDragScroll.ts

@@ -0,0 +1,220 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file usePointerDragScroll.ts
+ * @input A scroll container ref
+ * @output Lets a mouse drag the container's contents the way a finger does
+ * @position Internal behavior hook; consumed by Wheel.tsx
+ *
+ * ## Why this exists
+ *
+ * A wheel is a scroll container, which is what makes it feel right under a
+ * finger: the platform supplies panning, momentum, rubber-banding and the
+ * snap. A mouse gets none of that. Browsers do not drag-scroll an overflow
+ * container — press and pull on one and nothing happens at all, which is
+ * exactly what a wheel invites you to try.
+ *
+ * That leaves the mouse with the scroll wheel and a click on a visible row.
+ * Both work, and neither is the gesture the control is shaped like. It
+ * matters more than "mouse users are not the target": the touch surface is
+ * reviewed, themed and screenshotted on desktop browsers, where a wheel that
+ * ignores the pointer reads as broken rather than as touch-only.
+ *
+ * ## Mouse only, deliberately
+ *
+ * Touch and pen already pan natively, and this hook would be strictly worse
+ * than what they get — no momentum, no rubber-banding, no compositor
+ * threading. So it ignores every pointer type but `mouse` and leaves those
+ * gestures untouched.
+ *
+ * ## Snap has to be suspended for the duration
+ *
+ * `scroll-snap-type: y mandatory` re-snaps after every scroll, including a
+ * programmatic one, so a drag that assigns `scrollTop` is fighting it on
+ * every frame. Measured: dragging 5px at a time with mandatory snap on, 7 of
+ * 8 steps were yanked back to a snap position — the wheel sticks to a row and
+ * then jumps a whole one. The drag therefore suspends snapping, and restores
+ * it once the release has settled somewhere legal.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/DateInput/Wheel.tsx
+ * - /packages/core/src/DateInput/DateInputTouch.test.tsx
+ */
+
+import {useEffect, useRef} from 'react';
+
+/**
+ * Movement below this stays a click. A mouse shifts a pixel or two under the
+ * press of the button itself, and a wheel row is a click target.
+ */
+export const DRAG_SLOP = 4;
+
+/** How long to wait for a release's settle before restoring snapping. */
+const SETTLE_FALLBACK_MS = 260;
+
+/**
+ * Let a mouse drag `ref`'s contents, on a container that already scrolls and
+ * snaps for touch.
+ *
+ * @param ref - the scroll container
+ * @param isEnabled - skip while the wheel is hidden; a hidden panel keeps its
+ *   layout box, so its listeners would otherwise still be live
+ */
+export function usePointerDragScroll(
+  ref: React.RefObject<HTMLElement | null>,
+  isEnabled: boolean = true,
+): void {
+  useEffect(() => {
+    const element = ref.current;
+    if (element == null || !isEnabled) {
+      return;
+    }
+
+    let pointerId: number | null = null;
+    let originY = 0;
+    let originScrollTop = 0;
+    let isDragging = false;
+    // Survives from the drag's end to the click it produces, which is the
+    // whole reason it is not just `isDragging`.
+    let wasDragged = false;
+    let restoreTimer: number | undefined;
+
+    const restoreSnap = () => {
+      window.clearTimeout(restoreTimer);
+      element.removeEventListener('scrollend', restoreSnap);
+      // Back to the stylesheet's value rather than a hardcoded one, so this
+      // cannot drift from Wheel's own `scrollSnapType`.
+      element.style.removeProperty('scroll-snap-type');
+    };
+
+    const suspendSnap = () => {
+      window.clearTimeout(restoreTimer);
+      element.removeEventListener('scrollend', restoreSnap);
+      element.style.scrollSnapType = 'none';
+    };
+
+    const onPointerDown = (event: PointerEvent) => {
+      // Touch and pen pan natively, and better. Secondary buttons are for the
+      // context menu.
+      if (event.pointerType !== 'mouse' || event.button !== 0) {
+        return;
+      }
+      // Keep the press away from BottomSheet, which starts its own
+      // drag-to-dismiss from a `pointerdown` on its body and CAPTURES the
+      // pointer for it. Two things go wrong if it gets there first: the drag
+      // below is fighting the sheet for the same gesture, and — measured on
+      // the calendar too, so this is not new — every later pointer event
+      // retargets to the sheet body, which means a click that wobbles more
+      // than a pixel or two never reaches the row under it and selects
+      // nothing at all.
+      //
+      // A native listener during the real bubble phase is what it takes:
+      // the sheet's handler is a React prop, delegated at the root container,
+      // which is an ANCESTOR of this element. Same reasoning as
+      // useOwnScrollGesture, and the same trade — mouse drag-to-dismiss now
+      // starts from the grab handle, the header or the scrim rather than
+      // from inside a wheel, which is where a picker sheet puts it anyway.
+      event.stopPropagation();
+      pointerId = event.pointerId;
+      originY = event.clientY;
+      originScrollTop = element.scrollTop;
+      isDragging = false;
+      // Not captured yet: a press that never moves has to stay a click on the
+      // row under it, and capturing here would retarget that click.
+    };
+
+    const onPointerMove = (event: PointerEvent) => {
+      if (pointerId !== event.pointerId) {
+        return;
+      }
+      const delta = event.clientY - originY;
+      if (!isDragging) {
+        if (Math.abs(delta) < DRAG_SLOP) {
+          return;
+        }
+        isDragging = true;
+        element.setPointerCapture(event.pointerId);
+        suspendSnap();
+        // Dragging across rows would otherwise select their text, leaving the
+        // wheel looking highlighted after the gesture.
+        element.style.userSelect = 'none';
+      }
+      // Content follows the hand: pull up and the list moves up, which means
+      // scrolling further down it.
+      element.scrollTop = originScrollTop - delta;
+    };
+
+    const onPointerEnd = (event: PointerEvent) => {
+      if (pointerId !== event.pointerId) {
+        return;
+      }
+      pointerId = null;
+      if (!isDragging) {
+        return;
+      }
+      isDragging = false;
+      wasDragged = true;
+      element.style.removeProperty('user-select');
+      if (element.hasPointerCapture(event.pointerId)) {
+        element.releasePointerCapture(event.pointerId);
+      }
+
+      // The release lands mid-row. Glide to the nearest one and only then let
+      // snapping back on — restoring it here instead would jump the distance
+      // rather than travel it, and a jump is what this hook exists to avoid.
+      const rowHeight = firstRowHeight(element);
+      if (rowHeight > 0) {
+        const nearest = Math.round(element.scrollTop / rowHeight) * rowHeight;
+        element.scrollTo({top: nearest, behavior: 'smooth'});
+      }
+      // `scrollend` is the honest signal; the timer covers browsers that do
+      // not fire it, and the case where the glide had nowhere to go.
+      // Not `{once: true}`: a listener that never fires is never removed by
+      // it, so a component unmounted mid-glide would leave one attached.
+      // `restoreSnap` removes it itself, whichever of the two gets there
+      // first, and the cleanup below calls `restoreSnap` on unmount.
+      //
+      // eslint-disable-next-line @eslint-react/web-api-no-leaked-event-listener -- removed by restoreSnap, which the cleanup calls
+      element.addEventListener('scrollend', restoreSnap);
+      restoreTimer = window.setTimeout(restoreSnap, SETTLE_FALLBACK_MS);
+    };
+
+    // A drag ends over whichever row the mouse happens to be on, and that row
+    // would take the click as a selection. Swallow it — but only the one, and
+    // only after a real drag, so an ordinary click still selects.
+    const onClickCapture = (event: MouseEvent) => {
+      if (!wasDragged) {
+        return;
+      }
+      wasDragged = false;
+      event.stopPropagation();
+      event.preventDefault();
+    };
+
+    element.addEventListener('pointerdown', onPointerDown);
+    element.addEventListener('pointermove', onPointerMove);
+    element.addEventListener('pointerup', onPointerEnd);
+    element.addEventListener('pointercancel', onPointerEnd);
+    element.addEventListener('click', onClickCapture, {capture: true});
+    return () => {
+      element.removeEventListener('pointerdown', onPointerDown);
+      element.removeEventListener('pointermove', onPointerMove);
+      element.removeEventListener('pointerup', onPointerEnd);
+      element.removeEventListener('pointercancel', onPointerEnd);
+      element.removeEventListener('click', onClickCapture, {capture: true});
+      restoreSnap();
+    };
+  }, [ref, isEnabled]);
+}
+
+/**
+ * The pitch of the rows, read off the first one. Taken from layout rather
+ * than the token so a themed `--date-input-touch-wheel-item-size` is honoured
+ * without this hook having to know the variable exists.
+ */
+function firstRowHeight(element: HTMLElement): number {
+  const row = element.querySelector('[role="option"]');
+  return row instanceof HTMLElement ? row.offsetHeight : 0;
+}

package/src/DateInput/useScrollSettle.ts

@@ -0,0 +1,164 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useScrollSettle.ts
+ * @input A scroll container ref and a settle callback
+ * @output Calls back once, after scrolling (including momentum) stops
+ * @position Internal behavior hook; consumed by Wheel.tsx and MonthScroller.tsx
+ *
+ * A snap scroller commits its value when it comes to rest, so it needs a
+ * "scrolling stopped" signal. `scrollend` is that signal, but it is recent
+ * enough that mobile Safari below 26 does not have it — and it is exactly the
+ * browser this component targets. So: listen for `scrollend` where it exists,
+ * and fall back to a quiet-period timer everywhere else. The same
+ * belt-and-braces pattern is in core's `useScrollSpy`.
+ *
+ * ## The two things the timer must not mistake for rest
+ *
+ * A quiet period is a guess, and on iOS it guesses wrong twice unless it is
+ * told otherwise. Both mistakes were behind the same bug: opening the
+ * month/year wheels, flicking to an earlier month, and watching the month
+ * climb on its own afterwards — on real iOS and the simulator, never in
+ * Chrome.
+ *
+ * 1. **A finger resting mid-drag is not rest.** Hold a wheel still for a
+ *    moment without lifting and the scroll events stop, so the timer fires
+ *    and the value commits to whatever is under the band. Chrome hides this
+ *    because it has `scrollend`, which does not fire until the touch is
+ *    released.
+ *
+ * 2. **Momentum is not rest either.** iOS momentum runs on the UI thread and
+ *    keeps going for a second or more after the finger is gone, and its scroll
+ *    events arrive irregularly — the gaps in the slow tail routinely exceed
+ *    any sane quiet period. Chrome's compositor-driven momentum fires evenly,
+ *    so the same timer never trips there.
+ *
+ * A premature settle is not just a wrong value; it feeds back. The commit
+ * moves the value, the value moves the scroller back onto the committed row,
+ * that programmatic scroll does not stop the momentum still running
+ * underneath, and the fresh scroll events start the next premature settle —
+ * each one landing a row further along, which is why the month climbed.
+ *
+ * So: the settle waits for the touch to end, and then for a quiet period
+ * measured from the LAST scroll event, which is what makes it outlast
+ * momentum however long it runs. {@link useScrollSettle} also reports whether
+ * the scroller is at rest, so a caller can refuse to reposition one that is
+ * still moving.
+ *
+ * SYNC: When modified, update DateInputTouch.test.tsx.
+ */
+
+import {useEffect, useRef} from 'react';
+
+/**
+ * How long the scroller must be quiet before a settle is assumed. Long enough
+ * to outlast the browser's own snap animation (~150-300ms after the finger
+ * lifts), or a wheel would commit to whichever option it was passing rather
+ * than the one it settles on.
+ */
+export const SCROLL_QUIET_MS = 220;
+
+/** What {@link useScrollSettle} reports back about the scroller's state. */
+export type ScrollSettleState = {
+  /**
+   * False from the first touch until the scroller has genuinely stopped —
+   * momentum included. Read it before repositioning the scroller: doing that
+   * mid-flight fights the platform and, on iOS, restarts the cycle described
+   * in the file header.
+   */
+  isAtRestRef: React.RefObject<boolean>;
+};
+
+/**
+ * Run `onSettle` when `ref`'s element stops scrolling.
+ *
+ * @param ref - the scroll container
+ * @param onSettle - called with the settled element; may change every render
+ * @param isEnabled - skip attaching while false (e.g. a hidden panel)
+ */
+export function useScrollSettle(
+  ref: React.RefObject<HTMLElement | null>,
+  onSettle: (element: HTMLElement) => void,
+  isEnabled: boolean = true,
+): ScrollSettleState {
+  // The callback closes over render-fresh values (the option list, the current
+  // value); keeping it in a ref means the listeners attach once instead of
+  // re-attaching mid-scroll, which would drop an in-flight settle.
+  const onSettleRef = useRef(onSettle);
+  onSettleRef.current = onSettle;
+
+  const isAtRestRef = useRef(true);
+
+  useEffect(() => {
+    const element = ref.current;
+    if (element == null || !isEnabled) {
+      isAtRestRef.current = true;
+      return;
+    }
+
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let hasSettled = false;
+    let isTouching = false;
+
+    const settle = () => {
+      // A finger still on the glass is not rest, however quiet the scroller
+      // has gone. The release re-arms this.
+      if (hasSettled || isTouching) {
+        return;
+      }
+      hasSettled = true;
+      isAtRestRef.current = true;
+      clearTimeout(timer);
+      onSettleRef.current(element);
+    };
+
+    const arm = () => {
+      clearTimeout(timer);
+      timer = setTimeout(settle, SCROLL_QUIET_MS);
+    };
+
+    const onScroll = () => {
+      // A fresh scroll re-opens the window: whatever we settle on now is
+      // stale, and the settle that matters is the one after this gesture.
+      // Momentum keeps arriving here, so the quiet period is measured from
+      // the last of it however long it runs.
+      hasSettled = false;
+      isAtRestRef.current = false;
+      arm();
+    };
+
+    const onTouchStart = () => {
+      isTouching = true;
+      hasSettled = false;
+      isAtRestRef.current = false;
+      clearTimeout(timer);
+    };
+
+    const onTouchEnd = () => {
+      isTouching = false;
+      // Momentum may carry on from here and will re-arm this on its own; the
+      // timer covers the case where the finger lifted without a fling, which
+      // produces no further scroll events at all.
+      arm();
+    };
+
+    element.addEventListener('scroll', onScroll, {passive: true});
+    element.addEventListener('scrollend', settle);
+    element.addEventListener('touchstart', onTouchStart, {passive: true});
+    element.addEventListener('touchend', onTouchEnd, {passive: true});
+    element.addEventListener('touchcancel', onTouchEnd, {passive: true});
+
+    return () => {
+      clearTimeout(timer);
+      element.removeEventListener('scroll', onScroll);
+      element.removeEventListener('scrollend', settle);
+      element.removeEventListener('touchstart', onTouchStart);
+      element.removeEventListener('touchend', onTouchEnd);
+      element.removeEventListener('touchcancel', onTouchEnd);
+    };
+  }, [ref, isEnabled]);
+
+  return {isAtRestRef};
+}

package/src/DateRangeInput/DateRangeInput.doc.mjs

@@ -102,7 +102,7 @@ export const docs = {
       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`).',
+        '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',