@skdx/react 0.26.0 → 0.28.0

package/dist/utils/dateValue.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Date type-crossing layer for Calendar, DateField, DatePicker, TimeField.
+ * Accepts native `Date` or ISO-8601 string, emits `Date` shape, treats ISO
+ * string as canonical for persistence (required for HTML attributes and
+ * eventual `Temporal` migration). Copied identically across all five packages.
+ *
+ * @see `@skdx/shared`'s `contracts/date-value.ts`
+ */
+import { type Granularity } from './dateSegments.js';
+/** Anything a date-shaped member accepts: the native object, or its ISO-8601 wire form. */
+export type DateInput = Date | string;
+/** A date range, structurally identical to Calendar's own `DateRange`. */
+export interface DateRangeLike {
+    start: Date;
+    end: Date | null;
+}
+/** What {@link toCalendarValue} produces — the `Date`-shaped selection every framework emits. */
+export type DateValue = Date | Date[] | DateRangeLike | null;
+/** How many dates a selection holds, deciding how a wire string widens. */
+export type SelectionModeLike = 'single' | 'multiple' | 'range';
+/** @internal Puts {@link toDate}'s malformed-input warning back to "not yet warned". Only needed by tests. */
+export declare function resetMalformedDateWarning(): void;
+/**
+ * Reads a consumer-supplied value into a local `Date` or `null`. `Date` passes
+ * through untouched (`Invalid Date` → `null`). Strings are parsed field-by-field
+ * in local time (never via `new Date(string)`, which reads `YYYY-MM-DD` as UTC
+ * and shifts the date west of Greenwich). Invalid shapes → `null` + dev warning.
+ *
+ * @param input a `Date`, an ISO-8601 string, or `null`/`undefined`
+ * @param source the property it arrived on, named in the warning
+ * @returns the local calendar date, or `null` when unreadable
+ */
+export declare function toDate(input: DateInput | null | undefined, source?: string): Date | null;
+/**
+ * The canonical ISO-8601 string for a date — what to persist and what `<form>` submits.
+ * Uses local wall-clock fields (not `toISOString`, which would shift dates
+ * across the date line for half the planet).
+ *
+ * @param date the local date to render
+ * @param granularity how much of the time of day to include
+ * @returns `YYYY-MM-DD`, or `YYYY-MM-DDTHH:mm[:ss]` past `day`
+ */
+export declare function toISODateValue(date: Date, granularity?: Granularity): string;
+/**
+ * Reads any authored selection shape into the canonical `DateValue`. Wire
+ * string is self-describing: `2026-08-10` (single), `2026-08-10,2026-08-14`
+ * (set), `2026-08-10/2026-08-14` or `2026-08-10/` (range). Only exception:
+ * single-date `multiple` selection, widened via `mode`. `undefined` preserved
+ * to distinguish controlled from uncontrolled.
+ *
+ * @param input the authored selection, in any accepted form
+ * @param mode how many dates the selection holds
+ * @param source the property it arrived on, named in the warning
+ */
+export declare function toCalendarValue(input: DateInput | ReadonlyArray<DateInput> | {
+    start: DateInput;
+    end?: DateInput | null;
+} | null | undefined, mode: SelectionModeLike, source?: string): DateValue | undefined;
+/**
+ * The canonical wire string for a selection — what `value` takes as an
+ * attribute and what consumers persist.
+ *
+ * @param value a selection in the `Date` shape
+ * @returns the string, or `null` when nothing is selected
+ */
+export declare function toCalendarString(value: DateValue | undefined): string | null;
+/**
+ * Reads a time of day from a 24-hour string or a `Date`'s local wall-clock time.
+ * `Date` part is discarded (time of day is not an instant). Accepts `Date` to
+ * avoid conversion overhead in DatePicker compositions.
+ *
+ * @param input a `HH:mm[:ss]` string, a `Date`, or `null`/`undefined`
+ * @param source the property it arrived on, named in the warning
+ * @returns the 24-hour string, or `null` when unreadable
+ */
+export declare function toTimeValue(input: Date | string | null | undefined, source?: string): string | null;

package/dist/utils/dateValue.js

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

package/dist/utils/declaredChildren.cjs

@@ -0,0 +1 @@
+"use strict";var i=Object.create;var c=Object.defineProperty;var p=Object.getOwnPropertyDescriptor;var R=Object.getOwnPropertyNames;var f=Object.getPrototypeOf,l=Object.prototype.hasOwnProperty;var u=(e,t)=>{for(var a in t)c(e,a,{get:t[a],enumerable:!0})},d=(e,t,a,n)=>{if(t&&typeof t=="object"||typeof t=="function")for(let o of R(t))!l.call(e,o)&&o!==a&&c(e,o,{get:()=>t[o],enumerable:!(n=p(t,o))||n.enumerable});return e};var m=(e,t,a)=>(a=e!=null?i(f(e)):{},d(t||!e||!e.__esModule?c(a,"default",{value:e,enumerable:!0}):a,e)),g=e=>d(c({},"__esModule",{value:!0}),e);var N={};u(N,{forEachDeclaredElement:()=>s,hasDeclaredChild:()=>y});module.exports=g(N);var r=m(require("react"),1);function s(e,t){r.Children.forEach(e,a=>{if(!r.isValidElement(a))return;let n=a.props;if(a.type===r.Fragment||typeof a.type=="string"){s(n.children,t);return}t(a.type.displayName,n),s(n.children,t)})}function y(e,t){let a=!1;return s(e,n=>{n===t&&(a=!0)}),a}0&&(module.exports={forEachDeclaredElement,hasDeclaredChild});

package/dist/utils/declaredChildren.d.cts

