@skdx/react 0.26.0 → 0.28.0

package/dist/utils/dateSegments.cjs

@@ -1 +1 @@
-"use strict";var m=Object.defineProperty;var C=Object.getOwnPropertyDescriptor;var D=Object.getOwnPropertyNames;var P=Object.prototype.hasOwnProperty;var E=(e,n)=>{for(var t in n)m(e,t,{get:n[t],enumerable:!0})},H=(e,n,t,r)=>{if(n&&typeof n=="object"||typeof n=="function")for(let o of D(n))!P.call(e,o)&&o!==t&&m(e,o,{get:()=>n[o],enumerable:!(r=C(n,o))||r.enumerable});return e};var $=e=>H(m({},"__esModule",{value:!0}),e);var _={};E(_,{SEGMENT_PLACEHOLDERS:()=>g,buildSegments:()=>w,clearDateSegmentCache:()=>L,dateToFormValue:()=>Y,dateToValues:()=>N,daysInMonth:()=>h,formatSegmentText:()=>b,from24Hour:()=>y,getDayPeriodNames:()=>S,isComplete:()=>I,resolveHourCycle:()=>f,resolveLocale:()=>l,segmentRange:()=>x,segmentTypesFor:()=>p,stepSegment:()=>R,timeStringToValues:()=>U,to24Hour:()=>d,typeDigit:()=>V,valuesToDate:()=>G,valuesToTimeString:()=>A});module.exports=$(_);var g={year:"yyyy",month:"mm",day:"dd",hour:"hh",minute:"mm",second:"ss",dayPeriod:"--"},F={year:4,month:2,day:2,hour:2,minute:2,second:2,dayPeriod:0},v=Date.UTC(2024,0,15,13,45,56),c=new Map,s=new Map;function l(e){return e??new Intl.DateTimeFormat().resolvedOptions().locale}function f(e,n){if(n===12||n===24)return n;let t=new Intl.DateTimeFormat(l(e),{hour:"numeric"}).resolvedOptions(),r=t.hourCycle??(t.hour12?"h12":"h23");return r==="h11"||r==="h12"?12:24}function p(e,n){let t=e==="date"?["year","month","day"]:[];return(e==="time"||n!=="day")&&(t.push("hour","minute"),n==="second"&&t.push("second")),t}function h(e,n){return!e||!n?31:new Date(e,n,0).getDate()}function x(e,n,t){switch(e){case"year":return{min:1,max:9999};case"month":return{min:1,max:12};case"day":return{min:1,max:h(n.year,n.month)};case"hour":return t===12?{min:1,max:12}:{min:0,max:23};case"minute":case"second":return{min:0,max:59};case"dayPeriod":return{min:0,max:1}}}function S(e){let n=l(e),t=s.get(n);if(t)return t;let r=new Intl.DateTimeFormat(n,{hour:"numeric",hourCycle:"h12",timeZone:"UTC"}),o=u=>r.formatToParts(Date.UTC(2024,0,15,u)).find(a=>a.type==="dayPeriod")?.value??(u<12?"AM":"PM"),i=[o(1),o(13)];return s.set(n,i),i}function M(e,n){let t={timeZone:"UTC"};return e.includes("year")&&(t.year="numeric"),e.includes("month")&&(t.month="2-digit"),e.includes("day")&&(t.day="2-digit"),e.includes("hour")&&(t.hour="2-digit",t.hourCycle=n===12?"h12":"h23"),e.includes("minute")&&(t.minute="2-digit"),e.includes("second")&&(t.second="2-digit"),t}function O(e,n,t){let r=`${e}|${n.join(",")}|${t}`,o=c.get(r);if(o)return o;let i=new Intl.DateTimeFormat(e,M(n,t)).formatToParts(v),u=[];for(let a of i)a.type==="literal"?u.push({type:"literal",text:a.value.replace(/[\u202F\u2009\u00A0]/g," "),value:null,min:0,max:0,isPlaceholder:!1,isEditable:!1}):(a.type==="dayPeriod"||n.includes(a.type))&&u.push({type:a.type,text:"",value:null,min:0,max:0,isPlaceholder:!0,isEditable:!0});return c.set(r,u),u}function b(e,n,t){return n===null?g[e]:e==="dayPeriod"?S(t)[n===0?0:1]:String(n).padStart(F[e],"0")}function w(e){let n=l(e.locale),t=f(n,e.hourCycle),r=p(e.kind,e.granularity);return O(n,r,t).map(o=>{if(!o.isEditable)return o;let i=o.type,u=e.values[i]??null,{min:a,max:T}=x(i,e.values,t);return{type:i,text:b(i,u,n),value:u,min:a,max:T,isPlaceholder:u===null,isEditable:!0}})}function R(e,n){let{min:t,max:r}=e;if(e.value===null)return e.type==="year"?new Date().getFullYear():t;let o=r-t+1;return t+((e.value-t+n)%o+o)%o}function V(e,n,t){let r=n*10+t;r>e.max&&(r=t);let o=r*10>e.max;return{value:r,buffer:o?0:r,advance:o}}function I(e){return e.every(n=>!n.isEditable||n.value!==null&&n.value>=n.min&&n.value<=n.max)}function d(e,n,t){return t===24?e:e%12+(n===1?12:0)}function y(e,n){return n===24?[e,null]:[e%12===0?12:e%12,e<12?0:1]}function G(e,n){let{year:t,month:r,day:o}=e;if(!t||!r||!o)return null;let i=e.hour==null?0:d(e.hour,e.dayPeriod,n),u=new Date(t,r-1,o,i,e.minute??0,e.second??0,0);return t<100&&u.setFullYear(t),u}function N(e,n){let[t,r]=y(e.getHours(),n);return{year:e.getFullYear(),month:e.getMonth()+1,day:e.getDate(),hour:t,minute:e.getMinutes(),second:e.getSeconds(),dayPeriod:r}}function A(e,n,t){if(e.hour==null||e.minute==null||t===12&&e.dayPeriod==null)return null;let r=u=>String(u).padStart(2,"0"),o=d(e.hour,e.dayPeriod,t),i=`${r(o)}:${r(e.minute)}`;return n!=="second"?i:e.second==null?null:`${i}:${r(e.second)}`}function U(e,n){let t=/^(\d{1,2}):(\d{2})(?::(\d{2}))?$/.exec(e.trim());if(!t)return{};let r=Number(t[1]),o=Number(t[2]),i=t[3]===void 0?0:Number(t[3]);if(r>23||o>59||i>59)return{};let[u,a]=y(r,n);return{hour:u,minute:o,second:i,dayPeriod:a}}function Y(e,n){let t=(i,u=2)=>String(i).padStart(u,"0"),r=`${t(e.getFullYear(),4)}-${t(e.getMonth()+1)}-${t(e.getDate())}`;if(n==="day")return r;let o=`${t(e.getHours())}:${t(e.getMinutes())}`;return n==="second"?`${r}T${o}:${t(e.getSeconds())}`:`${r}T${o}`}function L(){c.clear(),s.clear()}0&&(module.exports={SEGMENT_PLACEHOLDERS,buildSegments,clearDateSegmentCache,dateToFormValue,dateToValues,daysInMonth,formatSegmentText,from24Hour,getDayPeriodNames,isComplete,resolveHourCycle,resolveLocale,segmentRange,segmentTypesFor,stepSegment,timeStringToValues,to24Hour,typeDigit,valuesToDate,valuesToTimeString});
+"use strict";var d=Object.defineProperty;var H=Object.getOwnPropertyDescriptor;var N=Object.getOwnPropertyNames;var M=Object.prototype.hasOwnProperty;var R=(e,n)=>{for(var t in n)d(e,t,{get:n[t],enumerable:!0})},V=(e,n,t,r)=>{if(n&&typeof n=="object"||typeof n=="function")for(let u of N(n))!M.call(e,u)&&u!==t&&d(e,u,{get:()=>n[u],enumerable:!(r=H(n,u))||r.enumerable});return e};var v=e=>V(d({},"__esModule",{value:!0}),e);var ee={};R(ee,{SEGMENT_PLACEHOLDERS:()=>S,buildSegments:()=>U,clampValuesToTimeRange:()=>Q,clearDateSegmentCache:()=>X,dateRangeViolation:()=>W,dateToFormValue:()=>s,dateToValues:()=>k,dayPeriodFromKey:()=>I,daysInMonth:()=>P,formatSegmentText:()=>F,from24Hour:()=>h,getDayPeriodNames:()=>y,isComplete:()=>j,parseDateFormValue:()=>q,resolveHourCycle:()=>T,resolveLocale:()=>m,segmentRange:()=>C,segmentStepFor:()=>_,segmentTypesFor:()=>D,segmentValueNow:()=>z,stepSegment:()=>Z,timeRangeViolation:()=>E,timeStepMismatch:()=>J,timeStringToValues:()=>$,to24Hour:()=>p,typeDigit:()=>B,valuesToDate:()=>K,valuesToTimeString:()=>w});module.exports=v(ee);var S={year:"yyyy",month:"mm",day:"dd",hour:"hh",minute:"mm",second:"ss",dayPeriod:"--"},x={year:4,month:2,day:2,hour:2,minute:2,second:2,dayPeriod:0},G={...x,month:1,day:1,hour:1},O=Date.UTC(2024,0,15,13,45,56),f=new Map,g=new Map;function m(e){return e??new Intl.DateTimeFormat().resolvedOptions().locale}function T(e,n){if(n===12||n===24)return n;let t=new Intl.DateTimeFormat(m(e),{hour:"numeric"}).resolvedOptions(),r=t.hourCycle??(t.hour12?"h12":"h23");return r==="h11"||r==="h12"?12:24}function D(e,n){let t=e==="date"?["year","month","day"]:[];return(e==="time"||n!=="day")&&(t.push("hour","minute"),n==="second"&&t.push("second")),t}function P(e,n){return!e||!n?31:new Date(e,n,0).getDate()}function C(e,n,t){switch(e){case"year":return{min:1,max:9999};case"month":return{min:1,max:12};case"day":return{min:1,max:P(n.year,n.month)};case"hour":return t===12?{min:1,max:12}:{min:0,max:23};case"minute":case"second":return{min:0,max:59};case"dayPeriod":return{min:0,max:1}}}function y(e){let n=m(e),t=g.get(n);if(t)return t;let r=new Intl.DateTimeFormat(n,{hour:"numeric",hourCycle:"h12",timeZone:"UTC"}),u=i=>r.formatToParts(Date.UTC(2024,0,15,i)).find(l=>l.type==="dayPeriod")?.value??(i<12?"AM":"PM"),o=[u(1),u(13)];return g.set(n,o),o}function I(e,n){if([...e].length!==1)return null;let t=e.toLowerCase();if(t==="a")return 0;if(t==="p")return 1;let r=y(n),u=l=>{let a=[...l][0];return a!==void 0&&a.localeCompare(e,n,{sensitivity:"base"})===0},o=u(r[0]),i=u(r[1]);return o&&i?null:o?0:i?1:null}function A(e,n){let t={timeZone:"UTC"};return e.includes("year")&&(t.year="numeric"),e.includes("month")&&(t.month="2-digit"),e.includes("day")&&(t.day="2-digit"),e.includes("hour")&&(t.hour="2-digit",t.hourCycle=n===12?"h12":"h23"),e.includes("minute")&&(t.minute="2-digit"),e.includes("second")&&(t.second="2-digit"),t}function L(e,n,t){let r=`${e}|${n.join(",")}|${t}`,u=f.get(r);if(u)return u;let o=new Intl.DateTimeFormat(e,A(n,t)).formatToParts(O),i=[];for(let l of o)l.type==="literal"?i.push({type:"literal",text:l.value.replace(/[\u202F\u2009\u00A0]/g," "),value:null,min:0,max:0,isPlaceholder:!1,isEditable:!1}):(l.type==="dayPeriod"||n.includes(l.type))&&i.push({type:l.type,text:"",value:null,min:0,max:0,isPlaceholder:!0,isEditable:!0});return f.set(r,i),i}function F(e,n,t,r,u=!0){if(n===null)return r?.(e)??S[e];if(e==="dayPeriod")return y(t)[n===0?0:1];let o=u?x:G;return String(n).padStart(o[e],"0")}function U(e){let n=m(e.locale),t=T(n,e.hourCycle),r=D(e.kind,e.granularity);return L(n,r,t).map(u=>{if(!u.isEditable)return u;let o=u.type,i=e.values[o]??null,{min:l,max:a}=C(o,e.values,t);return{type:o,text:F(o,i,n,e.getSegmentPlaceholder,e.shouldForceLeadingZeros??!0),value:i,min:l,max:a,isPlaceholder:i===null,isEditable:!0}})}function Y(e){let n=new Date;switch(e.type){case"year":return n.getFullYear();case"hour":{let t=n.getHours();return e.min===1?t%12===0?12:t%12:t}case"minute":return n.getMinutes();case"second":return n.getSeconds();case"dayPeriod":return n.getHours()<12?0:1;default:return e.min}}function _(e,n,t){let r=n==="second"?"second":"minute",u=n==="second"?1:60;if(e!==r||t===void 0||!Number.isFinite(t)||t<=0||t%u!==0)return 1;let o=t/u;return o<60?o:1}function Z(e,n,t=1){let{min:r,max:u}=e;if(e.value===null)return r+Math.floor((Y(e)-r)/t)*t;let o=Math.floor((u-r)/t)+1,i=e.value-r,l=(n>0?Math.floor(i/t):Math.ceil(i/t))+n;return r+(l%o+o)%o*t}function z(e){return Math.min(Math.max(e.value??e.min,e.min),e.max)}function B(e,n,t){let r=n*10+t;r>e.max&&(r=t);let u=r*10>e.max;return{value:r,buffer:u?0:r,advance:u}}function j(e){return e.every(n=>!n.isEditable||n.value!==null&&n.value>=n.min&&n.value<=n.max)}function p(e,n,t){return t===24?e:e%12+(n===1?12:0)}function h(e,n){return n===24?[e,null]:[e%12===0?12:e%12,e<12?0:1]}function K(e,n){let{year:t,month:r,day:u}=e;if(!t||!r||!u)return null;let o=e.hour==null?0:p(e.hour,e.dayPeriod,n),i=new Date(t,r-1,u,o,e.minute??0,e.second??0,0);return t<100&&i.setFullYear(t),i}function k(e,n){let[t,r]=h(e.getHours(),n);return{year:e.getFullYear(),month:e.getMonth()+1,day:e.getDate(),hour:t,minute:e.getMinutes(),second:e.getSeconds(),dayPeriod:r}}function w(e,n,t){if(e.hour==null||e.minute==null||t===12&&e.dayPeriod==null)return null;let r=i=>String(i).padStart(2,"0"),u=p(e.hour,e.dayPeriod,t),o=`${r(u)}:${r(e.minute)}`;return n!=="second"?o:e.second==null?null:`${o}:${r(e.second)}`}function $(e,n){let t=/^(\d{1,2}):(\d{2})(?::(\d{2}))?$/.exec(e.trim());if(!t)return{};let r=Number(t[1]),u=Number(t[2]),o=t[3]===void 0?0:Number(t[3]);if(r>23||u>59||o>59)return{};let[i,l]=h(r,n);return{hour:i,minute:u,second:o,dayPeriod:l}}function s(e,n){let t=(o,i=2)=>String(o).padStart(i,"0"),r=`${t(e.getFullYear(),4)}-${t(e.getMonth()+1)}-${t(e.getDate())}`;if(n==="day")return r;let u=`${t(e.getHours())}:${t(e.getMinutes())}`;return n==="second"?`${r}T${u}:${t(e.getSeconds())}`:`${r}T${u}`}function q(e){let n=/^(\d{4,})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2})(?::(\d{2}))?)?$/.exec(e.trim());if(!n)return null;let t=Number(n[1]),r=new Date(t,Number(n[2])-1,Number(n[3]),Number(n[4]??0),Number(n[5]??0),Number(n[6]??0));return t<100&&r.setFullYear(t),Number.isNaN(r.getTime())?null:r}function c(e){let n=/^(\d{1,2}):(\d{2})(?::(\d{2}))?$/.exec(e.trim());if(!n)return null;let t=r=>r.padStart(2,"0");return`${t(n[1])}:${n[2]}:${t(n[3]??"00")}`}function E(e,n,t){if(!e)return null;let r=c(e);if(r===null)return null;let u=n?c(n):null;if(u!==null&&r<u)return"underflow";let o=t?c(t):null;return o!==null&&r>o?"overflow":null}function b(e){let n=c(e);if(n===null)return null;let[t,r,u]=n.split(":").map(Number);return t*3600+r*60+u}function J(e,n,t){if(!e||n===void 0||!Number.isFinite(n)||n<=0)return!1;let r=b(e);if(r===null)return!1;let u=(t===void 0?0:b(t))??0;return((r-u)%n+n)%n!==0}function Q(e,n,t,r,u){let o=w(e,n,t),i=E(o,r,u);return i===null?e:{...e,...$(i==="underflow"?r:u,t)}}function W(e,n,t,r){if(!e)return null;let u=s(e,n);return t&&u<s(t,n)?"underflow":r&&u>s(r,n)?"overflow":null}function X(){f.clear(),g.clear()}0&&(module.exports={SEGMENT_PLACEHOLDERS,buildSegments,clampValuesToTimeRange,clearDateSegmentCache,dateRangeViolation,dateToFormValue,dateToValues,dayPeriodFromKey,daysInMonth,formatSegmentText,from24Hour,getDayPeriodNames,isComplete,parseDateFormValue,resolveHourCycle,resolveLocale,segmentRange,segmentStepFor,segmentTypesFor,segmentValueNow,stepSegment,timeRangeViolation,timeStepMismatch,timeStringToValues,to24Hour,typeDigit,valuesToDate,valuesToTimeString});

