@viasat/beam-react 2.47.0 → 2.48.0

package/lib/wip/DateField/DateField.es.js

@@ -1,206 +1,227 @@
-import { jsxs as S, jsx as l } from "react/jsx-runtime";
-import De from "clsx";
-import { forwardRef as Fe } from "react";
-import { s as a, b as he, c as s, a as xe } from "../../../chunks/DateField.Segment.C2qoaY0Z.js";
-import { t as ye } from "../../../chunks/constants.Cruz2A1w.js";
-import { H as Se } from "../../../chunks/form.context.cEuTL68U.js";
-import { LabelProvider as Ie } from "../../Form/contexts/label.context.es.js";
-import { HelperTextProvider as we } from "../../Form/contexts/helperText.context.es.js";
-import { useUniversalRef as Re } from "../../Form/hooks/useUniversalRef.hook.es.js";
-import { DateFieldSegments as Ne, PARTS_ORDER as I } from "./DateField.Segments.es.js";
-import { toISODateString as Ve } from "./DateField.utils.es.js";
-import { useDateFieldFocus as Be } from "./useDateFieldFocus.es.js";
-import { useDateFieldForm as Ce } from "./useDateFieldForm.es.js";
-import { useDateFieldKeyboard as Oe } from "./useDateFieldKeyboard.es.js";
-import { useDateFieldSegments as Pe } from "./useDateFieldSegments.es.js";
-import { useDateFieldValidity as Te } from "./useDateFieldValidity.es.js";
-import { useDateFieldValue as Me } from "./useDateFieldValue.es.js";
-import { useInvalidState as qe } from "./useInvalidState.es.js";
-const aa = Fe(
+import { jsxs as N, jsx as r } from "react/jsx-runtime";
+import xe from "clsx";
+import { forwardRef as Ie, useEffect as Ne } from "react";
+import { s as a, b as we, c as s, a as w } from "../../../chunks/DateField.Segment.BVe6TzWY.js";
+import { t as Re } from "../../../chunks/constants.Cruz2A1w.js";
+import { H as Ve } from "../../../chunks/form.context.cEuTL68U.js";
+import { LabelProvider as Me } from "../../Form/contexts/label.context.es.js";
+import { HelperTextProvider as Oe } from "../../Form/contexts/helperText.context.es.js";
+import { useUniversalRef as Be } from "../../Form/hooks/useUniversalRef.hook.es.js";
+import { DateFieldSegments as Ce, PARTS_ORDER as R } from "./DateField.Segments.es.js";
+import { isMinMaxMisconfigured as Ee, dateKeyOrNull as V, toISODateString as Pe } from "./DateField.utils.es.js";
+import { useDateFieldFocus as Te } from "./useDateFieldFocus.es.js";
+import { useDateFieldForm as qe } from "./useDateFieldForm.es.js";
+import { useDateFieldKeyboard as He } from "./useDateFieldKeyboard.es.js";
+import { useDateFieldSegments as Ke } from "./useDateFieldSegments.es.js";
+import { useDateFieldValidity as Le } from "./useDateFieldValidity.es.js";
+import { useDateFieldValue as $e } from "./useDateFieldValue.es.js";
+import { useInvalidState as je } from "./useInvalidState.es.js";
+const da = Ie(
   function({
-    value: w,
-    defaultValue: R,
-    onChange: N,
-    label: t = null,
-    helperText: o = null,
-    error: n,
-    hideRequiredMarker: V = !1,
-    validationRules: B,
-    width: C,
-    theme: m,
-    fluid: O = !1,
-    disabled: P = !1,
-    readOnly: T = !1,
-    required: M = !1,
-    name: u,
-    id: q,
-    className: L,
-    style: E,
-    "aria-label": H,
-    "aria-describedby": $,
-    "aria-labelledby": j,
-    ...K
-  }, W) {
+    value: M,
+    defaultValue: O,
+    onChange: B,
+    minDate: t,
+    maxDate: d,
+    getClampAnnouncement: C,
+    label: n = null,
+    helperText: u = null,
+    error: m,
+    hideRequiredMarker: E = !1,
+    validationRules: P,
+    width: T,
+    theme: c,
+    fluid: q = !1,
+    disabled: H = !1,
+    readOnly: K = !1,
+    required: L = !1,
+    name: f,
+    id: $,
+    className: j,
+    style: A,
+    "aria-label": W,
+    "aria-describedby": _,
+    "aria-labelledby": U,
+    ...k
+  }, z) {
     const {
       disabled: e,
-      readOnly: d,
-      required: f,
-      invalid: A,
-      errorMessageProvided: c,
-      defaultValue: U,
-      errorId: p,
-      helperTextId: _,
-      validationErrorsId: k,
-      labelId: b,
-      ariaDescribedBy: z,
-      ariaLabelledBy: G,
-      showErrors: J
-    } = Ce({
-      name: u,
-      disabled: P,
-      readOnly: T,
-      required: M,
-      defaultValue: R,
-      error: n,
-      hasHelperText: !!o,
-      hasLabel: !!t,
-      validationRules: B,
-      ariaDescribedBy: $,
-      ariaLabelledBy: j
-    }), { refFn: Q, ref: g } = Re(W), { segmentRefs: X, registerSegmentRef: Y } = Pe(), {
-      segmentText: Z,
-      segmentValues: v,
-      currentValue: D,
-      wasTouched: ee,
-      appendDigit: ae,
-      adjustSegment: re,
-      deleteLastDigit: le,
-      clearSegment: ie,
-      beginSegmentEdit: se,
-      commitOnBlur: de
-    } = Me({
-      value: w,
-      defaultValue: U,
-      onChange: N
+      readOnly: o,
+      required: p,
+      invalid: G,
+      errorMessageProvided: b,
+      defaultValue: J,
+      errorId: g,
+      helperTextId: Q,
+      validationErrorsId: X,
+      labelId: v,
+      ariaDescribedBy: Y,
+      ariaLabelledBy: Z,
+      showErrors: ee
+    } = qe({
+      name: f,
+      disabled: H,
+      readOnly: K,
+      required: L,
+      defaultValue: O,
+      error: m,
+      hasHelperText: !!u,
+      hasLabel: !!n,
+      validationRules: P,
+      ariaDescribedBy: _,
+      ariaLabelledBy: U
+    });
+    Ne(() => {
+      process.env.NODE_ENV !== "production" && Ee(t, d) && console.warn(
+        "DateField: `minDate` is after `maxDate` — no date satisfies both, so the blur clamp is disabled and values are left as typed."
+      );
+    }, [V(t), V(d)]);
+    const { refFn: ae, ref: F } = Be(z), { segmentRefs: re, registerSegmentRef: ie } = Ke(), {
+      segmentText: le,
+      segmentValues: D,
+      currentValue: h,
+      wasTouched: se,
+      appendDigit: te,
+      adjustSegment: de,
+      clearSegment: oe,
+      beginSegmentEdit: ne,
+      commitOnBlur: ue,
+      clampAnnouncement: me
+    } = $e({
+      value: M,
+      defaultValue: J,
+      onChange: B,
+      minDate: t,
+      maxDate: d,
+      getClampAnnouncement: C
     }), {
-      focusedSegment: F,
-      fieldTabIndex: te,
-      handleSegmentFocus: h,
-      handleFieldFocus: oe,
-      handleFieldBlur: ne,
-      handleFieldMouseDown: me,
+      focusedSegment: y,
+      fieldTabIndex: ce,
+      handleSegmentFocus: S,
+      handleFieldFocus: fe,
+      handleFieldBlur: pe,
+      handleFieldMouseDown: be,
       focusNext: x,
-      focusPrevious: ue
-    } = Be({
+      focusPrevious: ge
+    } = Te({
       disabled: e,
-      fieldRef: g,
-      segmentRefs: X,
-      partsOrder: I,
-      onSegmentFocusChange: se,
-      onFieldBlur: de
-    }), fe = Oe({
+      fieldRef: F,
+      segmentRefs: re,
+      partsOrder: R,
+      onSegmentFocusChange: ne,
+      onFieldBlur: ue
+    }), ve = He({
       disabled: e,
-      readOnly: d,
-      fieldRef: g,
+      readOnly: o,
+      fieldRef: F,
       focusNext: x,
-      focusPrevious: ue,
-      adjustSegment: re,
-      deleteLastDigit: le,
-      clearSegment: ie
-    }), { isInvalid: ce } = Te({
-      segments: v,
-      currentValue: D,
-      wasTouched: ee,
-      isFocused: F !== null
-    }), pe = (r, i) => {
-      const { advanced: ve } = ae(r, i);
-      ve && x(r);
-    }, y = qe({
-      formInvalid: A,
-      valueInvalid: ce
-    }), be = (r) => {
+      focusPrevious: ge,
+      adjustSegment: de,
+      clearSegment: oe
+    }), { isInvalid: Fe } = Le({
+      segments: D,
+      currentValue: h,
+      wasTouched: se,
+      isFocused: y !== null
+    }), De = (i, l) => {
+      const { advanced: Se } = te(i, l);
+      Se && x(i);
+    }, I = je({
+      formInvalid: G,
+      valueInvalid: Fe
+    }), he = (i) => {
       if (e) return;
-      const i = r.target.closest("label");
-      !i || i.id !== b || (r.preventDefault(), h(I[0]));
-    }, ge = De(
-      a[he],
-      m && ye(m),
-      O && a[`${s}fluid`],
-      y && a[`${s}error`],
+      const l = i.target.closest("label");
+      !l || l.id !== v || (i.preventDefault(), S(R[0]));
+    }, ye = xe(
+      a[we],
+      c && Re(c),
+      q && a[`${s}fluid`],
+      I && a[`${s}error`],
       e && a[`${s}disabled`],
-      d && a[`${s}read-only`],
-      L
+      o && a[`${s}read-only`],
+      j
     );
-    return /* @__PURE__ */ S(
+    return /* @__PURE__ */ N(
       "div",
       {
-        className: ge,
-        style: { ...E, maxWidth: C },
-        onMouseDownCapture: be,
+        className: ye,
+        style: { ...A, maxWidth: T },
+        onMouseDownCapture: he,
         children: [
-          /* @__PURE__ */ l(
-            Ie,
+          /* @__PURE__ */ r(
+            Me,
             {
-              ctxId: b,
+              ctxId: v,
               ctxDisabled: e,
-              ctxRequired: f && !V,
-              children: t
+              ctxRequired: p && !E,
+              children: n
             }
           ),
-          /* @__PURE__ */ l(
+          /* @__PURE__ */ r(
             "div",
             {
-              ...K,
-              ref: Q,
-              id: q,
+              ...k,
+              ref: ae,
+              id: $,
               role: "group",
-              "aria-label": H,
-              "aria-labelledby": G,
+              "aria-label": W,
+              "aria-labelledby": Z,
               "aria-disabled": e || void 0,
-              "aria-required": f || void 0,
-              "aria-invalid": y || void 0,
-              "aria-describedby": z,
-              "aria-errormessage": c ? p : void 0,
-              tabIndex: te,
-              className: a[xe.field],
-              onMouseDown: me,
-              onFocus: oe,
-              children: /* @__PURE__ */ l(
-                Ne,
+              "aria-required": p || void 0,
+              "aria-invalid": I || void 0,
+              "aria-describedby": Y,
+              "aria-errormessage": b ? g : void 0,
+              tabIndex: ce,
+              className: a[w.field],
+              onMouseDown: be,
+              onFocus: fe,
+              children: /* @__PURE__ */ r(
+                Ce,
                 {
-                  segmentText: Z,
-                  segmentValues: v,
-                  focusedSegment: F,
+                  segmentText: le,
+                  segmentValues: D,
+                  focusedSegment: y,
                   disabled: e,
-                  readOnly: d,
-                  onSegmentFocus: h,
-                  onSegmentBlur: ne,
-                  onSegmentInput: pe,
-                  onSegmentKeyDown: fe,
-                  registerSegmentRef: Y
+                  readOnly: o,
+                  onSegmentFocus: S,
+                  onSegmentBlur: pe,
+                  onSegmentInput: De,
+                  onSegmentKeyDown: ve,
+                  registerSegmentRef: ie
                 }
               )
             }
           ),
-          /* @__PURE__ */ l(
+          /* @__PURE__ */ r(
+            "span",
+            {
+              role: "status",
+              "aria-live": "polite",
+              "aria-atomic": "true",
+              className: a[w.srStatus],
+              children: me
+            }
+          ),
+          /* @__PURE__ */ r(
             "input",
             {
               type: "hidden",
-              name: u,
-              value: Ve(D),
+              name: f,
+              value: Pe(h),
               disabled: e
             }
           ),
-          /* @__PURE__ */ S(we, { ctxId: _, ctxDisabled: e, children: [
-            o,
-            c && /* @__PURE__ */ l(Se, { id: p, appearance: "negative", children: n })
+          /* @__PURE__ */ N(Oe, { ctxId: Q, ctxDisabled: e, children: [
+            u,
+            b && /* @__PURE__ */ r(Ve, { id: g, appearance: "negative", children: m })
           ] }),
-          J(k)
+          ee(X)
         ]
       }
     );
   }
 );
 export {
-  aa as DateField
+  da as DateField
 };

package/lib/wip/DateField/DateField.types.d.ts

@@ -89,9 +89,21 @@ export interface DateFieldProps extends DateFieldInputAttributes {
     defaultValue?: Nullable<Date>;
     /**
      * Fires when the derived `Date | null` value transitions.
-     * In DF-1, user-input handlers don't exist yet — wired up in DF-2.
      */
     onChange?: (value: Nullable<Date>) => void;
+    /**
+     * Lower bound; on blur, a touched value springs up to it. Use `validationRules` for validation.
+     */
+    minDate?: Date;
+    /**
+     * Upper bound; on blur, a touched value springs down to it. Use `validationRules` for validation.
+     */
+    maxDate?: Date;
+    /**
+     * Called when a touched value springs to a bound on blur; return a localized
+     * message announced politely to screen readers. Omit → no announcement.
+     */
+    getClampAnnouncement?: (clampedDate: Date) => string;
 }
 /**
  * Internal props for the segment subcomponent. Not part of the public API.
@@ -103,8 +115,15 @@ export interface DateFieldSegmentProps {
     /** Numeric segment value — used for `aria-valuenow`. `null` when the segment has no committed value. */
     value: Nullable<number>;
     /**
-     * The upper bound announced as `aria-valuemax`.
-     * For day: month-aware (e.g. 28 for Feb non-leap); for month: 12; for year: 9999.
+     * The lower bound announced as `aria-valuemin` — an intrinsic calendar
+     * range, NOT the `minDate` prop (day/month: always 1; year: always 1).
+     * Computed by `DateField.Segments` so the segment itself stays a pure renderer.
+     */
+    valueMin: number;
+    /**
+     * The upper bound announced as `aria-valuemax` — an intrinsic calendar
+     * range, NOT the `maxDate` prop (day: month-aware, e.g. 28 for Feb
+     * non-leap; month: 12; year: always 9999).
      * Computed by `DateField.Segments` so the segment itself stays a pure renderer.
      */
     valueMax: number;

package/lib/wip/DateField/DateField.utils.cjs.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const i=require("./DateField.validation.cjs.js"),s=31,o=12,m={day:s,month:o,year:9999},u=(e,t,n)=>Math.min(n,Math.max(t,e)),g=(e,t)=>((e-1)%t+t)%t+1,S=2024,y=(e,t)=>t==null?31:new Date(e??S,t,0).getDate(),M=()=>{const e=new Date;return{day:e.getDate(),month:e.getMonth()+1,year:e.getFullYear()}},N=(e,t,n,r)=>{if(n==="min")return e==="year"?null:1;if(n==="max")return e==="year"?null:e==="day"?r.daysInMonth:o;if(t==null)return r.today[e];if(e==="year")return u(t+n,1,9999);const a=e==="day"?s:o;return g(t+n,a)},T={day:"",month:"",year:""},c=e=>e instanceof Date&&!Number.isNaN(e.getTime()),d=e=>{const{day:t,month:n,year:r}=e;if(t==null||n==null||r==null)return null;const a=new Date(r,n-1,t);return a.setFullYear(r),Number.isNaN(a.getTime())||a.getFullYear()!==r||a.getMonth()!==n-1||a.getDate()!==t?null:a},f=(e,t)=>e==null&&t==null?!0:e==null||t==null?!1:e.getTime()===t.getTime(),_=e=>{if(!c(e))return"";const t=String(e.getFullYear()).padStart(4,"0"),n=String(e.getMonth()+1).padStart(2,"0"),r=String(e.getDate()).padStart(2,"0");return`${t}-${n}-${r}`},h=e=>e.filter(t=>t.type!=="literal").map(t=>t.type),D=e=>c(e)?{day:String(e.getDate()).padStart(2,"0"),month:String(e.getMonth()+1).padStart(2,"0"),year:String(e.getFullYear()).padStart(4,"0")}:T,l=(e,t)=>{if(t===""||e==="year"&&t.length<i.SEGMENT_MAX_LENGTH.year)return null;const n=parseInt(t,10);return Number.isNaN(n)||n===0?null:n},A=e=>d({day:l("day",e.day),month:l("month",e.month),year:l("year",e.year)}),E=(e,t)=>t===""?"":t.padStart(i.SEGMENT_MAX_LENGTH[e],"0"),p=(e,t,n)=>t===""?{displayValue:n,isPlaceholder:!0}:{displayValue:t.padStart(i.SEGMENT_MAX_LENGTH[e],"0"),isPlaceholder:!1},V=e=>{const t=window.getSelection();if(!t)return;const n=document.createRange();n.selectNodeContents(e),t.removeAllRanges(),t.addRange(n)},F=e=>{var n;if(!e)return;const t=(n=window.getSelection)==null?void 0:n.call(window);t&&t.rangeCount>0&&e.contains(t.anchorNode)&&t.removeAllRanges()};exports.DAY_SPIN_MAX=s;exports.MONTH_MAX=o;exports.SEGMENT_ARIA_MAX=m;exports.adjustSegmentValue=N;exports.clamp=u;exports.clearSelectionWithin=F;exports.deriveValue=d;exports.deriveValueFromText=A;exports.getDaysInMonth=y;exports.getSegmentDisplay=p;exports.getSegmentOrder=h;exports.isSameDateValue=f;exports.normalizeSegmentText=E;exports.segmentNumber=l;exports.segmentTextFromValue=D;exports.selectElementContents=V;exports.toISODateString=_;exports.todayParts=M;exports.wrapInRange=g;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const g=require("./DateField.validation.cjs.js"),u=31,s=12,c=1,d=9999,y=(e,t,n)=>Math.min(n,Math.max(t,e)),S=(e,t)=>((e-1)%t+t)%t+1,N=2024,h=(e,t)=>t==null?31:new Date(e??N,t,0).getDate(),T=()=>{const e=new Date;return{day:e.getDate(),month:e.getMonth()+1,year:e.getFullYear()}},l=e=>e instanceof Date&&!Number.isNaN(e.getTime()),_=(e,t,n,r)=>{if(n==="min")return e==="year"?null:1;if(n==="max")return e==="year"?null:e==="day"?r.daysInMonth:s;if(t==null){if(e==="year")return r.today.year;const f=e==="day"?u:s;return n>0?1:f}if(e==="year")return y(t+n,c,d);const o=e==="day"?u:s;return S(t+n,o)},A={day:"",month:"",year:""},M=e=>{const{day:t,month:n,year:r}=e;if(t==null||n==null||r==null)return null;const o=new Date(r,n-1,t);return o.setFullYear(r),Number.isNaN(o.getTime())||o.getFullYear()!==r||o.getMonth()!==n-1||o.getDate()!==t?null:o},E=(e,t)=>e==null&&t==null?!0:e==null||t==null?!1:e.getTime()===t.getTime(),a=e=>e.getFullYear()*1e4+(e.getMonth()+1)*100+e.getDate(),p=e=>l(e)?a(e):null,D=(e,t,n)=>{const r=a(e);return!(l(t)&&r<a(t)||l(n)&&r>a(n))},m=(e,t)=>l(e)&&l(t)&&a(e)>a(t),Y=(e,t,n)=>{if(m(t,n))return e;const r=a(e);return l(t)&&r<a(t)?new Date(t.getFullYear(),t.getMonth(),t.getDate()):l(n)&&r>a(n)?new Date(n.getFullYear(),n.getMonth(),n.getDate()):e},F=e=>{if(!l(e))return"";const t=String(e.getFullYear()).padStart(4,"0"),n=String(e.getMonth()+1).padStart(2,"0"),r=String(e.getDate()).padStart(2,"0");return`${t}-${n}-${r}`},R=e=>e.filter(t=>t.type!=="literal").map(t=>t.type),I=e=>l(e)?{day:String(e.getDate()).padStart(2,"0"),month:String(e.getMonth()+1).padStart(2,"0"),year:String(e.getFullYear()).padStart(4,"0")}:A,i=(e,t)=>{if(t===""||e==="year"&&t.length<g.SEGMENT_MAX_LENGTH.year)return null;const n=parseInt(t,10);return Number.isNaN(n)||n===0?null:n},V=e=>M({day:i("day",e.day),month:i("month",e.month),year:i("year",e.year)}),w=(e,t)=>t===""?"":t.padStart(g.SEGMENT_MAX_LENGTH[e],"0"),X=(e,t,n)=>t===""?{displayValue:n,isPlaceholder:!0}:{displayValue:t.padStart(g.SEGMENT_MAX_LENGTH[e],"0"),isPlaceholder:!1},O=e=>{const t=window.getSelection();if(!t)return;const n=document.createRange();n.selectNodeContents(e),t.removeAllRanges(),t.addRange(n)},P=e=>{var n;if(!e)return;const t=(n=window.getSelection)==null?void 0:n.call(window);t&&t.rangeCount>0&&e.contains(t.anchorNode)&&t.removeAllRanges()};exports.DAY_SPIN_MAX=u;exports.MONTH_MAX=s;exports.YEAR_MAX=d;exports.YEAR_MIN=c;exports.adjustSegmentValue=_;exports.clamp=y;exports.clampDateToRange=Y;exports.clearSelectionWithin=P;exports.dateKeyOrNull=p;exports.deriveValue=M;exports.deriveValueFromText=V;exports.getDaysInMonth=h;exports.getSegmentDisplay=X;exports.getSegmentOrder=R;exports.isDateInRange=D;exports.isMinMaxMisconfigured=m;exports.isSameDateValue=E;exports.normalizeSegmentText=w;exports.segmentNumber=i;exports.segmentTextFromValue=I;exports.selectElementContents=O;exports.toISODateString=F;exports.todayParts=T;exports.wrapInRange=S;

package/lib/wip/DateField/DateField.utils.d.ts

@@ -15,11 +15,12 @@ export declare const DAY_SPIN_MAX = 31;
 /** Absolute maximum for month (1-based). */
 export declare const MONTH_MAX = 12;
 /**
- * Announced aria-valuemax per segment type.
- * Day uses the absolute calendar max (31); month-aware override for day is
- * computed in `DateField.Segments` and passed as `valueMax` to `DateFieldSegment`.
+ * Absolute floor/ceiling for the free-spinning year segment. `minDate`/
+ * `maxDate` no longer bound the year directly (DF-10: the whole date clamps
+ * to those bounds on blur instead — see `commitOnBlur`).
  */
-export declare const SEGMENT_ARIA_MAX: Record<SegmentType, number>;
+export declare const YEAR_MIN = 1;
+export declare const YEAR_MAX = 9999;
 /** Clamps `n` to `[lo, hi]` (inclusive). */
 export declare const clamp: (n: number, lo: number, hi: number) => number;
 /**
@@ -49,7 +50,11 @@ export declare const todayParts: () => {
 export interface AdjustSegmentContext {
     /** Days in the current month (use {@link getDaysInMonth} to compute). */
     daysInMonth: number;
-    /** Today's local-date values used to seed an empty segment on the first press. */
+    /**
+     * Today's local-date values. Only `year` is read now — it seeds an empty
+     * year segment on the first press. Day/month seed to a fixed first/last
+     * valid value instead, so `day`/`month` here go unused.
+     */
     today: {
         day: number;
         month: number;
@@ -60,22 +65,15 @@ export interface AdjustSegmentContext {
  * Computes the next numeric value for a date segment after an increment,
  * decrement, or boundary jump.
  *
- * Returns `null` to signal "no change" (Home/End on the year segment, which
- * has no meaningful bound until DF-10 adds minDate/maxDate).
- *
- * Rules:
- * - **day spin (numeric delta)**: modular wrap within `[1, DAY_SPIN_MAX]` — the
- *   absolute calendar maximum. Out-of-range dates (e.g. Feb 31) are flagged
- *   invalid by the existing validity layer (`useDateFieldValidity`), not clamped here.
- * - **day End (`'max'`)**: uses `ctx.daysInMonth` — the last valid day of the
- *   currently selected month (month-aware).
- * - **month**: modular wrap within `[1, MONTH_MAX]`.
- * - **year**: clamp to `[1, 9999]`; no wrap.
- * - **Empty segment + numeric delta**: seeds to `ctx.today[type]` (first press
- *   sets today's value; subsequent presses step from there).
- * - **`'min'`**: returns 1 for day/month, null for year.
- * - **`'max'`**: returns `ctx.daysInMonth` for day (End → month-aware last
- *   valid day), MONTH_MAX for month, null for year.
+ * Day and month wrap modularly within their absolute ranges (day:
+ * `[1, DAY_SPIN_MAX]`; month: `[1, MONTH_MAX]`); out-of-range dates (e.g. Feb
+ * 31) are flagged by the validity layer, not clamped here. Year clamps (no
+ * wrap) within `[YEAR_MIN, YEAR_MAX]` and spins free of `minDate`/`maxDate`
+ * (DF-10: those clamp the whole date on blur instead — see `commitOnBlur`);
+ * year `'min'`/`'max'` (Home/End) are a no-op (`null`). An empty segment seeds
+ * on the first numeric press: day/month to a direction-based first/last valid
+ * value (positive amount → `1`, negative → `DAY_SPIN_MAX`/`MONTH_MAX`;
+ * EPTOOLS-2766), year to `ctx.today.year`.
  *
  * @param type - Segment kind (`'day'`, `'month'`, or `'year'`).
  * @param current - Current numeric value of the segment, or `null` when empty.
@@ -85,6 +83,36 @@ export interface AdjustSegmentContext {
 export declare const adjustSegmentValue: (type: SegmentType, current: Nullable<number>, amount: SegmentAdjustment, ctx: AdjustSegmentContext) => Nullable<number>;
 export declare const deriveValue: (segments: SegmentValues) => Nullable<Date>;
 export declare const isSameDateValue: (a: Nullable<Date>, b: Nullable<Date>) => boolean;
+/**
+ * `dateKey` for a possibly-absent/invalid `Date`, collapsing both to `null`
+ * (never `NaN` — a `NaN` dependency would itself churn every render). Used to
+ * key memo/callback deps on a bound's primitive calendar day instead of the
+ * `Date` object's identity.
+ */
+export declare const dateKeyOrNull: (d?: Nullable<Date>) => Nullable<number>;
+/**
+ * True when `value`'s calendar day falls within `[minDate, maxDate]`
+ * (inclusive). Compared by calendar day only, so a `maxDate` with a non-zero
+ * time-of-day still accepts the same day. A missing bound is unbounded on
+ * that side.
+ */
+export declare const isDateInRange: (value: Date, minDate?: Nullable<Date>, maxDate?: Nullable<Date>) => boolean;
+/**
+ * True when both bounds are valid Dates but `minDate`'s calendar day is after
+ * `maxDate`'s — a misconfiguration where no date can satisfy both. `DateField`
+ * dev-warns on this, and `clampDateToRange` skips clamping so a touched value
+ * isn't flip-flopped between the two bounds on repeated blurs.
+ */
+export declare const isMinMaxMisconfigured: (minDate?: Nullable<Date>, maxDate?: Nullable<Date>) => boolean;
+/**
+ * Clamps `value` to the nearest in-range bound by calendar day: `minDate` when
+ * the value is before it, `maxDate` when after, else the value unchanged. An
+ * invalid/absent bound is ignored (unbounded on that side). Returns a
+ * local-midnight `Date` on the bound's calendar day. Used by `commitOnBlur` to
+ * normalize a well-formed out-of-range date; structural invalids (Feb 30) never
+ * reach here since they derive to `null`.
+ */
+export declare const clampDateToRange: (value: Date, minDate?: Nullable<Date>, maxDate?: Nullable<Date>) => Date;
 export declare const toISODateString: (value: Nullable<Date>) => string;
 /** Ordered segment types from a parts array (literals stripped). */
 export declare const getSegmentOrder: (parts: ReadonlyArray<DateFieldPart>) => ReadonlyArray<SegmentType>;