@skdx/react 0.28.0 → 0.29.0

package/dist/utils/formControl.d.ts

@@ -1,82 +1,22 @@
 import * as React from 'react';
-/**
- * The two constraint-validation methods every form-associated component
- * publishes — the same pair `<skdx-*>` gets from the `FormAssociated` mixin
- * (`packages/web-components/src/internal/form-associated.ts`), and the same
- * pair a native `HTMLInputElement` has.
- *
- * On a root that renders a DOM element these are hung on that element, so
- * `ref.current` stays the node consumers already focus and measure. On a root
- * that renders no DOM of its own (`Select`, `Combobox`, `DatePicker`) the ref
- * *is* this object and nothing else.
- */
+/** The two constraint-validation methods every form-associated component publishes, the same pair a native `HTMLInputElement` has; hung onto the root's element, or the object itself when the root renders no DOM. */
 export interface FormValidityHandle {
     /** Returns whether the current value satisfies its constraints, firing `invalid` if not. */
     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.
-     */
+    /** Pushes an externally-computed error into the control, exactly like `HTMLInputElement.setCustomValidity()`: a non-empty message makes it invalid (`customError`) and is what {@link reportValidity} shows; `''` clears it. */
     setCustomValidity(message: string): void;
 }
-/**
- * Builds {@link FormValidityHandle} on top of whichever native control
- * actually carries the submitted value — the wrapped `<input>` for a
- * TextField, the visually-hidden one a composite renders for its selection.
- *
- * Both methods answer `true` when that control is absent, which is what a
- * control without a `name` is: it submits nothing, so there is nothing for it
- * to be invalid about. This mirrors the `?? true` fallbacks in the Web
- * Components mixin, where `ElementInternals` may not implement constraint
- * validation at all.
- */
+/** Builds {@link FormValidityHandle} on top of whichever native control actually carries the submitted value, both methods answering `true` when that control is absent (nothing to submit, nothing to be invalid about). */
 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.
- */
+/** The readable half of constraint validation — the control's own `ValidityState` and the message the browser would show — kept as a separate interface of live getters, since `Object.assign` can't carry accessors and a snapshot at ref-build time would go stale. */
 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.
-     */
+    /** The wrapped control's own `ValidityState`, live; `null` when no control has mounted. */
     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.
-     */
+    /** The message the browser would show for the current validity — `''` when valid or 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
@@ -85,22 +25,14 @@ type ValidityStateSource = Pick<HTMLInputElement, 'validity' | 'validationMessag
  */
 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
- * than replacing it, so every existing use of the ref (`focus()`,
- * `getBoundingClientRect()`, `contains()`) keeps working — this is additive,
- * not a swap.
+ * Render-phase form of {@link formValidityStateView}: the React Compiler reads a ref handed to a
+ * plain function as a render-phase ref access, and a hook boundary is where it stops looking.
  *
- * 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.
+ * @internal
+ */
+export declare function useFormValidityStateView(control: React.RefObject<ValidityStateSource | null>): FormValidityStateView;
+/**
+ * Publishes {@link FormValidityHandle} on the forwarded ref of a root that renders an element, assigning the methods onto the node rather than replacing it so existing ref uses keep working; `extra` adds accessor-shaped members like {@link formValidityStateView}.
  *
  * @example
  * ```tsx
@@ -110,29 +42,9 @@ export declare function formValidityStateView(control: React.RefObject<ValidityS
  * 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>, extra?: object): void;
+export declare function useFormValidityHandle<T extends HTMLElement, E extends object = object>(forwardedRef: React.Ref<T & FormValidityHandle & E> | undefined, nodeRef: React.RefObject<T | null>, control: React.RefObject<FormValidityHandle | null>, extra?: E): void;
 /**
- * Restores a control's declared default when the owning `<form>` is reset —
- * the React counterpart of `formResetCallback()` on `<skdx-*>`.
- *
- * `element` is any node the control always renders (its root, its input, its
- * trigger); the form is found from it with `closest('form')`, so a control
- * outside a form simply never subscribes. Resolved once, on mount — moving a
- * 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.
+ * Restores a control's declared default when the owning `<form>` is reset, found from `element` via `closest('form')` (or `formId`, which wins, for a control outside the DOM subtree of its form — a portalled dialog) and resolved once on mount; `onReset` fires through the component's normal change callback since a controlled value belongs to the parent.
  */
 export declare function useFormReset(element: React.RefObject<HTMLElement | null>, onReset: () => void, formId?: string): void;
 export {};

package/dist/utils/formControl.js

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

package/dist/utils/format-file-size.cjs