@@ -0,0 +1,14 @@
+import * as React from 'react';
+/**
+ * Walks the elements a consumer *declared* in `children`, reporting each one's
+ * component `displayName` and props.
+ *
+ * Needed on the server where registration effects don't run. Uses `displayName`
+ * to avoid cycles; wrapped parts won't be detected and fall back to the
+ * registration effect. Fragments and host elements are traversed.
+ *
+ * @internal
+ */
+export declare function forEachDeclaredElement(children: React.ReactNode, visit: (displayName: string | undefined, props: Record<string, unknown>) => void): void;
+/** Whether `children` declares an element whose component `displayName` is `displayName`. @internal */
+export declare function hasDeclaredChild(children: React.ReactNode, displayName: string): boolean;

package/dist/utils/declaredChildren.d.ts

@@ -0,0 +1,14 @@
+import * as React from 'react';
+/**
+ * Walks the elements a consumer *declared* in `children`, reporting each one's
+ * component `displayName` and props.
+ *
+ * Needed on the server where registration effects don't run. Uses `displayName`
+ * to avoid cycles; wrapped parts won't be detected and fall back to the
+ * registration effect. Fragments and host elements are traversed.
+ *
+ * @internal
+ */
+export declare function forEachDeclaredElement(children: React.ReactNode, visit: (displayName: string | undefined, props: Record<string, unknown>) => void): void;
+/** Whether `children` declares an element whose component `displayName` is `displayName`. @internal */
+export declare function hasDeclaredChild(children: React.ReactNode, displayName: string): boolean;

package/dist/utils/declaredChildren.js

@@ -0,0 +1 @@
+import*as t from"react";function o(r,a){t.Children.forEach(r,e=>{if(!t.isValidElement(e))return;let n=e.props;if(e.type===t.Fragment||typeof e.type=="string"){o(n.children,a);return}a(e.type.displayName,n),o(n.children,a)})}function c(r,a){let e=!1;return o(r,n=>{n===a&&(e=!0)}),e}export{o as forEachDeclaredElement,c as hasDeclaredChild};

package/dist/utils/direction.cjs

@@ -1 +1 @@
-"use strict";var s=Object.create;var n=Object.defineProperty;var a=Object.getOwnPropertyDescriptor;var D=Object.getOwnPropertyNames;var p=Object.getPrototypeOf,g=Object.prototype.hasOwnProperty;var x=(t,e)=>{for(var r in e)n(t,r,{get:e[r],enumerable:!0})},d=(t,e,r,c)=>{if(e&&typeof e=="object"||typeof e=="function")for(let i of D(e))!g.call(t,i)&&i!==r&&n(t,i,{get:()=>e[i],enumerable:!(c=a(e,i))||c.enumerable});return t};var m=(t,e,r)=>(r=t!=null?s(p(t)):{},d(e||!t||!t.__esModule?n(r,"default",{value:t,enumerable:!0}):r,t)),P=t=>d(n({},"__esModule",{value:!0}),t);var A={};x(A,{DirectionProvider:()=>R,directionalKey:()=>w,resolveDirection:()=>u,resolvePhysicalSide:()=>v,useDirection:()=>h});module.exports=P(A);var o=m(require("react"),1),f=require("react/jsx-runtime"),l=o.createContext(void 0);function R({dir:t,children:e}){return(0,f.jsx)(l.Provider,{value:t,children:e})}function h(t){let e=o.useContext(l);return t??e}function u(t,e){if(e)return e;let r=t?.closest("[dir]")?.getAttribute("dir")?.toLowerCase();return r==="rtl"||r==="ltr"?r:typeof document>"u"?"ltr":(document.dir||document.documentElement?.getAttribute("dir")||"").toLowerCase()==="rtl"?"rtl":"ltr"}function v(t,e){return t==="start"?e==="rtl"?"right":"left":t==="end"?e==="rtl"?"left":"right":t}var y={ArrowLeft:"ArrowRight",ArrowRight:"ArrowLeft"};function w(t,e,r){return u(e,r)==="rtl"?y[t]??t:t}0&&(module.exports={DirectionProvider,directionalKey,resolveDirection,resolvePhysicalSide,useDirection});
+"use strict";var a=Object.create;var n=Object.defineProperty;var D=Object.getOwnPropertyDescriptor;var p=Object.getOwnPropertyNames;var x=Object.getPrototypeOf,g=Object.prototype.hasOwnProperty;var m=(t,e)=>{for(var r in e)n(t,r,{get:e[r],enumerable:!0})},l=(t,e,r,c)=>{if(e&&typeof e=="object"||typeof e=="function")for(let i of p(e))!g.call(t,i)&&i!==r&&n(t,i,{get:()=>e[i],enumerable:!(c=D(e,i))||c.enumerable});return t};var R=(t,e,r)=>(r=t!=null?a(x(t)):{},l(e||!t||!t.__esModule?n(r,"default",{value:t,enumerable:!0}):r,t)),P=t=>l(n({},"__esModule",{value:!0}),t);var C={};m(C,{DirectionProvider:()=>h,directionalKey:()=>A,resolveDirection:()=>d,resolvePhysicalSide:()=>y,useDirection:()=>f,usePortalledDirection:()=>v});module.exports=P(C);var o=R(require("react"),1),s=require("react/jsx-runtime"),u=o.createContext(void 0);function h({dir:t,children:e}){return(0,s.jsx)(u.Provider,{value:t,children:e})}function f(t){let e=o.useContext(u);return t??e}function v(t,e){let r=f(e);return d(t.current,r)}function d(t,e){if(e)return e;let r=t?.closest("[dir]")?.getAttribute("dir")?.toLowerCase();return r==="rtl"||r==="ltr"?r:typeof document>"u"?"ltr":(document.dir||document.documentElement?.getAttribute("dir")||"").toLowerCase()==="rtl"?"rtl":"ltr"}function y(t,e){return t==="start"?e==="rtl"?"right":"left":t==="end"?e==="rtl"?"left":"right":t}var w={ArrowLeft:"ArrowRight",ArrowRight:"ArrowLeft"};function A(t,e,r){return d(e,r)==="rtl"?w[t]??t:t}0&&(module.exports={DirectionProvider,directionalKey,resolveDirection,resolvePhysicalSide,useDirection,usePortalledDirection});

