@skdx/vue 0.28.0 → 0.30.0

package/dist/utils/color.d.ts

@@ -1,20 +1,3 @@
-/**
- * Colour maths for pickers, swatches and contrast checks — parsing, the four
- * model conversions, and serialisation back to a string.
- *
- * Deliberately dependency-free and Vue-free: it is imported by
- * `SkdxColorPicker`, but nothing here knows what a component is, so it can be
- * unit-tested as plain arithmetic and reused by a Node-side token pipeline.
- * Mirrors `packages/react/src/utils/color.ts` exactly — a behavioural
- * difference between the two is a bug in one of them.
- *
- * **HSB is the canonical model** for anything that stores a colour over time.
- * RGB and hex cannot represent the hue of a black or a white — every fully
- * dark colour is `#000000` regardless of which hue it came from — so a picker
- * that round-trips through RGB on every drag loses the user's hue the moment
- * they drag brightness to zero. Convert to RGB/hex at the edges, not in the
- * middle.
- */
 /** sRGB colour: `r`/`g`/`b` in `0–255`, `a` in `0–1`. */
 export interface RgbColor {
     r: number;
@@ -29,30 +12,17 @@ export interface HslColor {
     l: number;
     a: number;
 }
-/**
- * HSB (a.k.a. HSV) colour: `h` in `0–360` degrees, `s` (saturation) and `b`
- * (brightness) in `0–100` percent, `a` in `0–1`.
- *
- * Note `b` is **brightness**, not blue — the field names follow the model's
- * own initials, the way `RgbColor.b` follows RGB's.
- */
+/** HSB (a.k.a. HSV) colour: `h` in `0–360` degrees, `s`/`b` in `0–100` percent, `a` in `0–1`; `b` is brightness, not blue. */
 export interface HsbColor {
     h: number;
     s: number;
     b: number;
     a: number;
 }
-/**
- * Serialisation targets for {@link formatColor}. `'hsb'` is this library's own
- * notation (`hsb(210, 60%, 85%)`) rather than a CSS colour — CSS has no HSB
- * function — so it round-trips through {@link parseColor} but must not be
- * dropped into a stylesheet.
- */
+/** Serialisation targets for {@link formatColor}; `'hsb'` is this library's own notation, not CSS, so it round-trips through {@link parseColor} but must not go in a stylesheet. */
 export type ColorFormat = 'hex' | 'rgb' | 'hsl' | 'hsb';
 /**
- * Serialises an sRGB colour as `#rrggbb`, or `#rrggbbaa` when `includeAlpha`
- * is set. Channels are clamped and rounded, so a computed colour with
- * `r: 255.4` still produces valid hex rather than `#ff.6…`.
+ * Serialises an sRGB colour as `#rrggbb`, or `#rrggbbaa` when `includeAlpha` is set, clamping and rounding channels so a computed colour with `r: 255.4` still produces valid hex.
  *
  * @example
  * ```ts
@@ -62,9 +32,7 @@ export type ColorFormat = 'hex' | 'rgb' | 'hsl' | 'hsb';
  */
 export declare function rgbToHex(rgb: RgbColor, includeAlpha?: boolean): string;
 /**
- * Parses `#rgb`, `#rgba`, `#rrggbb` or `#rrggbbaa` (leading `#` optional,
- * case-insensitive) into sRGB. Returns `null` for anything else — including
- * 5- and 7-digit strings, which look like hex but are not a colour.
+ * Parses `#rgb`, `#rgba`, `#rrggbb` or `#rrggbbaa` into sRGB, returning `null` for anything else, including 5- and 7-digit strings that look like hex but aren't a colour.
  *
  * @example
  * ```ts
@@ -74,11 +42,7 @@ export declare function rgbToHex(rgb: RgbColor, includeAlpha?: boolean): string;
  * ```
  */
 export declare function hexToRgb(hex: string): RgbColor | null;
-/**
- * sRGB → HSB. A greyscale colour reports hue `0`, because it genuinely has
- * none — see the module note on why that makes HSB, not RGB, the model to
- * store.
- */
+/** sRGB → HSB. A greyscale colour reports hue `0`, because it genuinely has none. */
 export declare function rgbToHsb(rgb: RgbColor): HsbColor;
 /** HSB → sRGB. */
 export declare function hsbToRgb(hsb: HsbColor): RgbColor;
@@ -86,33 +50,12 @@ export declare function hsbToRgb(hsb: HsbColor): RgbColor;
 export declare function rgbToHsl(rgb: RgbColor): HslColor;
 /** HSL → sRGB. */
 export declare function hslToRgb(hsl: HslColor): RgbColor;
-/**
- * HSB → HSL, computed directly rather than via RGB. The detour would quantise
- * to 8 bits and flatten the hue of any near-black colour, which is exactly the
- * loss this module exists to avoid.
- */
+/** HSB → HSL, computed directly rather than via RGB, since the detour would quantise to 8 bits and flatten near-black hues. */
 export declare function hsbToHsl(hsb: HsbColor): HslColor;
 /** HSL → HSB, the exact inverse of {@link hsbToHsl}, also without an RGB detour. */
 export declare function hslToHsb(hsl: HslColor): HsbColor;
 /**
- * Parses a colour string into the canonical {@link HsbColor}, returning
- * **`null` rather than throwing** for anything it does not understand — this
- * is fed by user-typed text and by whatever a consumer passes as `value`, so
- * "unparseable" is a normal outcome, not an exception.
- *
- * Tolerant about *formatting*, not about vocabulary. It accepts:
- *
- * - hex, with or without `#`, in 3/4/6/8 digits;
- * - `rgb()` / `rgba()`, with numeric or `%` channels;
- * - `hsl()` / `hsla()`, with or without the `%` on saturation/lightness and
- *   with or without `deg` on the hue;
- * - `hsb()` / `hsba()` / `hsv()` / `hsva()`, this library's own notation;
- * - comma-separated *or* space-separated arguments, with the modern
- *   `rgb(255 0 0 / 50%)` slash-alpha form.
- *
- * It does **not** know named colours (`red`, `transparent`), `color()`,
- * `lab()`/`oklch()`, or `turn`/`rad` hue units. Those all return `null`; a
- * 148-entry name table is a dependency's job, not a picker's.
+ * Parses a colour string (hex, `rgb()`, `hsl()`, or this library's own `hsb()`) into the canonical {@link HsbColor}, returning `null` rather than throwing for anything unrecognized, including named colours.
  *
  * @example
  * ```ts
@@ -124,17 +67,7 @@ export declare function hslToHsb(hsl: HslColor): HsbColor;
  */
 export declare function parseColor(input: string): HsbColor | null;
 /**
- * Serialises the canonical {@link HsbColor} back to a string in `format`.
- *
- * Alpha appears **only when it is not 1** — `#ff0000` rather than `#ff0000ff`,
- * `rgb(…)` rather than `rgba(…, 1)` — because that is what every consumer's
- * stylesheet, design tool and clipboard expects, and appending a redundant
- * `ff` to every hex is the fastest way to make a picker's output look wrong.
- * Pass `alpha: false` to drop it unconditionally, for a picker that does not
- * offer transparency at all.
- *
- * `parseColor(formatColor(c, f))` returns `c` to within the precision `f` can
- * carry: exact for `'hsb'`, and 8-bit-quantised for `'hex'` and `'rgb'`.
+ * Serialises the canonical {@link HsbColor} back to a string in `format`, omitting alpha only when it equals 1 unless `alpha: false` forces it off; round-trips through {@link parseColor} to the precision `format` can carry.
  *
  * @example
  * ```ts

package/dist/utils/color.js

@@ -1 +1 @@
-import{clamp as n}from"./clamp.js";function t(n,t=0){const r=10**t;return Math.round(n*r)/r}function r(n){return(n%360+360)%360}function s(t){return n(Math.round(t),0,255).toString(16).padStart(2,"0")}function u(n,t,s,u,e){return e?r(60*(u===n?(t-s)/e:u===t?(s-n)/e+2:(n-t)/e+4)):0}function e(n,s,u,e,l){const a=Math.floor(r(n)/60)%6,[o,c,i]=[[s,u,0],[u,s,0],[0,s,u],[0,u,s],[u,0,s],[s,0,u]][a]??[0,0,0];return{r:t(255*(o+e)),g:t(255*(c+e)),b:t(255*(i+e)),a:l}}function l(t,r=!1){const u=`#${s(t.r)}${s(t.g)}${s(t.b)}`;return r?`${u}${s(255*n(t.a,0,1))}`:u}var a=/^#?([\da-f]{3,8})$/i;function o(n){const r=a.exec(n.trim());if(!r)return null;let s=r[1];if((3===s.length||4===s.length)&&(s=s.split("").map(n=>n+n).join("")),6!==s.length&&8!==s.length)return null;const u=n=>parseInt(s.slice(n,n+2),16);return{r:u(0),g:u(2),b:u(4),a:8===s.length?t(u(6)/255,3):1}}function c(t){const r=n(t.r,0,255)/255,s=n(t.g,0,255)/255,e=n(t.b,0,255)/255,l=Math.max(r,s,e),a=l-Math.min(r,s,e);return{h:u(r,s,e,l,a),s:l?a/l*100:0,b:100*l,a:n(t.a,0,1)}}function i(t){const s=r(t.h),u=n(t.s,0,100)/100,l=n(t.b,0,100)/100,a=l*u;return e(s,a,a*(1-Math.abs(s/60%2-1)),l-a,n(t.a,0,1))}function h(t){const r=n(t.r,0,255)/255,s=n(t.g,0,255)/255,e=n(t.b,0,255)/255,l=Math.max(r,s,e),a=Math.min(r,s,e),o=l-a,c=(l+a)/2,i=o?o/(1-Math.abs(2*c-1)):0;return{h:u(r,s,e,l,o),s:n(100*i,0,100),l:100*c,a:n(t.a,0,1)}}function b(t){const s=r(t.h),u=n(t.s,0,100)/100,l=n(t.l,0,100)/100,a=(1-Math.abs(2*l-1))*u;return e(s,a,a*(1-Math.abs(s/60%2-1)),l-a/2,n(t.a,0,1))}function f(t){const s=n(t.s,0,100)/100,u=n(t.b,0,100)/100,e=u*(1-s/2),l=Math.min(e,1-e);return{h:r(t.h),s:l?(u-e)/l*100:0,l:100*e,a:n(t.a,0,1)}}function $(t){const s=n(t.s,0,100)/100,u=n(t.l,0,100)/100,e=u+s*Math.min(u,1-u);return{h:r(t.h),s:e?2*(1-u/e)*100:0,b:100*e,a:n(t.a,0,1)}}var g=/^(rgba?|hsla?|hsba?|hsva?)\(([^()]*)\)$/;function m(n){if(void 0===n)return null;const t=n.endsWith("%"),r=t?n.slice(0,-1):n.replace(/deg$/,"");if(""===r.trim())return null;const s=Number(r);return Number.isFinite(s)?{value:s,percent:t}:null}function p(n){const t=m(n);return t&&(t.percent?t.value/100*255:t.value)}function M(n){const t=m(n);return t&&t.value}function v(s){return{h:t(r(s.h),2),s:t(n(s.s,0,100),2),b:t(n(s.b,0,100),2),a:t(n(s.a,0,1),3)}}function d(n){if("string"!=typeof n)return null;const t=n.trim().toLowerCase();if(!t)return null;const r=g.exec(t);if(!r){const n=o(t);return n?v(c(n)):null}const s=r[1].replace(/a$/,""),u=r[2].replace(/\//g," ").split(/[\s,]+/).filter(Boolean);if(3!==u.length&&4!==u.length)return null;const e=function(n){if(void 0===n)return 1;const t=m(n);return t&&(t.percent?t.value/100:t.value)}(u[3]);if(null===e)return null;if("rgb"===s){const n=p(u[0]),t=p(u[1]),r=p(u[2]);return null===n||null===t||null===r?null:v(c({r:n,g:t,b:r,a:e}))}const l=M(u[0]),a=M(u[1]),i=M(u[2]);return null===l||null===a||null===i?null:v("hsl"===s?$({h:l,s:a,l:i,a:e}):{h:l,s:a,b:i,a:e})}function T(s,u,e=!0){const a=t(n(s.a,0,1),3),o=e&&a<1;if("rgb"===u){const{r:n,g:t,b:r}=i(s);return o?`rgba(${n}, ${t}, ${r}, ${a})`:`rgb(${n}, ${t}, ${r})`}if("hsl"===u){const n=f(s),r=t(n.h),u=t(n.s),e=t(n.l);return o?`hsla(${r}, ${u}%, ${e}%, ${a})`:`hsl(${r}, ${u}%, ${e}%)`}if("hsb"===u){const u=t(r(s.h)),e=t(n(s.s,0,100)),l=t(n(s.b,0,100));return o?`hsba(${u}, ${e}%, ${l}%, ${a})`:`hsb(${u}, ${e}%, ${l}%)`}return l(i(s),o)}export{T as formatColor,o as hexToRgb,f as hsbToHsl,i as hsbToRgb,$ as hslToHsb,b as hslToRgb,d as parseColor,l as rgbToHex,c as rgbToHsb,h as rgbToHsl};
+function n(n,t,r){return Math.min(Math.max(n,t),r)}function t(n,t=0){const r=10**t;return Math.round(n*r)/r}function r(n){return(n%360+360)%360}function u(t){return n(Math.round(t),0,255).toString(16).padStart(2,"0")}function e(n,t,u,e,s){if(!s)return 0;let l;return l=e===n?(t-u)/s:e===t?(u-n)/s+2:(n-t)/s+4,r(60*l)}function s(n,u,e,s,l){const a=Math.floor(r(n)/60)%6,[o,c,i]=[[u,e,0],[e,u,0],[0,u,e],[0,e,u],[e,0,u],[u,0,e]][a]??[0,0,0];return{r:t(255*(o+s)),g:t(255*(c+s)),b:t(255*(i+s)),a:l}}function l(t,r=!1){const e=`#${u(t.r)}${u(t.g)}${u(t.b)}`;return r?`${e}${u(255*n(t.a,0,1))}`:e}var a=/^#?([\da-f]{3,8})$/i;function o(n){const r=a.exec(n.trim());if(!r)return null;let u=r[1];if((3===u.length||4===u.length)&&(u=u.split("").map(n=>n+n).join("")),6!==u.length&&8!==u.length)return null;const e=n=>parseInt(u.slice(n,n+2),16);return{r:e(0),g:e(2),b:e(4),a:8===u.length?t(e(6)/255,3):1}}function c(t){const r=n(t.r,0,255)/255,u=n(t.g,0,255)/255,s=n(t.b,0,255)/255,l=Math.max(r,u,s),a=l-Math.min(r,u,s);return{h:e(r,u,s,l,a),s:l?a/l*100:0,b:100*l,a:n(t.a,0,1)}}function i(t){const u=r(t.h),e=n(t.s,0,100)/100,l=n(t.b,0,100)/100,a=l*e;return s(u,a,a*(1-Math.abs(u/60%2-1)),l-a,n(t.a,0,1))}function h(t){const r=n(t.r,0,255)/255,u=n(t.g,0,255)/255,s=n(t.b,0,255)/255,l=Math.max(r,u,s),a=Math.min(r,u,s),o=l-a,c=(l+a)/2,i=o?o/(1-Math.abs(2*c-1)):0;return{h:e(r,u,s,l,o),s:n(100*i,0,100),l:100*c,a:n(t.a,0,1)}}function f(t){const u=r(t.h),e=n(t.s,0,100)/100,l=n(t.l,0,100)/100,a=(1-Math.abs(2*l-1))*e;return s(u,a,a*(1-Math.abs(u/60%2-1)),l-a/2,n(t.a,0,1))}function b(t){const u=n(t.s,0,100)/100,e=n(t.b,0,100)/100,s=e*(1-u/2),l=Math.min(s,1-s);return{h:r(t.h),s:l?(e-s)/l*100:0,l:100*s,a:n(t.a,0,1)}}function $(t){const u=n(t.s,0,100)/100,e=n(t.l,0,100)/100,s=e+u*Math.min(e,1-e);return{h:r(t.h),s:s?2*(1-e/s)*100:0,b:100*s,a:n(t.a,0,1)}}var g=/^(rgba?|hsla?|hsba?|hsva?)\(([^()]*)\)$/;function m(n){if(void 0===n)return null;const t=n.endsWith("%"),r=t?n.slice(0,-1):n.replace(/deg$/,"");if(""===r.trim())return null;const u=Number(r);return Number.isFinite(u)?{value:u,percent:t}:null}function M(n){const t=m(n);return t&&(t.percent?t.value/100*255:t.value)}function p(n){const t=m(n);return t&&t.value}function v(u){return{h:t(r(u.h),2),s:t(n(u.s,0,100),2),b:t(n(u.b,0,100),2),a:t(n(u.a,0,1),3)}}function d(n){if("string"!=typeof n)return null;const t=n.trim().toLowerCase();if(!t)return null;const r=g.exec(t);if(!r){const n=o(t);return n?v(c(n)):null}const u=r[1].replace(/a$/,""),e=r[2].replace(/\//g," ").split(/[\s,]+/).filter(Boolean);return 3!==e.length&&4!==e.length?null:function(n,t){const r=function(n){if(void 0===n)return 1;const t=m(n);return t&&(t.percent?t.value/100:t.value)}(t[3]);if(null===r)return null;if("rgb"===n){const n=M(t[0]),u=M(t[1]),e=M(t[2]);return null===n||null===u||null===e?null:v(c({r:n,g:u,b:e,a:r}))}const u=p(t[0]),e=p(t[1]),s=p(t[2]);return null===u||null===e||null===s?null:v("hsl"===n?$({h:u,s:e,l:s,a:r}):{h:u,s:e,b:s,a:r})}(u,e)}function x(u,e,s=!0){const a=t(n(u.a,0,1),3),o=s&&a<1;if("rgb"===e){const{r:n,g:t,b:r}=i(u);return o?`rgba(${n}, ${t}, ${r}, ${a})`:`rgb(${n}, ${t}, ${r})`}if("hsl"===e){const n=b(u),r=t(n.h),e=t(n.s),s=t(n.l);return o?`hsla(${r}, ${e}%, ${s}%, ${a})`:`hsl(${r}, ${e}%, ${s}%)`}if("hsb"===e){const e=t(r(u.h)),s=t(n(u.s,0,100)),l=t(n(u.b,0,100));return o?`hsba(${e}, ${s}%, ${l}%, ${a})`:`hsb(${e}, ${s}%, ${l}%)`}return l(i(u),o)}export{x as formatColor,o as hexToRgb,b as hsbToHsl,i as hsbToRgb,$ as hslToHsb,f as hslToRgb,d as parseColor,l as rgbToHex,c as rgbToHsb,h as rgbToHsl};

package/dist/utils/composeRefs.d.cts

@@ -1,27 +1,11 @@
 import type { ComponentPublicInstance, Ref } from 'vue';
-/**
- * Anything a composed template ref is willing to write an element into: a Vue
- * `ref`, a plain setter function (for context state that isn't a `ref`), or
- * nothing at all, so call sites can pass an optional target unconditionally.
- */
+/** Anything a composed template ref can write into: a Vue `ref`, a plain setter, or nothing at all. */
 export type PossibleRef<T> = Ref<T | null> | ((node: T | null) => void) | null | undefined;
 /** The value Vue hands to a function template ref on mount and on unmount. */
 export type TemplateRefValue = Element | ComponentPublicInstance | null;
 /**
- * Merges any number of refs into a single function template ref, the Vue
- * counterpart of this package's React `composeRefs`. Bind with `:ref="..."`
- * wherever a component both keeps its own ref on a node and has to publish
- * that node elsewhere — a parent's context, most often.
- *
- * Timing matters: Vue invokes a function template ref synchronously from the
- * mount patch (and again with `null` on unmount), like React committing a
- * callback ref. A `watchEffect` instead lands a tick late — long enough for a
- * keyboard handler on an already-open popup to read an empty context ref —
- * and on unmount, a stopped effect scope never observes the ref going back to
- * `null`, leaving a detached element behind.
- *
- * Targets are written in the order given; refs are only invoked client-side,
- * so this stays SSR-safe.
+ * Merges any number of refs into a single function template ref, written
+ * synchronously on mount/unmount — unlike a `watchEffect`, which lands a tick late.
  *
  * @example
  * ```ts

package/dist/utils/composeRefs.d.ts

@@ -1,27 +1,11 @@
 import type { ComponentPublicInstance, Ref } from 'vue';
-/**
- * Anything a composed template ref is willing to write an element into: a Vue
- * `ref`, a plain setter function (for context state that isn't a `ref`), or
- * nothing at all, so call sites can pass an optional target unconditionally.
- */
+/** Anything a composed template ref can write into: a Vue `ref`, a plain setter, or nothing at all. */
 export type PossibleRef<T> = Ref<T | null> | ((node: T | null) => void) | null | undefined;
 /** The value Vue hands to a function template ref on mount and on unmount. */
 export type TemplateRefValue = Element | ComponentPublicInstance | null;
 /**
- * Merges any number of refs into a single function template ref, the Vue
- * counterpart of this package's React `composeRefs`. Bind with `:ref="..."`
- * wherever a component both keeps its own ref on a node and has to publish
- * that node elsewhere — a parent's context, most often.
- *
- * Timing matters: Vue invokes a function template ref synchronously from the
- * mount patch (and again with `null` on unmount), like React committing a
- * callback ref. A `watchEffect` instead lands a tick late — long enough for a
- * keyboard handler on an already-open popup to read an empty context ref —
- * and on unmount, a stopped effect scope never observes the ref going back to
- * `null`, leaving a detached element behind.
- *
- * Targets are written in the order given; refs are only invoked client-side,
- * so this stays SSR-safe.
+ * Merges any number of refs into a single function template ref, written
+ * synchronously on mount/unmount — unlike a `watchEffect`, which lands a tick late.
  *
  * @example
  * ```ts

package/dist/utils/controllable.cjs

@@ -0,0 +1 @@
+const u=require("./selection.cjs");function n(e,r){return Object.is(e,r)?!0:!Array.isArray(e)||!Array.isArray(r)||!e.every(t=>typeof t=="string")||!r.every(t=>typeof t=="string")?!1:u.sameSelection(e,r)}function i({controlled:e,uncontrolled:r}){return e!==void 0?e:r}function l({controlled:e}){return e!==void 0}function o(e,r){const t=i(e);return n(t,r)?{value:t,write:!1,emit:!1}:{value:r,write:!l(e),emit:!0}}function s(e,r){return o(e,r)}exports.controllableValue=i;exports.decideControllable=o;exports.decideReset=s;exports.isControlled=l;exports.sameControlledValue=n;

package/dist/utils/controllable.d.cts

@@ -0,0 +1,42 @@
+/**
+ * Whether two values are indistinguishable to a consumer, so no event is owed: `Object.is` for scalars, element-wise for the string arrays a selection carries.
+ *
+ * @param a the value now
+ * @param b the value proposed
+ */
+export declare function sameControlledValue(a: unknown, b: unknown): boolean;
+/** What the adapter currently holds on both sides of the controlled/uncontrolled split. */
+export interface ControllableState<T> {
+    /** The consumer's controlled value; `undefined` means the control owns its own value. */
+    controlled: T | undefined;
+    /** The value the adapter holds while uncontrolled; ignored once `controlled` is defined. */
+    uncontrolled: T | undefined;
+}
+/** What the adapter should do about a proposed change. */
+export interface ControllableDecision<T> {
+    /** The value in force after this decision — the proposal, or the current value when nothing changed. */
+    value: T | undefined;
+    /** Whether the adapter writes its own state; always `false` while controlled, since the consumer owns the value. */
+    write: boolean;
+    /** Whether the change event fires; only on an actual change, in both modes. */
+    emit: boolean;
+}
+/** The value in force: the controlled one when there is one, the adapter's own otherwise. */
+export declare function controllableValue<T>({ controlled, uncontrolled, }: ControllableState<T>): T | undefined;
+/** Whether the consumer owns the value, which is exactly "a controlled value was supplied". */
+export declare function isControlled<T>({ controlled }: ControllableState<T>): boolean;
+/**
+ * The decision for one proposed change.
+ *
+ * @param state what the adapter holds on both sides
+ * @param next the proposed value
+ * @returns the value in force, whether to write it, and whether to emit
+ */
+export declare function decideControllable<T>(state: ControllableState<T>, next: T | undefined): ControllableDecision<T>;
+/**
+ * The decision for a form reset, which restores `defaultValue` as it reads *now* — a consumer that changed the prop after mount expects the new default back, not the one the control was born with.
+ *
+ * @param state what the adapter holds on both sides
+ * @param liveDefault the `defaultValue` prop read at reset time
+ */
+export declare function decideReset<T>(state: ControllableState<T>, liveDefault: T | undefined): ControllableDecision<T>;

package/dist/utils/controllable.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Whether two values are indistinguishable to a consumer, so no event is owed: `Object.is` for scalars, element-wise for the string arrays a selection carries.
+ *
+ * @param a the value now
+ * @param b the value proposed
+ */
+export declare function sameControlledValue(a: unknown, b: unknown): boolean;
+/** What the adapter currently holds on both sides of the controlled/uncontrolled split. */
+export interface ControllableState<T> {
+    /** The consumer's controlled value; `undefined` means the control owns its own value. */
+    controlled: T | undefined;
+    /** The value the adapter holds while uncontrolled; ignored once `controlled` is defined. */
+    uncontrolled: T | undefined;
+}
+/** What the adapter should do about a proposed change. */
+export interface ControllableDecision<T> {
+    /** The value in force after this decision — the proposal, or the current value when nothing changed. */
+    value: T | undefined;
+    /** Whether the adapter writes its own state; always `false` while controlled, since the consumer owns the value. */
+    write: boolean;
+    /** Whether the change event fires; only on an actual change, in both modes. */
+    emit: boolean;
+}
+/** The value in force: the controlled one when there is one, the adapter's own otherwise. */
+export declare function controllableValue<T>({ controlled, uncontrolled, }: ControllableState<T>): T | undefined;
+/** Whether the consumer owns the value, which is exactly "a controlled value was supplied". */
+export declare function isControlled<T>({ controlled }: ControllableState<T>): boolean;
+/**
+ * The decision for one proposed change.
+ *
+ * @param state what the adapter holds on both sides
+ * @param next the proposed value
+ * @returns the value in force, whether to write it, and whether to emit
+ */
+export declare function decideControllable<T>(state: ControllableState<T>, next: T | undefined): ControllableDecision<T>;
+/**
+ * The decision for a form reset, which restores `defaultValue` as it reads *now* — a consumer that changed the prop after mount expects the new default back, not the one the control was born with.
+ *
+ * @param state what the adapter holds on both sides
+ * @param liveDefault the `defaultValue` prop read at reset time
+ */
+export declare function decideReset<T>(state: ControllableState<T>, liveDefault: T | undefined): ControllableDecision<T>;

package/dist/utils/controllable.js

@@ -0,0 +1 @@
+import{sameSelection as e}from"./selection.js";function r(r,t){return!!Object.is(r,t)||!!(Array.isArray(r)&&Array.isArray(t)&&r.every(e=>"string"==typeof e)&&t.every(e=>"string"==typeof e))&&e(r,t)}function t({controlled:e,uncontrolled:r}){return void 0!==e?e:r}function o({controlled:e}){return void 0!==e}function n(e,n){const i=t(e);return r(i,n)?{value:i,write:!1,emit:!1}:{value:n,write:!o(e),emit:!0}}function i(e,r){return n(e,r)}export{t as controllableValue,n as decideControllable,i as decideReset,o as isControlled,r as sameControlledValue};

package/dist/utils/date-segments.cjs

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

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

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