@skdx/vue 0.28.0 → 0.29.0

package/dist/utils/date-segments.d.ts

@@ -0,0 +1,223 @@
+/** 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 (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". */
+export type SegmentValues = Partial<Record<SegmentType, number | null>>;
+/** One rendered piece of a segmented field — an editable segment or a locale literal. */
+export interface Segment {
+    /** The segment this piece edits, or `'literal'` for the text between segments. */
+    type: SegmentType | 'literal';
+    /** What to render: the padded value, the placeholder, or the literal itself. */
+    text: string;
+    /** Current numeric value; `null` for literals and for untyped segments. */
+    value: number | null;
+    /** Lowest accepted value (`0` for literals). */
+    min: number;
+    /** Highest accepted value (`0` for literals). Dynamic for `day`. */
+    max: number;
+    /** Whether this segment is still showing its placeholder. */
+    isPlaceholder: boolean;
+    /** `false` only for literals. */
+    isEditable: boolean;
+}
+/** 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 names for each segment type. */
+export declare const SEGMENT_LABELS: Record<SegmentType, string>;
+/** Localization strings for segmented date/time fields. */
+export interface SegmentedLabelProps {
+    /**
+     * Words the accessible name of each segment type.
+     * @default undefined — the built-in English names ('year', 'month', 'AM/PM', …).
+     */
+    getSegmentLabel?: ((type: SegmentType) => string | undefined) | undefined;
+    /**
+     * Aria text for untyped segments.
+     * @default 'Empty'
+     */
+    emptySegmentText?: string | undefined;
+    /**
+     * Words the placeholder for each segment.
+     * @default undefined — the built-in English letters ('yyyy', 'mm', 'dd', …).
+     */
+    getSegmentPlaceholder?: SegmentPlaceholderResolver | undefined;
+}
+/** The runtime's own locale, used whenever `locale` is omitted — matches `calendar-locale`'s `resolveLocale`. */
+export declare function resolveLocale(locale?: string): string;
+/**
+ * The hour cycle to render with: the explicit `hourCycle` when given, otherwise
+ * whatever the locale resolves to (`h11`/`h12` → `12`, `h23`/`h24` → `24`).
+ *
+ * @example
+ * ```ts
+ * resolveHourCycle('en-US'); // 12
+ * resolveHourCycle('de-DE'); // 24
+ * ```
+ */
+export declare function resolveHourCycle(locale?: string, hourCycle?: HourCycle): HourCycle;
+/**
+ * The editable segments a field of this kind and granularity owns, in canonical (not locale) order; `dayPeriod` is appended by {@link buildSegments} only when the resolved hour cycle is 12.
+ *
+ * @example
+ * ```ts
+ * segmentTypesFor('date', 'minute'); // ['year','month','day','hour','minute']
+ * segmentTypesFor('time', 'second'); // ['hour','minute','second']
+ * ```
+ */
+export declare function segmentTypesFor(kind: 'date' | 'time', granularity: Granularity): SegmentType[];
+/** Days in a Gregorian month; `31` while either input is unknown, so `day` stays fully typeable. */
+export declare function daysInMonth(year: number | null | undefined, month: number | null | undefined): number;
+/** The accepted range of one segment, given the values around it. */
+export declare function segmentRange(type: SegmentType, values: SegmentValues, hourCycle: HourCycle): {
+    min: number;
+    max: number;
+};
+/** The locale's AM and PM names, e.g. `['AM', 'PM']` or `['vorm.', 'nachm.']`. */
+export declare function getDayPeriodNames(locale?: string): [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. */
+    kind: 'date' | 'time';
+    /** How far down the field is editable. */
+    granularity: Granularity;
+    /** BCP-47 locale deciding segment order, literals and AM/PM names. */
+    locale?: string | undefined;
+    /** Forced hour cycle; omitted means "whatever the locale uses". */
+    hourCycle?: HourCycle | undefined;
+    /** Current per-segment values. */
+    values: SegmentValues;
+    /** Words each segment's placeholder; omitted keeps the built-in English letters. */
+    getSegmentPlaceholder?: SegmentPlaceholderResolver | undefined;
+    /**
+     * 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 | undefined;
+}
+/**
+ * The full ordered render list for a segmented field — editable segments
+ * interleaved with the locale's literals.
+ *
+ * @example
+ * ```ts
+ * buildSegments({ kind: 'date', granularity: 'day', locale: 'en-US', values: {} })
+ *   .filter((s) => s.isEditable)
+ *   .map((s) => s.type); // ['month', 'day', 'year']
+ * ```
+ */
+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, falling back to `1` when `step` doesn't fit the grid.
+ *
+ * @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;
+/**
+ * Stepper one segment by `delta`, wrapping around its range, snapping onto the `step` grid like a native stepper when `step` is past 1.
+ * @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`, since mid-entry it can legitimately sit below minimum. */
+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). */
+    value: number;
+    /** Buffer to carry into the next keystroke on this segment; `0` once entry is complete. */
+    buffer: number;
+    /** Whether focus should move to the next editable segment. */
+    advance: boolean;
+}
+/**
+ * Types one digit into a segment: an overflowing keystroke restarts entry at that digit instead of being rejected, and focus advances once no further digit could fit.
+ *
+ * @param segment the segment being typed into
+ * @param buffer what has been typed into it so far (`0` when entry just started)
+ * @param digit the digit `0`–`9` just pressed
+ *
+ * @example
+ * ```ts
+ * // month, "1" already typed, user presses 5 → 15 overflows, restart at 5
+ * typeDigit(monthSegment, 1, 5); // { value: 5, buffer: 0, advance: true }
+ * ```
+ */
+export declare function typeDigit(segment: Segment, buffer: number, digit: number): DigitEntry;
+/** Whether every editable segment has been typed and sits inside its range. */
+export declare function isComplete(segments: Segment[]): boolean;
+/** Converts a possibly-12-hour `hour` plus `dayPeriod` into the 0-23 hour. */
+export declare function to24Hour(hour: number, dayPeriod: number | null | undefined, hourCycle: HourCycle): number;
+/** 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; 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. */
+export declare function dateToValues(date: Date, hourCycle: HourCycle): SegmentValues;
+/**
+ * The `HH:mm` / `HH:mm:ss` string these segment values describe — always 24
+ * hour, like `<input type="time">`, regardless of the rendered `hourCycle` —
+ * or `null` while hour or minute is untyped.
+ */
+export declare function valuesToTimeString(values: SegmentValues, granularity: Granularity, hourCycle: HourCycle): string | null;
+/** Parses `HH:mm[:ss]` (24 hour) into segment values for the given hour cycle. Invalid input yields empty values. */
+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}, built field by field rather than `new Date(string)`, which reads a bare `YYYY-MM-DD` as UTC midnight.
+ *
+ * @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.
+ *
+ * @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. */
+export declare function clearDateSegmentCache(): void;