package/dist/utils/dateSegments.d.cts

@@ -1,24 +1,12 @@
 /**
- * The segment engine behind {@link DateField} and {@link TimeField}: turns a
- * locale plus a granularity into an ordered list of editable segments, and
- * turns keystrokes into new segment values.
- *
- * Built entirely on `Intl.DateTimeFormat.formatToParts` — segment order *and*
- * the literals between segments come from CLDR, so there is no bundled
- * separator table, no locale data and no date library.
- *
- * Every framework package carries its own copy of this module (the same way
- * each carries its own `calendar/locale` and `numberFormat`), because
- * `@skdx/shared` is a dev-only dependency — contracts and test assertions, not
- * runtime code. See `reports/design-system-competitive-audit/RFC-segmented-field.md`.
- *
- * The module is deliberately framework-free and side-effect-free apart from its
- * `Intl` memo caches.
+ * Segment engine for segmented date/time fields: builds editable segments
+ * from locale and granularity via Intl.DateTimeFormat.formatToParts.
+ * Framework-free except for Intl memo caches.
  */
 /** One editable piece of a segmented date/time value. */
 export type SegmentType = 'year' | 'month' | 'day' | 'hour' | 'minute' | 'second' | 'dayPeriod';
-/** How far down a segmented field is editable. Ordered coarse → fine. */
-export type Granularity = 'day' | 'hour' | 'minute' | 'second';
+/** How far down a segmented field is editable (no 'hour': would duplicate 'minute'). */
+export type Granularity = 'day' | 'minute' | 'second';
 /** Whether hours read `1`–`12` (with an AM/PM segment) or `0`–`23`. */
 export type HourCycle = 12 | 24;
 /** Current numeric value of each editable segment; `null` means "not typed yet". */
