@skdx/vue 0.26.0 → 0.28.0

package/dist/utils/dateSegments.d.ts

@@ -1,24 +1,12 @@
 /**
- * The segment engine behind `SkdxDateField` and `SkdxTimeField`: 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,17 +28,11 @@ 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 `aria-valuetext` an untyped segment announces, so a spinbutton never reads a value the user did not enter. */
 export declare const EMPTY_VALUE_TEXT = "Empty";
-/**
- * Accessible name of each segment. Spelled for speech, not for code — a screen
- * reader announcing "dayPeriod" helps nobody.
- *
- * Exported so `getSegmentLabel` can fall back to it for the segment types a
- * consumer does not want to re-word.
- */
+/** Accessible name of each segment; exported so consumers can fall back to it. */
 export declare const SEGMENT_LABELS: 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;
@@ -86,8 +68,17 @@ 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;
+/** Generates placeholder text for a segment type. */
+export type SegmentPlaceholderResolver = (type: SegmentType) => string;
+/**
+ * Formats a segment's display text (zero-padded, AM/PM name, or 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. */
@@ -100,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
@@ -113,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, 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 stepSegment(segment: Segment, delta: number): 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). */
@@ -129,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)
@@ -152,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. */
@@ -169,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 e={year:"yyyy",month:"mm",day:"dd",hour:"hh",minute:"mm",second:"ss",dayPeriod:"--"},n="Empty",t={year:"year",month:"month",day:"day",hour:"hour",minute:"minute",second:"second",dayPeriod:"AM/PM"},r={year:4,month:2,day:2,hour:2,minute:2,second:2,dayPeriod:0},a=Date.UTC(2024,0,15,13,45,56),u=/* @__PURE__ */new Map,o=/* @__PURE__ */new Map;function i(e){return e??(new Intl.DateTimeFormat).resolvedOptions().locale}function s(e,n){if(12===n||24===n)return n;const t=new Intl.DateTimeFormat(i(e),{hour:"numeric"}).resolvedOptions(),r=t.hourCycle??(t.hour12?"h12":"h23");return"h11"===r||"h12"===r?12:24}function l(e,n){const t="date"===e?["year","month","day"]:[];return("time"===e||"day"!==n)&&(t.push("hour","minute"),"second"===n&&t.push("second")),t}function d(e,n){return e&&n?new Date(e,n,0).getDate():31}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:d(n.year,n.month)};case"hour":return 12===t?{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 m(e){const n=i(e),t=o.get(n);if(t)return t;const r=new Intl.DateTimeFormat(n,{hour:"numeric",hourCycle:"h12",timeZone:"UTC"}),a=e=>r.formatToParts(Date.UTC(2024,0,15,e)).find(e=>"dayPeriod"===e.type)?.value??(e<12?"AM":"PM"),u=[a(1),a(13)];return o.set(n,u),u}function y(n,t,a){return null===t?e[n]:"dayPeriod"===n?m(a)[0===t?0:1]:String(t).padStart(r[n],"0")}function h(e){const n=i(e.locale),t=s(n,e.hourCycle);return function(e,n,t){const r=`${e}|${n.join(",")}|${t}`,o=u.get(r);if(o)return o;const i=new Intl.DateTimeFormat(e,function(e,n){const 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=12===n?"h12":"h23"),e.includes("minute")&&(t.minute="2-digit"),e.includes("second")&&(t.second="2-digit"),t}(n,t)).formatToParts(a),s=[];for(const e of i)"literal"===e.type?s.push({type:"literal",text:e.value.replace(/[\u202F\u2009\u00A0]/g," "),value:null,min:0,max:0,isPlaceholder:!1,isEditable:!1}):("dayPeriod"===e.type||n.includes(e.type))&&s.push({type:e.type,text:"",value:null,min:0,max:0,isPlaceholder:!0,isEditable:!0});return u.set(r,s),s}(n,l(e.kind,e.granularity),t).map(r=>{if(!r.isEditable)return r;const a=r.type,u=e.values[a]??null,{min:o,max:i}=c(a,e.values,t);return{type:a,text:y(a,u,n),value:u,min:o,max:i,isPlaceholder:null===u,isEditable:!0}})}function f(e,n){const{min:t,max:r}=e;if(null===e.value)return"year"===e.type?/* @__PURE__ */(new Date).getFullYear():t;const a=r-t+1;return t+((e.value-t+n)%a+a)%a}function g(e,n,t){let r=10*n+t;r>e.max&&(r=t);const a=10*r>e.max;return{value:r,buffer:a?0:r,advance:a}}function p(e){return e.every(e=>!e.isEditable||null!==e.value&&e.value>=e.min&&e.value<=e.max)}function T(e,n,t){return 24===t?e:e%12+(1===n?12:0)}function v(e,n){return 24===n?[e,null]:[e%12==0?12:e%12,e<12?0:1]}function P(e,n){const{year:t,month:r,day:a}=e;if(!t||!r||!a)return null;const u=null==e.hour?0:T(e.hour,e.dayPeriod,n),o=new Date(t,r-1,a,u,e.minute??0,e.second??0,0);return t<100&&o.setFullYear(t),o}function x(e,n){const[t,r]=v(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 $(e,n,t){if(null==e.hour||null==e.minute||12===t&&null==e.dayPeriod)return null;const r=e=>String(e).padStart(2,"0"),a=`${r(T(e.hour,e.dayPeriod,t))}:${r(e.minute)}`;return"second"!==n?a:null==e.second?null:`${a}:${r(e.second)}`}function S(e,n){const t=/^(\d{1,2}):(\d{2})(?::(\d{2}))?$/.exec(e.trim());if(!t)return{};const r=Number(t[1]),a=Number(t[2]),u=void 0===t[3]?0:Number(t[3]);if(r>23||a>59||u>59)return{};const[o,i]=v(r,n);return{hour:o,minute:a,second:u,dayPeriod:i}}function D(e,n){const t=(e,n=2)=>String(e).padStart(n,"0"),r=`${t(e.getFullYear(),4)}-${t(e.getMonth()+1)}-${t(e.getDate())}`;if("day"===n)return r;const a=`${t(e.getHours())}:${t(e.getMinutes())}`;return"second"===n?`${r}T${a}:${t(e.getSeconds())}`:`${r}T${a}`}export{n as EMPTY_VALUE_TEXT,t as SEGMENT_LABELS,e as SEGMENT_PLACEHOLDERS,h as buildSegments,D as dateToFormValue,x as dateToValues,d as daysInMonth,y as formatSegmentText,v as from24Hour,m as getDayPeriodNames,p as isComplete,s as resolveHourCycle,i as resolveLocale,c as segmentRange,l as segmentTypesFor,f as stepSegment,S as timeStringToValues,T as to24Hour,g as typeDigit,P as valuesToDate,$ as valuesToTimeString};
+var e={year:"yyyy",month:"mm",day:"dd",hour:"hh",minute:"mm",second:"ss",dayPeriod:"--"},n="Empty",t={year:"year",month:"month",day:"day",hour:"hour",minute:"minute",second:"second",dayPeriod:"AM/PM"},r={year:4,month:2,day:2,hour:2,minute:2,second:2,dayPeriod:0},u={...r,month:1,day:1,hour:1},o=Date.UTC(2024,0,15,13,45,56),a=/* @__PURE__ */new Map,i=/* @__PURE__ */new Map;function s(e){return e??(new Intl.DateTimeFormat).resolvedOptions().locale}function l(e,n){if(12===n||24===n)return n;const t=new Intl.DateTimeFormat(s(e),{hour:"numeric"}).resolvedOptions(),r=t.hourCycle??(t.hour12?"h12":"h23");return"h11"===r||"h12"===r?12:24}function c(e,n){const t="date"===e?["year","month","day"]:[];return("time"===e||"day"!==n)&&(t.push("hour","minute"),"second"===n&&t.push("second")),t}function d(e,n){return e&&n?new Date(e,n,0).getDate():31}function m(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:d(n.year,n.month)};case"hour":return 12===t?{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 f(e){const n=s(e),t=i.get(n);if(t)return t;const r=new Intl.DateTimeFormat(n,{hour:"numeric",hourCycle:"h12",timeZone:"UTC"}),u=e=>r.formatToParts(Date.UTC(2024,0,15,e)).find(e=>"dayPeriod"===e.type)?.value??(e<12?"AM":"PM"),o=[u(1),u(13)];return i.set(n,o),o}function y(e,n){if(1!==[...e].length)return null;const t=e.toLowerCase();if("a"===t)return 0;if("p"===t)return 1;const r=f(n),u=t=>{const r=[...t][0];return void 0!==r&&0===r.localeCompare(e,n,{sensitivity:"base"})},o=u(r[0]),a=u(r[1]);return o&&a?null:o?0:a?1:null}function h(n,t,o,a,i=!0){if(null===t)return a?.(n)??e[n];if("dayPeriod"===n)return f(o)[0===t?0:1];const s=i?r:u;return String(t).padStart(s[n],"0")}function g(e){const n=s(e.locale),t=l(n,e.hourCycle);return function(e,n,t){const r=`${e}|${n.join(",")}|${t}`,u=a.get(r);if(u)return u;const i=new Intl.DateTimeFormat(e,function(e,n){const 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=12===n?"h12":"h23"),e.includes("minute")&&(t.minute="2-digit"),e.includes("second")&&(t.second="2-digit"),t}(n,t)).formatToParts(o),s=[];for(const e of i)"literal"===e.type?s.push({type:"literal",text:e.value.replace(/[\u202F\u2009\u00A0]/g," "),value:null,min:0,max:0,isPlaceholder:!1,isEditable:!1}):("dayPeriod"===e.type||n.includes(e.type))&&s.push({type:e.type,text:"",value:null,min:0,max:0,isPlaceholder:!0,isEditable:!0});return a.set(r,s),s}(n,c(e.kind,e.granularity),t).map(r=>{if(!r.isEditable)return r;const u=r.type,o=e.values[u]??null,{min:a,max:i}=m(u,e.values,t);return{type:u,text:h(u,o,n,e.getSegmentPlaceholder,e.shouldForceLeadingZeros??!0),value:o,min:a,max:i,isPlaceholder:null===o,isEditable:!0}})}function p(e,n,t){const r="second"===n?1:60;if(e!==("second"===n?"second":"minute")||void 0===t||!Number.isFinite(t)||t<=0||t%r!==0)return 1;const u=t/r;return u<60?u:1}function v(e,n,t=1){const{min:r,max:u}=e;if(null===e.value)return r+Math.floor((function(e){const n=/* @__PURE__ */new Date;switch(e.type){case"year":return n.getFullYear();case"hour":{const t=n.getHours();return 1===e.min?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}}(e)-r)/t)*t;const o=Math.floor((u-r)/t)+1,a=e.value-r;return r+(((n>0?Math.floor(a/t):Math.ceil(a/t))+n)%o+o)%o*t}function T(e){return Math.min(Math.max(e.value??e.min,e.min),e.max)}function x(e,n,t){let r=10*n+t;r>e.max&&(r=t);const u=10*r>e.max;return{value:r,buffer:u?0:r,advance:u}}function P(e){return e.every(e=>!e.isEditable||null!==e.value&&e.value>=e.min&&e.value<=e.max)}function $(e,n,t){return 24===t?e:e%12+(1===n?12:0)}function M(e,n){return 24===n?[e,null]:[e%12==0?12:e%12,e<12?0:1]}function S(e,n){const{year:t,month:r,day:u}=e;if(!t||!r||!u)return null;const o=null==e.hour?0:$(e.hour,e.dayPeriod,n),a=new Date(t,r-1,u,o,e.minute??0,e.second??0,0);return t<100&&a.setFullYear(t),a}function b(e,n){const[t,r]=M(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(null==e.hour||null==e.minute||12===t&&null==e.dayPeriod)return null;const r=e=>String(e).padStart(2,"0"),u=`${r($(e.hour,e.dayPeriod,t))}:${r(e.minute)}`;return"second"!==n?u:null==e.second?null:`${u}:${r(e.second)}`}function D(e,n){const t=/^(\d{1,2}):(\d{2})(?::(\d{2}))?$/.exec(e.trim());if(!t)return{};const r=Number(t[1]),u=Number(t[2]),o=void 0===t[3]?0:Number(t[3]);if(r>23||u>59||o>59)return{};const[a,i]=M(r,n);return{hour:a,minute:u,second:o,dayPeriod:i}}function F(e,n){const t=(e,n=2)=>String(e).padStart(n,"0"),r=`${t(e.getFullYear(),4)}-${t(e.getMonth()+1)}-${t(e.getDate())}`;if("day"===n)return r;const u=`${t(e.getHours())}:${t(e.getMinutes())}`;return"second"===n?`${r}T${u}:${t(e.getSeconds())}`:`${r}T${u}`}function N(e){const n=/^(\d{4,})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2})(?::(\d{2}))?)?$/.exec(e.trim());if(!n)return null;const 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 E(e){const n=/^(\d{1,2}):(\d{2})(?::(\d{2}))?$/.exec(e.trim());if(!n)return null;const t=e=>e.padStart(2,"0");return`${t(n[1])}:${n[2]}:${t(n[3]??"00")}`}function C(e,n,t){if(!e)return null;const r=E(e);if(null===r)return null;const u=n?E(n):null;if(null!==u&&r<u)return"underflow";const o=t?E(t):null;return null!==o&&r>o?"overflow":null}function V(e,n,t,r,u){const o=C(w(e,n,t),r,u);return null===o?e:{...e,...D("underflow"===o?r:u,t)}}function H(e,n,t,r){if(!e)return null;const u=F(e,n);return t&&u<F(t,n)?"underflow":r&&u>F(r,n)?"overflow":null}export{n as EMPTY_VALUE_TEXT,t as SEGMENT_LABELS,e as SEGMENT_PLACEHOLDERS,g as buildSegments,V as clampValuesToTimeRange,H as dateRangeViolation,F as dateToFormValue,b as dateToValues,y as dayPeriodFromKey,d as daysInMonth,h as formatSegmentText,M as from24Hour,f as getDayPeriodNames,P as isComplete,N as parseDateFormValue,l as resolveHourCycle,s as resolveLocale,m as segmentRange,p as segmentStepFor,c as segmentTypesFor,T as segmentValueNow,v as stepSegment,C as timeRangeViolation,D as timeStringToValues,$ as to24Hour,x as typeDigit,S as valuesToDate,w as valuesToTimeString};

package/dist/utils/dateValue.cjs

@@ -0,0 +1 @@
+const D=require("./is-dev-mode.cjs"),m=require("./dateSegments.cjs");var g=/^(\d{4,})-(\d{2})$/,N=/^(\d{4,}-\d{2}-\d{2})/,c=!1;function d(r,e){c||(c=!0,D.isDevMode()&&console.warn(`[skdx] ${e?`\`${e}\``:"A date property"} was given ${JSON.stringify(r)}, 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 — the property behaves as if it had not been supplied — rather than being coerced to today, to the epoch, or to an \`Invalid Date\` that would then poison every comparison after it.`))}function l(r,e){if(r==null)return null;if(r instanceof Date)return Number.isNaN(r.getTime())?null:r;if(typeof r!="string")return null;const t=r.trim();if(t==="")return null;const n=m.parseDateFormValue(t);if(n!==null){const i=N.exec(t)?.[1];return i!==void 0&&u(n)!==i?(d(t,e),null):n}const a=g.exec(t);if(a){const i=Number(a[2])-1;if(i>=0&&i<=11){const o=Number(a[1]),f=new Date(o,i,1);if(o<100&&f.setFullYear(o),!Number.isNaN(f.getTime()))return f}}return d(t,e),null}function u(r,e="day"){return m.dateToFormValue(r,e)}function h(r,e,t){if(r===void 0)return;if(r===null)return e==="multiple"?[]:null;if(typeof r=="string")return s(y(r,t),e);if(Array.isArray(r))return s(r.map(i=>l(i,t)).filter(i=>i!==null),e);if(r instanceof Date)return s(l(r,t),e);const n=r,a=l(n.start,t);return a===null?e==="multiple"?[]:null:{start:a,end:l(n.end,t)}}function s(r,e){return e!=="multiple"?r:r===null?[]:Array.isArray(r)?r:r instanceof Date?[r]:[]}function y(r,e){const t=r.trim();if(t==="")return null;if(t.includes("/")){const[n="",a=""]=t.split("/"),i=l(n,e);return i===null?null:{start:i,end:a===""?null:l(a,e)}}return t.includes(",")?t.split(",").map(n=>l(n,e)).filter(n=>n!==null):l(t,e)}function Y(r){return r==null?null:Array.isArray(r)?r.length===0?null:r.map(e=>u(e)).join(","):r instanceof Date?u(r):`${u(r.start)}/${r.end===null?"":u(r.end)}`}var b=/^(\d{1,2}):(\d{2})(?::(\d{2}))?$/;function M(r,e){if(r==null)return null;if(r instanceof Date){if(Number.isNaN(r.getTime()))return null;const a=f=>String(f).padStart(2,"0"),i=r.getSeconds(),o=`${a(r.getHours())}:${a(r.getMinutes())}`;return i===0?o:`${o}:${a(i)}`}if(typeof r!="string")return null;const t=r.trim();if(t==="")return null;const n=b.exec(t);return!n||Number(n[1])>23||Number(n[2])>59||n[3]!==void 0&&Number(n[3])>59?(d(t,e),null):t}exports.toCalendarString=Y;exports.toCalendarValue=h;exports.toDate=l;exports.toISODateValue=u;exports.toTimeValue=M;

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;

package/dist/utils/dateValue.d.ts

@@ -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.js';
+/** 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;

package/dist/utils/dateValue.js

@@ -0,0 +1 @@
+import{isDevMode as t}from"./is-dev-mode.js";import{dateToFormValue as e,parseDateFormValue as n}from"./dateSegments.js";var r=/^(\d{4,})-(\d{2})$/,u=/^(\d{4,}-\d{2}-\d{2})/,l=!1;function i(e,n){l||(l=!0,t()&&console.warn(`[skdx] ${n?`\`${n}\``:"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 — the property behaves as if it had not been supplied — rather than being coerced to today, to the epoch, or to an \`Invalid Date\` that would then poison every comparison after it.`))}function a(t,e){if(null==t)return null;if(t instanceof Date)return Number.isNaN(t.getTime())?null:t;if("string"!=typeof t)return null;const l=t.trim();if(""===l)return null;const a=n(l);if(null!==a){const t=u.exec(l)?.[1];return void 0!==t&&o(a)!==t?(i(l,e),null):a}const s=r.exec(l);if(s){const t=Number(s[2])-1;if(t>=0&&t<=11){const e=Number(s[1]),n=new Date(e,t,1);if(e<100&&n.setFullYear(e),!Number.isNaN(n.getTime()))return n}}return i(l,e),null}function o(t,n="day"){return e(t,n)}function s(t,e,n){if(void 0===t)return;if(null===t)return"multiple"===e?[]:null;if("string"==typeof t)return f(function(t,e){const n=t.trim();if(""===n)return null;if(n.includes("/")){const[t="",r=""]=n.split("/"),u=a(t,e);return null===u?null:{start:u,end:""===r?null:a(r,e)}}return n.includes(",")?n.split(",").map(t=>a(t,e)).filter(t=>null!==t):a(n,e)}(t,n),e);if(Array.isArray(t))return f(t.map(t=>a(t,n)).filter(t=>null!==t),e);if(t instanceof Date)return f(a(t,n),e);const r=t,u=a(r.start,n);return null===u?"multiple"===e?[]:null:{start:u,end:a(r.end,n)}}function f(t,e){return"multiple"!==e?t:null===t?[]:Array.isArray(t)?t:t instanceof Date?[t]:[]}function d(t){return null==t?null:Array.isArray(t)?0===t.length?null:t.map(t=>o(t)).join(","):t instanceof Date?o(t):`${o(t.start)}/${null===t.end?"":o(t.end)}`}var c=/^(\d{1,2}):(\d{2})(?::(\d{2}))?$/;function m(t,e){if(null==t)return null;if(t instanceof Date){if(Number.isNaN(t.getTime()))return null;const e=t=>String(t).padStart(2,"0"),n=t.getSeconds(),r=`${e(t.getHours())}:${e(t.getMinutes())}`;return 0===n?r:`${r}:${e(n)}`}if("string"!=typeof t)return null;const n=t.trim();if(""===n)return null;const r=c.exec(n);return!r||Number(r[1])>23||Number(r[2])>59||void 0!==r[3]&&Number(r[3])>59?(i(n,e),null):n}export{d as toCalendarString,s as toCalendarValue,a as toDate,o as toISODateValue,m as toTimeValue};

package/dist/utils/declaredChildren.cjs

@@ -0,0 +1 @@
+let c=require("vue");function a(r,l){const t=s=>(s??[]).some(e=>e.type===l||e.type===c.Fragment&&t(e.children));return t(r?.())}exports.slotDeclares=a;

package/dist/utils/declaredChildren.d.cts

@@ -0,0 +1,3 @@
+import { type Slot } from 'vue';
+/** Scans slot for component vnode, looking through fragments. @internal */
+export declare function slotDeclares(slot: Slot | undefined, component: unknown): boolean;

package/dist/utils/declaredChildren.d.ts

@@ -0,0 +1,3 @@
+import { type Slot } from 'vue';
+/** Scans slot for component vnode, looking through fragments. @internal */
+export declare function slotDeclares(slot: Slot | undefined, component: unknown): boolean;

package/dist/utils/declaredChildren.js

@@ -0,0 +1 @@
+import{Fragment as e}from"vue";function t(t,r){const o=t=>(t??[]).some(t=>t.type===r||t.type===e&&o(t.children));return o(t?.())}export{t as slotDeclares};

package/dist/utils/id.d.cts

@@ -1,24 +1,11 @@
 /**
- * @internal `useId()` where the running Vue has it (3.5+), otherwise undefined.
- *
- * The namespace import is deliberate: a named `useId` import would fail to
- * resolve on Vue 3.3/3.4 — inside the declared peer range — instead of
- * degrading. Only valid during `setup()`.
+ * @internal Vue's `useId()` if available (3.5+), else undefined. Only valid
+ * during `setup()`.
  */
 export declare function stableUid(): string | undefined;
 /**
  * @internal Generates a unique id like `skdx-<prefix>-<n>` for internal DOM
- * wiring (aria-*, htmlFor, etc.). Must be called during `setup()`.
- *
- * The tail comes from Vue 3.5's `useId()`, which yields the same value on the
- * server and on the client. The module-level counter cannot: it is a process
- * singleton, so in a long-lived Node server the second request emits
- * `skdx-tabs-4711` where the freshly-loaded client bundle emits `skdx-tabs-1` on
- * hydrate — both renders succeed, and every `aria-labelledby`/`for` written on
- * the server silently points at nothing. The counter stays as the fallback for
- * the 3.3/3.4 peer floor, where nothing was SSR-stable to begin with.
- *
- * ponytail: two Vue apps on one page both default `useId()` to the `v` prefix
- * and could collide; set `app.config.idPrefix` per app if that ever happens.
+ * wiring. Must be called during `setup()`. Uses Vue 3.5's `useId()` when
+ * available for SSR stability; falls back to module counter for 3.3/3.4.
  */
 export declare function nextId(prefix: string): string;

package/dist/utils/id.d.ts

@@ -1,24 +1,11 @@
 /**
- * @internal `useId()` where the running Vue has it (3.5+), otherwise undefined.
- *
- * The namespace import is deliberate: a named `useId` import would fail to
- * resolve on Vue 3.3/3.4 — inside the declared peer range — instead of
- * degrading. Only valid during `setup()`.
+ * @internal Vue's `useId()` if available (3.5+), else undefined. Only valid
+ * during `setup()`.
  */
 export declare function stableUid(): string | undefined;
 /**
  * @internal Generates a unique id like `skdx-<prefix>-<n>` for internal DOM
- * wiring (aria-*, htmlFor, etc.). Must be called during `setup()`.
- *
- * The tail comes from Vue 3.5's `useId()`, which yields the same value on the
- * server and on the client. The module-level counter cannot: it is a process
- * singleton, so in a long-lived Node server the second request emits
- * `skdx-tabs-4711` where the freshly-loaded client bundle emits `skdx-tabs-1` on
- * hydrate — both renders succeed, and every `aria-labelledby`/`for` written on
- * the server silently points at nothing. The counter stays as the fallback for
- * the 3.3/3.4 peer floor, where nothing was SSR-stable to begin with.
- *
- * ponytail: two Vue apps on one page both default `useId()` to the `v` prefix
- * and could collide; set `app.config.idPrefix` per app if that ever happens.
+ * wiring. Must be called during `setup()`. Uses Vue 3.5's `useId()` when
+ * available for SSR stability; falls back to module counter for 3.3/3.4.
  */
 export declare function nextId(prefix: string): string;

package/dist/utils/is-dev-mode.cjs

@@ -0,0 +1 @@
+function e(){return!1}exports.isDevMode=e;

package/dist/utils/is-dev-mode.d.cts

@@ -0,0 +1,6 @@
+/**
+ * Development-mode guard. Detects via `import.meta.env.DEV`, a Vite built-in.
+ * @returns `true` in development, `false` in production.
+ * @internal
+ */
+export declare function isDevMode(): boolean;

package/dist/utils/is-dev-mode.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Development-mode guard. Detects via `import.meta.env.DEV`, a Vite built-in.
+ * @returns `true` in development, `false` in production.
+ * @internal
+ */
+export declare function isDevMode(): boolean;

package/dist/utils/is-dev-mode.js

@@ -0,0 +1 @@
+function e(){return!1}export{e as isDevMode};

package/dist/utils/liveAnnouncer.d.cts

@@ -1,35 +1,21 @@
 /** Which of the two singleton live regions a message is routed to. */
 export type AnnouncePoliteness = 'polite' | 'assertive';
-/**
- * How long {@link announce} waits before writing a message, so a burst of
- * calls (a combobox re-filtering on every keystroke) collapses into the one
- * announcement the user actually cares about instead of a queue of stale
- * ones.
- */
+/** Debounce delay; collapses bursts (e.g., keystroke filtering) into one announcement. */
 export declare const ANNOUNCE_DEBOUNCE_MS = 150;
 /**
- * Announces `message` to screen readers through a process-wide `aria-live`
- * region, without rendering anything into your own template — for state
- * changes that have no visible text of their own (a filtered result count, a
- * re-sorted column).
- *
- * Debounced by {@link ANNOUNCE_DEBOUNCE_MS} and deduplicated: only the last
- * message in a burst is written, and a message identical to what the region
- * already holds is skipped (writing the same text back is not a DOM change,
- * so assistive tech would ignore it anyway). Empty/whitespace messages are
- * ignored. No-ops during SSR.
- *
+ * Announces message to screen readers via aria-live region (polite or assertive).
+ * Debounced, deduplicated (last message in burst wins), skips duplicates and
+ * empty text. No-op during SSR.
  * @example
  * ```ts
- * announce(`${results.length} results available`);
- * announce('Upload failed', 'assertive');
+ * announce(`${results.length} results`);
+ * announce('Failed', 'assertive');
  * ```
  */
 export declare function announce(message: string, politeness?: AnnouncePoliteness): void;
 /**
- * Empties the live region(s) and drops any debounced message still waiting to
- * be written — pass a politeness to clear just one. Mostly useful between
- * tests, and when navigating away from the thing a pending message describes.
+ * Clear region(s); pass politeness to clear only one. Useful between tests and
+ * when navigating away from the message's context.
  */
 export declare function clearAnnouncements(politeness?: AnnouncePoliteness): void;
 /** What {@link useLiveAnnouncer} returns. */
@@ -40,14 +26,12 @@ export interface LiveAnnouncerApi {
     clear: (politeness?: AnnouncePoliteness) => void;
 }
 /**
- * Composable form of {@link announce} — returns a stable `{ announce, clear }`
- * pair. There is no per-component state to set up or tear down (the regions
- * are process-wide singletons), so it is safe to call outside `setup()` too.
- *
+ * Composable form of announce. Returns stable { announce, clear } pair.
+ * No per-component state (process-wide singletons); safe outside setup().
  * @example
  * ```ts
  * const { announce } = useLiveAnnouncer();
- * watch(count, (n) => announce(`${n} results available`));
+ * watch(count, (n) => announce(`${n} results`));
  * ```
  */
 export declare function useLiveAnnouncer(): LiveAnnouncerApi;