@skdx/react 0.26.0

package/dist/field/Field.d.cts

@@ -0,0 +1,49 @@
+import * as React from 'react';
+import type { FieldContextValue, FieldProps, FieldsetProps } from './types.cjs';
+export declare const FieldProvider: {
+    (props: FieldContextValue & {
+        children: React.ReactNode;
+    }): React.JSX.Element;
+    displayName: string;
+}, useFieldContext: (consumerName: string) => FieldContextValue;
+/**
+ * Wraps one form control and wires its `FieldLabel`, `FieldDescription`, and
+ * `FieldError` to it: generated ids, `aria-describedby`, `aria-invalid`, and
+ * the `data-valid`/`data-invalid`/`data-touched`/`data-dirty`/`data-filled`
+ * state hooks on both the Field and the control. Any control works — an skdx
+ * component, a native `<input>`, or a third-party widget — because the Field
+ * finds it in its own subtree rather than expecting it to cooperate.
+ *
+ * Also owns the field's validation model: `validate` (sync or async),
+ * `mode`, server errors through `errors`, and the wrapped control's own
+ * native constraint validation as a fallback, so plain `required` works with
+ * no configuration.
+ *
+ * @example
+ * ```tsx
+ * <Field validate={(value) => (value ? null : 'Enter your name')}>
+ *   <FieldLabel>Name</FieldLabel>
+ *   <TextField />
+ *   <FieldDescription>As shown on your passport.</FieldDescription>
+ *   <FieldError />
+ * </Field>
+ * ```
+ */
+export declare const Field: React.ForwardRefExoticComponent<Omit<FieldProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+/**
+ * A {@link Field} that renders a `<fieldset>` and puts its `FieldLabel` in a
+ * `<legend>` — the grouping a `RadioGroup` or a set of checkboxes needs,
+ * since a `<label for>` may not point at a `[role="radiogroup"]`. Same props,
+ * same validation model, same state hooks; the group control is named with
+ * `aria-labelledby` instead of `for`/`id`.
+ *
+ * @example
+ * ```tsx
+ * <Fieldset validate={(value) => (value ? null : 'Choose a plan')}>
+ *   <FieldLabel>Plan</FieldLabel>
+ *   <RadioGroup>…</RadioGroup>
+ *   <FieldError />
+ * </Fieldset>
+ * ```
+ */
+export declare const Fieldset: React.ForwardRefExoticComponent<Omit<FieldsetProps, "ref"> & React.RefAttributes<HTMLFieldSetElement>>;

package/dist/field/Field.d.ts

@@ -0,0 +1,49 @@
+import * as React from 'react';
+import type { FieldContextValue, FieldProps, FieldsetProps } from './types.js';
+export declare const FieldProvider: {
+    (props: FieldContextValue & {
+        children: React.ReactNode;
+    }): React.JSX.Element;
+    displayName: string;
+}, useFieldContext: (consumerName: string) => FieldContextValue;
+/**
+ * Wraps one form control and wires its `FieldLabel`, `FieldDescription`, and
+ * `FieldError` to it: generated ids, `aria-describedby`, `aria-invalid`, and
+ * the `data-valid`/`data-invalid`/`data-touched`/`data-dirty`/`data-filled`
+ * state hooks on both the Field and the control. Any control works — an skdx
+ * component, a native `<input>`, or a third-party widget — because the Field
+ * finds it in its own subtree rather than expecting it to cooperate.
+ *
+ * Also owns the field's validation model: `validate` (sync or async),
+ * `mode`, server errors through `errors`, and the wrapped control's own
+ * native constraint validation as a fallback, so plain `required` works with
+ * no configuration.
+ *
+ * @example
+ * ```tsx
+ * <Field validate={(value) => (value ? null : 'Enter your name')}>
+ *   <FieldLabel>Name</FieldLabel>
+ *   <TextField />
+ *   <FieldDescription>As shown on your passport.</FieldDescription>
+ *   <FieldError />
+ * </Field>
+ * ```
+ */
+export declare const Field: React.ForwardRefExoticComponent<Omit<FieldProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+/**
+ * A {@link Field} that renders a `<fieldset>` and puts its `FieldLabel` in a
+ * `<legend>` — the grouping a `RadioGroup` or a set of checkboxes needs,
+ * since a `<label for>` may not point at a `[role="radiogroup"]`. Same props,
+ * same validation model, same state hooks; the group control is named with
+ * `aria-labelledby` instead of `for`/`id`.
+ *
+ * @example
+ * ```tsx
+ * <Fieldset validate={(value) => (value ? null : 'Choose a plan')}>
+ *   <FieldLabel>Plan</FieldLabel>
+ *   <RadioGroup>…</RadioGroup>
+ *   <FieldError />
+ * </Fieldset>
+ * ```
+ */
+export declare const Fieldset: React.ForwardRefExoticComponent<Omit<FieldsetProps, "ref"> & React.RefAttributes<HTMLFieldSetElement>>;

package/dist/field/Field.js

