@skdx/react 0.26.0 → 0.28.0

package/dist/form/Form.d.ts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import type { FormContextValue, FormProps } from './types.js';
+import type { FormContextValue, FormProps, FormRootProps } from './types.js';
 export declare const FormProvider: {
     (props: FormContextValue & {
         children: React.ReactNode;
@@ -7,31 +7,53 @@ export declare const FormProvider: {
     displayName: string;
 }, useFormContext: (consumerName: string) => FormContextValue;
 /**
- * Root of a form: wires the browser's native Constraint Validation API into
- * a headless error-message system and hands per-field `ValidityState`
- * snapshots down to `FormField`/`FormControl`/`FormMessage` via context.
- * Renders a plain `<form>`.
+ * Wires native Constraint Validation API into headless error-message system.
+ * Hands per-field `ValidityState` snapshots to `FormField`/`FormControl`/`FormMessage` via context.
+ * Uses native validators (`required`, `pattern`, `type="email"`, etc); no custom validators.
+ * On submit, `checkValidity()` captures native `invalid` events (suppressing bubbles),
+ * fires `onFieldInvalid` per failure, prevents submit if any field fails.
  *
- * No custom validators — `required`/`pattern`/`min`/`type="email"` etc. on
- * the consumer's own input (rendered through `FormControl`) do the
- * validating. On submit, `checkValidity()` runs across every field; if any
- * fail, the native `invalid` event is captured (suppressing the browser's
- * validation-bubble UI) to snapshot that field's validity, the submit is
- * prevented, and `onSubmit` is not called. Fields are also re-validated on
- * `blur` and `change`.
+ * Wrap with `FormAnatomy` for derived error summary/submit button.
+ * Use directly via `@skdx/react/primitives/form`'s `FormRoot` for full manual composition.
  *
  * @example
  * ```tsx
- * <Form onSubmit={(e) => console.log('submitted')}>
- *   <FormField name="email">
+ * import { FormControl, FormFieldRoot, FormLabel, FormMessage, FormRoot, FormSubmit } from '@skdx/react/primitives/form';
+ *
+ * <FormRoot onSubmit={(e) => console.log('submitted')}>
+ *   <FormFieldRoot name="email">
  *     <FormLabel>Email</FormLabel>
  *     <FormControl>
  *       <input type="email" required />
  *     </FormControl>
  *     <FormMessage match="valueMissing">Email is required.</FormMessage>
  *     <FormMessage match="typeMismatch">Enter a valid email.</FormMessage>
- *   </FormField>
+ *   </FormFieldRoot>
  *   <FormSubmit>Submit</FormSubmit>
+ * </FormRoot>
+ * ```
+ */
+export declare const FormRoot: React.ForwardRefExoticComponent<Omit<FormRootProps, "ref"> & React.RefAttributes<HTMLFormElement>>;
+/**
+ * A form: native constraint validation wired into a headless error-message
+ * system, with per-field `ValidityState` snapshots handed to every descendant
+ * `FormField`.
+ *
+ * Draws the derived anatomy from `errorSummary`/`submitLabel`: the error
+ * summary ahead of the fields, the fields (`children`), and the submit button
+ * after them. Both are opt-in **by presence of their copy** — a heading and a
+ * button label are the consumer's own words, so with neither prop set the
+ * form derives nothing at all. `children` is the form's own content, never a
+ * switch. `FormField` stays public — placing one is a real semantic decision
+ * — while `FormLabel`, `FormControl`, `FormMessage`, `FormSubmit` and `FormErrorSummary` are
+ * primitives.
+ *
+ * @example
+ * ```tsx
+ * <Form onSubmit={save} errorSummary="There is a problem" submitLabel="Save">
+ *   <FormField name="email" label="Email" message="Enter a valid email.">
+ *     <input type="email" required />
+ *   </FormField>
  * </Form>
  * ```
  */

package/dist/form/Form.js

@@ -1 +1 @@
-import*as l from"react";import{useComposedRefs as D}from"../utils/composeRefs.js";import{createSafeContext as _}from"../utils/createContext.js";import{skdxPart as A}from"../utils/part.js";import{Primitive as O}from"../utils/primitive.js";import{jsx as h}from"react/jsx-runtime";function U(e){return{badInput:e.badInput,customError:e.customError,patternMismatch:e.patternMismatch,rangeOverflow:e.rangeOverflow,rangeUnderflow:e.rangeUnderflow,stepMismatch:e.stepMismatch,tooLong:e.tooLong,tooShort:e.tooShort,typeMismatch:e.typeMismatch,valueMissing:e.valueMissing,valid:e.valid}}var[B,E]=_("Form"),G=l.forwardRef(({onSubmit:e,...t},o)=>{let i=l.useRef(null),m=D(o,i),[c,f]=l.useState({}),d=l.useCallback(r=>{if(!r||!("validity"in r)||!("name"in r))return;let a=r;a.name&&f(p=>({...p,[a.name]:U(a.validity)}))},[]);return l.useEffect(()=>{let r=i.current;if(!r)return;let a=u=>{u.preventDefault(),d(u.target)},p=u=>d(u.target);return r.addEventListener("invalid",a,!0),r.addEventListener("blur",p,!0),r.addEventListener("change",p,!0),()=>{r.removeEventListener("invalid",a,!0),r.removeEventListener("blur",p,!0),r.removeEventListener("change",p,!0)}},[d]),h(B,{validities:c,children:h(O.form,{...t,...A("form","root",t.className),ref:m,onSubmit:r=>{if(r.defaultPrevented)return;let a=i.current;if(a){if(!a.checkValidity()){r.preventDefault();return}e?.(r)}}})})});G.displayName="Form";import*as v from"react";import{createSafeContext as Y}from"../utils/createContext.js";import{skdxPart as $}from"../utils/part.js";import{Primitive as q}from"../utils/primitive.js";import{jsx as S}from"react/jsx-runtime";var[z,F]=Y("FormField"),g=v.forwardRef(({name:e,...t},o)=>{let i=v.useId(),m=v.useId();return S(z,{name:e,id:i,messageId:m,children:S(q.div,{...t,...$("form","field",t.className),ref:o})})});g.displayName="FormField";import*as x from"react";import{skdxPart as J}from"../utils/part.js";import{Primitive as K}from"../utils/primitive.js";import{jsx as Q}from"react/jsx-runtime";var L=x.forwardRef((e,t)=>{let o=F("FormLabel");return Q(K.label,{htmlFor:o.id,...e,...J("form","label",e.className),ref:t})});L.displayName="FormLabel";import*as M from"react";import{skdxPart as W}from"../utils/part.js";import{Slot as X}from"../utils/slot.js";import{jsx as Z}from"react/jsx-runtime";var C=M.forwardRef((e,t)=>{let o=F("FormControl"),m=E("FormControl").validities[o.name],c=m?!m.valid:!1,f={id:o.id,name:o.name,"aria-invalid":c||void 0,"aria-describedby":c?o.messageId:void 0};return Z(X,{...f,...e,...W("form","control",e.className),ref:t})});C.displayName="FormControl";import*as N from"react";import{skdxPart as j}from"../utils/part.js";import{Primitive as ee}from"../utils/primitive.js";import{jsx as re}from"react/jsx-runtime";var V=N.forwardRef(({match:e,forceMatch:t,...o},i)=>{let m=F("FormMessage"),f=E("FormMessage").validities[m.name],d=t??!1;return!d&&f&&(d=e?f[e]===!0:!f.valid),d?re(ee.span,{id:m.messageId,...o,...j("form","message",o.className),ref:i}):null});V.displayName="FormMessage";import*as T from"react";import{skdxPart as oe}from"../utils/part.js";import{Primitive as te}from"../utils/primitive.js";import{jsx as me}from"react/jsx-runtime";var k=T.forwardRef((e,t)=>me(te.button,{type:"submit",...e,...oe("form","submit",e.className),ref:t}));k.displayName="FormSubmit";import*as s from"react";import{collectFieldErrors as se,errorSummaryScope as ae,FIELD_VALIDITY_CHANGE_EVENT as I,focusFieldTarget as ie}from"../field/Field.js";import{useComposedRefs as ne}from"../utils/composeRefs.js";import{skdxPart as y}from"../utils/part.js";import{Primitive as le}from"../utils/primitive.js";import{jsx as P,jsxs as fe}from"react/jsx-runtime";var w=s.forwardRef(({autoFocus:e=!0,children:t,...o},i)=>{let[m,c]=s.useState([]),[f,d]=s.useState(0),r=s.useRef(null),a=s.useRef(null),p=ne(i,r),u=s.useRef(!1);return s.useEffect(()=>{let n=r.current;if(!n)return;let R=ae(n);a.current=R;let b=()=>d(H=>H+1);return R.addEventListener(I,b),()=>R.removeEventListener(I,b)},[]),s.useEffect(()=>{let n=a.current;n&&c(se(n))},[f]),s.useEffect(()=>{if(m.length===0){u.current=!1;return}u.current||(u.current=!0,e&&r.current?.focus())},[m,e]),fe(le.div,{role:"alert",tabIndex:-1,"data-skdx-error-summary":"",hidden:m.length===0||void 0,...o,...y("form","error-summary",o.className),ref:p,children:[m.length>0?t:null,P("ul",{...y("form","error-summary-list"),children:m.map(n=>P("li",{children:P("a",{...y("form","error-summary-link"),href:`#${n.id}`,onClick:R=>{R.preventDefault(),ie(n.id)},children:n.message})},n.id))})]})});w.displayName="FormErrorSummary";export{G as Form,C as FormControl,w as FormErrorSummary,g as FormField,L as FormLabel,V as FormMessage,B as FormProvider,k as FormSubmit,E as useFormContext};
+import*as m from"react";import{resetFields as De,validateFields as _e}from"../field/Field.js";import{createSafeContext as Be}from"../utils/createContext.js";import{skdxPart as Oe}from"../utils/part.js";import{Primitive as Ue}from"../utils/primitive.js";import{useCallbackRef as le}from"../utils/useCallbackRef.js";import*as P from"react";import{skdxPart as ge}from"../utils/part.js";import{Slot as be}from"../utils/slot.js";function W(...e){let r=[];for(let o of e)for(let s of(o??"").split(/\s+/))s&&!r.includes(s)&&r.push(s);return r.length>0?r.join(" "):void 0}import*as h from"react";import{FIELD_NAME_ATTRIBUTE as ue,FORM_FIELD_ATTRIBUTE as pe}from"../field/Field.js";import{createSafeContext as Fe}from"../utils/createContext.js";import{skdxPart as Re}from"../utils/part.js";import{Primitive as Ee}from"../utils/primitive.js";import{jsx as V}from"react/jsx-runtime";var[ye,x]=Fe("FormField"),X=h.forwardRef(({name:e,...r},o)=>{let s=h.useId(),n=h.useId();return V(ye,{name:e,id:s,messageId:n,children:V(Ee.div,{[pe]:"",[ue]:e,...r,...Re("form","field",r.className),ref:o})})});X.displayName="FormFieldRoot";var Z=h.forwardRef(({label:e,message:r,children:o,...s},n)=>V(X,{...s,ref:n,children:V(j,{label:e,message:r,children:o})}));Z.displayName="FormField";import{jsx as ve}from"react/jsx-runtime";var A=P.forwardRef(({children:e,...r},o)=>{let s=x("FormControl"),n=H("FormControl"),d=n.validities[s.name],f=(d?!d.valid:!1)||n.serverErrors(s.name).length>0,u=P.isValidElement(e)?e:null,a=W(r["aria-describedby"],u?.props["aria-describedby"],f?s.messageId:void 0),F={id:s.id,name:s.name,"aria-invalid":f||void 0};return ve(be,{...F,...r,"aria-describedby":a,...ge("form","control",r.className),ref:o,children:u?P.cloneElement(u,{"aria-describedby":a}):e})});A.displayName="FormControl";import*as l from"react";import{collectFieldErrors as he,ERROR_SUMMARY_RESCAN_EVENTS as ee,errorSummaryScope as xe,focusFieldTarget as Pe}from"../field/Field.js";import{useComposedRefs as Me}from"../utils/composeRefs.js";import{skdxPart as D}from"../utils/part.js";import{Primitive as Se}from"../utils/primitive.js";import{Fragment as re,jsx as w,jsxs as te}from"react/jsx-runtime";var _=l.forwardRef(({autoFocus:e=!0,children:r,...o},s)=>{let[n,d]=l.useState([]),[f,u]=l.useState(0),a=l.useRef(null),F=l.useRef(null),b=Me(s,a),y=l.useRef(!1);l.useEffect(()=>{let c=a.current;if(!c)return;let E=xe(c);F.current=E;let C=()=>u(g=>g+1);for(let g of ee)E.addEventListener(g,C,!0);return()=>{for(let g of ee)E.removeEventListener(g,C,!0)}},[]),l.useEffect(()=>{let c=F.current;c&&d(he(c))},[f]),l.useEffect(()=>{if(n.length===0){y.current=!1;return}y.current||(y.current=!0,e&&a.current?.focus())},[n,e]);let L=D("form","error-summary",o.className),T=w("ul",{role:"list",...D("form","error-summary-list"),children:n.map(c=>w("li",{children:w("a",{...D("form","error-summary-link"),href:`#${c.id}`,onClick:E=>{E.preventDefault(),Pe(c.id)},children:c.message})},c.id))}),v=o.asChild&&l.isValidElement(r)?l.cloneElement(r,void 0,te(re,{children:[n.length>0?r.props.children:null,T]})):te(re,{children:[n.length>0?r:null,T]});return w(Se.div,{role:"alert",tabIndex:-1,"data-skdx-error-summary":"",hidden:n.length===0||void 0,...o,...L,ref:b,children:v})});_.displayName="FormErrorSummary";import*as oe from"react";import{skdxPart as Le}from"../utils/part.js";import{Primitive as Te}from"../utils/primitive.js";import{jsx as Ce}from"react/jsx-runtime";var B=oe.forwardRef((e,r)=>{let o=x("FormLabel");return Ce(Te.label,{htmlFor:o.id,...e,...Le("form","label",e.className),ref:r})});B.displayName="FormLabel";import*as M from"react";import{FORM_MESSAGE_ATTRIBUTE as ke}from"../field/Field.js";import{skdxPart as Ne}from"../utils/part.js";import{Primitive as Ve}from"../utils/primitive.js";function se(e){return e===void 0?[]:(Array.isArray(e)?e:[e]).filter(o=>typeof o=="string"&&o.trim()!=="")}function O(e){return e.join(" ")}import{jsx as He}from"react/jsx-runtime";var U=M.forwardRef(({match:e,forceMatch:r,children:o,...s},n)=>{let d=x("FormMessage"),f=H("FormMessage"),u=f.validities[d.name],a=e?[]:f.serverErrors(d.name),F=r??a.length>0;!F&&u&&(F=e?u[e]===!0:!u.valid);let b=a.length===0?o:s.asChild&&M.isValidElement(o)?M.cloneElement(o,void 0,O(a)):O(a);return He(Ve.span,{id:d.messageId,hidden:!F||void 0,[ke]:"",...s,...Ne("form","message",s.className),ref:n,children:b})});U.displayName="FormMessage";import*as ne from"react";import{skdxPart as we}from"../utils/part.js";import{Primitive as Ie}from"../utils/primitive.js";import{jsx as Ae}from"react/jsx-runtime";var q=ne.forwardRef((e,r)=>Ae(Ie.button,{type:"submit",...e,...we("form","submit",e.className),ref:r}));q.displayName="FormSubmit";import{Fragment as ae,jsx as S,jsxs as ie}from"react/jsx-runtime";var me=({errorSummary:e,submitLabel:r,children:o})=>ie(ae,{children:[e?S(_,{children:S("h2",{className:"skdx-form__error-summary-title",children:e})}):null,o,r?S(q,{children:r}):null]}),j=({label:e,message:r,children:o})=>ie(ae,{children:[e?S(B,{children:e}):null,S(A,{children:o}),S(U,{children:r})]});import{jsx as I}from"react/jsx-runtime";function qe(e){return{badInput:e.badInput,customError:e.customError,patternMismatch:e.patternMismatch,rangeOverflow:e.rangeOverflow,rangeUnderflow:e.rangeUnderflow,stepMismatch:e.stepMismatch,tooLong:e.tooLong,tooShort:e.tooShort,typeMismatch:e.typeMismatch,valueMissing:e.valueMissing,valid:e.valid}}var[ze,H]=Be("Form"),ce=m.forwardRef(({errors:e,onSubmit:r,onReset:o,onFieldInvalid:s,validationMode:n="change",validationBehavior:d="native",...f},u)=>{let a=m.useRef(null),[F,b]=m.useState({}),[y,L]=m.useState([]),T=m.useRef(e);T.current!==e&&(T.current=e,y.length>0&&L([]));let v=m.useRef({validationMode:n,validationBehavior:d});v.current={validationMode:n,validationBehavior:d};let c=m.useRef(!1),E=le(s),C=le(o),g=m.useCallback(t=>y.includes(t)?[]:se(e?.[t]),[e,y]),k=m.useCallback(t=>{if(!t||!("validity"in t)||!("name"in t))return;let i=t;i.name&&b(R=>({...R,[i.name]:qe(i.validity)}))},[]),z=m.useCallback(t=>{let i=t?.name;i&&L(R=>R.includes(i)?R:[...R,i])},[]);m.useEffect(()=>{let t=a.current;if(!t)return;let i=null,R=p=>{p.preventDefault(),k(p.target);let N=p.target;if(N?.name&&N.validity&&E({name:N.name,validity:N.validity}),i)return;i=p.target;let fe=c.current||v.current.validationBehavior==="aria";queueMicrotask(()=>{let K=i;if(i=null,!K||fe)return;let Q=t.querySelector("[data-skdx-error-summary]");Q&&!Q.hasAttribute("hidden")||K.focus()})},Y=p=>{v.current.validationMode!=="submit"&&k(p.target)},$=p=>{v.current.validationMode==="change"&&k(p.target),z(p.target)},J=p=>{b({}),L([]),De(t),C(p)};return t.addEventListener("invalid",R,!0),t.addEventListener("blur",Y,!0),t.addEventListener("change",$,!0),t.addEventListener("reset",J),()=>{t.removeEventListener("invalid",R,!0),t.removeEventListener("blur",Y,!0),t.removeEventListener("change",$,!0),t.removeEventListener("reset",J)}},[k,z,E,C]);let G=m.useCallback(async()=>{let t=a.current;if(!t)return!0;c.current=!0;let i=t.checkValidity();c.current=!1;let R=await _e(t);return i&&R},[]);return m.useImperativeHandle(u,()=>a.current?Object.assign(a.current,{validate:G}):{validate:G}),I(ze,{validities:F,serverErrors:g,children:I(Ue.form,{...f,...Oe("form","root",f.className),ref:a,noValidate:d==="aria"?!0:f.noValidate,onSubmit:t=>{if(t.defaultPrevented)return;let i=a.current;if(i){if(d==="aria"){i.checkValidity(),r?.(t);return}if(!i.checkValidity()){t.preventDefault();return}r?.(t)}}})})});ce.displayName="FormRoot";var de=m.forwardRef(({errorSummary:e,submitLabel:r,children:o,...s},n)=>I(ce,{...s,ref:n,children:I(me,{errorSummary:e,submitLabel:r,children:o})}));de.displayName="Form";export{de as Form,A as FormControl,_ as FormErrorSummary,Z as FormField,ye as FormFieldProvider,X as FormFieldRoot,B as FormLabel,U as FormMessage,ze as FormProvider,ce as FormRoot,q as FormSubmit,H as useFormContext,x as useFormFieldContext};

package/dist/form/FormAnatomy.d.cts

@@ -0,0 +1,29 @@
+import type * as React from 'react';
+/**
+ * Anatomy a {@link Form} draws from `errorSummary`/`submitLabel`: summary,
+ * fields (`children`), submit button. Each piece is conditional.
+ *
+ * @internal
+ */
+export declare const FormAnatomy: ({ errorSummary, submitLabel, children, }: {
+    errorSummary?: string;
+    submitLabel?: string;
+    children?: React.ReactNode;
+}) => React.JSX.Element;
+/**
+ * The anatomy a {@link FormField} draws from `label`/`message`: the label, the
+ * control (`children`, injected with the field's id, name, `aria-invalid` and
+ * `aria-describedby` through `FormControl`'s slot), and the catch-all message
+ * the control's `aria-describedby` resolves to.
+ *
+ * `FormMessage` is rendered unconditionally and stays in the DOM `hidden`
+ * while the field is valid — an `aria-describedby` naming a missing element
+ * computes an *empty* description rather than falling back to none.
+ *
+ * @internal
+ */
+export declare const FormFieldAnatomy: ({ label, message, children, }: {
+    label?: React.ReactNode;
+    message?: React.ReactNode;
+    children?: React.ReactNode;
+}) => React.JSX.Element;

package/dist/form/FormAnatomy.d.ts

@@ -0,0 +1,29 @@
+import type * as React from 'react';
+/**
+ * Anatomy a {@link Form} draws from `errorSummary`/`submitLabel`: summary,
+ * fields (`children`), submit button. Each piece is conditional.
+ *
+ * @internal
+ */
+export declare const FormAnatomy: ({ errorSummary, submitLabel, children, }: {
+    errorSummary?: string;
+    submitLabel?: string;
+    children?: React.ReactNode;
+}) => React.JSX.Element;
+/**
+ * The anatomy a {@link FormField} draws from `label`/`message`: the label, the
+ * control (`children`, injected with the field's id, name, `aria-invalid` and
+ * `aria-describedby` through `FormControl`'s slot), and the catch-all message
+ * the control's `aria-describedby` resolves to.
+ *
+ * `FormMessage` is rendered unconditionally and stays in the DOM `hidden`
+ * while the field is valid — an `aria-describedby` naming a missing element
+ * computes an *empty* description rather than falling back to none.
+ *
+ * @internal
+ */
+export declare const FormFieldAnatomy: ({ label, message, children, }: {
+    label?: React.ReactNode;
+    message?: React.ReactNode;
+    children?: React.ReactNode;
+}) => React.JSX.Element;

package/dist/form/FormErrorSummary.d.cts

@@ -1,20 +1,10 @@
 import * as React from 'react';
 import type { FormErrorSummaryProps } from './types.cjs';
 /**
- * The GOV.UK error summary for a {@link Form}: a `role="alert"` container
- * listing one in-page link per currently-failing `Field`, focused the first
- * time it appears so a keyboard or screen-reader user lands on the errors
- * rather than back at the top of the page.
- *
- * It keeps no field registry. It scans its form for
- * `[data-skdx-field][data-invalid]` and re-scans whenever a Field's bubbling
- * `validity-change` event reaches it, so any Field anywhere in the form is
- * listed without registering itself. Clicking a link focuses that field's
- * control — or, when the field is a group, the first control *inside* the
- * group, which is the GOV.UK rule.
- *
- * Rendered (empty and `hidden`) even with nothing to report, so the alert
- * fires when its content appears.
+ * Error summary for a {@link Form}: `role="alert"` listing links to failing fields,
+ * focused on first appearance so keyboard and screen-reader users land on errors.
+ * Scans for `[data-skdx-field][data-invalid]` and re-scans on `validity-change` events.
+ * Rendered `hidden` when empty so the alert fires when errors appear.
  *
  * @example
  * ```tsx

package/dist/form/FormErrorSummary.d.ts

@@ -1,20 +1,10 @@
 import * as React from 'react';
 import type { FormErrorSummaryProps } from './types.js';
 /**
- * The GOV.UK error summary for a {@link Form}: a `role="alert"` container
- * listing one in-page link per currently-failing `Field`, focused the first
- * time it appears so a keyboard or screen-reader user lands on the errors
- * rather than back at the top of the page.
- *
- * It keeps no field registry. It scans its form for
- * `[data-skdx-field][data-invalid]` and re-scans whenever a Field's bubbling
- * `validity-change` event reaches it, so any Field anywhere in the form is
- * listed without registering itself. Clicking a link focuses that field's
- * control — or, when the field is a group, the first control *inside* the
- * group, which is the GOV.UK rule.
- *
- * Rendered (empty and `hidden`) even with nothing to report, so the alert
- * fires when its content appears.
+ * Error summary for a {@link Form}: `role="alert"` listing links to failing fields,
+ * focused on first appearance so keyboard and screen-reader users land on errors.
+ * Scans for `[data-skdx-field][data-invalid]` and re-scans on `validity-change` events.
+ * Rendered `hidden` when empty so the alert fires when errors appear.
  *
  * @example
  * ```tsx

package/dist/form/FormField.d.cts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import type { FormFieldContextValue, FormFieldProps } from './types.cjs';
+import type { FormFieldContextValue, FormFieldProps, FormFieldRootProps } from './types.cjs';
 export declare const FormFieldProvider: {
     (props: FormFieldContextValue & {
         children: React.ReactNode;
@@ -7,18 +7,31 @@ export declare const FormFieldProvider: {
     displayName: string;
 }, useFormFieldContext: (consumerName: string) => FormFieldContextValue;
 /**
- * Groups one field's `FormLabel`, `FormControl`, and `FormMessage`(s),
- * generating the shared `id`/`messageId` pair and distributing them plus
- * `name` via context. Renders a plain `<div>`.
+ * FormField's root: generates `id`/`messageId`, distributes them with `name` via context,
+ * renders a plain `<div>`. Use for manual composition to target specific `ValidityState` reasons.
  *
  * @example
  * ```tsx
- * <FormField name="username">
+ * import { FormControl, FormFieldRoot, FormLabel, FormMessage } from '@skdx/react/primitives/form';
+ *
+ * <FormFieldRoot name="username">
  *   <FormLabel>Username</FormLabel>
  *   <FormControl>
  *     <input required />
  *   </FormControl>
  *   <FormMessage>Username is required.</FormMessage>
+ * </FormFieldRoot>
+ * ```
+ */
+export declare const FormFieldRoot: React.ForwardRefExoticComponent<Omit<FormFieldRootProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+/**
+ * One field of a {@link Form}: its label, control, and validation message.
+ * `FormControl` injects `id`, `name`, `aria-invalid`, and `aria-describedby` into the control.
+ *
+ * @example
+ * ```tsx
+ * <FormField name="email" label="Email" message="Enter a valid email.">
+ *   <input type="email" required />
  * </FormField>
  * ```
  */

package/dist/form/FormField.d.ts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import type { FormFieldContextValue, FormFieldProps } from './types.js';
+import type { FormFieldContextValue, FormFieldProps, FormFieldRootProps } from './types.js';
 export declare const FormFieldProvider: {
     (props: FormFieldContextValue & {
         children: React.ReactNode;
@@ -7,18 +7,31 @@ export declare const FormFieldProvider: {
     displayName: string;
 }, useFormFieldContext: (consumerName: string) => FormFieldContextValue;
 /**
- * Groups one field's `FormLabel`, `FormControl`, and `FormMessage`(s),
- * generating the shared `id`/`messageId` pair and distributing them plus
- * `name` via context. Renders a plain `<div>`.
+ * FormField's root: generates `id`/`messageId`, distributes them with `name` via context,
+ * renders a plain `<div>`. Use for manual composition to target specific `ValidityState` reasons.
  *
  * @example
  * ```tsx
- * <FormField name="username">
+ * import { FormControl, FormFieldRoot, FormLabel, FormMessage } from '@skdx/react/primitives/form';
+ *
+ * <FormFieldRoot name="username">
  *   <FormLabel>Username</FormLabel>
  *   <FormControl>
  *     <input required />
  *   </FormControl>
  *   <FormMessage>Username is required.</FormMessage>
+ * </FormFieldRoot>
+ * ```
+ */
+export declare const FormFieldRoot: React.ForwardRefExoticComponent<Omit<FormFieldRootProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+/**
+ * One field of a {@link Form}: its label, control, and validation message.
+ * `FormControl` injects `id`, `name`, `aria-invalid`, and `aria-describedby` into the control.
+ *
+ * @example
+ * ```tsx
+ * <FormField name="email" label="Email" message="Enter a valid email.">
+ *   <input type="email" required />
  * </FormField>
  * ```
  */

package/dist/form/FormLabel.d.cts

@@ -1,9 +1,7 @@
 import * as React from 'react';
 import type { FormLabelProps } from './types.cjs';
 /**
- * A `<label>` for a {@link FormField}'s control. Reads the field's `id` from
- * context and sets `htmlFor` to it, so it must be rendered inside a
- * `FormField` alongside a `FormControl`.
+ * `<label>` for a {@link FormField}'s control. Reads the field's `id` and sets `htmlFor`. Must be used inside a `FormField`.
  *
  * @example
  * ```tsx

package/dist/form/FormLabel.d.ts

@@ -1,9 +1,7 @@
 import * as React from 'react';
 import type { FormLabelProps } from './types.js';
 /**
- * A `<label>` for a {@link FormField}'s control. Reads the field's `id` from
- * context and sets `htmlFor` to it, so it must be rendered inside a
- * `FormField` alongside a `FormControl`.
+ * `<label>` for a {@link FormField}'s control. Reads the field's `id` and sets `htmlFor`. Must be used inside a `FormField`.
  *
  * @example
  * ```tsx

package/dist/form/FormMessage.d.cts

@@ -1,11 +1,11 @@
 import * as React from 'react';
 import type { FormMessageProps } from './types.cjs';
 /**
- * A validation message for a {@link FormField}, rendered as a `<span>` whose
- * `id` matches the field's `aria-describedby`. Renders nothing until either
- * `forceMatch` is set, or the field has a validity snapshot that matches:
- * with `match`, only when that specific `ValidityState` flag (e.g.
- * `valueMissing`) is true; without it, whenever the field is invalid at all.
+ * Validation message for {@link FormField}: `<span>` with `id` matching
+ * the field's `aria-describedby`. `hidden` until `forceMatch` is set or
+ * field validity matches (specific `ValidityState` flag or any invalid).
+ *
+ * Kept `hidden`, not unmounted, so the IDREF resolves and skin can transition the message in.
  *
  * @example
  * ```tsx

package/dist/form/FormMessage.d.ts

@@ -1,11 +1,11 @@
 import * as React from 'react';
 import type { FormMessageProps } from './types.js';
 /**
- * A validation message for a {@link FormField}, rendered as a `<span>` whose
- * `id` matches the field's `aria-describedby`. Renders nothing until either
- * `forceMatch` is set, or the field has a validity snapshot that matches:
- * with `match`, only when that specific `ValidityState` flag (e.g.
- * `valueMissing`) is true; without it, whenever the field is invalid at all.
+ * Validation message for {@link FormField}: `<span>` with `id` matching
+ * the field's `aria-describedby`. `hidden` until `forceMatch` is set or
+ * field validity matches (specific `ValidityState` flag or any invalid).
+ *
+ * Kept `hidden`, not unmounted, so the IDREF resolves and skin can transition the message in.
  *
  * @example
  * ```tsx

package/dist/form/describedBy.d.cts

@@ -0,0 +1,7 @@
+/**
+ * Merges `aria-describedby` id lists instead of replacing. Consumer's descriptions announced first, validation message last.
+ *
+ * @param sources id lists (or single ids), most-consumer-owned first
+ * @returns merged list, or `undefined` when nothing to describe with
+ */
+export declare function mergeDescribedBy(...sources: Array<string | null | undefined>): string | undefined;

package/dist/form/describedBy.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Merges `aria-describedby` id lists instead of replacing. Consumer's descriptions announced first, validation message last.
+ *
+ * @param sources id lists (or single ids), most-consumer-owned first
+ * @returns merged list, or `undefined` when nothing to describe with
+ */
+export declare function mergeDescribedBy(...sources: Array<string | null | undefined>): string | undefined;

package/dist/form/index.d.cts

@@ -1,8 +1,4 @@
-export * from './Form.cjs';
+export { Form } from './Form.cjs';
 export { FormField } from './FormField.cjs';
-export { FormLabel } from './FormLabel.cjs';
-export { FormControl } from './FormControl.cjs';
-export { FormMessage } from './FormMessage.cjs';
-export { FormSubmit } from './FormSubmit.cjs';
-export { FormErrorSummary } from './FormErrorSummary.cjs';
-export type { FormProps, FormFieldProps, FormLabelProps, FormControlProps, FormMessageProps, FormSubmitProps, FormErrorSummaryProps, } from './types.cjs';
+export type { FormErrors } from './serverErrors.cjs';
+export type { FormProps, FormFieldProps } from './types.cjs';

package/dist/form/index.d.ts

@@ -1,8 +1,4 @@
-export * from './Form.js';
+export { Form } from './Form.js';
 export { FormField } from './FormField.js';
-export { FormLabel } from './FormLabel.js';
-export { FormControl } from './FormControl.js';
-export { FormMessage } from './FormMessage.js';
-export { FormSubmit } from './FormSubmit.js';
-export { FormErrorSummary } from './FormErrorSummary.js';
-export type { FormProps, FormFieldProps, FormLabelProps, FormControlProps, FormMessageProps, FormSubmitProps, FormErrorSummaryProps, } from './types.js';
+export type { FormErrors } from './serverErrors.js';
+export type { FormProps, FormFieldProps } from './types.js';

package/dist/form/primitives.d.cts

@@ -0,0 +1,29 @@
+/**
+ * Primitives for `Form` — `FormFieldRoot` is unwrapped grouping (lets `FormMessage` target one `ValidityState` reason).
+ *
+ * @example
+ * ```tsx
+ * import { FormRoot, FormErrorSummary, FormFieldRoot, FormLabel, FormControl, FormMessage, FormSubmit } from '@skdx/react/primitives/form';
+ *
+ * <FormRoot onSubmit={save}>
+ *   <FormErrorSummary />
+ *   <FormFieldRoot name="email">
+ *     <FormLabel>Email</FormLabel>
+ *     <FormControl>
+ *       <input type="email" required />
+ *     </FormControl>
+ *     <FormMessage match="valueMissing">Email is required.</FormMessage>
+ *     <FormMessage match="typeMismatch">Enter a valid email.</FormMessage>
+ *   </FormFieldRoot>
+ *   <FormSubmit>Save</FormSubmit>
+ * </FormRoot>
+ * ```
+ */
+export { FormRoot } from './Form.cjs';
+export { FormFieldRoot } from './FormField.cjs';
+export { FormLabel } from './FormLabel.cjs';
+export { FormControl } from './FormControl.cjs';
+export { FormMessage } from './FormMessage.cjs';
+export { FormSubmit } from './FormSubmit.cjs';
+export { FormErrorSummary } from './FormErrorSummary.cjs';
+export type { FormRootProps, FormFieldRootProps, FormLabelProps, FormControlProps, FormMessageProps, FormSubmitProps, FormErrorSummaryProps, ValiditySnapshot, } from './types.cjs';

package/dist/form/primitives.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Primitives for `Form` — `FormFieldRoot` is unwrapped grouping (lets `FormMessage` target one `ValidityState` reason).
+ *
+ * @example
+ * ```tsx
+ * import { FormRoot, FormErrorSummary, FormFieldRoot, FormLabel, FormControl, FormMessage, FormSubmit } from '@skdx/react/primitives/form';
+ *
+ * <FormRoot onSubmit={save}>
+ *   <FormErrorSummary />
+ *   <FormFieldRoot name="email">
+ *     <FormLabel>Email</FormLabel>
+ *     <FormControl>
+ *       <input type="email" required />
+ *     </FormControl>
+ *     <FormMessage match="valueMissing">Email is required.</FormMessage>
+ *     <FormMessage match="typeMismatch">Enter a valid email.</FormMessage>
+ *   </FormFieldRoot>
+ *   <FormSubmit>Save</FormSubmit>
+ * </FormRoot>
+ * ```
+ */
+export { FormRoot } from './Form.js';
+export { FormFieldRoot } from './FormField.js';
+export { FormLabel } from './FormLabel.js';
+export { FormControl } from './FormControl.js';
+export { FormMessage } from './FormMessage.js';
+export { FormSubmit } from './FormSubmit.js';
+export { FormErrorSummary } from './FormErrorSummary.js';
+export type { FormRootProps, FormFieldRootProps, FormLabelProps, FormControlProps, FormMessageProps, FormSubmitProps, FormErrorSummaryProps, ValiditySnapshot, } from './types.js';

package/dist/form/serverErrors.d.cts

@@ -0,0 +1,8 @@
+/**
+ * Form root's `errors` map — name-keyed channel for server/cross-field/async errors the browser cannot derive.
+ */
+export type FormErrors = Record<string, string | string[]>;
+/** Coerce field's entry into message list, drop blanks. */
+export declare function normalizeFormErrors(entry: string | string[] | undefined): string[];
+/** Join field's server errors into single message (one messageId per field). */
+export declare function formErrorText(messages: readonly string[]): string;

package/dist/form/serverErrors.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Form root's `errors` map — name-keyed channel for server/cross-field/async errors the browser cannot derive.
+ */
+export type FormErrors = Record<string, string | string[]>;
+/** Coerce field's entry into message list, drop blanks. */
+export declare function normalizeFormErrors(entry: string | string[] | undefined): string[];
+/** Join field's server errors into single message (one messageId per field). */
+export declare function formErrorText(messages: readonly string[]): string;