@skdx/react 0.26.0

package/dist/field/fieldCore.d.ts

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

package/dist/field/index.d.cts

@@ -0,0 +1,7 @@
+export { Field, Fieldset } from './Field.cjs';
+export { FieldLabel } from './FieldLabel.cjs';
+export { FieldDescription } from './FieldDescription.cjs';
+export { FieldError } from './FieldError.cjs';
+export { FieldCharacterCount } from './FieldCharacterCount.cjs';
+export type { FieldProps, FieldsetProps, FieldLabelProps, FieldDescriptionProps, FieldErrorProps, FieldCharacterCountProps, FieldOwnProps, FieldValidityDetail, FieldMode, FieldValidator, FieldValidationResult, FieldCharacterCountOptions, } from './types.cjs';
+export { CHARACTER_COUNT_ANNOUNCE_DELAY_MS, characterCountMessage, characterCountVisible, FIELD_CHARACTER_COUNT_ATTRIBUTE, FIELD_CONTROL_ATTRIBUTE, FIELD_CONTROL_SELECTOR, FIELD_VALIDITY_CHANGE_EVENT, NATIVE_INVALID_FALLBACK_MESSAGE, findFieldControl, type FieldSnapshot, collectFieldErrors, errorSummaryScope, focusFieldTarget, type FieldErrorEntry, } from './fieldCore.cjs';

package/dist/field/index.d.ts

@@ -0,0 +1,7 @@
+export { Field, Fieldset } from './Field.js';
+export { FieldLabel } from './FieldLabel.js';
+export { FieldDescription } from './FieldDescription.js';
+export { FieldError } from './FieldError.js';
+export { FieldCharacterCount } from './FieldCharacterCount.js';
+export type { FieldProps, FieldsetProps, FieldLabelProps, FieldDescriptionProps, FieldErrorProps, FieldCharacterCountProps, FieldOwnProps, FieldValidityDetail, FieldMode, FieldValidator, FieldValidationResult, FieldCharacterCountOptions, } from './types.js';
+export { CHARACTER_COUNT_ANNOUNCE_DELAY_MS, characterCountMessage, characterCountVisible, FIELD_CHARACTER_COUNT_ATTRIBUTE, FIELD_CONTROL_ATTRIBUTE, FIELD_CONTROL_SELECTOR, FIELD_VALIDITY_CHANGE_EVENT, NATIVE_INVALID_FALLBACK_MESSAGE, findFieldControl, type FieldSnapshot, collectFieldErrors, errorSummaryScope, focusFieldTarget, type FieldErrorEntry, } from './fieldCore.js';

package/dist/field/types.d.cts