@@ -0,0 +1 @@
+import*as a from"react";import{useComposedRefs as V}from"../utils/composeRefs.js";import{createSafeContext as de}from"../utils/createContext.js";import{announce as ue}from"../utils/liveAnnouncer.js";import{skdxPart as ce}from"../utils/part.js";import{Primitive as k}from"../utils/primitive.js";import{useCallbackRef as he}from"../utils/useCallbackRef.js";var P="validity-change",C="data-skdx-field",R="data-skdx-field-name",I="data-skdx-field-message",A="data-skdx-field-description",E="data-skdx-field-error",x="data-skdx-field-character-count",Z=1e3;function F(r){let e=Math.abs(r),t=e===1?"character":"characters";return r<0?`You have ${e} ${t} too many`:`You have ${e} ${t} remaining`}function b(r,e,t=0){return t<=0?!0:r>=e*t/100}var O="This field is invalid.",D="data-skdx-field-control",N=[`[${D}]`,'input:not([type="hidden"])',"select","textarea",'[role="textbox"]','[role="searchbox"]','[role="combobox"]','[role="listbox"]','[role="radiogroup"]','[role="group"]','[role="slider"]','[role="spinbutton"]','[role="checkbox"]','[role="radio"]','[role="switch"]'].join(", "),ee=new Set(["radiogroup","group"]),te=['input:not([disabled]):not([type="hidden"])',"select:not([disabled])","textarea:not([disabled])","button:not([disabled])",'[tabindex]:not([tabindex="-1"])'].join(", ");function M(r){return r==null?[]:(Array.isArray(r)?r:[r]).filter(t=>typeof t=="string"&&t.trim()!=="")}function _(r){for(let e of Array.from(r.querySelectorAll(N)))if(e.getAttribute("aria-hidden")!=="true"&&e.closest(`[${C}]`)===r)return e;return null}function L(r,e){for(let t of Array.from(r.querySelectorAll(e)))if(t.closest(`[${C}]`)===r)return t;return null}function re(r){if(!r)return;let e=r;return e.type==="checkbox"||e.type==="radio"?e.checked:"value"in r?e.value:r.querySelector('input[aria-hidden="true"]')?.value}function f(r){return r==null||r===!1||r===""?!1:!(Array.isArray(r)&&r.length===0)}function p(r,e,t){t?r.setAttribute(e,""):r.removeAttribute(e)}function oe(r,...e){let t=r.split(/\s+/).filter(Boolean);for(let o of e)o&&!t.includes(o)&&t.push(o);return t.join(" ")}function ie(r){return r.closest("form, skdx-form")??r.parentElement??r}function ne(r){return Array.from(r.querySelectorAll(`[${C}][data-invalid]`)).flatMap(t=>{let o=_(t),n=L(t,`[${E}]`)?.textContent?.trim()||t.getAttribute(I)||t.getAttribute(R)||"";return!o?.id||!n?[]:[{id:o.id,message:n}]})}function se(r,e=document){let t=e.getElementById(r);if(!t)return;let o=t.getAttribute("role"),n=(t.tagName==="FIELDSET"||o!==null&&ee.has(o)?t.querySelector(te):null)??t;n.focus(),n.scrollIntoView?.({block:"center"})}var g=class{constructor(e){this.options=e;this.props={};this.root=null;this.form=null;this.control=null;this.baseDescribedBy="";this.runToken=0;this.pending=!1;this.injected=[];this.custom=[];this.characterCount=null;this.handleInput=()=>{let e=this.isOverLimit(this.snapshot.count),t=this.readCount();this.update({dirty:!0,filled:f(this.resolveValue()),count:t,errors:this.composeErrors(t)}),this.scheduleCountAnnouncement(t,e),(this.props.mode==="change"||this.snapshot.errors.length>0)&&this.runValidation()};this.handleFocusOut=()=>{let e=this.readCount();this.update({touched:!0,filled:f(this.resolveValue()),count:e,errors:this.composeErrors(e)}),((this.props.mode??"blur")==="blur"||this.snapshot.errors.length>0)&&this.runValidation()};this.handleSubmit=e=>{if(e.target!==this.form)return;this.markTouched();let t=this.runValidation({silent:!0});if(S(t)){e.preventDefault();return}(t.length>0||this.pending)&&e.preventDefault()};this.snapshot={controlId:e.controlId,errors:[],valid:!0,touched:!1,dirty:!1,filled:!1,count:0}}get state(){return this.snapshot}setProps(e){let t=this.props.value;this.props=e;let o=M(e.errors??null),i=!ae(this.injected,o);i&&(this.injected=o);let n=e.value!==t;if(!i&&!n)return;let s=this.readCount();this.update({count:s,filled:f(this.resolveValue()),errors:this.composeErrors(s)})}setCharacterCount(e){if((this.characterCount?.maxLength??null)===(e?.maxLength??null)&&(this.characterCount?.threshold??0)===(e?.threshold??0))return;this.characterCount=e;let o=this.readCount();this.update({count:o,errors:this.composeErrors(o)})}readCount(){let e=this.resolveValue();return typeof e=="string"?e.length:0}countMessage(e){return(this.props.getCharacterCountMessage??F)(e)}isOverLimit(e){return this.characterCount!==null&&e>this.characterCount.maxLength}composeErrors(e=this.snapshot.count){let t=[...this.injected,...this.custom];return this.characterCount&&this.isOverLimit(e)&&t.push(this.countMessage(this.characterCount.maxLength-e)),t}scheduleCountAnnouncement(e,t){let o=this.characterCount;if(!o)return;if(clearTimeout(this.announceTimer),this.isOverLimit(e)){t||this.options.announce(this.countMessage(o.maxLength-e),"assertive");return}if(!b(e,o.maxLength,o.threshold))return;let i=o.maxLength-e;this.announceTimer=setTimeout(()=>{this.options.announce(this.countMessage(i),"polite")},1e3)}connect(e){this.root=e,e.setAttribute(C,""),e.addEventListener("input",this.handleInput,!0),e.addEventListener("change",this.handleInput,!0),e.addEventListener("focusout",this.handleFocusOut,!0),this.form=e.closest("form"),this.form&&e.ownerDocument.addEventListener("submit",this.handleSubmit,!0),this.sync();let t=this.readCount();this.update({filled:f(this.resolveValue()),count:t,errors:this.composeErrors(t)})}disconnect(){clearTimeout(this.announceTimer);let e=this.root;e&&(e.removeEventListener("input",this.handleInput,!0),e.removeEventListener("change",this.handleInput,!0),e.removeEventListener("focusout",this.handleFocusOut,!0),this.form&&e.ownerDocument.removeEventListener("submit",this.handleSubmit,!0),this.root=null,this.form=null,this.control=null)}sync(){let e=this.root;if(!e)return;let t=_(e);t!==this.control&&(this.control=t,this.baseDescribedBy=t?.getAttribute("aria-describedby")??"");let{name:o}=this.props;o?e.setAttribute(R,o):e.removeAttribute(R);let i=this.snapshot.errors.join(" ");if(i?e.setAttribute(I,i):e.removeAttribute(I),this.applyStateAttributes(e),!t)return;t.id||(t.id=this.options.controlId),t.id!==this.snapshot.controlId&&(this.snapshot={...this.snapshot,controlId:t.id},this.options.onSnapshotChange(this.snapshot));let n=L(e,`[${A}]`)!==null,s=L(e,`[${E}]`)!==null,l=oe(this.baseDescribedBy,n?this.options.descriptionId:void 0,s?this.options.errorId:void 0);l?t.setAttribute("aria-describedby",l):t.removeAttribute("aria-describedby"),this.snapshot.errors.length>0?t.setAttribute("aria-invalid","true"):t.removeAttribute("aria-invalid");let d=e.ownerDocument.getElementById(this.options.labelId)!==null;this.options.grouped&&d?t.setAttribute("aria-labelledby",this.options.labelId):t.getAttribute("aria-labelledby")===this.options.labelId&&t.removeAttribute("aria-labelledby"),this.applyStateAttributes(t)}validate(){return Promise.resolve(this.runValidation()).then(e=>e.length===0)}markTouched(){this.snapshot.touched||this.update({touched:!0})}applyStateAttributes(e){let{errors:t,touched:o,dirty:i,filled:n,count:s}=this.snapshot;p(e,"data-invalid",t.length>0),p(e,"data-valid",t.length===0),p(e,"data-touched",o),p(e,"data-dirty",i),p(e,"data-filled",n),p(e,"data-over-limit",this.isOverLimit(s))}resolveValue(){return this.props.value!==void 0?this.props.value:re(this.control)}nativeMessage(){let e=this.control;return!e?.validity||e.validity.valid?null:e.validationMessage||this.props.invalidMessage||O}runValidation(e={}){let t=++this.runToken,o=this.props.validate?.(this.resolveValue());return S(o)?(this.pending=!0,Promise.resolve(o).then(i=>t!==this.runToken?this.snapshot.errors:(this.pending=!1,this.commit(i,e)))):this.commit(o,e)}commit(e,t){if(this.custom=M(e),this.custom.length===0&&this.injected.length===0){let l=this.nativeMessage();l&&(this.custom=[l])}let o=this.readCount(),i=this.composeErrors(o),n=this.snapshot.errors.length===0;this.update({errors:i,count:o,filled:f(this.resolveValue())});let s=i[0];return s&&n&&!t.silent&&this.options.announce(s,"assertive"),i}update(e){let t={...this.snapshot,...e,valid:!0};t.valid=t.errors.length===0,!le(this.snapshot,t)&&(this.snapshot=t,this.sync(),this.options.onSnapshotChange(t),this.root?.dispatchEvent(new CustomEvent(P,{bubbles:!0,composed:!0,detail:{valid:t.valid,errors:t.errors,touched:t.touched,dirty:t.dirty,filled:t.filled,count:t.count}})))}};function S(r){return typeof r?.then=="function"}function ae(r,e){return r.length===e.length&&r.every((t,o)=>t===e[o])}function le(r,e){return r.controlId===e.controlId&&r.valid===e.valid&&r.touched===e.touched&&r.dirty===e.dirty&&r.filled===e.filled&&r.count===e.count&&r.errors.length===e.errors.length&&r.errors.every((t,o)=>t===e.errors[o])}import{jsx as T}from"react/jsx-runtime";var[H,c]=de("Field");function w(r,e,t){let o=a.useId(),i=a.useMemo(()=>({labelId:`${o}label`,descriptionId:`${o}description`,errorId:`${o}error`,controlId:`${o}control`}),[o]),[n,s]=a.useState(()=>({controlId:"",errors:[],valid:!0,touched:!1,dirty:!1,filled:!1,count:0})),l=he(r.onValidityChange),d=a.useMemo(()=>new g({...i,grouped:e,onSnapshotChange:u=>{s(u);let{controlId:v,...X}=u;l(X)},announce:ue}),[i,e,l]);a.useEffect(()=>{let u=t.current;if(u)return d.connect(u),s(d.state),()=>d.disconnect()},[d,t]),a.useEffect(()=>{d.setProps({validate:r.validate,mode:r.mode,errors:r.errors,value:r.value,name:r.name,getCharacterCountMessage:r.getCharacterCountMessage,invalidMessage:r.invalidMessage}),d.sync()});let m=a.useCallback(u=>d.setCharacterCount(u),[d]);return{...i,controlId:n.controlId||void 0,errors:n.errors,grouped:e,count:n.count,setCharacterCount:m,getCharacterCountMessage:r.getCharacterCountMessage}}var U=a.forwardRef(({validate:r,mode:e,errors:t,value:o,name:i,onValidityChange:n,getCharacterCountMessage:s,invalidMessage:l,...d},m)=>{let h=a.useRef(null),u=w({validate:r,mode:e,errors:t,value:o,name:i,onValidityChange:n,getCharacterCountMessage:s,invalidMessage:l},!1,h),v=V(m,h);return T(H,{...u,children:T(k.div,{...d,...ce("field","root",d.className),ref:v})})});U.displayName="Field";var B=a.forwardRef(({validate:r,mode:e,errors:t,value:o,name:i,onValidityChange:n,getCharacterCountMessage:s,invalidMessage:l,...d},m)=>{let h=a.useRef(null),u=w({validate:r,mode:e,errors:t,value:o,name:i,onValidityChange:n,getCharacterCountMessage:s,invalidMessage:l},!0,h),v=V(m,h);return T(H,{...u,children:T(k.fieldset,{...d,ref:v})})});B.displayName="Fieldset";import*as Y from"react";import{skdxPart as $}from"../utils/part.js";import{Primitive as G}from"../utils/primitive.js";import{jsx as j}from"react/jsx-runtime";var q=Y.forwardRef((r,e)=>{let t=c("FieldLabel");return t.grouped?j(G.legend,{id:t.labelId,...r,...$("field","label",r.className),ref:e}):j(G.label,{id:t.labelId,htmlFor:t.controlId,...r,...$("field","label",r.className),ref:e})});q.displayName="FieldLabel";import*as K from"react";import{skdxPart as pe}from"../utils/part.js";import{Primitive as me}from"../utils/primitive.js";import{jsx as fe}from"react/jsx-runtime";var z=K.forwardRef((r,e)=>{let t=c("FieldDescription");return fe(me.span,{id:t.descriptionId,[A]:"",...r,...pe("field","description",r.className),ref:e})});z.displayName="FieldDescription";import*as W from"react";import{skdxPart as ve}from"../utils/part.js";import{Primitive as ge}from"../utils/primitive.js";import{jsx as Ce}from"react/jsx-runtime";var J=W.forwardRef(({children:r,...e},t)=>{let o=c("FieldError");return o.errors.length===0?null:Ce(ge.span,{id:o.errorId,[E]:"",...e,...ve("field","error",e.className),ref:t,children:r??o.errors.join(" ")})});J.displayName="FieldError";import*as y from"react";import{skdxPart as Ee}from"../utils/part.js";import{Primitive as Fe}from"../utils/primitive.js";import{jsx as be}from"react/jsx-runtime";var Q=y.forwardRef(({maxLength:r,threshold:e=0,children:t,...o},i)=>{let n=c("FieldCharacterCount"),{setCharacterCount:s}=n;if(y.useEffect(()=>(s({maxLength:r,threshold:e}),()=>s(null)),[s,r,e]),!b(n.count,r,e))return null;let l=r-n.count;return be(Fe.span,{[x]:"","data-over-limit":l<0?"":void 0,...o,...Ee("field","character-count",o.className),ref:i,children:t??(n.getCharacterCountMessage??F)(l)})});Q.displayName="FieldCharacterCount";export{Z as CHARACTER_COUNT_ANNOUNCE_DELAY_MS,x as FIELD_CHARACTER_COUNT_ATTRIBUTE,D as FIELD_CONTROL_ATTRIBUTE,N as FIELD_CONTROL_SELECTOR,P as FIELD_VALIDITY_CHANGE_EVENT,U as Field,Q as FieldCharacterCount,z as FieldDescription,J as FieldError,q as FieldLabel,B as Fieldset,O as NATIVE_INVALID_FALLBACK_MESSAGE,F as characterCountMessage,b as characterCountVisible,ne as collectFieldErrors,ie as errorSummaryScope,_ as findFieldControl,se as focusFieldTarget};

