@viasat/beam-react 2.39.3 → 2.41.0

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

@@ -1,9 +1,14 @@
-import { ComponentPropsWithRef, ReactElement, FocusEvent } from 'react';
+import { ComponentPropsWithRef, ReactElement, FocusEvent, KeyboardEvent } from 'react';
 import { Nullable } from '@viasat/beam-shared/utils/types';
 import { ThemeTypes } from '@viasat/beam-shared/utils/constants';
 import { FormValidator } from '@viasat/beam-shared/components/form';
 type DateFieldInputAttributes = Omit<ComponentPropsWithRef<'input'>, 'value' | 'defaultValue' | 'onChange' | 'min' | 'max' | 'type' | 'size' | 'ref' | 'form' | 'autoComplete' | 'inputMode'>;
 export type SegmentType = 'day' | 'month' | 'year';
+/**
+ * Argument to `adjustSegment` / `adjustSegmentValue`.
+ * A numeric delta (e.g. ±1, ±5) or a boundary keyword for Home/End.
+ */
+export type SegmentAdjustment = number | 'min' | 'max';
 export type FocusTarget = SegmentType | 'all' | null;
 /** Per-segment values. Month is 1-12 (NOT 0-11). */
 export interface SegmentValues {
@@ -97,6 +102,12 @@ export interface DateFieldSegmentProps {
     type: SegmentType;
     /** 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.
+     * Computed by `DateField.Segments` so the segment itself stays a pure renderer.
+     */
+    valueMax: number;
     /** Pre-computed text to render inside the segment (buffer, formatted value, or placeholder). */
     displayValue: string;
     /** True when `displayValue` IS the placeholder (drives `data-placeholder` CSS hook). */
@@ -104,7 +115,9 @@ export interface DateFieldSegmentProps {
     isActive: boolean;
     disabled: boolean;
     readOnly: boolean;
+    /** Fires when the segment gains focus (Tab, click, or programmatic). */
     onFocus: () => void;
+    /** Fires when focus leaves the segment; `relatedTarget` drives field-exit detection. */
     onBlur: (event: FocusEvent<HTMLSpanElement>) => void;
     /**
      * Single-character input callback. DF-2 single-digit typing path. The
@@ -113,6 +126,12 @@ export interface DateFieldSegmentProps {
      * DF-13 will add a paste-aware branch for whole-value parsing.
      */
     onInput: (type: SegmentType, char: string) => void;
+    /**
+     * Fires on segment keydown. The orchestrator routes it into
+     * `useDateFieldKeyboard` (DF-3: ArrowLeft/Right segment nav, RTL-aware;
+     * DF-4/DF-5 extend with increment/clear).
+     */
+    onKeyDown: (type: SegmentType, event: KeyboardEvent<HTMLSpanElement>) => void;
     segmentRef: (element: HTMLSpanElement | null) => void;
 }
 export {};

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"),u={day:"",month:"",year:""},o=e=>e instanceof Date&&!Number.isNaN(e.getTime()),s=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},g=(e,t)=>e==null&&t==null?!0:e==null||t==null?!1:e.getTime()===t.getTime(),m=e=>{if(!o(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),c=e=>o(e)?{day:String(e.getDate()).padStart(2,"0"),month:String(e.getMonth()+1).padStart(2,"0"),year:String(e.getFullYear()).padStart(4,"0")}:u,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},S=e=>s({day:l("day",e.day),month:l("month",e.month),year:l("year",e.year)}),y=(e,t)=>t===""?"":t.padStart(i.SEGMENT_MAX_LENGTH[e],"0"),T=(e,t,n)=>t===""?{displayValue:n,isPlaceholder:!0}:{displayValue:t.padStart(i.SEGMENT_MAX_LENGTH[e],"0"),isPlaceholder:!1},p=e=>{const t=window.getSelection();if(!t)return;const n=document.createRange();n.selectNodeContents(e),t.removeAllRanges(),t.addRange(n)};exports.deriveValue=s;exports.deriveValueFromText=S;exports.getSegmentDisplay=T;exports.getSegmentOrder=d;exports.isSameDateValue=g;exports.normalizeSegmentText=y;exports.segmentNumber=l;exports.segmentTextFromValue=c;exports.selectElementContents=p;exports.toISODateString=m;
+"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;

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

@@ -1,5 +1,88 @@
 import { Nullable } from '@viasat/beam-shared/utils/types';
-import { DateFieldPart, SegmentText, SegmentType, SegmentValues } from './DateField.types';
+import { DateFieldPart, SegmentAdjustment, SegmentText, SegmentType, SegmentValues } from './DateField.types';
+/**
+ * Absolute spin ceiling for day — independent of the current month.
+ *
+ * Intentional divergence (MUI-X model, not React Aria clamp): the day segment
+ * spins to this absolute max (31) even though `aria-valuemax` is month-aware
+ * (28–30, computed in `DateField.Segments`). So a user can spin ONE step past the
+ * announced ceiling into an out-of-range day (e.g. April 30 → 31); the validity
+ * layer surfaces that via `aria-invalid` rather than clamping to `daysInMonth`.
+ * The announced-vs-reachable gap is deliberate — see docs/adr/calendar.md (spin
+ * model). Out-of-range days (e.g. Feb 31) are caught by the validity layer, not here.
+ */
+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`.
+ */
+export declare const SEGMENT_ARIA_MAX: Record<SegmentType, number>;
+/** Clamps `n` to `[lo, hi]` (inclusive). */
+export declare const clamp: (n: number, lo: number, hi: number) => number;
+/**
+ * Modular wrap within a 1-based inclusive range `[1, max]`.
+ * Handles negative deltas correctly (e.g. 1 − 1 in a max-12 range → 12).
+ */
+export declare const wrapInRange: (n: number, max: number) => number;
+/**
+ * Returns the number of days in the given month/year combination.
+ *
+ * - `month` is 1-based (1 = January, 12 = December).
+ * - When `month` is null (unknown), returns 31 (conservative maximum).
+ * - When `month` is provided but `year` is null, uses {@link LEAP_YEAR_FALLBACK}
+ *   so February correctly reports 29 days (leap-safe fallback).
+ */
+export declare const getDaysInMonth: (year: Nullable<number>, month: Nullable<number>) => number;
+/**
+ * Returns today's date parts as a plain object.
+ * Extracted so callers in the value hook and DF-8 can share the same helper.
+ */
+export declare const todayParts: () => {
+    day: number;
+    month: number;
+    year: number;
+};
+/** Context passed into {@link adjustSegmentValue} — kept pure by the caller. */
+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: {
+        day: number;
+        month: number;
+        year: number;
+    };
+}
+/**
+ * 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.
+ *
+ * @param type - Segment kind (`'day'`, `'month'`, or `'year'`).
+ * @param current - Current numeric value of the segment, or `null` when empty.
+ * @param amount - Numeric delta (e.g. ±1, ±5) or `'min'`/`'max'` for Home/End.
+ * @param ctx - Pure context: days-in-month and today's date parts.
+ */
+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;
 export declare const toISODateString: (value: Nullable<Date>) => string;
@@ -24,3 +107,8 @@ export interface SegmentDisplay {
 export declare const getSegmentDisplay: (type: SegmentType, text: string, placeholder: string) => SegmentDisplay;
 /** Selects an element's entire textContent (whole-segment highlight). */
 export declare const selectElementContents: (element: HTMLElement) => void;
+/** Clears the DOM selection when it currently lives inside `container`. Chrome
+ *  leaves the whole-segment Range highlighted after the field blurs; Safari
+ *  clears it automatically. Scoped to `container` so a selection elsewhere on
+ *  the page is untouched. */
+export declare const clearSelectionWithin: (container: HTMLElement | null) => void;

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

@@ -1,45 +1,74 @@
-import { SEGMENT_MAX_LENGTH as o } from "./DateField.validation.es.js";
-const s = { day: "", month: "", year: "" }, i = (e) => e instanceof Date && !Number.isNaN(e.getTime()), u = (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;
-}, m = (e, t) => e == null && t == null ? !0 : e == null || t == null ? !1 : e.getTime() === t.getTime(), d = (e) => {
-  if (!i(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}`;
-}, c = (e) => e.filter(
-  (t) => t.type !== "literal"
-).map((t) => t.type), y = (e) => i(e) ? {
-  day: String(e.getDate()).padStart(2, "0"),
-  month: String(e.getMonth() + 1).padStart(2, "0"),
-  year: String(e.getFullYear()).padStart(4, "0")
-} : s, l = (e, t) => {
-  if (t === "" || e === "year" && t.length < o.year) return null;
-  const n = parseInt(t, 10);
+import { SEGMENT_MAX_LENGTH as s } from "./DateField.validation.es.js";
+const i = 31, o = 12, f = {
+  day: i,
+  month: o,
+  year: 9999
+}, c = (t, e, n) => Math.min(n, Math.max(e, t)), g = (t, e) => ((t - 1) % e + e) % e + 1, d = 2024, h = (t, e) => e == null ? 31 : new Date(t ?? d, e, 0).getDate(), N = () => {
+  const t = /* @__PURE__ */ new Date();
+  return { day: t.getDate(), month: t.getMonth() + 1, year: t.getFullYear() };
+}, M = (t, e, n, r) => {
+  if (n === "min") return t === "year" ? null : 1;
+  if (n === "max")
+    return t === "year" ? null : t === "day" ? r.daysInMonth : o;
+  if (e == null) return r.today[t];
+  if (t === "year") return c(e + n, 1, 9999);
+  const a = t === "day" ? i : o;
+  return g(e + n, a);
+}, m = { day: "", month: "", year: "" }, u = (t) => t instanceof Date && !Number.isNaN(t.getTime()), y = (t) => {
+  const { day: e, month: n, year: r } = t;
+  if (e == null || n == null || r == null) return null;
+  const a = new Date(r, n - 1, e);
+  return a.setFullYear(r), Number.isNaN(a.getTime()) || a.getFullYear() !== r || a.getMonth() !== n - 1 || a.getDate() !== e ? null : a;
+}, D = (t, e) => t == null && e == null ? !0 : t == null || e == null ? !1 : t.getTime() === e.getTime(), p = (t) => {
+  if (!u(t)) return "";
+  const e = String(t.getFullYear()).padStart(4, "0"), n = String(t.getMonth() + 1).padStart(2, "0"), r = String(t.getDate()).padStart(2, "0");
+  return `${e}-${n}-${r}`;
+}, T = (t) => t.filter(
+  (e) => e.type !== "literal"
+).map((e) => e.type), A = (t) => u(t) ? {
+  day: String(t.getDate()).padStart(2, "0"),
+  month: String(t.getMonth() + 1).padStart(2, "0"),
+  year: String(t.getFullYear()).padStart(4, "0")
+} : m, l = (t, e) => {
+  if (e === "" || t === "year" && e.length < s.year) return null;
+  const n = parseInt(e, 10);
   return Number.isNaN(n) || n === 0 ? null : n;
-}, S = (e) => u({
-  day: l("day", e.day),
-  month: l("month", e.month),
-  year: l("year", e.year)
-}), p = (e, t) => t === "" ? "" : t.padStart(o[e], "0"), f = (e, t, n) => t === "" ? { displayValue: n, isPlaceholder: !0 } : {
-  displayValue: t.padStart(o[e], "0"),
+}, E = (t) => y({
+  day: l("day", t.day),
+  month: l("month", t.month),
+  year: l("year", t.year)
+}), _ = (t, e) => e === "" ? "" : e.padStart(s[t], "0"), w = (t, e, n) => e === "" ? { displayValue: n, isPlaceholder: !0 } : {
+  displayValue: e.padStart(s[t], "0"),
   isPlaceholder: !1
-}, N = (e) => {
-  const t = window.getSelection();
-  if (!t) return;
+}, F = (t) => {
+  const e = window.getSelection();
+  if (!e) return;
   const n = document.createRange();
-  n.selectNodeContents(e), t.removeAllRanges(), t.addRange(n);
+  n.selectNodeContents(t), e.removeAllRanges(), e.addRange(n);
+}, V = (t) => {
+  var n;
+  if (!t) return;
+  const e = (n = window.getSelection) == null ? void 0 : n.call(window);
+  e && e.rangeCount > 0 && t.contains(e.anchorNode) && e.removeAllRanges();
 };
 export {
-  u as deriveValue,
-  S as deriveValueFromText,
-  f as getSegmentDisplay,
-  c as getSegmentOrder,
-  m as isSameDateValue,
-  p as normalizeSegmentText,
+  i as DAY_SPIN_MAX,
+  o as MONTH_MAX,
+  f as SEGMENT_ARIA_MAX,
+  M as adjustSegmentValue,
+  c as clamp,
+  V as clearSelectionWithin,
+  y as deriveValue,
+  E as deriveValueFromText,
+  h as getDaysInMonth,
+  w as getSegmentDisplay,
+  T as getSegmentOrder,
+  D as isSameDateValue,
+  _ as normalizeSegmentText,
   l as segmentNumber,
-  y as segmentTextFromValue,
-  N as selectElementContents,
-  d as toISODateString
+  A as segmentTextFromValue,
+  F as selectElementContents,
+  p as toISODateString,
+  N as todayParts,
+  g as wrapInRange
 };

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

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const c=require("react");function M({disabled:n,fieldRef:i,segmentRefs:T,partsOrder:f,onSegmentFocusChange:x,onFieldBlur:k}){const[l,a]=c.useState(null),s=f[0],r=c.useRef(x),o=c.useRef(k);c.useEffect(()=>{r.current=x,o.current=k},[x,k]),c.useEffect(()=>{if(l===null||l==="all")return;const t=T.current.get(l);t&&document.activeElement!==t&&t.focus()},[l,T]);const b=c.useCallback(t=>{var u;n||(a(t),(u=r.current)==null||u.call(r,t))},[n]),y=c.useCallback(t=>{var u;n||t.target===i.current&&(a(s),(u=r.current)==null||u.call(r,s))},[n,i,s]),E=c.useCallback(t=>{var u,e;(u=i.current)!=null&&u.contains(t.relatedTarget)||(a(null),(e=o.current)==null||e.call(o))},[i]),v=c.useCallback(t=>{var e;if(n)return;t.target.closest("[data-segment]")||(t.preventDefault(),a(s),(e=r.current)==null||e.call(r,s))},[n,s]),I=c.useCallback(t=>{var D;const u=f.indexOf(t);if(u===-1)return;const e=f[u+1];e!=null&&(a(e),(D=r.current)==null||D.call(r,e))},[f]);return{focusedSegment:l,fieldTabIndex:n?-1:l===null?0:-1,handleSegmentFocus:b,handleFieldFocus:y,handleFieldBlur:E,handleFieldMouseDown:v,focusNext:I}}exports.useDateFieldFocus=M;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("react"),I=require("./DateField.utils.cjs.js");function M({disabled:n,fieldRef:a,segmentRefs:T,partsOrder:o,onSegmentFocusChange:b,onFieldBlur:D}){const[l,i]=e.useState(null),s=o[0],r=e.useRef(b),f=e.useRef(D);e.useEffect(()=>{r.current=b,f.current=D},[b,D]),e.useEffect(()=>{if(l===null||l==="all")return;const t=T.current.get(l);t&&document.activeElement!==t&&t.focus()},[l,T]);const _=e.useCallback(t=>{var u;n||(i(t),(u=r.current)==null||u.call(r,t))},[n]),v=e.useCallback(t=>{var u;n||t.target===a.current&&(i(s),(u=r.current)==null||u.call(r,s))},[n,a,s]),E=e.useCallback(t=>{var u,c;(u=a.current)!=null&&u.contains(t.relatedTarget)||(i(null),(c=f.current)==null||c.call(f),I.clearSelectionWithin(a.current))},[a]),d=e.useCallback(t=>{var c;if(n)return;t.target.closest("[data-segment]")||(t.preventDefault(),i(s),(c=r.current)==null||c.call(r,s))},[n,s]),k=e.useCallback((t,u)=>{var y;const c=o.indexOf(t);if(c===-1)return;const x=o[c+u];x!=null&&(i(x),(y=r.current)==null||y.call(r,x))},[o]),q=e.useCallback(t=>{k(t,1)},[k]),w=e.useCallback(t=>{k(t,-1)},[k]);return{focusedSegment:l,fieldTabIndex:n?-1:l===null?0:-1,handleSegmentFocus:_,handleFieldFocus:v,handleFieldBlur:E,handleFieldMouseDown:d,focusNext:q,focusPrevious:w}}exports.useDateFieldFocus=M;

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

@@ -1,8 +1,8 @@
-import { FocusEvent, MouseEvent, MutableRefObject } from 'react';
+import { FocusEvent, MouseEvent, MutableRefObject, RefObject } from 'react';
 import { FocusTarget, SegmentType } from './DateField.types';
 export interface UseDateFieldFocusArgs {
     disabled: boolean;
-    fieldRef: MutableRefObject<HTMLDivElement | null>;
+    fieldRef: RefObject<HTMLDivElement>;
     segmentRefs: MutableRefObject<Map<SegmentType, HTMLSpanElement>>;
     /** Ordered segment types (literals stripped). En-US hardcoded; DF-8 derives from locale. */
     partsOrder: ReadonlyArray<SegmentType>;
@@ -19,5 +19,6 @@ export interface UseDateFieldFocusReturn {
     handleFieldBlur: (event: FocusEvent<HTMLElement>) => void;
     handleFieldMouseDown: (event: MouseEvent<HTMLDivElement>) => void;
     focusNext: (currentType: SegmentType) => void;
+    focusPrevious: (currentType: SegmentType) => void;
 }
 export declare function useDateFieldFocus({ disabled, fieldRef, segmentRefs, partsOrder, onSegmentFocusChange, onFieldBlur, }: UseDateFieldFocusArgs): UseDateFieldFocusReturn;

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

@@ -1,65 +1,77 @@
-import { useState as N, useRef as I, useEffect as k, useCallback as s } from "react";
-function z({
+import { useState as j, useRef as E, useEffect as I, useCallback as e } from "react";
+import { clearSelectionWithin as m } from "./DateField.utils.es.js";
+function G({
   disabled: n,
-  fieldRef: f,
-  segmentRefs: D,
-  partsOrder: o,
-  onSegmentFocusChange: a,
-  onFieldBlur: T
+  fieldRef: i,
+  segmentRefs: v,
+  partsOrder: f,
+  onSegmentFocusChange: T,
+  onFieldBlur: D
 }) {
-  const [e, i] = N(null), l = o[0], r = I(a), x = I(T);
-  k(() => {
-    r.current = a, x.current = T;
-  }, [a, T]), k(() => {
-    if (e === null || e === "all") return;
-    const t = D.current.get(e);
+  const [s, l] = j(null), o = f[0], r = E(T), a = E(D);
+  I(() => {
+    r.current = T, a.current = D;
+  }, [T, D]), I(() => {
+    if (s === null || s === "all") return;
+    const t = v.current.get(s);
     t && document.activeElement !== t && t.focus();
-  }, [e, D]);
-  const p = s(
+  }, [s, v]);
+  const k = e(
     (t) => {
-      var u;
-      n || (i(t), (u = r.current) == null || u.call(r, t));
+      var c;
+      n || (l(t), (c = r.current) == null || c.call(r, t));
     },
     [n]
-  ), v = s(
+  ), w = e(
     (t) => {
-      var u;
-      n || t.target === f.current && (i(l), (u = r.current) == null || u.call(r, l));
+      var c;
+      n || t.target === i.current && (l(o), (c = r.current) == null || c.call(r, o));
     },
-    [n, f, l]
-  ), w = s(
+    [n, i, o]
+  ), M = e(
     (t) => {
-      var u, c;
-      (u = f.current) != null && u.contains(t.relatedTarget) || (i(null), (c = x.current) == null || c.call(x));
+      var c, u;
+      (c = i.current) != null && c.contains(t.relatedTarget) || (l(null), (u = a.current) == null || u.call(a), m(i.current));
     },
-    [f]
-  ), y = s(
+    [i]
+  ), N = e(
     (t) => {
-      var c;
+      var u;
       if (n) return;
-      t.target.closest("[data-segment]") || (t.preventDefault(), i(l), (c = r.current) == null || c.call(r, l));
+      t.target.closest("[data-segment]") || (t.preventDefault(), l(o), (u = r.current) == null || u.call(r, o));
     },
-    [n, l]
-  ), M = s(
-    (t) => {
-      var E;
-      const u = o.indexOf(t);
+    [n, o]
+  ), x = e(
+    (t, c) => {
+      var y;
+      const u = f.indexOf(t);
       if (u === -1) return;
-      const c = o[u + 1];
-      c != null && (i(c), (E = r.current) == null || E.call(r, c));
+      const p = f[u + c];
+      p != null && (l(p), (y = r.current) == null || y.call(r, p));
+    },
+    [f]
+  ), P = e(
+    (t) => {
+      x(t, 1);
+    },
+    [x]
+  ), W = e(
+    (t) => {
+      x(t, -1);
     },
-    [o]
+    [x]
   );
   return {
-    focusedSegment: e,
-    fieldTabIndex: n ? -1 : e === null ? 0 : -1,
-    handleSegmentFocus: p,
-    handleFieldFocus: v,
-    handleFieldBlur: w,
-    handleFieldMouseDown: y,
-    focusNext: M
+    focusedSegment: s,
+    fieldTabIndex: n ? -1 : s === null ? 0 : -1,
+    handleSegmentFocus: k,
+    handleFieldFocus: w,
+    handleFieldBlur: M,
+    handleFieldMouseDown: N,
+    focusNext: P,
+    focusPrevious: W
   };
 }
 export {
-  z as useDateFieldFocus
+  G as useDateFieldFocus
 };

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

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const s=require("react");function d({disabled:c,readOnly:a,fieldRef:u,focusNext:n,focusPrevious:o,adjustSegment:t}){const y=s.useMemo(()=>{const i={ArrowRight:({segment:r,isRTL:e})=>((e?o:n)(r),!0),ArrowLeft:({segment:r,isRTL:e})=>((e?n:o)(r),!0)};return a?i:{...i,ArrowUp:({segment:r})=>t(r,1),ArrowDown:({segment:r})=>t(r,-1),PageUp:({segment:r})=>t(r,5),PageDown:({segment:r})=>t(r,-5),Home:({segment:r})=>t(r,"min"),End:({segment:r})=>t(r,"max")}},[t,n,o,a]);return s.useCallback((i,r)=>{if(c||r.altKey||r.ctrlKey||r.metaKey||r.shiftKey)return;const e=y[r.key];if(!e)return;const l=u.current,b=!!l&&(getComputedStyle(l).direction==="rtl"||!!l.closest('[dir="rtl"]'));e({segment:i,event:r,isRTL:b})&&r.preventDefault()},[c,y,u])}exports.useDateFieldKeyboard=d;

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

@@ -0,0 +1,44 @@
+import { KeyboardEvent, RefObject } from 'react';
+import { SegmentAdjustment, SegmentType } from './DateField.types';
+/** Per-call context passed to each key binding. */
+export interface SegmentKeyContext {
+    /** Segment the key event fired on. */
+    segment: SegmentType;
+    /** The originating keydown event. */
+    event: KeyboardEvent<HTMLSpanElement>;
+    /** Whether the field is rendered right-to-left. */
+    isRTL: boolean;
+}
+/**
+ * A key binding: runs the action for one key, given the call context, and
+ * returns whether it handled the key. The dispatcher `preventDefault`s only when
+ * a binding returns `true`, so a binding can decline (return `false`) to leave
+ * the key to the browser's native default (e.g. page scroll).
+ */
+export type SegmentKeyBinding = (ctx: SegmentKeyContext) => boolean;
+export interface UseDateFieldKeyboardArgs {
+    /** When true, the dispatcher ignores all keys. */
+    disabled: boolean;
+    /**
+     * When true, value-mutation keys (ArrowUp/Down, PageUp/Down, Home, End) are
+     * left unbound so they fall through to the browser (native page scroll);
+     * only the navigation keys (ArrowLeft/Right) are bound. Blocks value mutation
+     * without suppressing scroll.
+     */
+    readOnly: boolean;
+    /** Field root ref, used to detect RTL direction. */
+    fieldRef: RefObject<HTMLDivElement>;
+    /** Move focus to the next segment in `PARTS_ORDER`. */
+    focusNext: (segment: SegmentType) => void;
+    /** Move focus to the previous segment in `PARTS_ORDER`. */
+    focusPrevious: (segment: SegmentType) => void;
+    /**
+     * Increment, decrement, or jump a segment to its min/max boundary.
+     * Provided by `useDateFieldValue`. Numeric `amount` wraps day/month and
+     * clamps year; `'min'`/`'max'` map to Home/End respectively. Returns `false`
+     * on a no-op (year `'min'`/`'max'` until DF-10 adds year bounds) so the
+     * dispatcher leaves the key to native page scroll.
+     */
+    adjustSegment: (type: SegmentType, amount: SegmentAdjustment) => boolean;
+}
+export declare function useDateFieldKeyboard({ disabled, readOnly, fieldRef, focusNext, focusPrevious, adjustSegment, }: UseDateFieldKeyboardArgs): (segment: SegmentType, event: KeyboardEvent<HTMLSpanElement>) => void;

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

@@ -0,0 +1,45 @@
+import { useMemo as u, useCallback as K } from "react";
+function A({
+  disabled: e,
+  readOnly: p,
+  fieldRef: w,
+  focusNext: t,
+  focusPrevious: l,
+  adjustSegment: i
+}) {
+  const y = u(
+    () => {
+      const o = {
+        // Nav keys always own the event (arrows are contentEditable caret keys we
+        // suppress even at the first/last segment), so they always report handled.
+        ArrowRight: ({ segment: r, isRTL: n }) => ((n ? l : t)(r), !0),
+        ArrowLeft: ({ segment: r, isRTL: n }) => ((n ? t : l)(r), !0)
+      };
+      return p ? o : {
+        ...o,
+        ArrowUp: ({ segment: r }) => i(r, 1),
+        ArrowDown: ({ segment: r }) => i(r, -1),
+        PageUp: ({ segment: r }) => i(r, 5),
+        PageDown: ({ segment: r }) => i(r, -5),
+        Home: ({ segment: r }) => i(r, "min"),
+        End: ({ segment: r }) => i(r, "max")
+        // ── Extension points ─────────────────────────────────────────────
+        // DF-5: Backspace / Delete (clear segment) → value action
+      };
+    },
+    [i, t, l, p]
+  );
+  return K(
+    (o, r) => {
+      if (e || r.altKey || r.ctrlKey || r.metaKey || r.shiftKey) return;
+      const n = y[r.key];
+      if (!n) return;
+      const c = w.current, a = !!c && (getComputedStyle(c).direction === "rtl" || !!c.closest('[dir="rtl"]'));
+      n({ segment: o, event: r, isRTL: a }) && r.preventDefault();
+    },
+    [e, y, w]
+  );
+}
+export {
+  A as useDateFieldKeyboard
+};

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

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const t=require("react"),r=require("./DateField.utils.cjs.js"),E=require("./DateField.validation.cjs.js");function j({value:u,defaultValue:F,onChange:m}){const T=t.useRef(u!==void 0),f=T.current,[c,g]=t.useState(()=>r.segmentTextFromValue(f?u??null:F??null)),[h,S]=t.useState(!1),s=t.useRef(c),a=t.useRef(new Set),x=t.useRef(!1),V={day:r.segmentNumber("day",c.day),month:r.segmentNumber("month",c.month),year:r.segmentNumber("year",c.year)},y=r.deriveValue(V),b=t.useRef(y),D=t.useRef(f?u??null:null),l=t.useRef(m);t.useEffect(()=>{l.current=m},[m]),t.useEffect(()=>{if(!T.current||x.current||r.isSameDateValue(u??null,D.current))return;D.current=u??null;const e=r.segmentTextFromValue(u??null);s.current=e,g(e),b.current=r.deriveValueFromText(e)},[u]);const o=t.useCallback(e=>{var i;const n=r.deriveValueFromText(e);r.isSameDateValue(n,b.current)||(b.current=n,(i=l.current)==null||i.call(l,n))},[]),_=t.useCallback((e,n)=>{const i=a.current.has(e)?"":s.current[e],d=E.tryAppendDigit(e,i,n);if(d.rejected)return{advanced:!1,rejected:!0};const R={...s.current,[e]:d.newBuffer};return s.current=R,g(R),S(!0),o(R),d.shouldAdvance?a.current.add(e):a.current.delete(e),{advanced:d.shouldAdvance,rejected:!1}},[o]),v=t.useCallback(e=>{x.current=!0,a.current.add(e)},[]),w=t.useCallback(()=>{x.current=!1;const e=s.current,n={day:r.normalizeSegmentText("day",e.day),month:r.normalizeSegmentText("month",e.month),year:r.normalizeSegmentText("year",e.year)};s.current=n,g(n),S(!0),o(n)},[o]);return{segmentText:c,segmentValues:V,currentValue:y,isControlled:f,wasTouched:h,appendDigit:_,beginSegmentEdit:v,commitOnBlur:w}}exports.useDateFieldValue=j;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const n=require("react"),t=require("./DateField.utils.cjs.js"),_=require("./DateField.validation.cjs.js");function M({value:c,defaultValue:N,onChange:x}){const R=n.useRef(c!==void 0),S=R.current,[o,m]=n.useState(()=>t.segmentTextFromValue(S?c??null:N??null)),[E,b]=n.useState(!1),s=n.useRef(o),d=n.useRef(new Set),f=n.useRef(!1),V={day:t.segmentNumber("day",o.day),month:t.segmentNumber("month",o.month),year:t.segmentNumber("year",o.year)},y=t.deriveValue(V),T=n.useRef(y),D=n.useRef(S?c??null:null),g=n.useRef(x);n.useEffect(()=>{g.current=x},[x]),n.useEffect(()=>{if(!R.current||f.current||t.isSameDateValue(c??null,D.current))return;D.current=c??null;const e=t.segmentTextFromValue(c??null);s.current=e,m(e),T.current=t.deriveValueFromText(e)},[c]);const a=n.useCallback(e=>{var u;const r=t.deriveValueFromText(e);t.isSameDateValue(r,T.current)||(T.current=r,(u=g.current)==null||u.call(g,r))},[]),j=n.useCallback((e,r)=>{const u=d.current.has(e)?"":s.current[e],l=_.tryAppendDigit(e,u,r);if(l.rejected)return{advanced:!1,rejected:!0};const i={...s.current,[e]:l.newBuffer};return s.current=i,m(i),b(!0),a(i),l.shouldAdvance?d.current.add(e):d.current.delete(e),{advanced:l.shouldAdvance,rejected:!1}},[a]),v=n.useCallback((e,r)=>{const u=s.current,l=t.segmentNumber(e,u[e]),i=t.getDaysInMonth(t.segmentNumber("year",u.year),t.segmentNumber("month",u.month)),F=t.adjustSegmentValue(e,l,r,{daysInMonth:i,today:t.todayParts()});if(F==null)return!1;f.current=!0;const C=String(F).padStart(_.SEGMENT_MAX_LENGTH[e],"0"),h={...u,[e]:C};return s.current=h,m(h),b(!0),a(h),d.current.add(e),!0},[a]),k=n.useCallback(e=>{f.current=!0,d.current.add(e)},[]),w=n.useCallback(()=>{f.current=!1;const e=s.current,r={day:t.normalizeSegmentText("day",e.day),month:t.normalizeSegmentText("month",e.month),year:t.normalizeSegmentText("year",e.year)};s.current=r,m(r),b(!0),a(r)},[a]);return{segmentText:o,segmentValues:V,currentValue:y,isControlled:S,wasTouched:E,appendDigit:j,adjustSegment:v,beginSegmentEdit:k,commitOnBlur:w}}exports.useDateFieldValue=M;

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

@@ -1,5 +1,5 @@
 import { Nullable } from '@viasat/beam-shared/utils/types';
-import { AppendDigitResult, SegmentText, SegmentType, SegmentValues } from './DateField.types';
+import { AppendDigitResult, SegmentAdjustment, SegmentText, SegmentType, SegmentValues } from './DateField.types';
 export interface UseDateFieldValueArgs {
     value?: Nullable<Date>;
     defaultValue?: Nullable<Date>;
@@ -13,6 +13,25 @@ export interface UseDateFieldValueReturn {
     isControlled: boolean;
     wasTouched: boolean;
     appendDigit: (type: SegmentType, digit: string) => AppendDigitResult;
+    /**
+     * Increments, decrements, or jumps a segment to its min/max boundary.
+     *
+     * - Numeric `amount` (e.g. ±1, ±5): day/month wrap modularly; year clamps
+     *   to [1, 9999]. An empty segment seeds to today's value on the first press.
+     * - `'min'` / `'max'`: jump to the lower/upper bound. No-op on year (no
+     *   meaningful bound until DF-10 adds minDate/maxDate).
+     *
+     * Follows the `appendDigit` mutation pattern: writes zero-padded `segmentText`,
+     * sets `wasTouched`, calls `emitIfChanged`, and marks the segment in
+     * `replaceNextRef` so a digit typed immediately after replaces rather than
+     * appends.
+     *
+     * @returns `true` if the segment was adjusted, `false` on a no-op (currently
+     * only year `'min'`/`'max'`, until DF-10 adds year bounds). The keyboard
+     * dispatcher uses this to decide whether to `preventDefault` — a no-op leaves
+     * the key to native (e.g. page scroll).
+     */
+    adjustSegment: (type: SegmentType, amount: SegmentAdjustment) => boolean;
     beginSegmentEdit: (type: SegmentType) => void;
     commitOnBlur: () => void;
 }