@@ -0,0 +1,107 @@
+import type { PrimitivePropsWithRef } from '../utils/primitive.cjs';
+import type { FieldCharacterCountOptions, FieldMode, FieldSnapshot, FieldValidator } from './fieldCore.cjs';
+export type { FieldCharacterCountOptions, FieldMode, FieldValidationResult, FieldValidator, } from './fieldCore.cjs';
+/** The state a `Field` reports through {@link FieldOwnProps.onValidityChange}. */
+export type FieldValidityDetail = Omit<FieldSnapshot, 'controlId'>;
+/** The validation-model props shared by {@link FieldProps} and {@link FieldsetProps}. */
+export interface FieldOwnProps {
+    /**
+     * Validator for this field, returning one message, several, or
+     * `null`/`undefined` when the value is acceptable. May be async; a
+     * resolution from a superseded run is discarded.
+     * @default undefined — only the `errors` prop and native constraint validation produce messages.
+     */
+    validate?: FieldValidator;
+    /**
+     * When validation first runs. Whatever the mode, a field that has already
+     * failed re-validates on every input, so the error clears as soon as the
+     * user fixes it.
+     * @default 'blur'
+     */
+    mode?: FieldMode;
+    /**
+     * Server-injected errors, always shown, listed before anything `validate`
+     * produces. Clearing the prop clears them.
+     * @default undefined
+     */
+    errors?: string | string[];
+    /**
+     * Value handed to `validate`. Omit and the Field reads the wrapped
+     * control's `checked` (checkbox/radio) or `value` property instead.
+     * @default undefined — read from the control.
+     */
+    value?: unknown;
+    /**
+     * Field name, used as the `FormErrorSummary` link text when the field
+     * renders no `FieldError` of its own.
+     * @default undefined
+     */
+    name?: string;
+    /**
+     * Fires whenever the field's validity or interaction state changes.
+     * @default undefined
+     */
+    onValidityChange?: (detail: FieldValidityDetail) => void;
+    /**
+     * Words every piece of character-count copy this Field produces: the text
+     * `FieldCharacterCount` renders, the message announced a typing pause after
+     * the last keystroke, and the error raised once the value passes the soft
+     * limit. A negative `remaining` means over the limit.
+     *
+     * One prop for all three deliberately — the announced count and the rendered
+     * count saying different things is worse than either being in English.
+     * @default undefined — the built-in GOV.UK wording ("You have 12 characters remaining").
+     */
+    getCharacterCountMessage?: (remaining: number) => string;
+    /**
+     * What the Field says when the wrapped control fails *native* constraint
+     * validation but the browser reports no message of its own. The browser's
+     * own messages are already localized; this fallback is the one the library
+     * supplies, so it is the one that needs translating.
+     * @default undefined — 'This field is invalid.'
+     */
+    invalidMessage?: string;
+}
+/** Props for {@link Field}, which wires one control to its label, description, and error text. */
+export interface FieldProps extends Omit<PrimitivePropsWithRef<'div'>, 'value'>, FieldOwnProps {
+}
+/** Props for {@link Fieldset}, a {@link Field} that groups several controls under a `<legend>`. */
+export interface FieldsetProps extends Omit<PrimitivePropsWithRef<'fieldset'>, 'value' | 'name'>, FieldOwnProps {
+}
+/** Props for {@link FieldLabel}, which renders a `<label>` — or a `<legend>` inside a {@link Fieldset}. */
+export interface FieldLabelProps extends PrimitivePropsWithRef<'label'> {
+}
+/** Props for {@link FieldDescription}, help text announced with the control. */
+export interface FieldDescriptionProps extends PrimitivePropsWithRef<'span'> {
+}
+/** Props for {@link FieldError}, rendered only while the field is invalid. */
+export interface FieldErrorProps extends PrimitivePropsWithRef<'span'> {
+}
+/** Props for {@link FieldCharacterCount}, the running "N characters remaining" count. */
+export interface FieldCharacterCountProps extends PrimitivePropsWithRef<'span'> {
+    /**
+     * The soft limit. Deliberately not the control's native `maxlength`, which
+     * silently truncates instead of telling the user they went over.
+     */
+    maxLength: number;
+    /**
+     * Percentage of `maxLength` that must be typed before the count appears at
+     * all — GOV.UK's way of keeping a long field quiet until it matters.
+     * @default 0 — visible from the first render.
+     */
+    threshold?: number;
+}
+/** @internal Field identity and state distributed to the Label/Description/Error parts. Not part of the public API. */
+export interface FieldContextValue {
+    labelId: string;
+    descriptionId: string;
+    errorId: string;
+    /** The id the control actually carries — `undefined` until the Field has connected to one, which no server render ever does. */
+    controlId?: string;
+    errors: string[];
+    grouped: boolean;
+    count: number;
+    setCharacterCount: (options: FieldCharacterCountOptions | null) => void;
+    /** The root's `getCharacterCountMessage`, so the rendered count uses the same wording as the announced one. */
+    getCharacterCountMessage?: (remaining: number) => string;
+}

package/dist/field/types.d.ts