package/dist/field/FieldCharacterCount.d.cts

@@ -0,0 +1,29 @@
+import * as React from 'react';
+import type { FieldCharacterCountProps } from './types.cjs';
+/**
+ * A running character count for the control a {@link Field} wraps — GOV.UK's
+ * pattern, which works the same for a `Textarea` and a `TextField` because the
+ * count belongs to the field, not to the control.
+ *
+ * `maxLength` is a *soft* limit: it is deliberately not set as the control's
+ * native `maxlength`, because that truncates silently and leaves the user with
+ * no idea their text was cut. Going over it instead makes the Field invalid
+ * through the same path as any other error — `data-invalid`, `aria-invalid` on
+ * the control, a message in `FieldError`, and a blocked submit — plus
+ * `data-over-limit` here and on the Field for styling.
+ *
+ * Nothing here is a live region. The count is announced through the shared
+ * announcer one typing pause after the last keystroke, so a screen reader hears
+ * one number instead of a running commentary over every character typed.
+ *
+ * @example
+ * ```tsx
+ * <Field>
+ *   <FieldLabel>Why are you applying?</FieldLabel>
+ *   <Textarea />
+ *   <FieldCharacterCount maxLength={200} threshold={75} />
+ *   <FieldError />
+ * </Field>
+ * ```
+ */
+export declare const FieldCharacterCount: React.ForwardRefExoticComponent<Omit<FieldCharacterCountProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;