package/dist/utils/direction.d.cts

@@ -52,6 +52,29 @@ export declare function DirectionProvider({ dir, children }: DirectionProviderPr
  * which case {@link directionalKey} falls back to the DOM.
  */
 export declare function useDirection(dirProp?: Direction): Direction | undefined;
+/**
+ * The direction a **portalled** panel has to carry on itself, resolved from an
+ * element still standing in the logical tree — its trigger.
+ *
+ * Step 3 of the resolution order above is a DOM walk, and a portalled panel has
+ * been moved out of the DOM subtree it logically belongs to: an application
+ * that expresses direction as `<div dir="rtl">` around its tree leaves the
+ * panel's own `closest('[dir]')` reaching nothing but `<html>`, so its submenu
+ * arrows stopped mirroring and its logical CSS laid out LTR. Resolving from
+ * the trigger and writing the answer onto
+ * the panel restores both at once, and re-roots the walk for everything inside
+ * it — an item, a SubTrigger, and the SubContent that resolves from *that*.
+ *
+ * The ref is read during render deliberately: the panel mounts in a commit
+ * after the trigger's, so `current` is already set on the render that first
+ * produces the panel, and the attribute is rewritten on every subsequent render
+ * anyway.
+ *
+ * @param anchorRef the trigger, or anything else still in the logical tree
+ * @param dirProp an explicit `dir` prop, if the component takes one
+ * @internal
+ */
+export declare function usePortalledDirection(anchorRef: React.RefObject<Element | null>, dirProp?: Direction): Direction;
 /** @internal Resolves `el`'s direction, with `override` (prop/provider) winning when set. */
 export declare function resolveDirection(el: Element | null | undefined, override?: Direction): Direction;
 /** @internal An edge named logically: `start`/`end` follow the writing direction. */

package/dist/utils/direction.d.ts

@@ -52,6 +52,29 @@ export declare function DirectionProvider({ dir, children }: DirectionProviderPr
  * which case {@link directionalKey} falls back to the DOM.
  */
 export declare function useDirection(dirProp?: Direction): Direction | undefined;
+/**
+ * The direction a **portalled** panel has to carry on itself, resolved from an
+ * element still standing in the logical tree — its trigger.
+ *
+ * Step 3 of the resolution order above is a DOM walk, and a portalled panel has
+ * been moved out of the DOM subtree it logically belongs to: an application
+ * that expresses direction as `<div dir="rtl">` around its tree leaves the
+ * panel's own `closest('[dir]')` reaching nothing but `<html>`, so its submenu
+ * arrows stopped mirroring and its logical CSS laid out LTR. Resolving from
+ * the trigger and writing the answer onto
+ * the panel restores both at once, and re-roots the walk for everything inside
+ * it — an item, a SubTrigger, and the SubContent that resolves from *that*.
+ *
+ * The ref is read during render deliberately: the panel mounts in a commit
+ * after the trigger's, so `current` is already set on the render that first
+ * produces the panel, and the attribute is rewritten on every subsequent render
+ * anyway.
+ *
+ * @param anchorRef the trigger, or anything else still in the logical tree
+ * @param dirProp an explicit `dir` prop, if the component takes one
+ * @internal
+ */
+export declare function usePortalledDirection(anchorRef: React.RefObject<Element | null>, dirProp?: Direction): Direction;
 /** @internal Resolves `el`'s direction, with `override` (prop/provider) winning when set. */
 export declare function resolveDirection(el: Element | null | undefined, override?: Direction): Direction;
 /** @internal An edge named logically: `start`/`end` follow the writing direction. */

package/dist/utils/direction.js

@@ -1 +1 @@
-import*as i from"react";import{jsx as d}from"react/jsx-runtime";var n=i.createContext(void 0);function u({dir:t,children:e}){return d(n.Provider,{value:t,children:e})}function f(t){let e=i.useContext(n);return t??e}function o(t,e){if(e)return e;let r=t?.closest("[dir]")?.getAttribute("dir")?.toLowerCase();return r==="rtl"||r==="ltr"?r:typeof document>"u"?"ltr":(document.dir||document.documentElement?.getAttribute("dir")||"").toLowerCase()==="rtl"?"rtl":"ltr"}function s(t,e){return t==="start"?e==="rtl"?"right":"left":t==="end"?e==="rtl"?"left":"right":t}var c={ArrowLeft:"ArrowRight",ArrowRight:"ArrowLeft"};function a(t,e,r){return o(e,r)==="rtl"?c[t]??t:t}export{u as DirectionProvider,a as directionalKey,o as resolveDirection,s as resolvePhysicalSide,f as useDirection};
+import*as i from"react";import{jsx as l}from"react/jsx-runtime";var n=i.createContext(void 0);function f({dir:t,children:e}){return l(n.Provider,{value:t,children:e})}function c(t){let e=i.useContext(n);return t??e}function s(t,e){let r=c(e);return o(t.current,r)}function o(t,e){if(e)return e;let r=t?.closest("[dir]")?.getAttribute("dir")?.toLowerCase();return r==="rtl"||r==="ltr"?r:typeof document>"u"?"ltr":(document.dir||document.documentElement?.getAttribute("dir")||"").toLowerCase()==="rtl"?"rtl":"ltr"}function a(t,e){return t==="start"?e==="rtl"?"right":"left":t==="end"?e==="rtl"?"left":"right":t}var d={ArrowLeft:"ArrowRight",ArrowRight:"ArrowLeft"};function D(t,e,r){return o(e,r)==="rtl"?d[t]??t:t}export{f as DirectionProvider,D as directionalKey,o as resolveDirection,a as resolvePhysicalSide,c as useDirection,s as usePortalledDirection};

package/dist/utils/formControl.cjs

@@ -1 +1 @@
-"use strict";var u=Object.create;var i=Object.defineProperty;var s=Object.getOwnPropertyDescriptor;var f=Object.getOwnPropertyNames;var m=Object.getPrototypeOf,R=Object.prototype.hasOwnProperty;var y=(e,t)=>{for(var r in t)i(e,r,{get:t[r],enumerable:!0})},o=(e,t,r,n)=>{if(t&&typeof t=="object"||typeof t=="function")for(let a of f(t))!R.call(e,a)&&a!==r&&i(e,a,{get:()=>t[a],enumerable:!(n=s(t,a))||n.enumerable});return e};var V=(e,t,r)=>(r=e!=null?u(m(e)):{},o(t||!e||!e.__esModule?i(r,"default",{value:e,enumerable:!0}):r,e)),p=e=>o(i({},"__esModule",{value:!0}),e);var v={};y(v,{formValidityHandle:()=>d,useFormReset:()=>b,useFormValidityHandle:()=>H});module.exports=p(v);var l=V(require("react"),1),c=require("./useCallbackRef.cjs");function d(e){return{checkValidity:()=>e.current?.checkValidity()??!0,reportValidity:()=>e.current?.reportValidity()??!0}}function H(e,t,r){l.useImperativeHandle(e,()=>{let n=d(r);return t.current?Object.assign(t.current,n):n})}function b(e,t){let r=(0,c.useCallbackRef)(t);l.useEffect(()=>{let n=e.current?.closest("form");if(n)return n.addEventListener("reset",r),()=>n.removeEventListener("reset",r)},[e,r])}0&&(module.exports={formValidityHandle,useFormReset,useFormValidityHandle});
+"use strict";var u=Object.create;var l=Object.defineProperty;var y=Object.getOwnPropertyDescriptor;var m=Object.getOwnPropertyNames;var V=Object.getPrototypeOf,f=Object.prototype.hasOwnProperty;var p=(e,t)=>{for(var i in t)l(e,i,{get:t[i],enumerable:!0})},c=(e,t,i,a)=>{if(t&&typeof t=="object"||typeof t=="function")for(let r of m(t))!f.call(e,r)&&r!==i&&l(e,r,{get:()=>t[r],enumerable:!(a=y(t,r))||a.enumerable});return e};var R=(e,t,i)=>(i=e!=null?u(V(e)):{},c(t||!e||!e.__esModule?l(i,"default",{value:e,enumerable:!0}):i,e)),v=e=>c(l({},"__esModule",{value:!0}),e);var F={};p(F,{formValidityHandle:()=>s,formValidityStateView:()=>g,useFormReset:()=>H,useFormValidityHandle:()=>b});module.exports=v(F);var o=R(require("react"),1),d=require("./useCallbackRef.cjs");function s(e){return{checkValidity:()=>e.current?.checkValidity()??!0,reportValidity:()=>e.current?.reportValidity()??!0,setCustomValidity:t=>e.current?.setCustomValidity(t)}}function g(e){return{get validity(){return e.current?.validity??null},get validationMessage(){return e.current?.validationMessage??""}}}function b(e,t,i,a){o.useImperativeHandle(e,()=>{let r=s(i),n=t.current?Object.assign(t.current,r):r;return a&&Object.defineProperties(n,Object.getOwnPropertyDescriptors(a)),n})}function H(e,t,i){let a=(0,d.useCallbackRef)(t);o.useEffect(()=>{let r=e.current,n=i?(r?.ownerDocument??document).getElementById(i):r?.closest("form")??null;if(n instanceof HTMLFormElement)return n.addEventListener("reset",a),()=>n.removeEventListener("reset",a)},[e,a,i])}0&&(module.exports={formValidityHandle,formValidityStateView,useFormReset,useFormValidityHandle});

package/dist/utils/formControl.d.cts

@@ -15,6 +15,18 @@ export interface FormValidityHandle {
     checkValidity(): boolean;
     /** Like {@link checkValidity}, but also shows the browser's validation message. */
     reportValidity(): boolean;
+    /**
+     * Pushes an externally-computed error into the control — a server response,
+     * a cross-field rule — exactly like `HTMLInputElement.setCustomValidity()`:
+     * a non-empty message makes the control invalid (`customError`) and is what
+     * {@link reportValidity} shows; `''` clears it.
+     *
+     * Without this, the only writable half of constraint validation lived on
+     * `<skdx-*>` alone (`FormAssociated` in
+     * `packages/web-components/src/internal/form-associated.ts`), so an error
+     * the browser cannot derive was unrepresentable in React.
+     */
+    setCustomValidity(message: string): void;
 }
 /**
  * Builds {@link FormValidityHandle} on top of whichever native control
@@ -28,6 +40,50 @@ export interface FormValidityHandle {
  * validation at all.
  */
 export declare function formValidityHandle(control: React.RefObject<FormValidityHandle | null>): FormValidityHandle;
+/**
+ * The *readable* half of constraint validation: the control's own
+ * `ValidityState` and the message the browser would show for it.
+ *
+ * Deliberately a separate interface from {@link FormValidityHandle} rather than
+ * two more members on it, for one hard reason and one soft one.
+ *
+ * The hard one: `apps/docs/scripts/tsdoc/extract.mjs` finds a React root's
+ * imperative API by resolving the handle type reached from a `use*Handle` call
+ * and accepting it only when **every** member is a `MethodSignature`. A
+ * property on `FormValidityHandle` would make that test fail, and every
+ * form-associated React root would publish "no methods" — a documentation
+ * regression across a dozen families, caused by adding an accessor to one.
+ *
+ * The soft one: these are accessors, not methods. They have to be *live* — a
+ * snapshot taken when the ref was built would report the validity the control
+ * had at mount — so they are installed as getters with
+ * `Object.defineProperties`, which is also why `Object.assign` cannot carry
+ * them.
+ */
+export interface FormValidityStateView {
+    /**
+     * The wrapped control's own `ValidityState`, live — read it to render your
+     * own error text (`validity.valueMissing`, `validity.patternMismatch`, …)
+     * instead of parsing the browser's message. `null` when no control has
+     * mounted, which is the same "nothing to be invalid about" the methods answer
+     * `true` for.
+     */
+    readonly validity: ValidityState | null;
+    /**
+     * The message the browser would show for the current validity — `''` when the
+     * control is valid, exactly like the native property. `''` too when no
+     * control has mounted.
+     */
+    readonly validationMessage: string;
+}
+/** Something with the two native validity accessors — a real `<input>`, in practice. */
+type ValidityStateSource = Pick<HTMLInputElement, 'validity' | 'validationMessage'>;
+/**
+ * Builds {@link FormValidityStateView} over whichever native control carries
+ * the value, as **getters**, so each read reflects the control's validity now
+ * rather than when the handle was assembled.
+ */
+export declare function formValidityStateView(control: React.RefObject<ValidityStateSource | null>): FormValidityStateView;
 /**
  * Publishes {@link FormValidityHandle} on the forwarded ref of a root that
  * *does* render an element: the two methods are assigned onto the node rather
@@ -38,6 +94,14 @@ export declare function formValidityHandle(control: React.RefObject<FormValidity
  * Attach `nodeRef` to the root element yourself; the forwarded ref must not
  * also be attached, since this hook owns it.
  *
+ * `extra` is for accessor-shaped additions — {@link formValidityStateView} is
+ * the only one today. It is copied with `Object.defineProperties` rather than
+ * `Object.assign`, because assignment would *invoke* each getter once and
+ * freeze its answer. Opt-in rather than always-on: a root whose element is
+ * itself form-associated (a `<button>`) already has native `validity` and
+ * `validationMessage` accessors, and shadowing those on every root to serve one
+ * family would be a change nobody asked for.
+ *
  * @example
  * ```tsx
  * const rootRef = React.useRef<HTMLDivElement>(null);
@@ -46,7 +110,7 @@ export declare function formValidityHandle(control: React.RefObject<FormValidity
  * return <Primitive.div {...props} ref={rootRef} />;
  * ```
  */
-export declare function useFormValidityHandle<T extends HTMLElement>(forwardedRef: React.ForwardedRef<T>, nodeRef: React.RefObject<T | null>, control: React.RefObject<FormValidityHandle | null>): void;
+export declare function useFormValidityHandle<T extends HTMLElement>(forwardedRef: React.ForwardedRef<T>, nodeRef: React.RefObject<T | null>, control: React.RefObject<FormValidityHandle | null>, extra?: object): void;
 /**
  * Restores a control's declared default when the owning `<form>` is reset —
  * the React counterpart of `formResetCallback()` on `<skdx-*>`.
@@ -57,10 +121,18 @@ export declare function useFormValidityHandle<T extends HTMLElement>(forwardedRe
  * mounted control into a different `<form>` does not re-associate it, the same
  * way a native input's `form` is fixed at parse time.
  *
+ * `formId` is the control's `form` prop, a form element's `id`, and it wins over
+ * the ancestor lookup exactly as the native `form` attribute does. Without it a
+ * control that is not a DOM descendant of its form — one inside a portalled
+ * dialog, which is where this matters — submitted with that form (the hidden
+ * input carries `form=`) and then quietly ignored its reset, because the reset
+ * listener was still looking for an ancestor there was none of.
+ *
  * Unlike the Web Components mixin, which writes the property back silently,
  * `onReset` here has to go through the component's normal setter and fire its
  * change callback: a *controlled* React control's value belongs to the parent,
  * and one that reset itself without telling the parent would be overwritten on
  * the very next render.
  */
-export declare function useFormReset(element: React.RefObject<HTMLElement | null>, onReset: () => void): void;
+export declare function useFormReset(element: React.RefObject<HTMLElement | null>, onReset: () => void, formId?: string): void;
+export {};

package/dist/utils/formControl.d.ts

@@ -15,6 +15,18 @@ export interface FormValidityHandle {
     checkValidity(): boolean;
     /** Like {@link checkValidity}, but also shows the browser's validation message. */
     reportValidity(): boolean;
+    /**
+     * Pushes an externally-computed error into the control — a server response,
+     * a cross-field rule — exactly like `HTMLInputElement.setCustomValidity()`:
+     * a non-empty message makes the control invalid (`customError`) and is what
+     * {@link reportValidity} shows; `''` clears it.
+     *
+     * Without this, the only writable half of constraint validation lived on
+     * `<skdx-*>` alone (`FormAssociated` in
+     * `packages/web-components/src/internal/form-associated.ts`), so an error
+     * the browser cannot derive was unrepresentable in React.
+     */
+    setCustomValidity(message: string): void;
 }
 /**
  * Builds {@link FormValidityHandle} on top of whichever native control
@@ -28,6 +40,50 @@ export interface FormValidityHandle {
  * validation at all.
  */
 export declare function formValidityHandle(control: React.RefObject<FormValidityHandle | null>): FormValidityHandle;
+/**
+ * The *readable* half of constraint validation: the control's own
+ * `ValidityState` and the message the browser would show for it.
+ *
+ * Deliberately a separate interface from {@link FormValidityHandle} rather than
+ * two more members on it, for one hard reason and one soft one.
+ *
+ * The hard one: `apps/docs/scripts/tsdoc/extract.mjs` finds a React root's
+ * imperative API by resolving the handle type reached from a `use*Handle` call
+ * and accepting it only when **every** member is a `MethodSignature`. A
+ * property on `FormValidityHandle` would make that test fail, and every
+ * form-associated React root would publish "no methods" — a documentation
+ * regression across a dozen families, caused by adding an accessor to one.
+ *
+ * The soft one: these are accessors, not methods. They have to be *live* — a
+ * snapshot taken when the ref was built would report the validity the control
+ * had at mount — so they are installed as getters with
+ * `Object.defineProperties`, which is also why `Object.assign` cannot carry
+ * them.
+ */
+export interface FormValidityStateView {
+    /**
+     * The wrapped control's own `ValidityState`, live — read it to render your
+     * own error text (`validity.valueMissing`, `validity.patternMismatch`, …)
+     * instead of parsing the browser's message. `null` when no control has
+     * mounted, which is the same "nothing to be invalid about" the methods answer
+     * `true` for.
+     */
+    readonly validity: ValidityState | null;
+    /**
+     * The message the browser would show for the current validity — `''` when the
+     * control is valid, exactly like the native property. `''` too when no
+     * control has mounted.
+     */
+    readonly validationMessage: string;
+}
+/** Something with the two native validity accessors — a real `<input>`, in practice. */
+type ValidityStateSource = Pick<HTMLInputElement, 'validity' | 'validationMessage'>;
+/**
+ * Builds {@link FormValidityStateView} over whichever native control carries
+ * the value, as **getters**, so each read reflects the control's validity now
+ * rather than when the handle was assembled.
+ */
+export declare function formValidityStateView(control: React.RefObject<ValidityStateSource | null>): FormValidityStateView;
 /**
  * Publishes {@link FormValidityHandle} on the forwarded ref of a root that
  * *does* render an element: the two methods are assigned onto the node rather
@@ -38,6 +94,14 @@ export declare function formValidityHandle(control: React.RefObject<FormValidity
  * Attach `nodeRef` to the root element yourself; the forwarded ref must not
  * also be attached, since this hook owns it.
  *
+ * `extra` is for accessor-shaped additions — {@link formValidityStateView} is
+ * the only one today. It is copied with `Object.defineProperties` rather than
+ * `Object.assign`, because assignment would *invoke* each getter once and
+ * freeze its answer. Opt-in rather than always-on: a root whose element is
+ * itself form-associated (a `<button>`) already has native `validity` and
+ * `validationMessage` accessors, and shadowing those on every root to serve one
+ * family would be a change nobody asked for.
+ *
  * @example
  * ```tsx
  * const rootRef = React.useRef<HTMLDivElement>(null);
@@ -46,7 +110,7 @@ export declare function formValidityHandle(control: React.RefObject<FormValidity
  * return <Primitive.div {...props} ref={rootRef} />;
  * ```
  */
-export declare function useFormValidityHandle<T extends HTMLElement>(forwardedRef: React.ForwardedRef<T>, nodeRef: React.RefObject<T | null>, control: React.RefObject<FormValidityHandle | null>): void;
+export declare function useFormValidityHandle<T extends HTMLElement>(forwardedRef: React.ForwardedRef<T>, nodeRef: React.RefObject<T | null>, control: React.RefObject<FormValidityHandle | null>, extra?: object): void;
 /**
  * Restores a control's declared default when the owning `<form>` is reset —
  * the React counterpart of `formResetCallback()` on `<skdx-*>`.
@@ -57,10 +121,18 @@ export declare function useFormValidityHandle<T extends HTMLElement>(forwardedRe
  * mounted control into a different `<form>` does not re-associate it, the same
  * way a native input's `form` is fixed at parse time.
  *
+ * `formId` is the control's `form` prop, a form element's `id`, and it wins over
+ * the ancestor lookup exactly as the native `form` attribute does. Without it a
+ * control that is not a DOM descendant of its form — one inside a portalled
+ * dialog, which is where this matters — submitted with that form (the hidden
+ * input carries `form=`) and then quietly ignored its reset, because the reset
+ * listener was still looking for an ancestor there was none of.
+ *
  * Unlike the Web Components mixin, which writes the property back silently,
  * `onReset` here has to go through the component's normal setter and fire its
  * change callback: a *controlled* React control's value belongs to the parent,
  * and one that reset itself without telling the parent would be overwritten on
  * the very next render.
  */
-export declare function useFormReset(element: React.RefObject<HTMLElement | null>, onReset: () => void): void;
+export declare function useFormReset(element: React.RefObject<HTMLElement | null>, onReset: () => void, formId?: string): void;
+export {};

package/dist/utils/formControl.js

@@ -1 +1 @@
-import*as a from"react";import{useCallbackRef as i}from"./useCallbackRef.js";function l(e){return{checkValidity:()=>e.current?.checkValidity()??!0,reportValidity:()=>e.current?.reportValidity()??!0}}function c(e,n,r){a.useImperativeHandle(e,()=>{let t=l(r);return n.current?Object.assign(n.current,t):t})}function d(e,n){let r=i(n);a.useEffect(()=>{let t=e.current?.closest("form");if(t)return t.addEventListener("reset",r),()=>t.removeEventListener("reset",r)},[e,r])}export{l as formValidityHandle,d as useFormReset,c as useFormValidityHandle};
+import*as l from"react";import{useCallbackRef as o}from"./useCallbackRef.js";function c(e){return{checkValidity:()=>e.current?.checkValidity()??!0,reportValidity:()=>e.current?.reportValidity()??!0,setCustomValidity:t=>e.current?.setCustomValidity(t)}}function s(e){return{get validity(){return e.current?.validity??null},get validationMessage(){return e.current?.validationMessage??""}}}function u(e,t,a,i){l.useImperativeHandle(e,()=>{let n=c(a),r=t.current?Object.assign(t.current,n):n;return i&&Object.defineProperties(r,Object.getOwnPropertyDescriptors(i)),r})}function y(e,t,a){let i=o(t);l.useEffect(()=>{let n=e.current,r=a?(n?.ownerDocument??document).getElementById(a):n?.closest("form")??null;if(r instanceof HTMLFormElement)return r.addEventListener("reset",i),()=>r.removeEventListener("reset",i)},[e,i,a])}export{c as formValidityHandle,s as formValidityStateView,y as useFormReset,u as useFormValidityHandle};

package/dist/utils/hiddenInput.cjs

@@ -1 +1 @@
-"use strict";var u=Object.create;var o=Object.defineProperty;var I=Object.getOwnPropertyDescriptor;var H=Object.getOwnPropertyNames;var c=Object.getPrototypeOf,f=Object.prototype.hasOwnProperty;var l=(t,n)=>{for(var e in n)o(t,e,{get:n[e],enumerable:!0})},p=(t,n,e,d)=>{if(n&&typeof n=="object"||typeof n=="function")for(let i of H(n))!f.call(t,i)&&i!==e&&o(t,i,{get:()=>n[i],enumerable:!(d=I(n,i))||d.enumerable});return t};var h=(t,n,e)=>(e=t!=null?u(c(t)):{},p(n||!t||!t.__esModule?o(e,"default",{value:t,enumerable:!0}):e,t)),m=t=>p(o({},"__esModule",{value:!0}),t);var R={};l(R,{HiddenInput:()=>r});module.exports=m(R);var a=h(require("react"),1),s=require("react/jsx-runtime");function y(){}var r=a.forwardRef((t,n)=>(0,s.jsx)("input",{"aria-hidden":!0,tabIndex:-1,onChange:y,...t,ref:n,style:{position:"absolute",pointerEvents:"none",opacity:0,margin:0,width:1,height:1,...t.style}}));r.displayName="HiddenInput";0&&(module.exports={HiddenInput});
+"use strict";var h=Object.create;var a=Object.defineProperty;var b=Object.getOwnPropertyDescriptor;var g=Object.getOwnPropertyNames;var I=Object.getPrototypeOf,R=Object.prototype.hasOwnProperty;var H=(e,t)=>{for(var n in t)a(e,n,{get:t[n],enumerable:!0})},s=(e,t,n,i)=>{if(t&&typeof t=="object"||typeof t=="function")for(let o of g(t))!R.call(e,o)&&o!==n&&a(e,o,{get:()=>t[o],enumerable:!(i=b(t,o))||i.enumerable});return e};var M=(e,t,n)=>(n=e!=null?h(I(e)):{},s(t||!e||!e.__esModule?a(n,"default",{value:e,enumerable:!0}):n,e)),E=e=>s(a({},"__esModule",{value:!0}),e);var P={};H(P,{HiddenInput:()=>d,MirroredValues:()=>L});module.exports=E(P);var p=M(require("react"),1),r=require("react/jsx-runtime");function V(){}var d=p.forwardRef((e,t)=>(0,r.jsx)("input",{"aria-hidden":!0,tabIndex:-1,onChange:V,...e,ref:t,style:{position:"absolute",pointerEvents:"none",opacity:0,margin:0,width:1,height:1,...e.style}}));d.displayName="HiddenInput";function L({name:e,values:t,required:n,disabled:i,form:o,autoComplete:f,singleValued:c,controlRef:m}){if(!e)return null;let y=t.length>0?t:n||c?[""]:[];return(0,r.jsx)(r.Fragment,{children:y.map((u,l)=>(0,r.jsx)(d,{ref:l===0?m:void 0,type:"text",name:e,value:u,required:n,disabled:i,form:o,autoComplete:l===0?f:void 0},u||l))})}0&&(module.exports={HiddenInput,MirroredValues});

package/dist/utils/hiddenInput.d.cts

@@ -2,17 +2,35 @@ import * as React from 'react';
 interface HiddenInputProps extends React.InputHTMLAttributes<HTMLInputElement> {
 }
 /**
- * Visually hidden native input rendered by form controls (Checkbox, Switch,
- * RadioGroup, Slider, FileUpload) so they participate in native form
- * submission. Ref-forwarded so FileUpload can `.click()` it programmatically.
- *
- * Deliberately *not* `readOnly`: a readonly input is barred from constraint
- * validation, so `required` would never report `valueMissing` — which is the
- * one thing this input exists to carry into the form. The no-op `onChange` is
- * what `readOnly` was really buying (silencing React's
- * controlled-value-without-handler warning); the control is 1×1px,
- * `pointer-events: none` and out of the tab order, so there is no user path to
- * edit it anyway.
+ * Visually hidden native input for form controls to participate in form submission.
+ * Never `readOnly` or `type="hidden"` — both break constraint validation.
+ * Ref-forwarded for programmatic `.click()`.
  */
 export declare const HiddenInput: React.ForwardRefExoticComponent<HiddenInputProps & React.RefAttributes<HTMLInputElement>>;
+/** What {@link MirroredValues} needs to mirror one array-valued selection. */
+export interface MirroredValuesProps {
+    /** Required shared name; without it, nothing is rendered. */
+    name: string | undefined;
+    /** Selected values in submission order. */
+    values: readonly string[];
+    /** Marks controls required; empty selection triggers `valueMissing`. */
+    required?: boolean;
+    /** Withholds value from submission. */
+    disabled?: boolean;
+    /** `form` attribute for non-descendant controls. */
+    form?: string;
+    /** Browser autofill hint on first control only. */
+    autoComplete?: string;
+    /** True for single-valued control that submits empty entry when empty. */
+    singleValued?: boolean;
+    /** Ref to first control; answers for entire set. */
+    controlRef?: React.RefObject<HTMLInputElement | null>;
+}
+/**
+ * Mirrors one hidden native control per value, all sharing one `name`,
+ * so `formData.getAll(name)` reads the selection exactly like native `<select multiple>`.
+ * Never `type="hidden"` or `readOnly` — both break constraint validation.
+ * Empty selection submits no entries; only `disabled` withholds value.
+ */
+export declare function MirroredValues({ name, values, required, disabled, form, autoComplete, singleValued, controlRef, }: MirroredValuesProps): React.ReactElement | null;
 export {};

package/dist/utils/hiddenInput.d.ts

@@ -2,17 +2,35 @@ import * as React from 'react';
 interface HiddenInputProps extends React.InputHTMLAttributes<HTMLInputElement> {
 }
 /**
- * Visually hidden native input rendered by form controls (Checkbox, Switch,
- * RadioGroup, Slider, FileUpload) so they participate in native form
- * submission. Ref-forwarded so FileUpload can `.click()` it programmatically.
- *
- * Deliberately *not* `readOnly`: a readonly input is barred from constraint
- * validation, so `required` would never report `valueMissing` — which is the
- * one thing this input exists to carry into the form. The no-op `onChange` is
- * what `readOnly` was really buying (silencing React's
- * controlled-value-without-handler warning); the control is 1×1px,
- * `pointer-events: none` and out of the tab order, so there is no user path to
- * edit it anyway.
+ * Visually hidden native input for form controls to participate in form submission.
+ * Never `readOnly` or `type="hidden"` — both break constraint validation.
+ * Ref-forwarded for programmatic `.click()`.
  */
 export declare const HiddenInput: React.ForwardRefExoticComponent<HiddenInputProps & React.RefAttributes<HTMLInputElement>>;
+/** What {@link MirroredValues} needs to mirror one array-valued selection. */
+export interface MirroredValuesProps {
+    /** Required shared name; without it, nothing is rendered. */
+    name: string | undefined;
+    /** Selected values in submission order. */
+    values: readonly string[];
+    /** Marks controls required; empty selection triggers `valueMissing`. */
+    required?: boolean;
+    /** Withholds value from submission. */
+    disabled?: boolean;
+    /** `form` attribute for non-descendant controls. */
+    form?: string;
+    /** Browser autofill hint on first control only. */
+    autoComplete?: string;
+    /** True for single-valued control that submits empty entry when empty. */
+    singleValued?: boolean;
+    /** Ref to first control; answers for entire set. */
+    controlRef?: React.RefObject<HTMLInputElement | null>;
+}
+/**
+ * Mirrors one hidden native control per value, all sharing one `name`,
+ * so `formData.getAll(name)` reads the selection exactly like native `<select multiple>`.
+ * Never `type="hidden"` or `readOnly` — both break constraint validation.
+ * Empty selection submits no entries; only `disabled` withholds value.
+ */
+export declare function MirroredValues({ name, values, required, disabled, form, autoComplete, singleValued, controlRef, }: MirroredValuesProps): React.ReactElement | null;
 export {};

package/dist/utils/hiddenInput.js

@@ -1 +1 @@
-import*as n from"react";import{jsx as d}from"react/jsx-runtime";function i(){}var o=n.forwardRef((t,e)=>d("input",{"aria-hidden":!0,tabIndex:-1,onChange:i,...t,ref:e,style:{position:"absolute",pointerEvents:"none",opacity:0,margin:0,width:1,height:1,...t.style}}));o.displayName="HiddenInput";export{o as HiddenInput};
+import*as a from"react";import{Fragment as y,jsx as o}from"react/jsx-runtime";function m(){}var l=a.forwardRef((e,t)=>o("input",{"aria-hidden":!0,tabIndex:-1,onChange:m,...e,ref:t,style:{position:"absolute",pointerEvents:"none",opacity:0,margin:0,width:1,height:1,...e.style}}));l.displayName="HiddenInput";function h({name:e,values:t,required:r,disabled:d,form:u,autoComplete:s,singleValued:p,controlRef:f}){if(!e)return null;let c=t.length>0?t:r||p?[""]:[];return o(y,{children:c.map((i,n)=>o(l,{ref:n===0?f:void 0,type:"text",name:e,value:i,required:r,disabled:d,form:u,autoComplete:n===0?s:void 0},i||n))})}export{l as HiddenInput,h as MirroredValues};

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

@@ -0,0 +1 @@
+"use strict";var t=Object.defineProperty;var s=Object.getOwnPropertyDescriptor;var u=Object.getOwnPropertyNames;var a=Object.prototype.hasOwnProperty;var i=(o,e)=>{for(var n in e)t(o,n,{get:e[n],enumerable:!0})},p=(o,e,n,c)=>{if(e&&typeof e=="object"||typeof e=="function")for(let r of u(e))!a.call(o,r)&&r!==n&&t(o,r,{get:()=>e[r],enumerable:!(c=s(e,r))||c.enumerable});return o};var d=o=>p(t({},"__esModule",{value:!0}),o);var l={};i(l,{isDevMode:()=>f});module.exports=d(l);function f(){try{return process.env.NODE_ENV!=="production"}catch{return!1}}0&&(module.exports={isDevMode});

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

@@ -0,0 +1,6 @@
+/**
+ * Development-mode guard for logging dev-only diagnostics.
+ * @returns `true` in development, `false` in production.
+ * @internal
+ */
+export declare function isDevMode(): boolean;

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

@@ -0,0 +1,6 @@
+/**
+ * Development-mode guard for logging dev-only diagnostics.
+ * @returns `true` in development, `false` in production.
+ * @internal
+ */
+export declare function isDevMode(): boolean;

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

@@ -0,0 +1 @@
+function e(){try{return process.env.NODE_ENV!=="production"}catch{return!1}}export{e as isDevMode};