@viasat/beam-react 2.47.1 → 2.48.0

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

@@ -1,204 +1,227 @@
-import { jsxs as S, jsx as l } from "react/jsx-runtime";
-import ve from "clsx";
-import { forwardRef as De } from "react";
-import { s as a, b as Fe, c as s, a as he } from "../../../chunks/DateField.Segment.C2qoaY0Z.js";
-import { t as xe } from "../../../chunks/constants.Cruz2A1w.js";
-import { H as ye } from "../../../chunks/form.context.cEuTL68U.js";
-import { LabelProvider as Se } from "../../Form/contexts/label.context.es.js";
-import { HelperTextProvider as Ie } from "../../Form/contexts/helperText.context.es.js";
-import { useUniversalRef as we } from "../../Form/hooks/useUniversalRef.hook.es.js";
-import { DateFieldSegments as Re, PARTS_ORDER as I } from "./DateField.Segments.es.js";
-import { toISODateString as Ne } from "./DateField.utils.es.js";
-import { useDateFieldFocus as Ve } from "./useDateFieldFocus.es.js";
-import { useDateFieldForm as Be } from "./useDateFieldForm.es.js";
-import { useDateFieldKeyboard as Ce } from "./useDateFieldKeyboard.es.js";
-import { useDateFieldSegments as Oe } from "./useDateFieldSegments.es.js";
-import { useDateFieldValidity as Pe } from "./useDateFieldValidity.es.js";
-import { useDateFieldValue as Te } from "./useDateFieldValue.es.js";
-import { useInvalidState as Me } from "./useInvalidState.es.js";
-const ea = De(
+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: E,
-    style: H,
-    "aria-label": L,
-    "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
-    } = Be({
-      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 } = we(W), { segmentRefs: X, registerSegmentRef: Y } = Oe(), {
-      segmentText: Z,
-      segmentValues: v,
-      currentValue: D,
-      wasTouched: ee,
-      appendDigit: ae,
-      adjustSegment: re,
-      clearSegment: le,
-      beginSegmentEdit: ie,
-      commitOnBlur: se
-    } = Te({
-      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: de,
-      handleSegmentFocus: h,
-      handleFieldFocus: te,
-      handleFieldBlur: oe,
-      handleFieldMouseDown: ne,
+      focusedSegment: y,
+      fieldTabIndex: ce,
+      handleSegmentFocus: S,
+      handleFieldFocus: fe,
+      handleFieldBlur: pe,
+      handleFieldMouseDown: be,
       focusNext: x,
-      focusPrevious: me
-    } = Ve({
+      focusPrevious: ge
+    } = Te({
       disabled: e,
-      fieldRef: g,
-      segmentRefs: X,
-      partsOrder: I,
-      onSegmentFocusChange: ie,
-      onFieldBlur: se
-    }), ue = Ce({
+      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: me,
-      adjustSegment: re,
-      clearSegment: le
-    }), { isInvalid: fe } = Pe({
-      segments: v,
-      currentValue: D,
-      wasTouched: ee,
-      isFocused: F !== null
-    }), ce = (r, i) => {
-      const { advanced: ge } = ae(r, i);
-      ge && x(r);
-    }, y = Me({
-      formInvalid: A,
-      valueInvalid: fe
-    }), pe = (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]));
-    }, be = ve(
-      a[Fe],
-      m && xe(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`],
-      E
+      o && a[`${s}read-only`],
+      j
     );
-    return /* @__PURE__ */ S(
+    return /* @__PURE__ */ N(
       "div",
       {
-        className: be,
-        style: { ...H, maxWidth: C },
-        onMouseDownCapture: pe,
+        className: ye,
+        style: { ...A, maxWidth: T },
+        onMouseDownCapture: he,
         children: [
-          /* @__PURE__ */ l(
-            Se,
+          /* @__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": L,
-              "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: de,
-              className: a[he.field],
-              onMouseDown: ne,
-              onFocus: te,
-              children: /* @__PURE__ */ l(
-                Re,
+              "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: oe,
-                  onSegmentInput: ce,
-                  onSegmentKeyDown: ue,
-                  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: Ne(D),
+              name: f,
+              value: Pe(h),
               disabled: e
             }
           ),
-          /* @__PURE__ */ S(Ie, { ctxId: _, ctxDisabled: e, children: [
-            o,
-            c && /* @__PURE__ */ l(ye, { 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 {
-  ea 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 s=require("./DateField.validation.cjs.js"),i=31,l=12,S={day:i,month:l,year:9999},u=(e,t,n)=>Math.min(n,Math.max(t,e)),g=(e,t)=>((e-1)%t+t)%t+1,y=2024,M=(e,t)=>t==null?31:new Date(e??y,t,0).getDate(),N=()=>{const e=new Date;return{day:e.getDate(),month:e.getMonth()+1,year:e.getFullYear()}},f=(e,t,n,r)=>{if(n==="min")return e==="year"?null:1;if(n==="max")return e==="year"?null:e==="day"?r.daysInMonth:l;if(t==null){if(e==="year")return r.today.year;const m=e==="day"?i:l;return n>0?1:m}if(e==="year")return u(t+n,1,9999);const a=e==="day"?i:l;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},_=(e,t)=>e==null&&t==null?!0:e==null||t==null?!1:e.getTime()===t.getTime(),h=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}`},D=e=>e.filter(t=>t.type!=="literal").map(t=>t.type),A=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,o=(e,t)=>{if(t===""||e==="year"&&t.length<s.SEGMENT_MAX_LENGTH.year)return null;const n=parseInt(t,10);return Number.isNaN(n)||n===0?null:n},E=e=>d({day:o("day",e.day),month:o("month",e.month),year:o("year",e.year)}),p=(e,t)=>t===""?"":t.padStart(s.SEGMENT_MAX_LENGTH[e],"0"),V=(e,t,n)=>t===""?{displayValue:n,isPlaceholder:!0}:{displayValue:t.padStart(s.SEGMENT_MAX_LENGTH[e],"0"),isPlaceholder:!1},F=e=>{const t=window.getSelection();if(!t)return;const n=document.createRange();n.selectNodeContents(e),t.removeAllRanges(),t.addRange(n)},I=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=i;exports.MONTH_MAX=l;exports.SEGMENT_ARIA_MAX=S;exports.adjustSegmentValue=f;exports.clamp=u;exports.clearSelectionWithin=I;exports.deriveValue=d;exports.deriveValueFromText=E;exports.getDaysInMonth=M;exports.getSegmentDisplay=V;exports.getSegmentOrder=D;exports.isSameDateValue=_;exports.normalizeSegmentText=p;exports.segmentNumber=o;exports.segmentTextFromValue=A;exports.selectElementContents=F;exports.toISODateString=h;exports.todayParts=N;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;
 /**
@@ -64,24 +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**: direction-based first/last valid value
- *   for day/month — positive amount → `1`, negative amount → `DAY_SPIN_MAX`/
- *   `MONTH_MAX`. Year has no natural bound, so it seeds to `ctx.today.year`
- *   regardless of direction.
- * - **`'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.
@@ -91,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>;