@skdx/docs-kit 0.35.0

package/dist/shared/core/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/shared/core/date-segments.js

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

package/dist/shared/core/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/shared/core/date-value.js

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

package/dist/shared/core/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/shared/core/dev-mode.js

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

package/dist/shared/core/dialogs.d.ts

@@ -0,0 +1,96 @@
+/** Which of the three canned dialogs an entry is. */
+export type DialogsKind = 'alert' | 'confirm' | 'prompt';
+/** Options common to alert, confirm and prompt; a bare string is the title. */
+export interface DialogsOptions {
+    /** Heading of the dialog, rendered as its title and accessible name. */
+    title: string;
+    /**
+     * Body text under the title, rendered as the dialog's description.
+     *
+     * @default undefined — no description.
+     */
+    description?: string | undefined;
+    /**
+     * Label of the confirming button.
+     *
+     * @default 'OK' for alert and prompt, 'Confirm' for confirm
+     */
+    confirmLabel?: string | undefined;
+    /**
+     * Label of the cancelling button; alerts have none.
+     *
+     * @default 'Cancel'
+     */
+    cancelLabel?: string | undefined;
+    /**
+     * Severity rung the skin colours the dialog by, mirrored to `data-status`.
+     *
+     * @default undefined — the skin's own default.
+     */
+    status?: string | undefined;
+}
+/** Options for a prompt, which adds a single text field to the confirm shape. */
+export interface DialogsPromptOptions extends DialogsOptions {
+    /**
+     * Text the field starts with.
+     *
+     * @default ''
+     */
+    defaultValue?: string | undefined;
+    /**
+     * Visible label of the text field.
+     *
+     * @default 'Value'
+     */
+    label?: string | undefined;
+    /**
+     * Placeholder shown in the empty field.
+     *
+     * @default undefined — no placeholder.
+     */
+    placeholder?: string | undefined;
+}
+/** A queued dialog as the host renders it: resolved options plus the settle callback. */
+export interface DialogsEntry extends DialogsPromptOptions {
+    /** Stable identity, for keying the rendered dialog. */
+    id: string;
+    /** Which canned dialog this is. */
+    kind: DialogsKind;
+    /** Resolved confirming label, never undefined. */
+    confirmLabel: string;
+    /** Resolved cancelling label, `undefined` for alerts. */
+    cancelLabel: string | undefined;
+}
+/** What settling an entry hands back: nothing for alert, a boolean for confirm, text or null for prompt. */
+export type DialogsResult = void | boolean | string | null;
+/** The queue every host renders from and every caller awaits on. */
+export interface DialogsStore {
+    /** Subscribes to queue changes. Returns its own unsubscribe. */
+    subscribe: (listener: () => void) => () => void;
+    /** The entry currently shown, or `null` — a stable reference until the queue changes. */
+    getCurrent: () => DialogsEntry | null;
+    /** Shows a message with one button; resolves when it is dismissed. */
+    alert(options: DialogsOptions | string): Promise<void>;
+    /** Asks a yes/no question; resolves `true` on confirm, `false` on cancel or dismissal. */
+    confirm(options: DialogsOptions | string): Promise<boolean>;
+    /** Asks for one line of text; resolves the text on confirm, `null` on cancel or dismissal. */
+    prompt(options: DialogsPromptOptions | string): Promise<string | null>;
+    /** Resolves and removes the entry with `id`, then shows the next one. No-ops for an id that is not current. */
+    settle(id: string, result: DialogsResult): void;
+}
+/**
+ * Creates the dialog queue once per app. Hand it to the `Dialogs` host and call
+ * `alert`, `confirm` or `prompt` from anywhere; each returns a promise that
+ * settles with the user's answer.
+ *
+ * @example
+ * ```ts
+ * const dialogs = createDialogs();
+ * if (await dialogs.confirm({ title: 'Delete the project?', status: 'danger' })) remove();
+ * ```
+ */
+export declare function createDialogs(): DialogsStore;
+/** What cancelling or dismissing `entry` resolves with: `false` for confirm, `null` for prompt, nothing for alert. */
+export declare function dialogsCancelResult(entry: DialogsEntry): DialogsResult;
+/** What confirming `entry` resolves with: `true` for confirm, the typed `draft` for prompt, nothing for alert. */
+export declare function dialogsConfirmResult(entry: DialogsEntry, draft: string): DialogsResult;