package/dist/field/FieldCharacterCount.d.ts

@@ -0,0 +1,29 @@
+import * as React from 'react';
+import type { FieldCharacterCountProps } from './types.js';
+/**
+ * A running character count for the control a {@link Field} wraps — GOV.UK's
+ * pattern, which works the same for a `Textarea` and a `TextField` because the
+ * count belongs to the field, not to the control.
+ *
+ * `maxLength` is a *soft* limit: it is deliberately not set as the control's
+ * native `maxlength`, because that truncates silently and leaves the user with
+ * no idea their text was cut. Going over it instead makes the Field invalid
+ * through the same path as any other error — `data-invalid`, `aria-invalid` on
+ * the control, a message in `FieldError`, and a blocked submit — plus
+ * `data-over-limit` here and on the Field for styling.
+ *
+ * Nothing here is a live region. The count is announced through the shared
+ * announcer one typing pause after the last keystroke, so a screen reader hears
+ * one number instead of a running commentary over every character typed.
+ *
+ * @example
+ * ```tsx
+ * <Field>
+ *   <FieldLabel>Why are you applying?</FieldLabel>
+ *   <Textarea />
+ *   <FieldCharacterCount maxLength={200} threshold={75} />
+ *   <FieldError />
+ * </Field>
+ * ```
+ */
+export declare const FieldCharacterCount: React.ForwardRefExoticComponent<Omit<FieldCharacterCountProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;