@@ -0,0 +1,2 @@
+'use client';
+"use strict";var a=Object.defineProperty;var l=Object.getOwnPropertyDescriptor;var m=Object.getOwnPropertyNames;var s=Object.prototype.hasOwnProperty;var u=(e,t)=>{for(var i in t)a(e,i,{get:t[i],enumerable:!0})},b=(e,t,i,n)=>{if(t&&typeof t=="object"||typeof t=="function")for(let r of m(t))!s.call(e,r)&&r!==i&&a(e,r,{get:()=>t[r],enumerable:!(n=l(t,r))||n.enumerable});return e};var g=e=>b(a({},"__esModule",{value:!0}),e);var c={};u(c,{formatFileSize:()=>y});module.exports=g(c);var o=["byte","kilobyte","megabyte","gigabyte","terabyte"];function y(e,t){let i=e,n=0;for(;i>=1e3&&n<o.length-1;)i/=1e3,n+=1;return new Intl.NumberFormat(t,{style:"unit",unit:o[n],unitDisplay:"narrow",maximumFractionDigits:1}).format(i)}0&&(module.exports={formatFileSize});

package/dist/utils/format-file-size.d.cts

@@ -0,0 +1,9 @@
+/**
+ * Formats a byte count as short, localised, readable text — `999B`, `1.5kB`,
+ * `1.2MB` — for a FileUpload file row.
+ *
+ * @param bytes - A `File.size`, in bytes.
+ * @param locale - BCP 47 tag, or omitted for the runtime's own locale.
+ * @returns The formatted size, e.g. `'1.5kB'`.
+ */
+export declare function formatFileSize(bytes: number, locale?: string): string;

package/dist/utils/format-file-size.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Formats a byte count as short, localised, readable text — `999B`, `1.5kB`,
+ * `1.2MB` — for a FileUpload file row.
+ *
+ * @param bytes - A `File.size`, in bytes.
+ * @param locale - BCP 47 tag, or omitted for the runtime's own locale.
+ * @returns The formatted size, e.g. `'1.5kB'`.
+ */
+export declare function formatFileSize(bytes: number, locale?: string): string;

package/dist/utils/format-file-size.js

@@ -0,0 +1,2 @@
+'use client';
+var i=["byte","kilobyte","megabyte","gigabyte","terabyte"];function a(n,r){let t=n,e=0;for(;t>=1e3&&e<i.length-1;)t/=1e3,e+=1;return new Intl.NumberFormat(r,{style:"unit",unit:i[e],unitDisplay:"narrow",maximumFractionDigits:1}).format(t)}export{a as formatFileSize};

package/dist/utils/glyph-data.cjs

@@ -0,0 +1,2 @@
+'use client';
+"use strict";var c=Object.defineProperty;var s=Object.getOwnPropertyDescriptor;var M=Object.getOwnPropertyNames;var a=Object.prototype.hasOwnProperty;var i=(r,l)=>{for(var t in l)c(r,t,{get:l[t],enumerable:!0})},p=(r,l,t,n)=>{if(l&&typeof l=="object"||typeof l=="function")for(let o of M(l))!a.call(r,o)&&o!==t&&c(r,o,{get:()=>l[o],enumerable:!(n=s(l,o))||n.enumerable});return r};var v=r=>p(c({},"__esModule",{value:!0}),r);var y={};i(y,{GLYPHS:()=>g,GLYPH_STROKE_WIDTH:()=>f});module.exports=v(y);var f=1.5,e=(r,l="0 0 16 16")=>({viewBox:l,d:r,fill:!1}),h=(r,l="0 0 16 16")=>({viewBox:l,d:r,fill:!0}),g={check:e("M3 8.5l3 3 7-7"),dash:e("M4 8h8"),close:e("M4 4l8 8M12 4l-8 8"),dot:h("M8 5a3 3 0 1 0 0 6 3 3 0 1 0 0-6z"),star:h("M10 1.5l2.6 5.6 6.1.7-4.5 4.2 1.2 6-5.4-3-5.4 3 1.2-6-4.5-4.2 6.1-.7z","0 0 20 20"),"chevron-down":e("M4 6l4 4 4-4"),"chevron-right":e("M6 4l4 4-4 4"),"chevron-left":e("M10 4l-4 4 4 4"),"arrow-right":e("M3 8h10M9 4l4 4-4 4"),"arrow-left":e("M13 8H3M7 4L3 8l4 4"),"chevrons-right":e("M3 4l4 4-4 4M9 4l4 4-4 4"),"chevrons-left":e("M13 4L9 8l4 4M7 4L3 8l4 4"),play:h("M5 3.5l7 4.5-7 4.5z"),pause:h("M4.5 3h2.5v10H4.5zM9 3h2.5v10H9z")};0&&(module.exports={GLYPHS,GLYPH_STROKE_WIDTH});