package/dist/shared/core/dialogs.js

@@ -0,0 +1 @@
+var d={alert:"OK",confirm:"Confirm",prompt:"OK"};function g(){let n=[],i=new Set,l=0;function s(){for(let e of i)e()}function o(e,t){let r=typeof t=="string"?{title:t}:t,a={...r,id:`skdx-dialogs-${++l}`,kind:e,confirmLabel:r.confirmLabel??d[e],cancelLabel:e==="alert"?void 0:r.cancelLabel??"Cancel"};return new Promise(u=>{n.push({entry:a,resolve:u}),n.length===1&&s()})}return{subscribe(e){return i.add(e),()=>{i.delete(e)}},getCurrent:()=>n[0]?.entry??null,alert:e=>o("alert",e).then(()=>{}),confirm:e=>o("confirm",e).then(t=>t===!0),prompt:e=>o("prompt",e).then(t=>typeof t=="string"?t:null),settle(e,t){if(n[0]?.entry.id!==e)return;let{resolve:r}=n.shift();r(t),s()}}}function f(n){if(n.kind==="confirm")return!1;if(n.kind==="prompt")return null}function p(n,i){if(n.kind==="confirm")return!0;if(n.kind==="prompt")return i}export{g as createDialogs,f as dialogsCancelResult,p as dialogsConfirmResult};

package/dist/shared/core/dismissal.d.ts

@@ -0,0 +1,56 @@
+/** What `onFocusOutside` receives: `focusin` is not cancelable, so the handler gets a cancelable stand-in carrying the original as its `detail`. */
+export type FocusOutsideEvent = CustomEvent<FocusEvent>;
+/** Either flavour of outside interaction, as `onInteractOutside` sees it. */
+export type InteractOutsideEvent = PointerEvent | FocusOutsideEvent;
+/** One open dismissible layer, as the stack knows it: only what counts as inside it. */
+export interface DismissLayer {
+    /** The layer's own elements, read fresh each time since a panel mounts and unmounts under the same layer. */
+    insideElements: () => Array<Element | null | undefined>;
+}
+/** Registers an open layer and returns its teardown; layers close out of order (a parent unmount takes its children), so the teardown removes by identity, not by position. */
+export declare function pushDismissLayer(layer: DismissLayer): () => void;
+/**
+ * Whether `target` sits inside a layer that opened within `layer`: a portalled
+ * listbox or popover whose trigger lives in this panel. `contains()` cannot see
+ * it, so an outside-interaction check must ask the stack as well. Transitive,
+ * so a Select inside a Popover inside a Dialog still counts for the Dialog.
+ */
+export declare function nestedLayerContains(layer: DismissLayer, target: Node): boolean;
+/** The layer nothing else is open inside: push order cannot rank nested layers, because a framework's effects run child-first. */
+export declare function topDismissLayer(candidates?: readonly DismissLayer[]): DismissLayer | undefined;
+/** The one layer an Escape belongs to: sibling non-modal layers can be open at once, so the layer holding the key's target answers, and the top layer only when none does. */
+export declare function escapeLayer(target: Node | null): DismissLayer | undefined;
+/**
+ * Runs one layer's share of a document-level Escape keydown: at most one layer
+ * handles a given Escape, and `preventDefault()` comes after the consumer's
+ * handler — never before, so a veto is read from the same event — and only when
+ * this layer was the one that handled it. Preventing matters because the close
+ * watcher of an ancestor native `<dialog>` skips a canceled Escape, which is
+ * what stops one press from closing both the top layer and the Dialog around it.
+ *
+ * Listen on the document, not the panel: a layer must answer Escape while focus
+ * sits outside it (virtual focus, a portalled submenu), which a panel-level
+ * listener never sees.
+ *
+ * @param event the document keydown
+ * @param layer the layer asking whether the key is its own
+ * @param handler the consumer's Escape handler, or `undefined` for a layer that leaves Escape to the platform (a native `<dialog>`)
+ * @returns whether this layer handled the key
+ */
+export declare function handleEscapeKeyDown(event: KeyboardEvent, layer: DismissLayer, handler: ((event: KeyboardEvent) => void) | undefined): boolean;
+/** The cancelable stand-in an auto-focus handler receives; there is no native event for "about to move focus". */
+export type AutoFocusEvent = CustomEvent<null>;
+/** Announces an automatic focus move as a cancelable event and reports whether it may go ahead. */
+export declare function autoFocusEvent(type: 'open-auto-focus' | 'close-auto-focus', handler?: (event: AutoFocusEvent) => void): boolean;
+/** The cancelable stand-in for a `focusin` that landed outside the layer. */
+export declare function focusOutsideEvent(event: FocusEvent): FocusOutsideEvent;
+/** Marks an overlay's open-time focus move so other layers don't read it as outside interaction; released in a microtask because `focus()` dispatches `focusin` synchronously. */
+export declare function focusOnOpen(move: () => void): void;
+/** The node a `focusin` moved focus to, or `null` when it is not a move this layer may be dismissed by: another layer opening, or focus clearing to `<body>`. */
+export declare function focusOutsideTarget(event: FocusEvent): Node | null;
+/** Whether an outside-interaction target is the overlay's own trigger, including through the trigger's shadow root. */
+export declare function triggerContains(trigger: Element | null | undefined, target: Node | null): boolean;
+/**
+ * The native `<dialog>` backdrop, normalised onto the same `PointerEvent` channel as every other outside pointer-down, or `null` when the press landed inside the panel. The backdrop is not an element: a pointer on it targets the dialog itself, which `contains()` would misread as inside.
+ */
+export declare function backdropPointerDown(event: MouseEvent, dialog: Element | null | undefined): PointerEvent | null;