package/dist/field/FieldDescription.d.cts

@@ -0,0 +1,17 @@
+import * as React from 'react';
+import type { FieldDescriptionProps } from './types.cjs';
+/**
+ * Help text for a {@link Field}. Its generated `id` is added to the wrapped
+ * control's `aria-describedby`, so screen readers announce it *with* the
+ * control instead of leaving it to be discovered by browsing.
+ *
+ * @example
+ * ```tsx
+ * <Field>
+ *   <FieldLabel>Password</FieldLabel>
+ *   <TextField type="password" />
+ *   <FieldDescription>At least 12 characters.</FieldDescription>
+ * </Field>
+ * ```
+ */
+export declare const FieldDescription: React.ForwardRefExoticComponent<Omit<FieldDescriptionProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;

package/dist/field/FieldDescription.d.ts

@@ -0,0 +1,17 @@
+import * as React from 'react';
+import type { FieldDescriptionProps } from './types.js';
+/**
+ * Help text for a {@link Field}. Its generated `id` is added to the wrapped
+ * control's `aria-describedby`, so screen readers announce it *with* the
+ * control instead of leaving it to be discovered by browsing.
+ *
+ * @example
+ * ```tsx
+ * <Field>
+ *   <FieldLabel>Password</FieldLabel>
+ *   <TextField type="password" />
+ *   <FieldDescription>At least 12 characters.</FieldDescription>
+ * </Field>
+ * ```
+ */
+export declare const FieldDescription: React.ForwardRefExoticComponent<Omit<FieldDescriptionProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;

package/dist/field/FieldError.d.cts

@@ -0,0 +1,21 @@
+import * as React from 'react';
+import type { FieldErrorProps } from './types.cjs';
+/**
+ * The error text for a {@link Field}. Renders nothing while the field is
+ * valid; once it renders, its generated `id` joins the control's
+ * `aria-describedby` and the control gains `aria-invalid="true"`.
+ *
+ * With no children it renders the field's current messages, which is also
+ * the text a `FormErrorSummary` uses for its link — pass your own children to
+ * override the copy.
+ *
+ * @example
+ * ```tsx
+ * <Field validate={(value) => (value ? null : 'Enter your name')}>
+ *   <FieldLabel>Name</FieldLabel>
+ *   <TextField />
+ *   <FieldError />
+ * </Field>
+ * ```
+ */
+export declare const FieldError: React.ForwardRefExoticComponent<Omit<FieldErrorProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;

package/dist/field/FieldError.d.ts