package/dist/utils/date-segments.js

@@ -0,0 +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},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:t%12==0?12:t%12}case"minute":return n.getMinutes();case"second":return n.getSeconds();case"dayPeriod":return n.getHours()<12?0:1;case"day":case"month":case"literal":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/date-value.cjs

@@ -0,0 +1 @@
+const c=require("./date-segments.cjs");var D=/^(\d{4,})-(\d{2})$/,g=/^(\d{4,}-\d{2}-\d{2})/,d=!1;function f(r,t){d||(d=!0,console.warn(`[skdx] ${t?`\`${t}\``:"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 i(r,t){if(r==null)return null;if(r instanceof Date)return Number.isNaN(r.getTime())?null:r;if(typeof r!="string")return null;const e=r.trim();if(e==="")return null;const n=c.parseDateFormValue(e);if(n!==null){const a=g.exec(e)?.[1];return a!==void 0&&o(n)!==a?(f(e,t),null):n}const l=h(e);return l||(f(e,t),null)}function h(r){const t=D.exec(r);if(!t)return null;const e=Number(t[2])-1;if(e<0||e>11)return null;const n=Number(t[1]),l=new Date(n,e,1);return n<100&&l.setFullYear(n),Number.isNaN(l.getTime())?null:l}function o(r,t="day"){return c.dateToFormValue(r,t)}function N(r,t,e){if(r===void 0)return;if(r===null)return t==="multiple"?[]:null;if(typeof r=="string")return u(y(r,e),t);if(Array.isArray(r))return u(r.map(a=>i(a,e)).filter(a=>a!==null),t);if(r instanceof Date)return u(i(r,e),t);const n=r,l=i(n.start,e);return l===null?t==="multiple"?[]:null:{start:l,end:i(n.end,e)}}function u(r,t){return t!=="multiple"?r:r===null?[]:Array.isArray(r)?r:r instanceof Date?[r]:[]}function y(r,t){const e=r.trim();if(e==="")return null;if(e.includes("/")){const[n="",l=""]=e.split("/"),a=i(n,t);return a===null?null:{start:a,end:l===""?null:i(l,t)}}return e.includes(",")?e.split(",").map(n=>i(n,t)).filter(n=>n!==null):i(e,t)}function Y(r){return r==null?null:Array.isArray(r)?r.length===0?null:r.map(t=>o(t)).join(","):r instanceof Date?o(r):`${o(r.start)}/${r.end===null?"":o(r.end)}`}var b=/^(\d{1,2}):(\d{2})(?::(\d{2}))?$/;function M(r,t){if(r==null)return null;if(r instanceof Date){if(Number.isNaN(r.getTime()))return null;const l=m=>String(m).padStart(2,"0"),a=r.getSeconds(),s=`${l(r.getHours())}:${l(r.getMinutes())}`;return a===0?s:`${s}:${l(a)}`}if(typeof r!="string")return null;const e=r.trim();if(e==="")return null;const n=b.exec(e);return!n||Number(n[1])>23||Number(n[2])>59||n[3]!==void 0&&Number(n[3])>59?(f(e,t),null):e}exports.toCalendarString=Y;exports.toCalendarValue=N;exports.toDate=i;exports.toISODateValue=o;exports.toTimeValue=M;

package/dist/utils/date-value.d.cts

@@ -0,0 +1,57 @@
+import { type Granularity } from './date-segments.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". */
+export declare function resetMalformedDateWarning(): void;
+/**
+ * Reads a consumer-supplied value into a local `Date` or `null`, parsing strings field-by-field (never via `new Date(string)`, which reads `YYYY-MM-DD` as UTC) and warning in dev on invalid shapes.
+ *
+ * @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 — using local wall-clock fields, not `toISOString`, which would shift dates across the date line.
+ *
+ * @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`; the wire string is self-describing except for a single-date `multiple` selection, widened via `mode`.
+ *
+ * @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 | undefined;
+} | 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, discarding the date part since time of day is not an instant.
+ *
+ * @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/date-value.d.ts

@@ -0,0 +1,57 @@
+import { type Granularity } from './date-segments.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". */
+export declare function resetMalformedDateWarning(): void;
+/**
+ * Reads a consumer-supplied value into a local `Date` or `null`, parsing strings field-by-field (never via `new Date(string)`, which reads `YYYY-MM-DD` as UTC) and warning in dev on invalid shapes.
+ *
+ * @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 — using local wall-clock fields, not `toISOString`, which would shift dates across the date line.
+ *
+ * @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`; the wire string is self-describing except for a single-date `multiple` selection, widened via `mode`.
+ *
+ * @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 | undefined;
+} | 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, discarding the date part since time of day is not an instant.
+ *
+ * @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/date-value.js

@@ -0,0 +1 @@
+import{dateToFormValue as n,parseDateFormValue as t}from"./date-segments.js";var e=/^(\d{4,})-(\d{2})$/,r=/^(\d{4,}-\d{2}-\d{2})/,u=!1;function l(n,t){u||(u=!0,console.warn(`[skdx] ${t?`\`${t}\``:"A date property"} was given ${JSON.stringify(n)}, 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 i(n,u){if(null==n)return null;if(n instanceof Date)return Number.isNaN(n.getTime())?null:n;if("string"!=typeof n)return null;const i=n.trim();if(""===i)return null;const o=t(i);if(null!==o){const n=r.exec(i)?.[1];return void 0!==n&&a(o)!==n?(l(i,u),null):o}const s=function(n){const t=e.exec(n);if(!t)return null;const r=Number(t[2])-1;if(r<0||r>11)return null;const u=Number(t[1]),l=new Date(u,r,1);return u<100&&l.setFullYear(u),Number.isNaN(l.getTime())?null:l}(i);return s||(l(i,u),null)}function a(t,e="day"){return n(t,e)}function o(n,t,e){if(void 0===n)return;if(null===n)return"multiple"===t?[]:null;if("string"==typeof n)return s(function(n,t){const e=n.trim();if(""===e)return null;if(e.includes("/")){const[n="",r=""]=e.split("/"),u=i(n,t);return null===u?null:{start:u,end:""===r?null:i(r,t)}}return e.includes(",")?e.split(",").map(n=>i(n,t)).filter(n=>null!==n):i(e,t)}(n,e),t);if(Array.isArray(n))return s(n.map(n=>i(n,e)).filter(n=>null!==n),t);if(n instanceof Date)return s(i(n,e),t);const r=n,u=i(r.start,e);return null===u?"multiple"===t?[]:null:{start:u,end:i(r.end,e)}}function s(n,t){return"multiple"!==t?n:null===n?[]:Array.isArray(n)?n:n instanceof Date?[n]:[]}function f(n){return null==n?null:Array.isArray(n)?0===n.length?null:n.map(n=>a(n)).join(","):n instanceof Date?a(n):`${a(n.start)}/${null===n.end?"":a(n.end)}`}var c=/^(\d{1,2}):(\d{2})(?::(\d{2}))?$/;function d(n,t){if(null==n)return null;if(n instanceof Date){if(Number.isNaN(n.getTime()))return null;const t=n=>String(n).padStart(2,"0"),e=n.getSeconds(),r=`${t(n.getHours())}:${t(n.getMinutes())}`;return 0===e?r:`${r}:${t(e)}`}if("string"!=typeof n)return null;const e=n.trim();if(""===e)return null;const r=c.exec(e);return!r||Number(r[1])>23||Number(r[2])>59||void 0!==r[3]&&Number(r[3])>59?(l(e,t),null):e}export{f as toCalendarString,o as toCalendarValue,i as toDate,a as toISODateValue,d as toTimeValue};

package/dist/utils/declaredChildren.cjs

@@ -1 +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;
+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

@@ -1,3 +1,9 @@
 import { type Slot } from 'vue';
-/** Scans slot for component vnode, looking through fragments. @internal */
-export declare function slotDeclares(slot: Slot | undefined, component: unknown): boolean;
+/**
+ * Getter that scans slot for component vnode, looking through fragments. @internal
+ *
+ * Deferred, not evaluated: invoking a slot from `setup()` is what Vue's
+ * "Slot invoked outside of the render function" warning names. Call the result
+ * from inside a render or a computed the template reads.
+ */
+export declare function slotDeclares(slot: Slot | undefined, component: unknown): () => boolean;

package/dist/utils/declaredChildren.d.ts

@@ -1,3 +1,9 @@
 import { type Slot } from 'vue';
-/** Scans slot for component vnode, looking through fragments. @internal */
-export declare function slotDeclares(slot: Slot | undefined, component: unknown): boolean;
+/**
+ * Getter that scans slot for component vnode, looking through fragments. @internal
+ *
+ * Deferred, not evaluated: invoking a slot from `setup()` is what Vue's
+ * "Slot invoked outside of the render function" warning names. Call the result
+ * from inside a render or a computed the template reads.
+ */
+export declare function slotDeclares(slot: Slot | undefined, component: unknown): () => boolean;

package/dist/utils/declaredChildren.js

@@ -1 +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};
+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/dev-mode.cjs

@@ -0,0 +1 @@
+function e(){try{if(typeof process<"u"&&process.env.NODE_ENV==="development")return!0}catch{}return typeof ngDevMode<"u"&&ngDevMode===!0}exports.isDevMode=e;

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

@@ -0,0 +1,12 @@
+/**
+ * Whether this build is a development build, so dev-only diagnostics may throw rather than log.
+ *
+ * Only an explicit development signal answers yes; an unset or unrecognised flag says
+ * nothing, so a bundle that defines none of the three is treated as production. The
+ * probes read build-time constants rather than arguments, so a test that needs a
+ * particular answer mocks this module.
+ *
+ * @returns `true` in development, `false` in production and when nothing says.
+ * @internal
+ */
+export declare function isDevMode(): boolean;

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

@@ -0,0 +1,12 @@
+/**
+ * Whether this build is a development build, so dev-only diagnostics may throw rather than log.
+ *
+ * Only an explicit development signal answers yes; an unset or unrecognised flag says
+ * nothing, so a bundle that defines none of the three is treated as production. The
+ * probes read build-time constants rather than arguments, so a test that needs a
+ * particular answer mocks this module.
+ *
+ * @returns `true` in development, `false` in production and when nothing says.
+ * @internal
+ */
+export declare function isDevMode(): boolean;

package/dist/utils/dev-mode.js

@@ -0,0 +1 @@
+function e(){try{if(typeof process<"u"&&"development"===process.env.NODE_ENV)return!0}catch{}return typeof ngDevMode<"u"&&!0===ngDevMode}export{e as isDevMode};

package/dist/utils/direction.d.cts

@@ -1,34 +1,18 @@
 import { type MaybeRefOrGetter } from 'vue';
 /**
  * Writing direction resolution, shared by every component whose keyboard
- * behaviour is horizontal (arrow-key navigation, submenu open/close, slider
- * stepping, resize handles). Mirrors
- * `packages/react/src/utils/direction.tsx`.
+ * behaviour is horizontal. The one rule: under `dir="rtl"`, ArrowLeft and
+ * ArrowRight swap meaning; call {@link directionalKey} once and keep
+ * LTR-authored branches otherwise.
  *
- * There is exactly one rule to apply: **under `dir="rtl"`, ArrowLeft and
- * ArrowRight swap meaning.** Everything else — Home/End, the vertical arrows,
- * typeahead — is direction-agnostic, so handlers call {@link directionalKey}
- * once at the top and then keep their existing LTR-authored branches.
- *
- * Direction is resolved in this order:
- *
- * 1. an explicit `dir` prop on the component, if it accepts one;
- * 2. the nearest {@link provideDirection};
- * 3. the nearest `[dir]` ancestor **in the DOM** — which is what a plain
- *    `dir="rtl"` attribute on any skdx component produces, since `dir` is a
- *    global HTML attribute and Vue falls it through to the root element;
- * 4. `document.dir`.
- *
- * Step 3 is why most components need no `dir` prop of their own and no
- * provider: `<SkdxTabsList dir="rtl">` already renders `dir="rtl"` on the
- * tablist, and the handler reads it back off `event.currentTarget`.
+ * Resolved in order: an explicit `dir` prop, the nearest {@link provideDirection},
+ * the nearest `[dir]` ancestor in the DOM, then `document.dir`.
  */
 /** Writing direction of a subtree. */
 export type Direction = 'ltr' | 'rtl';
 /**
  * Declares the writing direction for every skdx component in the current
- * component's subtree. Call it from a wrapper component's `setup` when the
- * direction is not already expressed as a `dir` attribute in the DOM.
+ * subtree, for use when direction isn't already a `dir` attribute in the DOM.
  *
  * @example
  * ```ts
@@ -37,12 +21,7 @@ export type Direction = 'ltr' | 'rtl';
  * ```
  */
 export declare function provideDirection(dir: MaybeRefOrGetter<Direction>): void;
-/**
- * The direction declared by an explicit prop or the nearest
- * {@link provideDirection}, or `undefined` when neither is present — in which
- * case {@link directionalKey} falls back to the DOM. Must be called from
- * `setup`; the returned getter may be called at any time.
- */
+/** The direction declared by an explicit prop or the nearest {@link provideDirection} (or `undefined` when neither is present); call it from `setup`, and call the returned getter any time. */
 export declare function useDirection(dirProp?: MaybeRefOrGetter<Direction | undefined>): () => Direction | undefined;
 /** @internal Resolves `el`'s direction, with `override` (prop/provider) winning when set. */
 export declare function resolveDirection(el: Element | null | undefined, override?: Direction): Direction;
@@ -52,23 +31,13 @@ export type LogicalSide = 'start' | 'end' | 'top' | 'bottom';
 export type PhysicalSide = 'left' | 'right' | 'top' | 'bottom';
 /**
  * Resolves a logical edge to the physical one it lands on: `start`/`end` swap
- * under RTL, `top`/`bottom` and already-physical `left`/`right` pass through.
- *
- * Components keep publishing the *logical* value (Drawer's `data-placement`,
- * an overlay's `side` prop) and only resolve at the last moment — a component
- * that stored `left` instead of `start` would break RTL for every consumer
- * downstream.
- *
+ * under RTL, `top`/`bottom` and physical `left`/`right` pass through.
  * @internal
  */
 export declare function resolvePhysicalSide(side: LogicalSide | PhysicalSide, direction: Direction): PhysicalSide;
 /**
- * Translates the key the user physically pressed into the key an
- * LTR-authored handler should act on: in RTL, ArrowLeft and ArrowRight swap.
- * Every other key is returned unchanged, so this is safe to apply
- * unconditionally — including in vertical widgets, where neither key means
- * anything.
- *
+ * Translates the key the user physically pressed into the key an LTR-authored
+ * handler should act on: in RTL, ArrowLeft and ArrowRight swap.
  * @internal
  */
 export declare function directionalKey(key: string, el: Element | null | undefined, override?: Direction): string;

package/dist/utils/direction.d.ts

@@ -1,34 +1,18 @@
 import { type MaybeRefOrGetter } from 'vue';
 /**
  * Writing direction resolution, shared by every component whose keyboard
- * behaviour is horizontal (arrow-key navigation, submenu open/close, slider
- * stepping, resize handles). Mirrors
- * `packages/react/src/utils/direction.tsx`.
+ * behaviour is horizontal. The one rule: under `dir="rtl"`, ArrowLeft and
+ * ArrowRight swap meaning; call {@link directionalKey} once and keep
+ * LTR-authored branches otherwise.
  *
- * There is exactly one rule to apply: **under `dir="rtl"`, ArrowLeft and
- * ArrowRight swap meaning.** Everything else — Home/End, the vertical arrows,
- * typeahead — is direction-agnostic, so handlers call {@link directionalKey}
- * once at the top and then keep their existing LTR-authored branches.
- *
- * Direction is resolved in this order:
- *
- * 1. an explicit `dir` prop on the component, if it accepts one;
- * 2. the nearest {@link provideDirection};
- * 3. the nearest `[dir]` ancestor **in the DOM** — which is what a plain
- *    `dir="rtl"` attribute on any skdx component produces, since `dir` is a
- *    global HTML attribute and Vue falls it through to the root element;
- * 4. `document.dir`.
- *
- * Step 3 is why most components need no `dir` prop of their own and no
- * provider: `<SkdxTabsList dir="rtl">` already renders `dir="rtl"` on the
- * tablist, and the handler reads it back off `event.currentTarget`.
+ * Resolved in order: an explicit `dir` prop, the nearest {@link provideDirection},
+ * the nearest `[dir]` ancestor in the DOM, then `document.dir`.
  */
 /** Writing direction of a subtree. */
 export type Direction = 'ltr' | 'rtl';
 /**
  * Declares the writing direction for every skdx component in the current
- * component's subtree. Call it from a wrapper component's `setup` when the
- * direction is not already expressed as a `dir` attribute in the DOM.
+ * subtree, for use when direction isn't already a `dir` attribute in the DOM.
  *
  * @example
  * ```ts
@@ -37,12 +21,7 @@ export type Direction = 'ltr' | 'rtl';
  * ```
  */
 export declare function provideDirection(dir: MaybeRefOrGetter<Direction>): void;
-/**
- * The direction declared by an explicit prop or the nearest
- * {@link provideDirection}, or `undefined` when neither is present — in which
- * case {@link directionalKey} falls back to the DOM. Must be called from
- * `setup`; the returned getter may be called at any time.
- */
+/** The direction declared by an explicit prop or the nearest {@link provideDirection} (or `undefined` when neither is present); call it from `setup`, and call the returned getter any time. */
 export declare function useDirection(dirProp?: MaybeRefOrGetter<Direction | undefined>): () => Direction | undefined;
 /** @internal Resolves `el`'s direction, with `override` (prop/provider) winning when set. */
 export declare function resolveDirection(el: Element | null | undefined, override?: Direction): Direction;
@@ -52,23 +31,13 @@ export type LogicalSide = 'start' | 'end' | 'top' | 'bottom';
 export type PhysicalSide = 'left' | 'right' | 'top' | 'bottom';
 /**
  * Resolves a logical edge to the physical one it lands on: `start`/`end` swap
- * under RTL, `top`/`bottom` and already-physical `left`/`right` pass through.
- *
- * Components keep publishing the *logical* value (Drawer's `data-placement`,
- * an overlay's `side` prop) and only resolve at the last moment — a component
- * that stored `left` instead of `start` would break RTL for every consumer
- * downstream.
- *
+ * under RTL, `top`/`bottom` and physical `left`/`right` pass through.
  * @internal
  */
 export declare function resolvePhysicalSide(side: LogicalSide | PhysicalSide, direction: Direction): PhysicalSide;
 /**
- * Translates the key the user physically pressed into the key an
- * LTR-authored handler should act on: in RTL, ArrowLeft and ArrowRight swap.
- * Every other key is returned unchanged, so this is safe to apply
- * unconditionally — including in vertical widgets, where neither key means
- * anything.
- *
+ * Translates the key the user physically pressed into the key an LTR-authored
+ * handler should act on: in RTL, ArrowLeft and ArrowRight swap.
  * @internal
  */
 export declare function directionalKey(key: string, el: Element | null | undefined, override?: Direction): string;

package/dist/utils/dismissal.cjs

@@ -0,0 +1 @@
+var s=[];function c(e,t){return e.insideElements().some(n=>t.insideElements().some(r=>r&&n?.contains(r)))}function a(e){return s.push(e),()=>{const t=s.indexOf(e);t!==-1&&s.splice(t,1)}}function u(e=s){for(let t=e.length-1;t>=0;t--){const n=e[t];if(!e.some(r=>r!==n&&c(n,r)))return n}}function i(e){return u(e?s.filter(t=>t.insideElements().some(n=>n?.contains(e))):[])??u()}function l(e,t,n){return e.key!=="Escape"||!n||i(e.target)!==t?!1:(n(e),e.preventDefault(),!0)}function f(e,t){if(!t)return!0;const n=new CustomEvent(e,{cancelable:!0,detail:null});return t(n),!n.defaultPrevented}function y(e){return new CustomEvent("focus-outside",{detail:e,cancelable:!0})}var o=0;function p(e){o+=1;try{e()}finally{queueMicrotask(()=>{o-=1})}}function m(e){if(o>0)return null;const t=e.target;return!t||t===document.body?null:t}function d(e,t){return!t||e.target!==t?null:e instanceof PointerEvent?e:new PointerEvent("pointerdown",{bubbles:!0,cancelable:!0,composed:!0,pointerType:"mouse",clientX:e.clientX,clientY:e.clientY,screenX:e.screenX,screenY:e.screenY,button:e.button,buttons:e.buttons,ctrlKey:e.ctrlKey,shiftKey:e.shiftKey,altKey:e.altKey,metaKey:e.metaKey})}exports.autoFocusEvent=f;exports.backdropPointerDown=d;exports.escapeLayer=i;exports.focusOnOpen=p;exports.focusOutsideEvent=y;exports.focusOutsideTarget=m;exports.handleEscapeKeyDown=l;exports.pushDismissLayer=a;exports.topDismissLayer=u;