@skdx/vue 0.26.0

package/dist/utils/color.d.cts

@@ -0,0 +1,147 @@
+/**
+ * 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;
+    g: number;
+    b: number;
+    a: number;
+}
+/** HSL colour: `h` in `0–360` degrees, `s`/`l` in `0–100` percent, `a` in `0–1`. */
+export interface HslColor {
+    h: number;
+    s: number;
+    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.
+ */
+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.
+ */
+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…`.
+ *
+ * @example
+ * ```ts
+ * rgbToHex({ r: 217, g: 76, b: 76, a: 0.5 });       // '#d94c4c'
+ * rgbToHex({ r: 217, g: 76, b: 76, a: 0.5 }, true); // '#d94c4c80'
+ * ```
+ */
+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.
+ *
+ * @example
+ * ```ts
+ * hexToRgb('#f00');       // { r: 255, g: 0, b: 0, a: 1 }
+ * hexToRgb('#ff000080');  // { r: 255, g: 0, b: 0, a: 0.502 }
+ * hexToRgb('nope');       // null
+ * ```
+ */
+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.
+ */
+export declare function rgbToHsb(rgb: RgbColor): HsbColor;
+/** HSB → sRGB. */
+export declare function hsbToRgb(hsb: HsbColor): RgbColor;
+/** sRGB → HSL. */
+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.
+ */
+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.
+ *
+ * @example
+ * ```ts
+ * parseColor('#d94c4c');                 // { h: 0, s: 64.98, b: 85.1, a: 1 }
+ * parseColor('rgb(255 0 0 / 50%)');      // { h: 0, s: 100, b: 100, a: 0.5 }
+ * parseColor('hsl(210, 60%, 85%)');      // { h: 210, s: 19.15, b: 94, a: 1 }
+ * parseColor('rebeccapurple');           // null
+ * ```
+ */
+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'`.
+ *
+ * @example
+ * ```ts
+ * formatColor({ h: 0, s: 100, b: 100, a: 1 }, 'hex');          // '#ff0000'
+ * formatColor({ h: 0, s: 100, b: 100, a: 0.5 }, 'hex');        // '#ff000080'
+ * formatColor({ h: 0, s: 100, b: 100, a: 0.5 }, 'rgb');        // 'rgba(255, 0, 0, 0.5)'
+ * formatColor({ h: 0, s: 100, b: 100, a: 0.5 }, 'hex', false); // '#ff0000'
+ * ```
+ */
+export declare function formatColor(color: HsbColor, format: ColorFormat, alpha?: boolean): string;

package/dist/utils/color.d.ts

@@ -0,0 +1,147 @@
+/**
+ * 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;
+    g: number;
+    b: number;
+    a: number;
+}
+/** HSL colour: `h` in `0–360` degrees, `s`/`l` in `0–100` percent, `a` in `0–1`. */
+export interface HslColor {
+    h: number;
+    s: number;
+    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.
+ */
+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.
+ */
+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…`.
+ *
+ * @example
+ * ```ts
+ * rgbToHex({ r: 217, g: 76, b: 76, a: 0.5 });       // '#d94c4c'
+ * rgbToHex({ r: 217, g: 76, b: 76, a: 0.5 }, true); // '#d94c4c80'
+ * ```
+ */
+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.
+ *
+ * @example
+ * ```ts
+ * hexToRgb('#f00');       // { r: 255, g: 0, b: 0, a: 1 }
+ * hexToRgb('#ff000080');  // { r: 255, g: 0, b: 0, a: 0.502 }
+ * hexToRgb('nope');       // null
+ * ```
+ */
+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.
+ */
+export declare function rgbToHsb(rgb: RgbColor): HsbColor;
+/** HSB → sRGB. */
+export declare function hsbToRgb(hsb: HsbColor): RgbColor;
+/** sRGB → HSL. */
+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.
+ */
+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.
+ *
+ * @example
+ * ```ts
+ * parseColor('#d94c4c');                 // { h: 0, s: 64.98, b: 85.1, a: 1 }
+ * parseColor('rgb(255 0 0 / 50%)');      // { h: 0, s: 100, b: 100, a: 0.5 }
+ * parseColor('hsl(210, 60%, 85%)');      // { h: 210, s: 19.15, b: 94, a: 1 }
+ * parseColor('rebeccapurple');           // null
+ * ```
+ */
+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'`.
+ *
+ * @example
+ * ```ts
+ * formatColor({ h: 0, s: 100, b: 100, a: 1 }, 'hex');          // '#ff0000'
+ * formatColor({ h: 0, s: 100, b: 100, a: 0.5 }, 'hex');        // '#ff000080'
+ * formatColor({ h: 0, s: 100, b: 100, a: 0.5 }, 'rgb');        // 'rgba(255, 0, 0, 0.5)'
+ * formatColor({ h: 0, s: 100, b: 100, a: 0.5 }, 'hex', false); // '#ff0000'
+ * ```
+ */
+export declare function formatColor(color: HsbColor, format: ColorFormat, alpha?: boolean): string;

package/dist/utils/color.js

@@ -0,0 +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};

package/dist/utils/composeRefs.cjs

@@ -0,0 +1 @@
+function c(f,s){typeof f=="function"?f(s):f&&(f.value=s)}function i(...f){return s=>{const n=(s&&"$el"in s?s.$el:s)??null;for(const o of f)c(o,n)}}exports.composeRefs=i;

package/dist/utils/composeRefs.d.cts

@@ -0,0 +1,40 @@
+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.
+ */
+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 the result with
+ * `:ref="..."` wherever a component both keeps its own ref on a node and has
+ * to publish that node somewhere else — a parent's context, most often.
+ *
+ * The point is *when* the write happens. Vue invokes a function template ref
+ * synchronously from inside the patch that mounts the element, and again with
+ * `null` from inside the patch that unmounts it, exactly like React committing
+ * a callback ref. Publishing through a `watchEffect` instead costs a full tick
+ * (the effect is a pre-flush job, so it lands on the flush *after* the ref is
+ * assigned), which is long enough for a keyboard handler on an already-open
+ * popup to read an empty context ref and no-op. The unmount half matters just
+ * as much: a component's effect scope is stopped *before* its subtree is
+ * unmounted, so a watcher never observes the ref going back to `null` and the
+ * context is left holding a detached element.
+ *
+ * Targets are written in the order given, which matters only for a setter that
+ * compares against another target's previous value — list it first.
+ *
+ * Refs are only ever invoked on the client — Vue does not set template refs
+ * while server-rendering — so this stays SSR-safe.
+ *
+ * @example
+ * ```ts
+ * const contentRef = ref<HTMLElement | null>(null);
+ * const setContentRef = composeRefs(contentRef, context.contentRef);
+ * // <div :ref="setContentRef" />
+ * ```
+ */
+export declare function composeRefs<T extends Element = HTMLElement>(...refs: PossibleRef<T>[]): (node: TemplateRefValue) => void;

package/dist/utils/composeRefs.d.ts

@@ -0,0 +1,40 @@
+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.
+ */
+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 the result with
+ * `:ref="..."` wherever a component both keeps its own ref on a node and has
+ * to publish that node somewhere else — a parent's context, most often.
+ *
+ * The point is *when* the write happens. Vue invokes a function template ref
+ * synchronously from inside the patch that mounts the element, and again with
+ * `null` from inside the patch that unmounts it, exactly like React committing
+ * a callback ref. Publishing through a `watchEffect` instead costs a full tick
+ * (the effect is a pre-flush job, so it lands on the flush *after* the ref is
+ * assigned), which is long enough for a keyboard handler on an already-open
+ * popup to read an empty context ref and no-op. The unmount half matters just
+ * as much: a component's effect scope is stopped *before* its subtree is
+ * unmounted, so a watcher never observes the ref going back to `null` and the
+ * context is left holding a detached element.
+ *
+ * Targets are written in the order given, which matters only for a setter that
+ * compares against another target's previous value — list it first.
+ *
+ * Refs are only ever invoked on the client — Vue does not set template refs
+ * while server-rendering — so this stays SSR-safe.
+ *
+ * @example
+ * ```ts
+ * const contentRef = ref<HTMLElement | null>(null);
+ * const setContentRef = composeRefs(contentRef, context.contentRef);
+ * // <div :ref="setContentRef" />
+ * ```
+ */
+export declare function composeRefs<T extends Element = HTMLElement>(...refs: PossibleRef<T>[]): (node: TemplateRefValue) => void;

package/dist/utils/composeRefs.js

@@ -0,0 +1 @@
+function n(n,o){"function"==typeof n?n(o):n&&(n.value=o)}function o(...o){return e=>{const t=(e&&"$el"in e?e.$el:e)??null;for(const e of o)n(e,t)}}export{o as composeRefs};

package/dist/utils/dateSegments.cjs

@@ -0,0 +1 @@
+var f={year:"yyyy",month:"mm",day:"dd",hour:"hh",minute:"mm",second:"ss",dayPeriod:"--"},S="Empty",p={year:"year",month:"month",day:"day",hour:"hour",minute:"minute",second:"second",dayPeriod:"AM/PM"},D={year:4,month:2,day:2,hour:2,minute:2,second:2,dayPeriod:0},v=Date.UTC(2024,0,15,13,45,56),m=new Map,d=new Map;function c(e){return e??new Intl.DateTimeFormat().resolvedOptions().locale}function y(e,t){if(t===12||t===24)return t;const n=new Intl.DateTimeFormat(c(e),{hour:"numeric"}).resolvedOptions(),r=n.hourCycle??(n.hour12?"h12":"h23");return r==="h11"||r==="h12"?12:24}function h(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 g(e,t){return!e||!t?31:new Date(e,t,0).getDate()}function T(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:g(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 E(e){const t=c(e),n=d.get(t);if(n)return n;const r=new Intl.DateTimeFormat(t,{hour:"numeric",hourCycle:"h12",timeZone:"UTC"}),o=u=>r.formatToParts(Date.UTC(2024,0,15,u)).find(a=>a.type==="dayPeriod")?.value??(u<12?"AM":"PM"),i=[o(1),o(13)];return d.set(t,i),i}function x(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 M(e,t,n){const r=`${e}|${t.join(",")}|${n}`,o=m.get(r);if(o)return o;const i=new Intl.DateTimeFormat(e,x(t,n)).formatToParts(v),u=[];for(const a of i)a.type==="literal"?u.push({type:"literal",text:a.value.replace(/[\u202F\u2009\u00A0]/g," "),value:null,min:0,max:0,isPlaceholder:!1,isEditable:!1}):(a.type==="dayPeriod"||t.includes(a.type))&&u.push({type:a.type,text:"",value:null,min:0,max:0,isPlaceholder:!0,isEditable:!0});return m.set(r,u),u}function P(e,t,n){return t===null?f[e]:e==="dayPeriod"?E(n)[t===0?0:1]:String(t).padStart(D[e],"0")}function $(e){const t=c(e.locale),n=y(t,e.hourCycle);return M(t,h(e.kind,e.granularity),n).map(r=>{if(!r.isEditable)return r;const o=r.type,i=e.values[o]??null,{min:u,max:a}=T(o,e.values,n);return{type:o,text:P(o,i,t),value:i,min:u,max:a,isPlaceholder:i===null,isEditable:!0}})}function F(e,t){const{min:n,max:r}=e;if(e.value===null)return e.type==="year"?new Date().getFullYear():n;const o=r-n+1;return n+((e.value-n+t)%o+o)%o}function C(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 b(e){return e.every(t=>!t.isEditable||t.value!==null&&t.value>=t.min&&t.value<=t.max)}function s(e,t,n){return n===24?e:e%12+(t===1?12:0)}function l(e,t){return t===24?[e,null]:[e%12===0?12:e%12,e<12?0:1]}function L(e,t){const{year:n,month:r,day:o}=e;if(!n||!r||!o)return null;const i=e.hour==null?0:s(e.hour,e.dayPeriod,t),u=new Date(n,r-1,o,i,e.minute??0,e.second??0,0);return n<100&&u.setFullYear(n),u}function A(e,t){const[n,r]=l(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 N(e,t,n){if(e.hour==null||e.minute==null||n===12&&e.dayPeriod==null)return null;const r=i=>String(i).padStart(2,"0"),o=`${r(s(e.hour,e.dayPeriod,n))}:${r(e.minute)}`;return t!=="second"?o:e.second==null?null:`${o}:${r(e.second)}`}function w(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]),i=n[3]===void 0?0:Number(n[3]);if(r>23||o>59||i>59)return{};const[u,a]=l(r,t);return{hour:u,minute:o,second:i,dayPeriod:a}}function H(e,t){const n=(i,u=2)=>String(i).padStart(u,"0"),r=`${n(e.getFullYear(),4)}-${n(e.getMonth()+1)}-${n(e.getDate())}`;if(t==="day")return r;const o=`${n(e.getHours())}:${n(e.getMinutes())}`;return t==="second"?`${r}T${o}:${n(e.getSeconds())}`:`${r}T${o}`}exports.EMPTY_VALUE_TEXT=S;exports.SEGMENT_LABELS=p;exports.SEGMENT_PLACEHOLDERS=f;exports.buildSegments=$;exports.dateToFormValue=H;exports.dateToValues=A;exports.daysInMonth=g;exports.formatSegmentText=P;exports.from24Hour=l;exports.getDayPeriodNames=E;exports.isComplete=b;exports.resolveHourCycle=y;exports.resolveLocale=c;exports.segmentRange=T;exports.segmentTypesFor=h;exports.stepSegment=F;exports.timeStringToValues=w;exports.to24Hour=s;exports.typeDigit=C;exports.valuesToDate=L;exports.valuesToTimeString=N;

package/dist/utils/dateSegments.d.cts

@@ -0,0 +1,173 @@
+/**
+ * The segment engine behind `SkdxDateField` and `SkdxTimeField`: turns a
+ * locale plus a granularity into an ordered list of editable segments, and
+ * turns keystrokes into new segment values.
+ *
+ * Built entirely on `Intl.DateTimeFormat.formatToParts` — segment order *and*
+ * the literals between segments come from CLDR, so there is no bundled
+ * separator table, no locale data and no date library.
+ *
+ * Every framework package carries its own copy of this module (the same way
+ * each carries its own `calendar/locale` and `numberFormat`), because
+ * `@skdx/shared` is a dev-only dependency — contracts and test assertions, not
+ * runtime code. See `reports/design-system-competitive-audit/RFC-segmented-field.md`.
+ *
+ * The module is deliberately framework-free and side-effect-free apart from its
+ * `Intl` memo caches.
+ */
+/** One editable piece of a segmented date/time value. */
+export type SegmentType = 'year' | 'month' | 'day' | 'hour' | 'minute' | 'second' | 'dayPeriod';
+/** How far down a segmented field is editable. Ordered coarse → fine. */
+export type Granularity = 'day' | 'hour' | 'minute' | 'second';
+/** 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;
+}
+/** Placeholder text shown before a segment has been typed. */
+export declare const SEGMENT_PLACEHOLDERS: Record<SegmentType, string>;
+/** The `aria-valuetext` an untyped segment announces, so a spinbutton never reads a value the user did not enter. */
+export declare const EMPTY_VALUE_TEXT = "Empty";
+/**
+ * Accessible name of each segment. Spelled for speech, not for code — a screen
+ * reader announcing "dayPeriod" helps nobody.
+ *
+ * Exported so `getSegmentLabel` can fall back to it for the segment types a
+ * consumer does not want to re-word.
+ */
+export declare const SEGMENT_LABELS: Record<SegmentType, string>;
+/** The runtime's own locale, used whenever `locale` is omitted — matches `calendar/locale`'s `resolveLocale`. */
+export declare function resolveLocale(locale?: string): string;
+/**
+ * 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];
+/** How a segment renders: zero-padded digits, the locale's AM/PM name, or the placeholder. */
+export declare function formatSegmentText(type: SegmentType, value: number | null, locale?: string): string;
+/** 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;
+    /** Forced hour cycle; omitted means "whatever the locale uses". */
+    hourCycle?: HourCycle;
+    /** Current per-segment values. */
+    values: SegmentValues;
+}
+/**
+ * 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[];
+/**
+ * Steps one segment by `delta`, wrapping around its range (Arrow Up on `12:59`
+ * minutes gives `12:00`, not `12:59`). An untyped segment starts at `min`,
+ * except `year`, which starts at the current year rather than year 1.
+ */
+export declare function stepSegment(segment: Segment, delta: number): 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, with React Aria's roll-over behaviour: a
+ * keystroke that would overflow the segment restarts entry at that digit
+ * instead of being rejected, and focus advances as soon as no further digit
+ * could fit.
+ *
+ * @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. Time segments the field does not own default
+ * to `0`, exactly 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;
+/** @internal Drops every memoized `Intl` result. Only needed by tests that switch locales in one process. */
+export declare function clearDateSegmentCache(): void;