package/dist/utils/glyph-data.d.cts

@@ -0,0 +1,13 @@
+/** A built-in glyph name. */
+export type GlyphName = 'check' | 'dash' | 'close' | 'dot' | 'star' | 'chevron-down' | 'chevron-right' | 'chevron-left' | 'arrow-right' | 'arrow-left' | 'chevrons-right' | 'chevrons-left' | 'play' | 'pause';
+/** The shape behind a {@link GlyphName}. */
+export interface Glyph {
+    viewBox: string;
+    d: string;
+    /** Filled with currentColor rather than stroked. */
+    fill: boolean;
+}
+/** Stroke width every stroked glyph is drawn at. */
+export declare const GLYPH_STROKE_WIDTH = 1.5;
+/** Every built-in glyph, keyed by name. */
+export declare const GLYPHS: Record<GlyphName, Glyph>;

package/dist/utils/glyph-data.d.ts

@@ -0,0 +1,13 @@
+/** A built-in glyph name. */
+export type GlyphName = 'check' | 'dash' | 'close' | 'dot' | 'star' | 'chevron-down' | 'chevron-right' | 'chevron-left' | 'arrow-right' | 'arrow-left' | 'chevrons-right' | 'chevrons-left' | 'play' | 'pause';
+/** The shape behind a {@link GlyphName}. */
+export interface Glyph {
+    viewBox: string;
+    d: string;
+    /** Filled with currentColor rather than stroked. */
+    fill: boolean;
+}
+/** Stroke width every stroked glyph is drawn at. */
+export declare const GLYPH_STROKE_WIDTH = 1.5;
+/** Every built-in glyph, keyed by name. */
+export declare const GLYPHS: Record<GlyphName, Glyph>;

package/dist/utils/glyph-data.js

@@ -0,0 +1,2 @@
+'use client';
+var t=1.5,l=(e,o="0 0 16 16")=>({viewBox:o,d:e,fill:!1}),r=(e,o="0 0 16 16")=>({viewBox:o,d:e,fill:!0}),h={check:l("M3 8.5l3 3 7-7"),dash:l("M4 8h8"),close:l("M4 4l8 8M12 4l-8 8"),dot:r("M8 5a3 3 0 1 0 0 6 3 3 0 1 0 0-6z"),star:r("M10 1.5l2.6 5.6 6.1.7-4.5 4.2 1.2 6-5.4-3-5.4 3 1.2-6-4.5-4.2 6.1-.7z","0 0 20 20"),"chevron-down":l("M4 6l4 4 4-4"),"chevron-right":l("M6 4l4 4-4 4"),"chevron-left":l("M10 4l-4 4 4 4"),"arrow-right":l("M3 8h10M9 4l4 4-4 4"),"arrow-left":l("M13 8H3M7 4L3 8l4 4"),"chevrons-right":l("M3 4l4 4-4 4M9 4l4 4-4 4"),"chevrons-left":l("M13 4L9 8l4 4M7 4L3 8l4 4"),play:r("M5 3.5l7 4.5-7 4.5z"),pause:r("M4.5 3h2.5v10H4.5zM9 3h2.5v10H9z")};export{h as GLYPHS,t as GLYPH_STROKE_WIDTH};

package/dist/utils/hiddenInput.cjs

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

package/dist/utils/hiddenInput.d.cts

@@ -1,12 +1,13 @@
-import * as React from 'react';
+import type * as React from 'react';
 interface HiddenInputProps extends React.InputHTMLAttributes<HTMLInputElement> {
 }