@@ -40,7 +28,7 @@ export interface Segment {
     /** `false` only for literals. */
     isEditable: boolean;
 }
-/** Placeholder text shown before a segment has been typed. */
+/** Default placeholder text; unreachable by Intl and untranslatable by locale. */
 export declare const SEGMENT_PLACEHOLDERS: Record<SegmentType, string>;
 /** The runtime's own locale, used whenever `locale` is omitted — matches `calendar/locale`'s `resolveLocale`. */
 export declare function resolveLocale(locale?: string): string;
@@ -76,8 +64,21 @@ export declare function segmentRange(type: SegmentType, values: SegmentValues, h
 };
 /** The locale's AM and PM names, e.g. `['AM', 'PM']` or `['vorm.', 'nachm.']`. */
 export declare function getDayPeriodNames(locale?: string): [string, string];
-/** How a segment renders: zero-padded digits, the locale's AM/PM name, or the placeholder. */
-export declare function formatSegmentText(type: SegmentType, value: number | null, locale?: string): string;
+/** Converts a keystroke to day period index (0 AM, 1 PM, null if neither). */
+export declare function dayPeriodFromKey(key: string, locale?: string): number | null;
+/**
+ * Words the placeholder of one segment type. Return the built-in
+ * {@link SEGMENT_PLACEHOLDERS} entry for the types you do not want to change.
+ */
+export type SegmentPlaceholderResolver = (type: SegmentType) => string;
+/**
+ * How a segment renders: zero-padded digits, the locale's AM/PM name, or the
+ * placeholder.
+ *
+ * @param shouldForceLeadingZeros `false` renders a one-digit month, day or hour
+ * bare — see {@link SEGMENT_PAD_UNFORCED} for why those three and no others.
+ */
+export declare function formatSegmentText(type: SegmentType, value: number | null, locale?: string, getSegmentPlaceholder?: SegmentPlaceholderResolver, shouldForceLeadingZeros?: boolean): string;
 /** Options for {@link buildSegments}. */
 export interface BuildSegmentsOptions {
     /** `'date'` adds year/month/day ahead of the time segments. */
@@ -90,6 +91,14 @@ export interface BuildSegmentsOptions {
     hourCycle?: HourCycle;
     /** Current per-segment values. */
     values: SegmentValues;
+    /** Words each segment's placeholder; omitted keeps the built-in English letters. */
+    getSegmentPlaceholder?: SegmentPlaceholderResolver;
+    /**
+     * Whether a one-digit month, day or hour renders zero-padded (`05`) or bare
+     * (`5`). Never touches `year`, `minute` or `second`.
+     * @default true
+     */
+    shouldForceLeadingZeros?: boolean;
 }
 /**
  * The full ordered render list for a segmented field — editable segments
@@ -103,12 +112,40 @@ export interface BuildSegmentsOptions {
  * ```
  */
 export declare function buildSegments(options: BuildSegmentsOptions): Segment[];
+/**
+ * How many units one Arrow press moves a segment, given the field-level `step`
+ * in seconds; drives only the finest rendered segment, like `<input
+ * type="time" step>` does. Falls back to `1` when `step` isn't a whole number
+ * of the segment's unit, or isn't smaller than the segment's 60-value range.
+ *
+ * @example
+ * ```ts
+ * segmentStepFor('minute', 'minute', 900); // 15
+ * segmentStepFor('hour', 'minute', 900); // 1 — only the finest segment steps
+ * ```
+ */
+export declare function segmentStepFor(type: SegmentType, granularity: Granularity, step?: number): number;
 /**
  * Steps one segment by `delta`, wrapping around its range (Arrow Up on `12:59`
- * minutes gives `12:00`, not `12:59`). An untyped segment starts at `min`,
- * except `year`, which starts at the current year rather than year 1.
+ * minutes gives `12:00`). An untyped segment starts from
+ * {@link untypedSegmentStart} rather than from `delta` applied to nothing.
+ *
+ * With a `step` past 1, the segment only lands on the grid `min`, `min +
+ * step`, … at or below `max`, wrapping off its last grid point back to `min`.
+ * A value already off the grid snaps to the next grid point in the direction
+ * pressed, like a native stepper.
+ *
+ * @param step the segment's own step, from {@link segmentStepFor}
  */
-export declare function stepSegment(segment: Segment, delta: number): number;
+export declare function stepSegment(segment: Segment, delta: number, step?: number): number;
+/**
+ * The `aria-valuenow` a segment publishes: its current value pulled back
+ * inside its own `aria-valuemin`/`aria-valuemax`. Mid-entry a segment can
+ * legitimately sit below its minimum (typing `0` into the month segment); the
+ * raw digits still reach the user via `aria-valuetext`, which a spinbutton
+ * announces in preference to the number.
+ */
+export declare function segmentValueNow(segment: Segment): number;
 /** The result of typing one digit into a segment. */
 export interface DigitEntry {
     /** The segment's new value. May be below `min` mid-entry (typing `0` then `5` into a month). */
@@ -119,10 +156,10 @@ export interface DigitEntry {
     advance: boolean;
 }
 /**
- * Types one digit into a segment, with React Aria's roll-over behaviour: a
- * keystroke that would overflow the segment restarts entry at that digit
- * instead of being rejected, and focus advances as soon as no further digit
- * could fit.
+ * Types one digit into a segment: a keystroke that would overflow the segment
+ * restarts entry at that digit instead of being rejected, and focus advances
+ * once no further digit could fit. Stated here and pinned by tests, since no
+ * external source specifies this per-segment behaviour precisely enough to check against.
  *
  * @param segment the segment being typed into
  * @param buffer what has been typed into it so far (`0` when entry just started)
@@ -142,9 +179,9 @@ export declare function to24Hour(hour: number, dayPeriod: number | null | undefi
 /** Converts a 0-23 hour into the `[hour, dayPeriod]` pair the given cycle renders. */
 export declare function from24Hour(hour: number, hourCycle: HourCycle): [number, number | null];
 /**
- * The `Date` these segment values describe, in local time, or `null` while any
- * date segment is still untyped. Time segments the field does not own default
- * to `0`, exactly like `<input type="date">`.
+ * The `Date` these segment values describe, in local time, or `null` while
+ * any date segment is still untyped; unowned time segments default to `0`,
+ * like `<input type="date">`.
  */
 export declare function valuesToDate(values: SegmentValues, hourCycle: HourCycle): Date | null;
 /** Splits a `Date` back into segment values for the given hour cycle. */
@@ -159,5 +196,49 @@ export declare function valuesToTimeString(values: SegmentValues, granularity: G
 export declare function timeStringToValues(time: string, hourCycle: HourCycle): SegmentValues;
 /** The `YYYY-MM-DD` / `YYYY-MM-DDTHH:mm[:ss]` string a segmented date field submits. */
 export declare function dateToFormValue(date: Date, granularity: Granularity): string;
+/**
+ * The inverse of {@link dateToFormValue}: reads a `YYYY-MM-DD` or
+ * `YYYY-MM-DDTHH:mm[:ss]` string back into a local `Date`. Built field by
+ * field rather than handed to `new Date(string)`, which reads a bare
+ * `YYYY-MM-DD` as UTC midnight — the previous day west of Greenwich.
+ *
+ * @param value a string in the shape {@link dateToFormValue} produces
+ * @returns the local date, or `null` when the string is not one of those shapes
+ */
+export declare function parseDateFormValue(value: string): Date | null;
+/** Which side of a `min`/`max` bound a value falls outside, or `null` when it is in range. */
+export type RangeViolation = 'underflow' | 'overflow';
+/**
+ * Whether a `HH:mm[:ss]` time falls outside `min`/`max`, compared as strings
+ * (24-hour times sort chronologically when zero-padded).
+ *
+ * @param value the field's current wire value, or `null` while incomplete
+ * @param min the earliest accepted time, `HH:mm[:ss]`
+ * @param max the latest accepted time, `HH:mm[:ss]`
+ * @returns which bound was crossed, or `null` when in range
+ */
+export declare function timeRangeViolation(value: string | null | undefined, min?: string, max?: string): RangeViolation | null;
+/**
+ * Whether an `HH:mm[:ss]` time misses the `step` grid — the `stepMismatch`
+ * `<input type="time" step>` raises. Step counts seconds, anchored on `min` or midnight.
+ * (The other four ports mirror `step` to a hidden input; this one computes it directly.)
+ *
+ * @param value the field's current wire value, or `null` while incomplete
+ * @param step the field's step in seconds; non-positive or non-finite is no constraint
+ * @param min the step base — the same `min` the range check uses
+ */
+export declare function timeStepMismatch(value: string | null | undefined, step?: number, min?: string): boolean;
+/**
+ * Pulls segment values inside `min`/`max` bounds (Home/End only).
+ * Arrow-stepping and typing deliberately do not clamp so out-of-bounds
+ * values stay reachable for validation.
+ */
+export declare function clampValuesToTimeRange(values: SegmentValues, granularity: Granularity, hourCycle: HourCycle, min?: string, max?: string): SegmentValues;
+/**
+ * Whether a `Date` falls outside `minDate`/`maxDate`, compared at the field's
+ * `granularity` (a `day` field ignores time of day). String-compared via
+ * {@link dateToFormValue} to match the native input's behavior.
+ */
+export declare function dateRangeViolation(value: Date | null | undefined, granularity: Granularity, minDate?: Date, maxDate?: Date): RangeViolation | null;
 /** @internal Drops every memoized `Intl` result. Only needed by tests that switch locales in one process. */
 export declare function clearDateSegmentCache(): void;

package/dist/utils/dateSegments.d.ts

@@ -1,24 +1,12 @@
 /**
- * The segment engine behind {@link DateField} and {@link TimeField}: turns a
- * locale plus a granularity into an ordered list of editable segments, and
- * turns keystrokes into new segment values.
- *
- * Built entirely on `Intl.DateTimeFormat.formatToParts` — segment order *and*
- * the literals between segments come from CLDR, so there is no bundled
- * separator table, no locale data and no date library.
- *
- * Every framework package carries its own copy of this module (the same way
- * each carries its own `calendar/locale` and `numberFormat`), because
- * `@skdx/shared` is a dev-only dependency — contracts and test assertions, not
- * runtime code. See `reports/design-system-competitive-audit/RFC-segmented-field.md`.
- *
- * The module is deliberately framework-free and side-effect-free apart from its
- * `Intl` memo caches.
+ * Segment engine for segmented date/time fields: builds editable segments
+ * from locale and granularity via Intl.DateTimeFormat.formatToParts.
+ * Framework-free except for Intl memo caches.
  */
 /** One editable piece of a segmented date/time value. */
 export type SegmentType = 'year' | 'month' | 'day' | 'hour' | 'minute' | 'second' | 'dayPeriod';
-/** How far down a segmented field is editable. Ordered coarse → fine. */
-export type Granularity = 'day' | 'hour' | 'minute' | 'second';
+/** How far down a segmented field is editable (no 'hour': would duplicate 'minute'). */
+export type Granularity = 'day' | 'minute' | 'second';
 /** Whether hours read `1`–`12` (with an AM/PM segment) or `0`–`23`. */
 export type HourCycle = 12 | 24;
 /** Current numeric value of each editable segment; `null` means "not typed yet". */
@@ -40,7 +28,7 @@ export interface Segment {
     /** `false` only for literals. */
     isEditable: boolean;
 }
-/** Placeholder text shown before a segment has been typed. */
+/** Default placeholder text; unreachable by Intl and untranslatable by locale. */
 export declare const SEGMENT_PLACEHOLDERS: Record<SegmentType, string>;
 /** The runtime's own locale, used whenever `locale` is omitted — matches `calendar/locale`'s `resolveLocale`. */
 export declare function resolveLocale(locale?: string): string;
@@ -76,8 +64,21 @@ export declare function segmentRange(type: SegmentType, values: SegmentValues, h
 };
 /** The locale's AM and PM names, e.g. `['AM', 'PM']` or `['vorm.', 'nachm.']`. */
 export declare function getDayPeriodNames(locale?: string): [string, string];
-/** How a segment renders: zero-padded digits, the locale's AM/PM name, or the placeholder. */
-export declare function formatSegmentText(type: SegmentType, value: number | null, locale?: string): string;
+/** Converts a keystroke to day period index (0 AM, 1 PM, null if neither). */
+export declare function dayPeriodFromKey(key: string, locale?: string): number | null;
+/**
+ * Words the placeholder of one segment type. Return the built-in
+ * {@link SEGMENT_PLACEHOLDERS} entry for the types you do not want to change.
+ */
+export type SegmentPlaceholderResolver = (type: SegmentType) => string;
+/**
+ * How a segment renders: zero-padded digits, the locale's AM/PM name, or the
+ * placeholder.
+ *
+ * @param shouldForceLeadingZeros `false` renders a one-digit month, day or hour
+ * bare — see {@link SEGMENT_PAD_UNFORCED} for why those three and no others.
+ */
+export declare function formatSegmentText(type: SegmentType, value: number | null, locale?: string, getSegmentPlaceholder?: SegmentPlaceholderResolver, shouldForceLeadingZeros?: boolean): string;
 /** Options for {@link buildSegments}. */
 export interface BuildSegmentsOptions {
     /** `'date'` adds year/month/day ahead of the time segments. */
@@ -90,6 +91,14 @@ export interface BuildSegmentsOptions {
     hourCycle?: HourCycle;
     /** Current per-segment values. */
     values: SegmentValues;
+    /** Words each segment's placeholder; omitted keeps the built-in English letters. */
+    getSegmentPlaceholder?: SegmentPlaceholderResolver;
+    /**
+     * Whether a one-digit month, day or hour renders zero-padded (`05`) or bare
+     * (`5`). Never touches `year`, `minute` or `second`.
+     * @default true
+     */
+    shouldForceLeadingZeros?: boolean;
 }
 /**
  * The full ordered render list for a segmented field — editable segments
@@ -103,12 +112,40 @@ export interface BuildSegmentsOptions {
  * ```
  */
 export declare function buildSegments(options: BuildSegmentsOptions): Segment[];
+/**
+ * How many units one Arrow press moves a segment, given the field-level `step`
+ * in seconds; drives only the finest rendered segment, like `<input
+ * type="time" step>` does. Falls back to `1` when `step` isn't a whole number
+ * of the segment's unit, or isn't smaller than the segment's 60-value range.
+ *
+ * @example
+ * ```ts
+ * segmentStepFor('minute', 'minute', 900); // 15
+ * segmentStepFor('hour', 'minute', 900); // 1 — only the finest segment steps
+ * ```
+ */
+export declare function segmentStepFor(type: SegmentType, granularity: Granularity, step?: number): number;
 /**
  * Steps one segment by `delta`, wrapping around its range (Arrow Up on `12:59`
- * minutes gives `12:00`, not `12:59`). An untyped segment starts at `min`,
- * except `year`, which starts at the current year rather than year 1.
+ * minutes gives `12:00`). An untyped segment starts from
+ * {@link untypedSegmentStart} rather than from `delta` applied to nothing.
+ *
+ * With a `step` past 1, the segment only lands on the grid `min`, `min +
+ * step`, … at or below `max`, wrapping off its last grid point back to `min`.
+ * A value already off the grid snaps to the next grid point in the direction
+ * pressed, like a native stepper.
+ *
+ * @param step the segment's own step, from {@link segmentStepFor}
  */
-export declare function stepSegment(segment: Segment, delta: number): number;
+export declare function stepSegment(segment: Segment, delta: number, step?: number): number;
+/**
+ * The `aria-valuenow` a segment publishes: its current value pulled back
+ * inside its own `aria-valuemin`/`aria-valuemax`. Mid-entry a segment can
+ * legitimately sit below its minimum (typing `0` into the month segment); the
+ * raw digits still reach the user via `aria-valuetext`, which a spinbutton
+ * announces in preference to the number.
+ */
+export declare function segmentValueNow(segment: Segment): number;
 /** The result of typing one digit into a segment. */
 export interface DigitEntry {
     /** The segment's new value. May be below `min` mid-entry (typing `0` then `5` into a month). */
@@ -119,10 +156,10 @@ export interface DigitEntry {
     advance: boolean;
 }
 /**
- * Types one digit into a segment, with React Aria's roll-over behaviour: a
- * keystroke that would overflow the segment restarts entry at that digit
- * instead of being rejected, and focus advances as soon as no further digit
- * could fit.
+ * Types one digit into a segment: a keystroke that would overflow the segment
+ * restarts entry at that digit instead of being rejected, and focus advances
+ * once no further digit could fit. Stated here and pinned by tests, since no
+ * external source specifies this per-segment behaviour precisely enough to check against.
  *
  * @param segment the segment being typed into
  * @param buffer what has been typed into it so far (`0` when entry just started)
@@ -142,9 +179,9 @@ export declare function to24Hour(hour: number, dayPeriod: number | null | undefi
 /** Converts a 0-23 hour into the `[hour, dayPeriod]` pair the given cycle renders. */
 export declare function from24Hour(hour: number, hourCycle: HourCycle): [number, number | null];
 /**
- * The `Date` these segment values describe, in local time, or `null` while any
- * date segment is still untyped. Time segments the field does not own default
- * to `0`, exactly like `<input type="date">`.
+ * The `Date` these segment values describe, in local time, or `null` while
+ * any date segment is still untyped; unowned time segments default to `0`,
+ * like `<input type="date">`.
  */
 export declare function valuesToDate(values: SegmentValues, hourCycle: HourCycle): Date | null;
 /** Splits a `Date` back into segment values for the given hour cycle. */
@@ -159,5 +196,49 @@ export declare function valuesToTimeString(values: SegmentValues, granularity: G
 export declare function timeStringToValues(time: string, hourCycle: HourCycle): SegmentValues;
 /** The `YYYY-MM-DD` / `YYYY-MM-DDTHH:mm[:ss]` string a segmented date field submits. */
 export declare function dateToFormValue(date: Date, granularity: Granularity): string;
+/**
+ * The inverse of {@link dateToFormValue}: reads a `YYYY-MM-DD` or
+ * `YYYY-MM-DDTHH:mm[:ss]` string back into a local `Date`. Built field by
+ * field rather than handed to `new Date(string)`, which reads a bare
+ * `YYYY-MM-DD` as UTC midnight — the previous day west of Greenwich.
+ *
+ * @param value a string in the shape {@link dateToFormValue} produces
+ * @returns the local date, or `null` when the string is not one of those shapes
+ */
+export declare function parseDateFormValue(value: string): Date | null;
+/** Which side of a `min`/`max` bound a value falls outside, or `null` when it is in range. */
+export type RangeViolation = 'underflow' | 'overflow';
+/**
+ * Whether a `HH:mm[:ss]` time falls outside `min`/`max`, compared as strings
+ * (24-hour times sort chronologically when zero-padded).
+ *
+ * @param value the field's current wire value, or `null` while incomplete
+ * @param min the earliest accepted time, `HH:mm[:ss]`
+ * @param max the latest accepted time, `HH:mm[:ss]`
+ * @returns which bound was crossed, or `null` when in range
+ */
+export declare function timeRangeViolation(value: string | null | undefined, min?: string, max?: string): RangeViolation | null;
+/**
+ * Whether an `HH:mm[:ss]` time misses the `step` grid — the `stepMismatch`
+ * `<input type="time" step>` raises. Step counts seconds, anchored on `min` or midnight.
+ * (The other four ports mirror `step` to a hidden input; this one computes it directly.)
+ *
+ * @param value the field's current wire value, or `null` while incomplete
+ * @param step the field's step in seconds; non-positive or non-finite is no constraint
+ * @param min the step base — the same `min` the range check uses
+ */
+export declare function timeStepMismatch(value: string | null | undefined, step?: number, min?: string): boolean;
+/**
+ * Pulls segment values inside `min`/`max` bounds (Home/End only).
+ * Arrow-stepping and typing deliberately do not clamp so out-of-bounds
+ * values stay reachable for validation.
+ */
+export declare function clampValuesToTimeRange(values: SegmentValues, granularity: Granularity, hourCycle: HourCycle, min?: string, max?: string): SegmentValues;
+/**
+ * Whether a `Date` falls outside `minDate`/`maxDate`, compared at the field's
+ * `granularity` (a `day` field ignores time of day). String-compared via
+ * {@link dateToFormValue} to match the native input's behavior.
+ */
+export declare function dateRangeViolation(value: Date | null | undefined, granularity: Granularity, minDate?: Date, maxDate?: Date): RangeViolation | null;
 /** @internal Drops every memoized `Intl` result. Only needed by tests that switch locales in one process. */
 export declare function clearDateSegmentCache(): void;

package/dist/utils/dateSegments.js

@@ -1 +1 @@
-var g={year:"yyyy",month:"mm",day:"dd",hour:"hh",minute:"mm",second:"ss",dayPeriod:"--"},f={year:4,month:2,day:2,hour:2,minute:2,second:2,dayPeriod:0},p=Date.UTC(2024,0,15,13,45,56),l=new Map,m=new Map;function c(e){return e??new Intl.DateTimeFormat().resolvedOptions().locale}function h(e,t){if(t===12||t===24)return t;let n=new Intl.DateTimeFormat(c(e),{hour:"numeric"}).resolvedOptions(),r=n.hourCycle??(n.hour12?"h12":"h23");return r==="h11"||r==="h12"?12:24}function x(e,t){let n=e==="date"?["year","month","day"]:[];return(e==="time"||t!=="day")&&(n.push("hour","minute"),t==="second"&&n.push("second")),n}function S(e,t){return!e||!t?31:new Date(e,t,0).getDate()}function b(e,t,n){switch(e){case"year":return{min:1,max:9999};case"month":return{min:1,max:12};case"day":return{min:1,max:S(t.year,t.month)};case"hour":return n===12?{min:1,max:12}:{min:0,max:23};case"minute":case"second":return{min:0,max:59};case"dayPeriod":return{min:0,max:1}}}function T(e){let t=c(e),n=m.get(t);if(n)return n;let r=new Intl.DateTimeFormat(t,{hour:"numeric",hourCycle:"h12",timeZone:"UTC"}),o=u=>r.formatToParts(Date.UTC(2024,0,15,u)).find(a=>a.type==="dayPeriod")?.value??(u<12?"AM":"PM"),i=[o(1),o(13)];return m.set(t,i),i}function C(e,t){let n={timeZone:"UTC"};return e.includes("year")&&(n.year="numeric"),e.includes("month")&&(n.month="2-digit"),e.includes("day")&&(n.day="2-digit"),e.includes("hour")&&(n.hour="2-digit",n.hourCycle=t===12?"h12":"h23"),e.includes("minute")&&(n.minute="2-digit"),e.includes("second")&&(n.second="2-digit"),n}function D(e,t,n){let r=`${e}|${t.join(",")}|${n}`,o=l.get(r);if(o)return o;let i=new Intl.DateTimeFormat(e,C(t,n)).formatToParts(p),u=[];for(let a of i)a.type==="literal"?u.push({type:"literal",text:a.value.replace(/[\u202F\u2009\u00A0]/g," "),value:null,min:0,max:0,isPlaceholder:!1,isEditable:!1}):(a.type==="dayPeriod"||t.includes(a.type))&&u.push({type:a.type,text:"",value:null,min:0,max:0,isPlaceholder:!0,isEditable:!0});return l.set(r,u),u}function P(e,t,n){return t===null?g[e]:e==="dayPeriod"?T(n)[t===0?0:1]:String(t).padStart(f[e],"0")}function E(e){let t=c(e.locale),n=h(t,e.hourCycle),r=x(e.kind,e.granularity);return D(t,r,n).map(o=>{if(!o.isEditable)return o;let i=o.type,u=e.values[i]??null,{min:a,max:y}=b(i,e.values,n);return{type:i,text:P(i,u,t),value:u,min:a,max:y,isPlaceholder:u===null,isEditable:!0}})}function H(e,t){let{min:n,max:r}=e;if(e.value===null)return e.type==="year"?new Date().getFullYear():n;let o=r-n+1;return n+((e.value-n+t)%o+o)%o}function $(e,t,n){let r=t*10+n;r>e.max&&(r=n);let o=r*10>e.max;return{value:r,buffer:o?0:r,advance:o}}function F(e){return e.every(t=>!t.isEditable||t.value!==null&&t.value>=t.min&&t.value<=t.max)}function s(e,t,n){return n===24?e:e%12+(t===1?12:0)}function d(e,t){return t===24?[e,null]:[e%12===0?12:e%12,e<12?0:1]}function v(e,t){let{year:n,month:r,day:o}=e;if(!n||!r||!o)return null;let i=e.hour==null?0:s(e.hour,e.dayPeriod,t),u=new Date(n,r-1,o,i,e.minute??0,e.second??0,0);return n<100&&u.setFullYear(n),u}function M(e,t){let[n,r]=d(e.getHours(),t);return{year:e.getFullYear(),month:e.getMonth()+1,day:e.getDate(),hour:n,minute:e.getMinutes(),second:e.getSeconds(),dayPeriod:r}}function O(e,t,n){if(e.hour==null||e.minute==null||n===12&&e.dayPeriod==null)return null;let r=u=>String(u).padStart(2,"0"),o=s(e.hour,e.dayPeriod,n),i=`${r(o)}:${r(e.minute)}`;return t!=="second"?i:e.second==null?null:`${i}:${r(e.second)}`}function w(e,t){let n=/^(\d{1,2}):(\d{2})(?::(\d{2}))?$/.exec(e.trim());if(!n)return{};let r=Number(n[1]),o=Number(n[2]),i=n[3]===void 0?0:Number(n[3]);if(r>23||o>59||i>59)return{};let[u,a]=d(r,t);return{hour:u,minute:o,second:i,dayPeriod:a}}function R(e,t){let n=(i,u=2)=>String(i).padStart(u,"0"),r=`${n(e.getFullYear(),4)}-${n(e.getMonth()+1)}-${n(e.getDate())}`;if(t==="day")return r;let o=`${n(e.getHours())}:${n(e.getMinutes())}`;return t==="second"?`${r}T${o}:${n(e.getSeconds())}`:`${r}T${o}`}function V(){l.clear(),m.clear()}export{g as SEGMENT_PLACEHOLDERS,E as buildSegments,V as clearDateSegmentCache,R as dateToFormValue,M as dateToValues,S as daysInMonth,P as formatSegmentText,d as from24Hour,T as getDayPeriodNames,F as isComplete,h as resolveHourCycle,c as resolveLocale,b as segmentRange,x as segmentTypesFor,H as stepSegment,w as timeStringToValues,s as to24Hour,$ as typeDigit,v as valuesToDate,O as valuesToTimeString};
+var S={year:"yyyy",month:"mm",day:"dd",hour:"hh",minute:"mm",second:"ss",dayPeriod:"--"},y={year:4,month:2,day:2,hour:2,minute:2,second:2,dayPeriod:0},x={...y,month:1,day:1,hour:1},T=Date.UTC(2024,0,15,13,45,56),m=new Map,d=new Map;function f(e){return e??new Intl.DateTimeFormat().resolvedOptions().locale}function D(e,n){if(n===12||n===24)return n;let t=new Intl.DateTimeFormat(f(e),{hour:"numeric"}).resolvedOptions(),r=t.hourCycle??(t.hour12?"h12":"h23");return r==="h11"||r==="h12"?12:24}function P(e,n){let t=e==="date"?["year","month","day"]:[];return(e==="time"||n!=="day")&&(t.push("hour","minute"),n==="second"&&t.push("second")),t}function C(e,n){return!e||!n?31:new Date(e,n,0).getDate()}function F(e,n,t){switch(e){case"year":return{min:1,max:9999};case"month":return{min:1,max:12};case"day":return{min:1,max:C(n.year,n.month)};case"hour":return t===12?{min:1,max:12}:{min:0,max:23};case"minute":case"second":return{min:0,max:59};case"dayPeriod":return{min:0,max:1}}}function p(e){let n=f(e),t=d.get(n);if(t)return t;let r=new Intl.DateTimeFormat(n,{hour:"numeric",hourCycle:"h12",timeZone:"UTC"}),u=i=>r.formatToParts(Date.UTC(2024,0,15,i)).find(l=>l.type==="dayPeriod")?.value??(i<12?"AM":"PM"),o=[u(1),u(13)];return d.set(n,o),o}function V(e,n){if([...e].length!==1)return null;let t=e.toLowerCase();if(t==="a")return 0;if(t==="p")return 1;let r=p(n),u=l=>{let a=[...l][0];return a!==void 0&&a.localeCompare(e,n,{sensitivity:"base"})===0},o=u(r[0]),i=u(r[1]);return o&&i?null:o?0:i?1:null}function w(e,n){let t={timeZone:"UTC"};return e.includes("year")&&(t.year="numeric"),e.includes("month")&&(t.month="2-digit"),e.includes("day")&&(t.day="2-digit"),e.includes("hour")&&(t.hour="2-digit",t.hourCycle=n===12?"h12":"h23"),e.includes("minute")&&(t.minute="2-digit"),e.includes("second")&&(t.second="2-digit"),t}function $(e,n,t){let r=`${e}|${n.join(",")}|${t}`,u=m.get(r);if(u)return u;let o=new Intl.DateTimeFormat(e,w(n,t)).formatToParts(T),i=[];for(let l of o)l.type==="literal"?i.push({type:"literal",text:l.value.replace(/[\u202F\u2009\u00A0]/g," "),value:null,min:0,max:0,isPlaceholder:!1,isEditable:!1}):(l.type==="dayPeriod"||n.includes(l.type))&&i.push({type:l.type,text:"",value:null,min:0,max:0,isPlaceholder:!0,isEditable:!0});return m.set(r,i),i}function E(e,n,t,r,u=!0){if(n===null)return r?.(e)??S[e];if(e==="dayPeriod")return p(t)[n===0?0:1];let o=u?y:x;return String(n).padStart(o[e],"0")}function v(e){let n=f(e.locale),t=D(n,e.hourCycle),r=P(e.kind,e.granularity);return $(n,r,t).map(u=>{if(!u.isEditable)return u;let o=u.type,i=e.values[o]??null,{min:l,max:a}=F(o,e.values,t);return{type:o,text:E(o,i,n,e.getSegmentPlaceholder,e.shouldForceLeadingZeros??!0),value:i,min:l,max:a,isPlaceholder:i===null,isEditable:!0}})}function H(e){let n=new Date;switch(e.type){case"year":return n.getFullYear();case"hour":{let t=n.getHours();return e.min===1?t%12===0?12:t%12:t}case"minute":return n.getMinutes();case"second":return n.getSeconds();case"dayPeriod":return n.getHours()<12?0:1;default:return e.min}}function G(e,n,t){let r=n==="second"?"second":"minute",u=n==="second"?1:60;if(e!==r||t===void 0||!Number.isFinite(t)||t<=0||t%u!==0)return 1;let o=t/u;return o<60?o:1}function O(e,n,t=1){let{min:r,max:u}=e;if(e.value===null)return r+Math.floor((H(e)-r)/t)*t;let o=Math.floor((u-r)/t)+1,i=e.value-r,l=(n>0?Math.floor(i/t):Math.ceil(i/t))+n;return r+(l%o+o)%o*t}function I(e){return Math.min(Math.max(e.value??e.min,e.min),e.max)}function A(e,n,t){let r=n*10+t;r>e.max&&(r=t);let u=r*10>e.max;return{value:r,buffer:u?0:r,advance:u}}function L(e){return e.every(n=>!n.isEditable||n.value!==null&&n.value>=n.min&&n.value<=n.max)}function h(e,n,t){return t===24?e:e%12+(n===1?12:0)}function b(e,n){return n===24?[e,null]:[e%12===0?12:e%12,e<12?0:1]}function U(e,n){let{year:t,month:r,day:u}=e;if(!t||!r||!u)return null;let o=e.hour==null?0:h(e.hour,e.dayPeriod,n),i=new Date(t,r-1,u,o,e.minute??0,e.second??0,0);return t<100&&i.setFullYear(t),i}function Y(e,n){let[t,r]=b(e.getHours(),n);return{year:e.getFullYear(),month:e.getMonth()+1,day:e.getDate(),hour:t,minute:e.getMinutes(),second:e.getSeconds(),dayPeriod:r}}function N(e,n,t){if(e.hour==null||e.minute==null||t===12&&e.dayPeriod==null)return null;let r=i=>String(i).padStart(2,"0"),u=h(e.hour,e.dayPeriod,t),o=`${r(u)}:${r(e.minute)}`;return n!=="second"?o:e.second==null?null:`${o}:${r(e.second)}`}function M(e,n){let t=/^(\d{1,2}):(\d{2})(?::(\d{2}))?$/.exec(e.trim());if(!t)return{};let r=Number(t[1]),u=Number(t[2]),o=t[3]===void 0?0:Number(t[3]);if(r>23||u>59||o>59)return{};let[i,l]=b(r,n);return{hour:i,minute:u,second:o,dayPeriod:l}}function c(e,n){let t=(o,i=2)=>String(o).padStart(i,"0"),r=`${t(e.getFullYear(),4)}-${t(e.getMonth()+1)}-${t(e.getDate())}`;if(n==="day")return r;let u=`${t(e.getHours())}:${t(e.getMinutes())}`;return n==="second"?`${r}T${u}:${t(e.getSeconds())}`:`${r}T${u}`}function _(e){let n=/^(\d{4,})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2})(?::(\d{2}))?)?$/.exec(e.trim());if(!n)return null;let t=Number(n[1]),r=new Date(t,Number(n[2])-1,Number(n[3]),Number(n[4]??0),Number(n[5]??0),Number(n[6]??0));return t<100&&r.setFullYear(t),Number.isNaN(r.getTime())?null:r}function s(e){let n=/^(\d{1,2}):(\d{2})(?::(\d{2}))?$/.exec(e.trim());if(!n)return null;let t=r=>r.padStart(2,"0");return`${t(n[1])}:${n[2]}:${t(n[3]??"00")}`}function R(e,n,t){if(!e)return null;let r=s(e);if(r===null)return null;let u=n?s(n):null;if(u!==null&&r<u)return"underflow";let o=t?s(t):null;return o!==null&&r>o?"overflow":null}function g(e){let n=s(e);if(n===null)return null;let[t,r,u]=n.split(":").map(Number);return t*3600+r*60+u}function Z(e,n,t){if(!e||n===void 0||!Number.isFinite(n)||n<=0)return!1;let r=g(e);if(r===null)return!1;let u=(t===void 0?0:g(t))??0;return((r-u)%n+n)%n!==0}function z(e,n,t,r,u){let o=N(e,n,t),i=R(o,r,u);return i===null?e:{...e,...M(i==="underflow"?r:u,t)}}function B(e,n,t,r){if(!e)return null;let u=c(e,n);return t&&u<c(t,n)?"underflow":r&&u>c(r,n)?"overflow":null}function j(){m.clear(),d.clear()}export{S as SEGMENT_PLACEHOLDERS,v as buildSegments,z as clampValuesToTimeRange,j as clearDateSegmentCache,B as dateRangeViolation,c as dateToFormValue,Y as dateToValues,V as dayPeriodFromKey,C as daysInMonth,E as formatSegmentText,b as from24Hour,p as getDayPeriodNames,L as isComplete,_ as parseDateFormValue,D as resolveHourCycle,f as resolveLocale,F as segmentRange,G as segmentStepFor,P as segmentTypesFor,I as segmentValueNow,O as stepSegment,R as timeRangeViolation,Z as timeStepMismatch,M as timeStringToValues,h as to24Hour,A as typeDigit,U as valuesToDate,N as valuesToTimeString};

package/dist/utils/dateValue.cjs

@@ -0,0 +1 @@
+"use strict";var f=Object.defineProperty;var p=Object.getOwnPropertyDescriptor;var y=Object.getOwnPropertyNames;var N=Object.prototype.hasOwnProperty;var h=(e,t)=>{for(var n in t)f(e,n,{get:t[n],enumerable:!0})},x=(e,t,n,r)=>{if(t&&typeof t=="object"||typeof t=="function")for(let a of y(t))!N.call(e,a)&&a!==n&&f(e,a,{get:()=>t[a],enumerable:!(r=p(t,a))||r.enumerable});return e};var M=e=>x(f({},"__esModule",{value:!0}),e);var L={};h(L,{resetMalformedDateWarning:()=>b,toCalendarString:()=>$,toCalendarValue:()=>A,toDate:()=>u,toISODateValue:()=>o,toTimeValue:()=>V});module.exports=M(L);var d=require("./dateSegments.cjs"),g=require("./is-dev-mode.cjs"),I=/^(\d{4,})-(\d{2})$/,Y=/^(\d{4,}-\d{2}-\d{2})/,c=!1;function b(){c=!1}function m(e,t){c||(c=!0,(0,g.isDevMode)()&&console.warn(`[skdx] ${t?`\`${t}\``:"A date property"} was given ${JSON.stringify(e)}, which is not an ISO-8601 date. Expected \`YYYY-MM-DD\`, \`YYYY-MM-DDTHH:mm[:ss]\`, or a bare \`YYYY-MM\` for a month. The value is ignored \u2014 the property behaves as if it had not been supplied \u2014 rather than being coerced to today, to the epoch, or to an \`Invalid Date\` that would then poison every comparison after it.`))}function u(e,t){if(e==null)return null;if(e instanceof Date)return Number.isNaN(e.getTime())?null:e;if(typeof e!="string")return null;let n=e.trim();if(n==="")return null;let r=(0,d.parseDateFormValue)(n);if(r!==null){let i=Y.exec(n)?.[1];return i!==void 0&&o(r)!==i?(m(n,t),null):r}let a=I.exec(n);if(a){let i=Number(a[2])-1;if(i>=0&&i<=11){let l=Number(a[1]),s=new Date(l,i,1);if(l<100&&s.setFullYear(l),!Number.isNaN(s.getTime()))return s}}return m(n,t),null}function o(e,t="day"){return(0,d.dateToFormValue)(e,t)}function A(e,t,n){if(e===void 0)return;if(e===null)return t==="multiple"?[]:null;if(typeof e=="string"){let i=S(e,n);return D(i,t)}if(Array.isArray(e)){let i=e.map(l=>u(l,n)).filter(l=>l!==null);return D(i,t)}if(e instanceof Date)return D(u(e,n),t);let r=e,a=u(r.start,n);return a===null?t==="multiple"?[]:null:{start:a,end:u(r.end,n)}}function D(e,t){return t!=="multiple"?e:e===null?[]:Array.isArray(e)?e:e instanceof Date?[e]:[]}function S(e,t){let n=e.trim();if(n==="")return null;if(n.includes("/")){let[r="",a=""]=n.split("/"),i=u(r,t);return i===null?null:{start:i,end:a===""?null:u(a,t)}}return n.includes(",")?n.split(",").map(r=>u(r,t)).filter(r=>r!==null):u(n,t)}function $(e){return e==null?null:Array.isArray(e)?e.length===0?null:e.map(t=>o(t)).join(","):e instanceof Date?o(e):`${o(e.start)}/${e.end===null?"":o(e.end)}`}var T=/^(\d{1,2}):(\d{2})(?::(\d{2}))?$/;function V(e,t){if(e==null)return null;if(e instanceof Date){if(Number.isNaN(e.getTime()))return null;let a=s=>String(s).padStart(2,"0"),i=e.getSeconds(),l=`${a(e.getHours())}:${a(e.getMinutes())}`;return i===0?l:`${l}:${a(i)}`}if(typeof e!="string")return null;let n=e.trim();if(n==="")return null;let r=T.exec(n);return!r||Number(r[1])>23||Number(r[2])>59||r[3]!==void 0&&Number(r[3])>59?(m(n,t),null):n}0&&(module.exports={resetMalformedDateWarning,toCalendarString,toCalendarValue,toDate,toISODateValue,toTimeValue});

package/dist/utils/dateValue.d.cts

@@ -0,0 +1,76 @@
+/**
+ * Date type-crossing layer for Calendar, DateField, DatePicker, TimeField.
+ * Accepts native `Date` or ISO-8601 string, emits `Date` shape, treats ISO
+ * string as canonical for persistence (required for HTML attributes and
+ * eventual `Temporal` migration). Copied identically across all five packages.
+ *
+ * @see `@skdx/shared`'s `contracts/date-value.ts`
+ */
+import { type Granularity } from './dateSegments.cjs';
+/** Anything a date-shaped member accepts: the native object, or its ISO-8601 wire form. */
+export type DateInput = Date | string;
+/** A date range, structurally identical to Calendar's own `DateRange`. */
+export interface DateRangeLike {
+    start: Date;
+    end: Date | null;
+}
+/** What {@link toCalendarValue} produces — the `Date`-shaped selection every framework emits. */
+export type DateValue = Date | Date[] | DateRangeLike | null;
+/** How many dates a selection holds, deciding how a wire string widens. */
+export type SelectionModeLike = 'single' | 'multiple' | 'range';
+/** @internal Puts {@link toDate}'s malformed-input warning back to "not yet warned". Only needed by tests. */
+export declare function resetMalformedDateWarning(): void;
+/**
+ * Reads a consumer-supplied value into a local `Date` or `null`. `Date` passes
+ * through untouched (`Invalid Date` → `null`). Strings are parsed field-by-field
+ * in local time (never via `new Date(string)`, which reads `YYYY-MM-DD` as UTC
+ * and shifts the date west of Greenwich). Invalid shapes → `null` + dev warning.
+ *
+ * @param input a `Date`, an ISO-8601 string, or `null`/`undefined`
+ * @param source the property it arrived on, named in the warning
+ * @returns the local calendar date, or `null` when unreadable
+ */
+export declare function toDate(input: DateInput | null | undefined, source?: string): Date | null;
+/**
+ * The canonical ISO-8601 string for a date — what to persist and what `<form>` submits.
+ * Uses local wall-clock fields (not `toISOString`, which would shift dates
+ * across the date line for half the planet).
+ *
+ * @param date the local date to render
+ * @param granularity how much of the time of day to include
+ * @returns `YYYY-MM-DD`, or `YYYY-MM-DDTHH:mm[:ss]` past `day`
+ */
+export declare function toISODateValue(date: Date, granularity?: Granularity): string;
+/**
+ * Reads any authored selection shape into the canonical `DateValue`. Wire
+ * string is self-describing: `2026-08-10` (single), `2026-08-10,2026-08-14`
+ * (set), `2026-08-10/2026-08-14` or `2026-08-10/` (range). Only exception:
+ * single-date `multiple` selection, widened via `mode`. `undefined` preserved
+ * to distinguish controlled from uncontrolled.
+ *
+ * @param input the authored selection, in any accepted form
+ * @param mode how many dates the selection holds
+ * @param source the property it arrived on, named in the warning
+ */
+export declare function toCalendarValue(input: DateInput | ReadonlyArray<DateInput> | {
+    start: DateInput;
+    end?: DateInput | null;
+} | null | undefined, mode: SelectionModeLike, source?: string): DateValue | undefined;
+/**
+ * The canonical wire string for a selection — what `value` takes as an
+ * attribute and what consumers persist.
+ *
+ * @param value a selection in the `Date` shape
+ * @returns the string, or `null` when nothing is selected
+ */
+export declare function toCalendarString(value: DateValue | undefined): string | null;
+/**
+ * Reads a time of day from a 24-hour string or a `Date`'s local wall-clock time.
+ * `Date` part is discarded (time of day is not an instant). Accepts `Date` to
+ * avoid conversion overhead in DatePicker compositions.
+ *
+ * @param input a `HH:mm[:ss]` string, a `Date`, or `null`/`undefined`
+ * @param source the property it arrived on, named in the warning
+ * @returns the 24-hour string, or `null` when unreadable
+ */
+export declare function toTimeValue(input: Date | string | null | undefined, source?: string): string | null;