@@ -0,0 +1,107 @@
+import type { PrimitivePropsWithRef } from '../utils/primitive.js';
+import type { FieldCharacterCountOptions, FieldMode, FieldSnapshot, FieldValidator } from './fieldCore.js';
+export type { FieldCharacterCountOptions, FieldMode, FieldValidationResult, FieldValidator, } from './fieldCore.js';
+/** The state a `Field` reports through {@link FieldOwnProps.onValidityChange}. */
+export type FieldValidityDetail = Omit<FieldSnapshot, 'controlId'>;
+/** The validation-model props shared by {@link FieldProps} and {@link FieldsetProps}. */
+export interface FieldOwnProps {
+    /**
+     * Validator for this field, returning one message, several, or
+     * `null`/`undefined` when the value is acceptable. May be async; a
+     * resolution from a superseded run is discarded.
+     * @default undefined — only the `errors` prop and native constraint validation produce messages.
+     */
+    validate?: FieldValidator;
+    /**
+     * When validation first runs. Whatever the mode, a field that has already
+     * failed re-validates on every input, so the error clears as soon as the
+     * user fixes it.
+     * @default 'blur'
+     */
+    mode?: FieldMode;
+    /**
+     * Server-injected errors, always shown, listed before anything `validate`
+     * produces. Clearing the prop clears them.
+     * @default undefined
+     */
+    errors?: string | string[];
+    /**
+     * Value handed to `validate`. Omit and the Field reads the wrapped
+     * control's `checked` (checkbox/radio) or `value` property instead.
+     * @default undefined — read from the control.
+     */
+    value?: unknown;
+    /**
+     * Field name, used as the `FormErrorSummary` link text when the field
+     * renders no `FieldError` of its own.
+     * @default undefined
+     */
+    name?: string;
+    /**
+     * Fires whenever the field's validity or interaction state changes.
+     * @default undefined
+     */
+    onValidityChange?: (detail: FieldValidityDetail) => void;
+    /**
+     * Words every piece of character-count copy this Field produces: the text
+     * `FieldCharacterCount` renders, the message announced a typing pause after
+     * the last keystroke, and the error raised once the value passes the soft
+     * limit. A negative `remaining` means over the limit.
+     *
+     * One prop for all three deliberately — the announced count and the rendered
+     * count saying different things is worse than either being in English.
+     * @default undefined — the built-in GOV.UK wording ("You have 12 characters remaining").
+     */
+    getCharacterCountMessage?: (remaining: number) => string;
+    /**
+     * What the Field says when the wrapped control fails *native* constraint
+     * validation but the browser reports no message of its own. The browser's
+     * own messages are already localized; this fallback is the one the library
+     * supplies, so it is the one that needs translating.
+     * @default undefined — 'This field is invalid.'
+     */
+    invalidMessage?: string;
+}
+/** Props for {@link Field}, which wires one control to its label, description, and error text. */
+export interface FieldProps extends Omit<PrimitivePropsWithRef<'div'>, 'value'>, FieldOwnProps {
+}
+/** Props for {@link Fieldset}, a {@link Field} that groups several controls under a `<legend>`. */
+export interface FieldsetProps extends Omit<PrimitivePropsWithRef<'fieldset'>, 'value' | 'name'>, FieldOwnProps {
+}
+/** Props for {@link FieldLabel}, which renders a `<label>` — or a `<legend>` inside a {@link Fieldset}. */
+export interface FieldLabelProps extends PrimitivePropsWithRef<'label'> {
+}
+/** Props for {@link FieldDescription}, help text announced with the control. */
+export interface FieldDescriptionProps extends PrimitivePropsWithRef<'span'> {
+}
+/** Props for {@link FieldError}, rendered only while the field is invalid. */
+export interface FieldErrorProps extends PrimitivePropsWithRef<'span'> {
+}
+/** Props for {@link FieldCharacterCount}, the running "N characters remaining" count. */
+export interface FieldCharacterCountProps extends PrimitivePropsWithRef<'span'> {
+    /**
+     * The soft limit. Deliberately not the control's native `maxlength`, which
+     * silently truncates instead of telling the user they went over.
+     */
+    maxLength: number;
+    /**
+     * Percentage of `maxLength` that must be typed before the count appears at
+     * all — GOV.UK's way of keeping a long field quiet until it matters.
+     * @default 0 — visible from the first render.
+     */
+    threshold?: number;
+}
+/** @internal Field identity and state distributed to the Label/Description/Error parts. Not part of the public API. */
+export interface FieldContextValue {
+    labelId: string;
+    descriptionId: string;
+    errorId: string;
+    /** The id the control actually carries — `undefined` until the Field has connected to one, which no server render ever does. */
+    controlId?: string;
+    errors: string[];
+    grouped: boolean;
+    count: number;
+    setCharacterCount: (options: FieldCharacterCountOptions | null) => void;
+    /** The root's `getCharacterCountMessage`, so the rendered count uses the same wording as the announced one. */
+    getCharacterCountMessage?: (remaining: number) => string;
+}

package/dist/file-upload/FileUpload.cjs