-/**
- * 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>>;
+/** Visually hidden native input for form controls to participate in form submission, never `readOnly` or `type="hidden"` since both break constraint validation; ref-forwarded for programmatic `.click()`. */
+export declare const HiddenInput: {
+    ({ ref: forwardedRef, ...props }: Omit<HiddenInputProps, "ref"> & {
+        ref?: React.Ref<HTMLInputElement> | undefined;
+    }): React.ReactNode;
+    displayName: string;
+};
 /** What {@link MirroredValues} needs to mirror one array-valued selection. */
 export interface MirroredValuesProps {
     /** Required shared name; without it, nothing is rendered. */
@@ -14,23 +15,18 @@ export interface MirroredValuesProps {
     /** Selected values in submission order. */
     values: readonly string[];
     /** Marks controls required; empty selection triggers `valueMissing`. */
-    required?: boolean;
+    required?: boolean | undefined;
     /** Withholds value from submission. */
-    disabled?: boolean;
+    disabled?: boolean | undefined;
     /** `form` attribute for non-descendant controls. */
-    form?: string;
+    form?: string | undefined;
     /** Browser autofill hint on first control only. */
-    autoComplete?: string;
+    autoComplete?: string | undefined;
     /** True for single-valued control that submits empty entry when empty. */
-    singleValued?: boolean;
+    singleValued?: boolean | undefined;
     /** Ref to first control; answers for entire set. */
-    controlRef?: React.RefObject<HTMLInputElement | null>;
+    controlRef?: React.RefObject<HTMLInputElement | null> | undefined;
 }
-/**
- * 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.
- */
+/** Mirrors one hidden native control per value, all sharing one `name`, so `formData.getAll(name)` reads the selection like native `<select multiple>`; empty selection submits no entries unless `required` or `singleValued`. */
 export declare function MirroredValues({ name, values, required, disabled, form, autoComplete, singleValued, controlRef, }: MirroredValuesProps): React.ReactElement | null;
 export {};

package/dist/utils/hiddenInput.d.ts

@@ -1,12 +1,13 @@
-import * as React from 'react';
+import type * as React from 'react';
 interface HiddenInputProps extends React.InputHTMLAttributes<HTMLInputElement> {
 }
-/**
- * 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>>;
+/** Visually hidden native input for form controls to participate in form submission, never `readOnly` or `type="hidden"` since both break constraint validation; ref-forwarded for programmatic `.click()`. */
+export declare const HiddenInput: {
+    ({ ref: forwardedRef, ...props }: Omit<HiddenInputProps, "ref"> & {
+        ref?: React.Ref<HTMLInputElement> | undefined;
+    }): React.ReactNode;
+    displayName: string;
+};
 /** What {@link MirroredValues} needs to mirror one array-valued selection. */
 export interface MirroredValuesProps {
     /** Required shared name; without it, nothing is rendered. */
@@ -14,23 +15,18 @@ export interface MirroredValuesProps {
     /** Selected values in submission order. */
     values: readonly string[];
     /** Marks controls required; empty selection triggers `valueMissing`. */
-    required?: boolean;
+    required?: boolean | undefined;
     /** Withholds value from submission. */
-    disabled?: boolean;
+    disabled?: boolean | undefined;
     /** `form` attribute for non-descendant controls. */
-    form?: string;
+    form?: string | undefined;
     /** Browser autofill hint on first control only. */
-    autoComplete?: string;
+    autoComplete?: string | undefined;
     /** True for single-valued control that submits empty entry when empty. */
-    singleValued?: boolean;
+    singleValued?: boolean | undefined;
     /** Ref to first control; answers for entire set. */
-    controlRef?: React.RefObject<HTMLInputElement | null>;
+    controlRef?: React.RefObject<HTMLInputElement | null> | undefined;
 }
-/**
- * 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.
- */
+/** Mirrors one hidden native control per value, all sharing one `name`, so `formData.getAll(name)` reads the selection like native `<select multiple>`; empty selection submits no entries unless `required` or `singleValued`. */
 export declare function MirroredValues({ name, values, required, disabled, form, autoComplete, singleValued, controlRef, }: MirroredValuesProps): React.ReactElement | null;
 export {};

package/dist/utils/hiddenInput.js

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

package/dist/utils/liveAnnouncer.cjs

@@ -1 +1,2 @@
-"use strict";var m=Object.create;var c=Object.defineProperty;var v=Object.getOwnPropertyDescriptor;var x=Object.getOwnPropertyNames;var L=Object.getPrototypeOf,g=Object.prototype.hasOwnProperty;var E=(e,n)=>{for(var t in n)c(e,t,{get:n[t],enumerable:!0})},s=(e,n,t,o)=>{if(n&&typeof n=="object"||typeof n=="function")for(let i of x(n))!g.call(e,i)&&i!==t&&c(e,i,{get:()=>n[i],enumerable:!(o=v(n,i))||o.enumerable});return e};var P=(e,n,t)=>(t=e!=null?m(L(e)):{},s(n||!e||!e.__esModule?c(t,"default",{value:e,enumerable:!0}):t,e)),T=e=>s(c({},"__esModule",{value:!0}),e);var N={};E(N,{ANNOUNCE_DEBOUNCE_MS:()=>d,LiveAnnouncer:()=>f,announce:()=>u,clearAnnouncements:()=>A,useLiveAnnouncer:()=>C});module.exports=T(N);var l=P(require("react"),1),d=150,y="position:absolute;border:0;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0, 0, 0, 0);white-space:nowrap;word-wrap:normal;",S=["polite","assertive"],r=new Map;function p(e){return document.querySelector(`[data-skdx-live-announcer="${e}"]`)}function a(e){let n=p(e);if(n)return n;let t=document.createElement("div");return t.setAttribute("aria-live",e),t.setAttribute("aria-atomic","true"),t.setAttribute("data-skdx-live-announcer",e),t.style.cssText=y,document.body.appendChild(t),t}function u(e,n="polite"){if(typeof document>"u")return;let t=e.trim();t&&(a(n),clearTimeout(r.get(n)),r.set(n,setTimeout(()=>{r.delete(n);let o=a(n);o.textContent!==t&&(o.textContent=t)},d)))}function A(e){for(let n of S){if(e!==void 0&&n!==e)continue;clearTimeout(r.get(n)),r.delete(n);let t=p(n);t&&(t.textContent="")}}var w={announce:u,clear:A};function C(){return w}function f({message:e,politeness:n="polite"}){return l.useEffect(()=>{u(e,n)},[e,n]),null}f.displayName="LiveAnnouncer";0&&(module.exports={ANNOUNCE_DEBOUNCE_MS,LiveAnnouncer,announce,clearAnnouncements,useLiveAnnouncer});
+'use client';
+"use strict";var f=Object.create;var i=Object.defineProperty;var m=Object.getOwnPropertyDescriptor;var v=Object.getOwnPropertyNames;var L=Object.getPrototypeOf,g=Object.prototype.hasOwnProperty;var P=(n,e)=>{for(var o in e)i(n,o,{get:e[o],enumerable:!0})},u=(n,e,o,r)=>{if(e&&typeof e=="object"||typeof e=="function")for(let t of v(e))!g.call(n,t)&&t!==o&&i(n,t,{get:()=>e[t],enumerable:!(r=m(e,t))||r.enumerable});return n};var x=(n,e,o)=>(o=n!=null?f(L(n)):{},u(e||!n||!n.__esModule?i(o,"default",{value:n,enumerable:!0}):o,n)),y=n=>u(i({},"__esModule",{value:!0}),n);var M={};P(M,{ANNOUNCE_DEBOUNCE_MS:()=>d.ANNOUNCE_DEBOUNCE_MS,LiveAnnouncer:()=>A,announce:()=>c,clearAnnouncements:()=>a,useLiveAnnouncer:()=>h});module.exports=y(M);var s=x(require("react"),1),l=require("./announcer.cjs"),d=require("./announcer.cjs"),p=new l.Announcer;function E(){let n=document.querySelectorAll("dialog[open]"),e=n[n.length-1]??document.body;for(let o of document.querySelectorAll("[data-skdx-live-announcer]"))o.parentElement!==e&&e.append(o)}function c(n,e="polite"){p.announce(n,e),typeof document<"u"&&E()}function a(n){p.clear(n)}var N={announce:c,clear:a};function h(){return N}function A({message:n,politeness:e="polite"}){return s.useEffect(()=>{c(n,e)},[n,e]),null}A.displayName="LiveAnnouncer";0&&(module.exports={ANNOUNCE_DEBOUNCE_MS,LiveAnnouncer,announce,clearAnnouncements,useLiveAnnouncer});

package/dist/utils/liveAnnouncer.d.cts

@@ -1,10 +1,7 @@
-/** Which of the two singleton live regions a message is routed to. */
-export type AnnouncePoliteness = 'polite' | 'assertive';
-/** Debounce for announce; burst of calls collapses to final message only. */
-export declare const ANNOUNCE_DEBOUNCE_MS = 150;
+import { type AnnouncePoliteness } from './announcer.cjs';
+export { ANNOUNCE_DEBOUNCE_MS, type AnnouncePoliteness } from './announcer.cjs';
 /**
- * Announces to screen readers via process-wide `aria-live` region.
- * Debounced and deduplicated; skips empty/whitespace. No-op during SSR.
+ * Announces to screen readers via a process-wide `aria-live` region, debounced to the last message of a burst; a repeat is re-announced, empty/whitespace is skipped, and SSR is a no-op.
  *
  * @example
  * ```ts
@@ -38,7 +35,7 @@ export interface LiveAnnouncerProps {
      * Which live region to use.
      * @default 'polite'
      */
-    politeness?: AnnouncePoliteness;
+    politeness?: AnnouncePoliteness | undefined;
 }
 /**
  * Declarative announcer; announces message on change.

package/dist/utils/liveAnnouncer.d.ts

@@ -1,10 +1,7 @@
-/** Which of the two singleton live regions a message is routed to. */
-export type AnnouncePoliteness = 'polite' | 'assertive';
-/** Debounce for announce; burst of calls collapses to final message only. */
-export declare const ANNOUNCE_DEBOUNCE_MS = 150;
+import { type AnnouncePoliteness } from './announcer.js';
+export { ANNOUNCE_DEBOUNCE_MS, type AnnouncePoliteness } from './announcer.js';
 /**
- * Announces to screen readers via process-wide `aria-live` region.
- * Debounced and deduplicated; skips empty/whitespace. No-op during SSR.
+ * Announces to screen readers via a process-wide `aria-live` region, debounced to the last message of a burst; a repeat is re-announced, empty/whitespace is skipped, and SSR is a no-op.
  *
  * @example
  * ```ts
@@ -38,7 +35,7 @@ export interface LiveAnnouncerProps {
      * Which live region to use.
      * @default 'polite'
      */
-    politeness?: AnnouncePoliteness;
+    politeness?: AnnouncePoliteness | undefined;
 }
 /**
  * Declarative announcer; announces message on change.

package/dist/utils/liveAnnouncer.js

@@ -1 +1,2 @@
-import*as c from"react";var a=150,l="position:absolute;border:0;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0, 0, 0, 0);white-space:nowrap;word-wrap:normal;",d=["polite","assertive"],o=new Map;function u(n){return document.querySelector(`[data-skdx-live-announcer="${n}"]`)}function r(n){let e=u(n);if(e)return e;let t=document.createElement("div");return t.setAttribute("aria-live",n),t.setAttribute("aria-atomic","true"),t.setAttribute("data-skdx-live-announcer",n),t.style.cssText=l,document.body.appendChild(t),t}function s(n,e="polite"){if(typeof document>"u")return;let t=n.trim();t&&(r(e),clearTimeout(o.get(e)),o.set(e,setTimeout(()=>{o.delete(e);let i=r(e);i.textContent!==t&&(i.textContent=t)},a)))}function p(n){for(let e of d){if(n!==void 0&&e!==n)continue;clearTimeout(o.get(e)),o.delete(e);let t=u(e);t&&(t.textContent="")}}var A={announce:s,clear:p};function m(){return A}function f({message:n,politeness:e="polite"}){return c.useEffect(()=>{s(n,e)},[n,e]),null}f.displayName="LiveAnnouncer";export{a as ANNOUNCE_DEBOUNCE_MS,f as LiveAnnouncer,s as announce,p as clearAnnouncements,m as useLiveAnnouncer};
+'use client';
+import*as t from"react";import{Announcer as r}from"./announcer.js";import{ANNOUNCE_DEBOUNCE_MS as m}from"./announcer.js";var i=new r;function u(){let n=document.querySelectorAll("dialog[open]"),e=n[n.length-1]??document.body;for(let o of document.querySelectorAll("[data-skdx-live-announcer]"))o.parentElement!==e&&e.append(o)}function c(n,e="polite"){i.announce(n,e),typeof document<"u"&&u()}function s(n){i.clear(n)}var l={announce:c,clear:s};function A(){return l}function p({message:n,politeness:e="polite"}){return t.useEffect(()=>{c(n,e)},[n,e]),null}p.displayName="LiveAnnouncer";export{m as ANNOUNCE_DEBOUNCE_MS,p as LiveAnnouncer,c as announce,s as clearAnnouncements,A as useLiveAnnouncer};

package/dist/utils/measure-auto-resize.cjs

@@ -0,0 +1,2 @@
+'use client';
+"use strict";var g=Object.defineProperty;var a=Object.getOwnPropertyDescriptor;var c=Object.getOwnPropertyNames;var m=Object.prototype.hasOwnProperty;var p=(e,t)=>{for(var r in t)g(e,r,{get:t[r],enumerable:!0})},x=(e,t,r,n)=>{if(t&&typeof t=="object"||typeof t=="function")for(let o of c(t))!m.call(e,o)&&o!==r&&g(e,o,{get:()=>t[o],enumerable:!(n=a(t,o))||n.enumerable});return e};var H=e=>x(g({},"__esModule",{value:!0}),e);var f={};p(f,{measureAutoResizeHeight:()=>T});module.exports=H(f);function T(e,t,r){let n=getComputedStyle(e),o=d=>parseFloat(d)||0,l=o(n.borderTopWidth)+o(n.borderBottomWidth),u=o(n.paddingTop)+o(n.paddingBottom),h=n.boxSizing==="border-box",s=o(n.lineHeight),b=d=>d*s+(h?u+l:0);e.style.height="auto";let i=e.scrollHeight+(h?l:-u);return r!=null&&s>0&&(i=Math.max(i,b(r))),t!=null&&s>0&&(i=Math.min(i,b(t))),i}0&&(module.exports={measureAutoResizeHeight});

package/dist/utils/measure-auto-resize.d.cts

@@ -0,0 +1,5 @@
+/**
+ * Returns the pixel height an auto-resizing `<textarea>` should be given so it
+ * shows all of its content, floored at `minRows` and capped to `maxRows`.
+ */
+export declare function measureAutoResizeHeight(node: HTMLTextAreaElement, maxRows?: number, minRows?: number): number;