package/dist/shared/core/dismissal.js

@@ -0,0 +1 @@
+var s=[];function c(e,n){let t=n;for(;t;){if(e.contains(t))return!0;let o=t.getRootNode();t=o instanceof ShadowRoot?o.host:null}return!1}function a(e,n){return e.insideElements().some(t=>n.insideElements().some(o=>o&&t&&c(t,o)))}function d(e){return s.push(e),()=>{let n=s.indexOf(e);n!==-1&&s.splice(n,1)}}function m(e,n){let t=new Set([e]),o=!0;for(;o;){o=!1;for(let u of s)t.has(u)||[...t].some(r=>a(r,u))&&(t.add(u),o=!0)}return t.delete(e),[...t].some(u=>u.insideElements().some(r=>r&&c(r,n)))}function l(e=s){for(let n=e.length-1;n>=0;n--){let t=e[n];if(!e.some(o=>o!==t&&a(t,o)))return t}}function f(e){let n=e?s.filter(t=>t.insideElements().some(o=>o?.contains(e))):[];return l(n)??l()}function y(e,n,t){return e.key!=="Escape"||!t||f(e.target)!==n?!1:(t(e),e.preventDefault(),!0)}function p(e,n){if(!n)return!0;let t=new CustomEvent(e,{cancelable:!0,detail:null});return n(t),!t.defaultPrevented}function E(e){return new CustomEvent("focus-outside",{detail:e,cancelable:!0})}var i=0;function b(e){i+=1;try{e()}finally{queueMicrotask(()=>{i-=1})}}function v(e){if(i>0)return null;let n=e.target;return!n||n===document.body?null:n}function x(e,n){if(!e||!n)return!1;if(e.contains(n))return!0;let t=e.getRootNode();return t instanceof ShadowRoot&&t.host.contains(n)}function D(e,n){return!n||e.target!==n?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})}export{p as autoFocusEvent,D as backdropPointerDown,f as escapeLayer,b as focusOnOpen,E as focusOutsideEvent,v as focusOutsideTarget,y as handleEscapeKeyDown,m as nestedLayerContains,d as pushDismissLayer,l as topDismissLayer,x as triggerContains};