@@ -0,0 +1 @@
+"use strict";var de=Object.create;var c=Object.defineProperty;var se=Object.getOwnPropertyDescriptor;var me=Object.getOwnPropertyNames;var fe=Object.getPrototypeOf,ce=Object.prototype.hasOwnProperty;var ue=(e,t)=>{for(var o in t)c(e,o,{get:t[o],enumerable:!0})},M=(e,t,o,r)=>{if(t&&typeof t=="object"||typeof t=="function")for(let i of me(t))!ce.call(e,i)&&i!==o&&c(e,i,{get:()=>t[i],enumerable:!(r=se(t,i))||r.enumerable});return e};var s=(e,t,o)=>(o=e!=null?de(fe(e)):{},M(t||!e||!e.__esModule?c(o,"default",{value:e,enumerable:!0}):o,e)),Fe=e=>M(c({},"__esModule",{value:!0}),e);var Pe={};ue(Pe,{FileUpload:()=>x,FileUploadDropzone:()=>R,FileUploadInput:()=>D,FileUploadItem:()=>v,FileUploadItemDelete:()=>C,FileUploadTrigger:()=>I});module.exports=Fe(Pe);var a=s(require("react"),1),S=require("../utils/createContext.cjs"),O=require("../utils/part.cjs"),V=require("../utils/primitive.cjs"),W=require("../utils/useControllableState.cjs"),b=require("react/jsx-runtime"),[Ue,n]=(0,S.createSafeContext)("FileUpload");function ge(e,t){if(!t)return!0;let o=t.split(",").map(l=>l.trim().toLowerCase()).filter(Boolean);if(o.length===0)return!0;let r=e.name.toLowerCase(),i=e.type.toLowerCase();return o.some(l=>l.startsWith(".")?r.endsWith(l):l.endsWith("/*")?i.startsWith(l.slice(0,-1)):i===l)}function ye(e,t){let o=[];return ge(e,t.accept)||o.push("file-invalid-type"),t.maxFileSize!==void 0&&e.size>t.maxFileSize&&o.push("file-too-large"),t.minFileSize!==void 0&&e.size<t.minFileSize&&o.push("file-too-small"),o.push(...t.validate?.(e)??[]),o}var x=a.forwardRef(({value:e,defaultValue:t=[],onValueChange:o,accept:r,multiple:i=!1,disabled:l=!1,maxFiles:k,maxFileSize:w,minFileSize:T,validate:E,onFileReject:L,...z},re)=>{let H=a.useRef(null),[g=[],m]=(0,W.useControllableState)({prop:e,defaultProp:t,onChange:o}),ae=a.useCallback(y=>{if(l)return;let f=i?g:[],N=(i?k??1/0:1)-f.length,d=[];for(let P of Array.from(y)){let h=ye(P,{accept:r,maxFileSize:w,minFileSize:T,validate:E});if(d.length>=N&&h.push("too-many-files"),h.length>0){L?.({file:P,errors:h});continue}d.push(P)}d.length!==0&&m([...f,...d])},[l,i,g,k,m,r,w,T,E,L]),ne=a.useCallback(y=>{m((f=[])=>f.filter((N,d)=>d!==y))},[m]),pe=a.useCallback(()=>{l||H.current?.click()},[l]);return(0,b.jsx)(Ue,{inputRef:H,files:g,disabled:l,accept:r,multiple:i,addFiles:ae,removeFile:ne,openPicker:pe,children:(0,b.jsx)(V.Primitive.div,{"data-disabled":l?"":void 0,...z,...(0,O.skdxPart)("file-upload","root",z.className),ref:re})})});x.displayName="FileUpload";var u=s(require("react"),1),B=require("../utils/part.cjs"),p=require("../utils/primitive.cjs");var A=require("react/jsx-runtime"),R=u.forwardRef((e,t)=>{let o=n("FileUploadDropzone"),[r,i]=u.useState(!1);return(0,A.jsx)(p.Primitive.div,{role:"button",tabIndex:o.disabled?-1:0,"aria-disabled":o.disabled||void 0,"data-disabled":o.disabled?"":void 0,"data-dragging":r?"":void 0,...e,...(0,B.skdxPart)("file-upload","dropzone",e.className),ref:t,onClick:(0,p.composeEventHandlers)(e.onClick,()=>o.openPicker()),onKeyDown:(0,p.composeEventHandlers)(e.onKeyDown,l=>{(l.key==="Enter"||l.key===" ")&&!o.disabled&&(l.preventDefault(),o.openPicker())}),onDragOver:(0,p.composeEventHandlers)(e.onDragOver,l=>{l.preventDefault(),o.disabled||i(!0)}),onDragLeave:(0,p.composeEventHandlers)(e.onDragLeave,()=>i(!1)),onDrop:(0,p.composeEventHandlers)(e.onDrop,l=>{l.preventDefault(),i(!1),o.disabled||o.addFiles(l.dataTransfer.files)})})});R.displayName="FileUploadDropzone";var K=s(require("react"),1),_=require("../utils/composeRefs.cjs"),q=require("../utils/hiddenInput.cjs"),G=require("../utils/part.cjs"),J=require("../utils/primitive.cjs");var Q=require("react/jsx-runtime"),D=K.forwardRef((e,t)=>{let o=n("FileUploadInput"),r=(0,_.useComposedRefs)(t,o.inputRef);return(0,Q.jsx)(q.HiddenInput,{type:"file",accept:o.accept,multiple:o.multiple,disabled:o.disabled,...e,...(0,G.skdxPart)("file-upload","input",e.className),ref:r,onChange:(0,J.composeEventHandlers)(e.onChange,i=>{i.target.files&&o.addFiles(i.target.files),i.target.value=""})})});D.displayName="FileUploadInput";var X=s(require("react"),1),Y=require("../utils/part.cjs"),Z=require("../utils/primitive.cjs"),$=require("react/jsx-runtime"),v=X.forwardRef(({index:e,status:t="idle",progress:o,...r},i)=>(0,$.jsx)(Z.Primitive.div,{"data-status":t,"data-progress":o,...r,...(0,Y.skdxPart)("file-upload","item",r.className),ref:i}));v.displayName="FileUploadItem";var j=s(require("react"),1),ee=require("../utils/part.cjs"),F=require("../utils/primitive.cjs");var oe=require("react/jsx-runtime"),C=j.forwardRef(({index:e,...t},o)=>{let r=n("FileUploadItemDelete");return(0,oe.jsx)(F.Primitive.button,{type:"button","aria-label":"Remove file",disabled:r.disabled,"data-disabled":r.disabled?"":void 0,...t,...(0,ee.skdxPart)("file-upload","item-delete",t.className),ref:o,onClick:(0,F.composeEventHandlers)(t.onClick,()=>{r.disabled||r.removeFile(e)})})});C.displayName="FileUploadItemDelete";var te=s(require("react"),1),ie=require("../utils/part.cjs"),U=require("../utils/primitive.cjs");var le=require("react/jsx-runtime"),I=te.forwardRef((e,t)=>{let o=n("FileUploadTrigger");return(0,le.jsx)(U.Primitive.button,{type:"button",disabled:o.disabled,"data-disabled":o.disabled?"":void 0,...e,...(0,ie.skdxPart)("file-upload","trigger",e.className),ref:t,onClick:(0,U.composeEventHandlers)(e.onClick,()=>o.openPicker())})});I.displayName="FileUploadTrigger";0&&(module.exports={FileUpload,FileUploadDropzone,FileUploadInput,FileUploadItem,FileUploadItemDelete,FileUploadTrigger});