package/dist/utils/measure-auto-resize.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Returns the pixel height an auto-resizing `<textarea>` should be given so it
+ * shows all of its content, floored at `minRows` and capped to `maxRows`.
+ */
+export declare function measureAutoResizeHeight(node: HTMLTextAreaElement, maxRows?: number, minRows?: number): number;

package/dist/utils/measure-auto-resize.js

@@ -0,0 +1,2 @@
+'use client';
+function b(n,s,d){let t=getComputedStyle(n),e=i=>parseFloat(i)||0,g=e(t.borderTopWidth)+e(t.borderBottomWidth),l=e(t.paddingTop)+e(t.paddingBottom),u=t.boxSizing==="border-box",r=e(t.lineHeight),h=i=>i*r+(u?l+g:0);n.style.height="auto";let o=n.scrollHeight+(u?g:-l);return d!=null&&r>0&&(o=Math.max(o,h(d))),s!=null&&r>0&&(o=Math.min(o,h(s))),o}export{b as measureAutoResizeHeight};

package/dist/utils/mentions.cjs

@@ -0,0 +1,3 @@
+'use client';
+"use strict";var l=Object.defineProperty;var g=Object.getOwnPropertyDescriptor;var d=Object.getOwnPropertyNames;var m=Object.prototype.hasOwnProperty;var p=(e,t)=>{for(var r in t)l(e,r,{get:t[r],enumerable:!0})},h=(e,t,r,n)=>{if(t&&typeof t=="object"||typeof t=="function")for(let o of d(t))!m.call(e,o)&&o!==r&&l(e,o,{get:()=>t[o],enumerable:!(n=g(t,o))||n.enumerable});return e};var b=e=>h(l({},"__esModule",{value:!0}),e);var C={};p(C,{DEFAULT_MENTION_TRIGGER:()=>M,caretAnchor:()=>A,findMentionToken:()=>T,insertMention:()=>y,isMentionDismissed:()=>E});module.exports=b(C);var M="@",x=/[\p{L}\p{N}_]/u;function R(e){return e===void 0?["@"]:typeof e=="string"?[...e]:e}function T(e,t,r={}){let{allowedSpaces:n=0,requireWordBoundary:o=!0}=r,s=R(r.triggers),c=Math.max(0,Math.min(t,e.length)),f=0;for(let i=c-1;i>=0;i--){let u=e[i];if(u===`
+`||u==="\r")return null;if(s.includes(u)){let a=i>0?e[i-1]:"";return o&&a!==""&&x.test(a)?null:{trigger:u,query:e.slice(i+1,c),start:i,end:c}}if(/\s/.test(u)&&++f>n)return null}return null}function E(e,t){return e!==null&&e.start===t}function y(e,t,r,n=!0){let o=e.slice(t.end),s=n&&!/^\s/.test(o)?" ":"";return{value:e.slice(0,t.start)+r+s+o,caret:t.start+r.length+s.length}}function A(e,t){return{getBoundingClientRect:()=>{let n=e();return{x:n.left,y:n.top,top:n.top,left:n.left,bottom:n.top+n.height,right:n.left,width:0,height:n.height}},contextElement:t}}0&&(module.exports={DEFAULT_MENTION_TRIGGER,caretAnchor,findMentionToken,insertMention,isMentionDismissed});