@@ -0,0 +1,21 @@
+import * as React from 'react';
+import type { FieldErrorProps } from './types.js';
+/**
+ * The error text for a {@link Field}. Renders nothing while the field is
+ * valid; once it renders, its generated `id` joins the control's
+ * `aria-describedby` and the control gains `aria-invalid="true"`.
+ *
+ * With no children it renders the field's current messages, which is also
+ * the text a `FormErrorSummary` uses for its link — pass your own children to
+ * override the copy.
+ *
+ * @example
+ * ```tsx
+ * <Field validate={(value) => (value ? null : 'Enter your name')}>
+ *   <FieldLabel>Name</FieldLabel>
+ *   <TextField />
+ *   <FieldError />
+ * </Field>
+ * ```
+ */
+export declare const FieldError: React.ForwardRefExoticComponent<Omit<FieldErrorProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;

package/dist/field/FieldLabel.d.cts

@@ -0,0 +1,18 @@
+import * as React from 'react';
+import type { FieldLabelProps } from './types.cjs';
+/**
+ * The label for a {@link Field}'s control. Renders a `<label>` whose
+ * `htmlFor` points at whatever control the Field discovered — or a
+ * `<legend>` inside a {@link Fieldset}, since a `<label for>` may not
+ * reference a `[role="radiogroup"]` (there the Field puts `aria-labelledby`
+ * on the group instead).
+ *
+ * @example
+ * ```tsx
+ * <Field>
+ *   <FieldLabel>Email</FieldLabel>
+ *   <TextField type="email" />
+ * </Field>
+ * ```
+ */
+export declare const FieldLabel: React.ForwardRefExoticComponent<Omit<FieldLabelProps, "ref"> & React.RefAttributes<HTMLLabelElement>>;

package/dist/field/FieldLabel.d.ts

@@ -0,0 +1,18 @@
+import * as React from 'react';
+import type { FieldLabelProps } from './types.js';
+/**
+ * The label for a {@link Field}'s control. Renders a `<label>` whose
+ * `htmlFor` points at whatever control the Field discovered — or a
+ * `<legend>` inside a {@link Fieldset}, since a `<label for>` may not
+ * reference a `[role="radiogroup"]` (there the Field puts `aria-labelledby`
+ * on the group instead).
+ *
+ * @example
+ * ```tsx
+ * <Field>
+ *   <FieldLabel>Email</FieldLabel>
+ *   <TextField type="email" />
+ * </Field>
+ * ```
+ */
+export declare const FieldLabel: React.ForwardRefExoticComponent<Omit<FieldLabelProps, "ref"> & React.RefAttributes<HTMLLabelElement>>;

package/dist/field/fieldCore.d.cts