package/dist/file-upload/FileUpload.d.cts

@@ -0,0 +1,59 @@
+import * as React from 'react';
+import type { FileUploadContextValue, FileUploadProps } from './types.cjs';
+/**
+ * Controllable `File[]` list. `FileUploadDropzone`/`FileUploadTrigger` both
+ * just proxy a click to a visually-hidden native `<input type="file">`
+ * (`FileUploadInput`) — the OS file dialog and drag/drop are the platform's
+ * job, this component only tracks the resulting file list.
+ */
+/**
+ * Reads the state a {@link FileUpload} root publishes to its parts:
+ * the current `files`, the `accept`/`multiple`/`disabled` settings, the ref to
+ * the visually-hidden native `<input type="file">`, and
+ * `addFiles`/`removeFile`/`openPicker`.
+ *
+ * `FileUploadDropzone`, `FileUploadTrigger`, `FileUploadInput` and
+ * `FileUploadItemDelete` each read it under their own name, which is the name
+ * the hook puts in the error it throws when one of them is rendered outside a
+ * `FileUpload` — every one of those parts is a proxy to the root's input, and a
+ * proxy with no target silently does nothing. Not part of the public API.
+ *
+ * @internal
+ */
+export declare const FileUploadProvider: {
+    (props: FileUploadContextValue & {
+        children: React.ReactNode;
+    }): React.JSX.Element;
+    displayName: string;
+}, useFileUploadContext: (consumerName: string) => FileUploadContextValue;
+/**
+ * Root of a file-selection widget: owns a controllable `File[]` list and
+ * hands it down to `FileUploadDropzone` / `FileUploadTrigger` /
+ * `FileUploadInput` / `FileUploadItem` / `FileUploadItemDelete` via context.
+ * Sets `data-disabled` when `disabled`. Renders a plain `<div>`.
+ *
+ * The OS file dialog and drag-and-drop are the platform's job —
+ * `FileUploadDropzone`/`FileUploadTrigger` both just proxy to a
+ * visually-hidden native `<input type="file">` (`FileUploadInput`); this
+ * component only tracks the resulting files, filtering both entry points
+ * through `accept` (the native attribute alone only filters the picker, not
+ * drag-and-drop) and applying `multiple`. Works controlled (`value` +
+ * `onValueChange`) or uncontrolled (`defaultValue`).
+ *
+ * @example
+ * ```tsx
+ * <FileUpload accept="image/*" multiple onValueChange={setFiles}>
+ *   <FileUploadDropzone>
+ *     Drag files here or <FileUploadTrigger>browse</FileUploadTrigger>
+ *     <FileUploadInput />
+ *   </FileUploadDropzone>
+ *   {files.map((file, index) => (
+ *     <FileUploadItem key={file.name} index={index}>
+ *       {file.name}
+ *       <FileUploadItemDelete index={index} />
+ *     </FileUploadItem>
+ *   ))}
+ * </FileUpload>
+ * ```
+ */
+export declare const FileUpload: React.ForwardRefExoticComponent<Omit<FileUploadProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/file-upload/FileUpload.d.ts