package/dist/utils/mentions.d.cts

@@ -0,0 +1,116 @@
+/** The trigger character a Mentions field uses when it configures none. */
+export declare const DEFAULT_MENTION_TRIGGER = "@";
+/** The mention being typed: its trigger character, the text after it, and the range the pair occupies. */
+export interface MentionToken {
+    /** The trigger character that opened the token. */
+    trigger: string;
+    /** Text between the trigger character and the caret — what the item list is filtered by. */
+    query: string;
+    /** Offset of the trigger character in the field value. */
+    start: number;
+    /** Offset just past the query; always the caret offset the token was found at. */
+    end: number;
+}
+/** Where a trigger character is allowed to open a token, and what abandons one. */
+export interface MentionTokenOptions {
+    /**
+     * Trigger characters, either as an array or as one string read a character at a time.
+     * @defaultValue `'@'`
+     */
+    triggers?: string | readonly string[] | undefined;
+    /**
+     * How many spaces a query may contain before the token is abandoned.
+     * @defaultValue 0
+     */
+    allowedSpaces?: number | undefined;
+    /**
+     * Whether a trigger opens a token only at the start of the value or after a non-word character, so `user@example` is left alone.
+     * @defaultValue true
+     */
+    requireWordBoundary?: boolean | undefined;
+}
+/**
+ * The mention token the caret sits in, found by scanning backwards from the
+ * caret to the nearest trigger character.
+ *
+ * Returns `null` for every condition that ends a mention: no trigger before
+ * the caret, a line break between them, more spaces than `allowedSpaces`, a
+ * trigger that fails the word-boundary rule, or a caret that has moved out of
+ * the token. There is no token to cancel — call this again after every value,
+ * caret or selection change and the answer is the whole state.
+ *
+ * @param value the field's full text
+ * @param caret the caret offset, clamped into the value
+ * @param options the trigger and boundary rules
+ */
+export declare function findMentionToken(value: string, caret: number, options?: MentionTokenOptions): MentionToken | null;
+/**
+ * Whether an Escape recorded at `dismissedAt` still suppresses this token.
+ *
+ * Escape closes the popup while the token is still syntactically alive, so the
+ * offset of the dismissed trigger is held until {@link findMentionToken}
+ * returns `null` — which is the adapter's cue to forget it.
+ *
+ * @param token the token found for the current caret, or `null`
+ * @param dismissedAt the `start` of the token Escape closed, or `null`
+ */
+export declare function isMentionDismissed(token: MentionToken | null, dismissedAt: number | null): boolean;
+/** The field value and caret offset an insertion produces. */
+export interface MentionInsertion {
+    /** The whole field value with the token's range replaced. */
+    value: string;
+    /** Caret offset just past the inserted text, and past the appended space when one was added. */
+    caret: number;
+}
+/**
+ * Replaces a token's range with the serialized mention text.
+ *
+ * @param value the field value the token was found in
+ * @param token the token being replaced, from {@link findMentionToken}
+ * @param text the full replacement including the trigger character
+ * @param appendSpace whether a single space follows the mention, skipped when the value already continues with whitespace
+ */
+export declare function insertMention(value: string, token: MentionToken, text: string, appendSpace?: boolean): MentionInsertion;
+/** The caret's position in viewport coordinates, as an adapter measured it. */
+export interface CaretRect {
+    /** Distance in pixels from the viewport's top edge to the caret's top. */
+    top: number;
+    /** Distance in pixels from the viewport's left edge to the caret. */
+    left: number;
+    /** The caret's height in pixels, normally the field's computed line height. */
+    height: number;
+}
+/** The rectangle floating-ui reads off a positioning reference. */
+export interface AnchorRect {
+    x: number;
+    y: number;
+    top: number;
+    left: number;
+    bottom: number;
+    right: number;
+    width: number;
+    height: number;
+}
+/** A positioning reference that is a rectangle rather than an element. */
+export interface VirtualAnchor {
+    getBoundingClientRect(): AnchorRect;
+    /** The element the rect lives inside, so floating-ui can observe ancestor scroll and resize. */
+    contextElement: Element;
+}
+/**
+ * Wraps a caret measurement as the zero-width virtual anchor the popup is
+ * positioned against.
+ *
+ * The measurement is re-read on every call, so one anchor survives a moved
+ * caret without being rebuilt, and `contextElement` is what lets floating-ui
+ * observe the ancestor scroll and resize that make it re-read.
+ *
+ * @param measure re-reads the caret rectangle, normally closing over a {@link MeasureCaretRect}, its field and the offset
+ * @param contextElement the field the caret sits in
+ */
+export declare function caretAnchor(measure: () => CaretRect, contextElement: Element): VirtualAnchor;
+/**
+ * The caret measurement each adapter implements with its own DOM work: the
+ * viewport rectangle of the caret at `offset` inside `field`.
+ */
+export type MeasureCaretRect = (field: HTMLTextAreaElement | HTMLInputElement, offset: number) => CaretRect;