@@ -0,0 +1,284 @@
+/**
+ * The framework-free engine behind `Field`. Everything here is plain DOM
+ * work — discovering the control inside a Field, injecting the ARIA wiring
+ * onto it, running the validation model, and mirroring the interaction state
+ * as `data-*` — so all five framework packages run the *same* algorithm and
+ * the shared `assertFieldContract` assertions mean the same thing everywhere.
+ *
+ * The framework layer above this only ever: creates a controller, hands it
+ * props, calls `sync()` after each render, and re-renders when the controller
+ * says its snapshot changed.
+ *
+ * See `reports/design-system-competitive-audit/14-rfc-field-fieldset-validation.md`.
+ */
+/** When a Field first runs its validator. See {@link FieldControllerProps.mode}. */
+export type FieldMode = 'change' | 'blur' | 'submit';
+/** What a validator may return: one message, several, or nothing when the value is acceptable. */
+export type FieldValidationResult = string | string[] | null | undefined | void;
+/** A Field's validator, sync or async. */
+export type FieldValidator = (value: unknown) => FieldValidationResult | Promise<FieldValidationResult>;
+/** The bubbling DOM event a Field fires whenever its snapshot changes; a Form's ErrorSummary listens for it. */
+export declare const FIELD_VALIDITY_CHANGE_EVENT = "validity-change";
+/** Marks a Field root, so the error summary can find failing fields without a registry. */
+export declare const FIELD_ROOT_ATTRIBUTE = "data-skdx-field";
+/** Marks a Field's name, used as the error-summary link text when nothing else supplies one. */
+export declare const FIELD_NAME_ATTRIBUTE = "data-skdx-field-name";
+/**
+ * The Field's current messages, written straight onto the root the moment
+ * validity changes.
+ *
+ * This exists so the error summary never depends on a framework's render
+ * timing: a Field dispatches `validity-change` synchronously from its own DOM
+ * listener, *before* React/Vue/Angular/Lit have rendered the Error element, so
+ * a summary that could only read that element's text would scan a field that
+ * is already `data-invalid` and find nothing to link to.
+ */
+export declare const FIELD_MESSAGE_ATTRIBUTE = "data-skdx-field-message";
+/** Marks a Field's description element, so its id can be added to the control's `aria-describedby`. */
+export declare const FIELD_DESCRIPTION_ATTRIBUTE = "data-skdx-field-description";
+/** Marks a Field's error element, so its id can be added to `aria-describedby` and its text read by the summary. */
+export declare const FIELD_ERROR_ATTRIBUTE = "data-skdx-field-error";
+/** Marks a Field's character-count element, so it can be styled and found without a framework ref. */
+export declare const FIELD_CHARACTER_COUNT_ATTRIBUTE = "data-skdx-field-character-count";
+/**
+ * How long the character count waits after the last keystroke before it
+ * announces the remaining count.
+ *
+ * GOV.UK's number, and the reason it exists: a live region that fires on every
+ * keystroke reads a running commentary over the character the user just typed.
+ * One announcement per typing pause is the whole point of the pattern.
+ */
+export declare const CHARACTER_COUNT_ANNOUNCE_DELAY_MS = 1000;
+/** What a Field's character count is configured with. */
+export interface FieldCharacterCountOptions {
+    /** The soft limit. Deliberately *not* the control's native `maxlength`, which truncates silently. */
+    maxLength: number;
+    /**
+     * Percentage of `maxLength` that must be typed before the count is shown and
+     * announced at all. `0` shows it from the first render.
+     * @default 0
+     */
+    threshold?: number;
+}
+/** The default count copy, in GOV.UK's wording. Negative `remaining` means over the limit. */
+export declare function characterCountMessage(remaining: number): string;
+/** Whether a count has passed its threshold and should be rendered/announced. */
+export declare function characterCountVisible(count: number, maxLength: number, threshold?: number): boolean;
+/**
+ * Used when a control fails native constraint validation but the engine
+ * reports no message of its own (jsdom and some browsers leave
+ * `validationMessage` empty). A Field is never invalid without something to
+ * say, because an error with no message is unannounceable.
+ */
+export declare const NATIVE_INVALID_FALLBACK_MESSAGE = "This field is invalid.";
+/**
+ * Opt-in marker saying "I am my Field's control". Discovery's escape hatch for
+ * a composite whose role element the Field cannot reach: `<skdx-date-field>`
+ * keeps its `role="group"` in a shadow root, so only the host is findable from
+ * the Field's light DOM.
+ */
+export declare const FIELD_CONTROL_ATTRIBUTE = "data-skdx-field-control";
+/**
+ * How a Field recognises the control it wraps. First match in document order
+ * wins, which is why group roles work: a `[role="radiogroup"]` precedes the
+ * radios inside it.
+ */
+export declare const FIELD_CONTROL_SELECTOR: string;
+/** The public state of one Field, handed to the framework layer and to `validity-change` listeners. */
+export interface FieldSnapshot {
+    /** The id of the discovered control — the Label's `for`, and the error summary's link target. */
+    controlId: string;
+    /** Every current message, server-injected first. Empty means valid. */
+    errors: string[];
+    /** `errors.length === 0`. */
+    valid: boolean;
+    /** The control has been blurred at least once. */
+    touched: boolean;
+    /** The value has been edited at least once. */
+    dirty: boolean;
+    /** The control currently holds a value. */
+    filled: boolean;
+    /** Length of the control's value, tracked only while a character count is configured. */
+    count: number;
+}
+/** The props the framework layer forwards into the controller on every render. */
+export interface FieldControllerProps {
+    /** See {@link FieldValidator}. */
+    validate?: FieldValidator;
+    /**
+     * When validation first runs. After a failure the field re-validates on
+     * every input regardless, so an error clears as soon as it is fixed.
+     * @default 'blur'
+     */
+    mode?: FieldMode;
+    /** Server-injected errors, always shown, listed before anything `validate` produces. */
+    errors?: string | string[];
+    /** Value handed to `validate`; `undefined` reads it off the control instead. */
+    value?: unknown;
+    /** Field name, used as the error-summary link text when no error element is rendered. */
+    name?: string;
+    /**
+     * Words the character-count copy — the text `FieldCharacterCount` renders,
+     * the message announced one typing pause later, and the error raised once
+     * the value goes over the soft limit. A negative `remaining` means over the
+     * limit.
+     * @default undefined — {@link characterCountMessage}'s English wording.
+     */
+    getCharacterCountMessage?: (remaining: number) => string;
+    /**
+     * Replaces {@link NATIVE_INVALID_FALLBACK_MESSAGE}: what the Field says when
+     * the wrapped control fails native constraint validation but the engine
+     * reports no message of its own.
+     * @default undefined — 'This field is invalid.'
+     */
+    invalidMessage?: string;
+}
+/** Everything the controller needs that the framework layer owns. */
+export interface FieldControllerOptions {
+    /** Id of the Label element, used for a group's `aria-labelledby`. */
+    labelId: string;
+    /** Id of the Description element. */
+    descriptionId: string;
+    /** Id of the Error element. */
+    errorId: string;
+    /** Fallback id assigned to a control that has none of its own. */
+    controlId: string;
+    /** True for a `Fieldset`: the Label is a `<legend>` and the control is labelled by `aria-labelledby`. */
+    grouped: boolean;
+    /** Called whenever the snapshot changes, so the framework layer can re-render. */
+    onSnapshotChange: (snapshot: FieldSnapshot) => void;
+    /**
+     * The live-region `announce`. The engine picks the politeness per message, because
+     * the two things it says want different ones: an error the user has already
+     * moved past interrupts, a running character count must not.
+     */
+    announce: (message: string, politeness: 'polite' | 'assertive') => void;
+}
+/** Coerces whatever a validator (or the `errors` prop) returned into a message list. */
+export declare function normalizeMessages(result: FieldValidationResult | string | string[]): string[];
+/** The first control inside `root` that belongs to *this* Field rather than to a nested one. */
+export declare function findFieldControl(root: Element): HTMLElement | null;
+/**
+ * The value a validator sees when the consumer passed none: a checkbox or
+ * radio reports `checked`, everything else reports its `value` property, and a
+ * composite root that has no `value` of its own (a `role="group"` segmented
+ * field, a `role="radiogroup"`) reports whatever its form-participation input
+ * would submit.
+ *
+ * ponytail: a composite control that keeps its value only in framework state
+ * and mirrors it nowhere — no `value` property, and no `name` so no hidden
+ * input either — needs the explicit `value` prop. Pass it if you build one.
+ */
+export declare function readControlValue(control: HTMLElement | null): unknown;
+/** Whether a value counts as entered, for `data-filled`. */
+export declare function isFilled(value: unknown): boolean;
+/** One failing field, as listed by a Form's ErrorSummary. */
+export interface FieldErrorEntry {
+    /** The control's id — the link's `href` target. */
+    id: string;
+    /** The message shown as the link text. */
+    message: string;
+}
+/**
+ * The form (or `<skdx-form>`) a summary should scan and listen on, falling
+ * back to the summary's own parent when it is used standalone.
+ */
+export declare function errorSummaryScope(root: Element): Element;
+/** Every currently-failing Field in `scope`, in document order — the summary's list. */
+export declare function collectFieldErrors(scope: ParentNode): FieldErrorEntry[];
+/**
+ * Sends focus to a failing field the GOV.UK way: straight to the control,
+ * unless the target is a group — then to the first control inside it, because
+ * focusing a `<fieldset>`/`[role="radiogroup"]` announces the group but leaves
+ * the user with nothing to operate.
+ */
+export declare function focusFieldTarget(id: string, doc?: Document): void;
+/**
+ * Owns one Field's state machine. Created by the framework layer, given the
+ * Field's root element on `connect()`, and told about re-renders via `sync()`.
+ */
+export declare class FieldController {
+    private readonly options;
+    private props;
+    private root;
+    private form;
+    private control;
+    /** The `aria-describedby` the consumer put on the control themselves, preserved across rewrites. */
+    private baseDescribedBy;
+    /** Bumped on every validation run; a resolution from a superseded run is discarded. */
+    private runToken;
+    private pending;
+    /** Messages from the `errors` prop. Always listed first. */
+    private injected;
+    /** Messages from the last `validate` run, or the native constraint-validation fallback. */
+    private custom;
+    /** Set by a mounted character-count part; `null` while the Field has none. */
+    private characterCount;
+    private announceTimer;
+    private snapshot;
+    constructor(options: FieldControllerOptions);
+    /** The current state. Read by the framework layer to render the parts. */
+    get state(): FieldSnapshot;
+    /** Replaces the forwarded props. Safe to call on every render. */
+    setProps(props: FieldControllerProps): void;
+    /**
+     * Registers (or clears) the character count. Called by the count part on
+     * mount, on prop change, and on unmount.
+     */
+    setCharacterCount(options: FieldCharacterCountOptions | null): void;
+    /** Length of the control's current value; `0` when it holds something that is not text. */
+    private readCount;
+    /** The count copy, in the consumer's wording when they supplied one. */
+    private countMessage;
+    /** True once the value is longer than the configured soft limit. */
+    private isOverLimit;
+    /**
+     * Server errors first, then whatever the last validation run produced, then
+     * the over-limit message — so going over the limit makes the Field invalid
+     * through exactly the same path as any other error, and blocks submit.
+     */
+    private composeErrors;
+    /**
+     * Says the count, sparingly. Under the limit it is queued politely, one
+     * typing pause after the last keystroke, so a burst of typing produces one
+     * number instead of a running commentary. Crossing the limit interrupts —
+     * once, on the transition, not on every keystroke past it.
+     *
+     * The over-limit message cannot ride on `commit()`'s error announcement: by
+     * the time validation runs, `update()` has already put the message into
+     * `errors`, so `commit()` no longer sees the field as newly-invalid.
+     */
+    private scheduleCountAnnouncement;
+    /** Attaches the controller to its rendered root element. */
+    connect(root: HTMLElement): void;
+    /** Detaches every listener. */
+    disconnect(): void;
+    /**
+     * Re-discovers the control and re-applies every injected attribute. The
+     * framework layer calls this after each render, because a render may have
+     * swapped the control or mounted/unmounted the Description or Error.
+     */
+    sync(): void;
+    /**
+     * Runs validation now. Resolves to whether the field is valid — the
+     * imperative entry point `<skdx-field>.validate()` and Angular's
+     * `SkdxFieldComponent.validate()` expose directly.
+     */
+    validate(): Promise<boolean>;
+    /** Marks the field touched without validating (used by a submit pass before it validates). */
+    private markTouched;
+    private applyStateAttributes;
+    private resolveValue;
+    private nativeMessage;
+    /**
+     * Returns the new message list — synchronously for a sync validator, which
+     * is what lets the submit handler decide whether to `preventDefault()`
+     * before the browser submits.
+     */
+    private runValidation;
+    private commit;
+    private update;
+    private readonly handleInput;
+    private readonly handleFocusOut;
+    private readonly handleSubmit;
+}