@@ -0,0 +1,59 @@
+import * as React from 'react';
+import type { FileUploadContextValue, FileUploadProps } from './types.js';
+/**
+ * Controllable `File[]` list. `FileUploadDropzone`/`FileUploadTrigger` both
+ * just proxy a click to a visually-hidden native `<input type="file">`
+ * (`FileUploadInput`) — the OS file dialog and drag/drop are the platform's
+ * job, this component only tracks the resulting file list.
+ */
+/**
+ * Reads the state a {@link FileUpload} root publishes to its parts:
+ * the current `files`, the `accept`/`multiple`/`disabled` settings, the ref to
+ * the visually-hidden native `<input type="file">`, and
+ * `addFiles`/`removeFile`/`openPicker`.
+ *
+ * `FileUploadDropzone`, `FileUploadTrigger`, `FileUploadInput` and
+ * `FileUploadItemDelete` each read it under their own name, which is the name
+ * the hook puts in the error it throws when one of them is rendered outside a
+ * `FileUpload` — every one of those parts is a proxy to the root's input, and a
+ * proxy with no target silently does nothing. Not part of the public API.
+ *
+ * @internal
+ */
+export declare const FileUploadProvider: {
+    (props: FileUploadContextValue & {
+        children: React.ReactNode;
+    }): React.JSX.Element;
+    displayName: string;
+}, useFileUploadContext: (consumerName: string) => FileUploadContextValue;
+/**
+ * Root of a file-selection widget: owns a controllable `File[]` list and
+ * hands it down to `FileUploadDropzone` / `FileUploadTrigger` /
+ * `FileUploadInput` / `FileUploadItem` / `FileUploadItemDelete` via context.
+ * Sets `data-disabled` when `disabled`. Renders a plain `<div>`.
+ *
+ * The OS file dialog and drag-and-drop are the platform's job —
+ * `FileUploadDropzone`/`FileUploadTrigger` both just proxy to a
+ * visually-hidden native `<input type="file">` (`FileUploadInput`); this
+ * component only tracks the resulting files, filtering both entry points
+ * through `accept` (the native attribute alone only filters the picker, not
+ * drag-and-drop) and applying `multiple`. Works controlled (`value` +
+ * `onValueChange`) or uncontrolled (`defaultValue`).
+ *
+ * @example
+ * ```tsx
+ * <FileUpload accept="image/*" multiple onValueChange={setFiles}>
+ *   <FileUploadDropzone>
+ *     Drag files here or <FileUploadTrigger>browse</FileUploadTrigger>
+ *     <FileUploadInput />
+ *   </FileUploadDropzone>
+ *   {files.map((file, index) => (
+ *     <FileUploadItem key={file.name} index={index}>
+ *       {file.name}
+ *       <FileUploadItemDelete index={index} />
+ *     </FileUploadItem>
+ *   ))}
+ * </FileUpload>
+ * ```
+ */
+export declare const FileUpload: React.ForwardRefExoticComponent<Omit<FileUploadProps, "ref"> & React.RefAttributes<HTMLDivElement>>;