@vjdesigns/vjdesigns-ui 0.0.0-stage → 1.5.0

package/dist/components/forms/Field/Field.d.ts

@@ -0,0 +1,171 @@
+import { ComponentPropsWithRef, ReactNode } from 'react';
+import { Orientation, Size } from '../../../types/common';
+/** Props shared by `Field` and `Fieldset`. */
+interface FieldCommonProps {
+    /**
+     * Visible label (a `<legend>` in `Fieldset`). Always required so every
+     * control has an accessible name; use `labelVisuallyHidden` when the design
+     * has no visible label.
+     */
+    label: ReactNode;
+    /** Keep the label for screen readers but hide it visually (e.g. a search box next to a visible heading). */
+    labelVisuallyHidden?: boolean;
+    /** Help text, wired to the control with `aria-describedby`. */
+    hint?: ReactNode;
+    /**
+     * Error message. When present the field is invalid (unless `invalid={false}`),
+     * and the message is wired with `aria-describedby` and `aria-errormessage`.
+     * It renders with a leading error icon so the state isn't conveyed by color alone.
+     * With `invalid={false}` the message is not rendered.
+     */
+    error?: ReactNode;
+    /** Invalid state. Defaults to `true` when `error` is present, otherwise `false`. */
+    invalid?: boolean;
+    /**
+     * Required. Controls set native `required` (or `aria-required` for custom
+     * controls), which is what assistive tech announces; the label shows
+     * `requiredIndicator`.
+     */
+    required?: boolean;
+    /** Disabled. Passed to controls through context; `Fieldset` also sets native `disabled`, which disables every descendant control. */
+    disabled?: boolean;
+    /** Read-only. Passed to controls through context. */
+    readOnly?: boolean;
+    /** Size shared with controls that don't set their own. Also scales the label. */
+    size?: Size;
+    /**
+     * Visual marker shown after the label when `required`. Defaults to a `*`
+     * that is `aria-hidden` (the control's native `required` carries the
+     * meaning for assistive tech). Pass `false` or `null` to hide it, or any node to customize.
+     */
+    requiredIndicator?: ReactNode;
+    /**
+     * Show a marker after the label when the field is *not* required. `true`
+     * shows "(optional)"; pass a node to customize or localize it. Off by default.
+     * Use it in forms where most fields are required.
+     */
+    optionalIndicator?: ReactNode;
+    /**
+     * Put the error message in a `role="alert"` live region, so it is announced
+     * when it appears. Off by default: announcing every inline validation
+     * message is noisy. Turn it on for errors that appear after submit or an
+     * async check. The live region stays mounted while `announceError` is on,
+     * so the message is announced reliably when it is added.
+     */
+    announceError?: boolean;
+}
+/** Props for `FieldLabel`. */
+export interface FieldLabelProps extends ComponentPropsWithRef<"label"> {
+    /** Show `requiredIndicator` or `optionalIndicator`. Defaults to the surrounding Field's `required`. */
+    required?: boolean;
+    /** Marker shown when required. Defaults to an `aria-hidden` `*`. `false` or `null` hides it. */
+    requiredIndicator?: ReactNode;
+    /** Marker shown when not required. `true` shows "(optional)". Off by default. */
+    optionalIndicator?: ReactNode;
+    /** Label size. Defaults to the surrounding Field's size, then `md`. */
+    size?: Size;
+}
+/**
+ * The label of a Field. Reads `htmlFor` and `id` from the surrounding Field;
+ * use it standalone for custom layouts (pass `htmlFor` outside a Field).
+ */
+export declare function FieldLabel({ required, requiredIndicator, optionalIndicator, size, className, children, ...props }: FieldLabelProps): import("react").JSX.Element;
+/** Props for `FieldHint`. */
+export type FieldHintProps = ComponentPropsWithRef<"p">;
+/**
+ * Help text for a Field. Takes the Field's hint id and registers itself, so
+ * controls reference it with `aria-describedby`. Renders nothing when empty.
+ */
+export declare function FieldHint({ className, children, ...props }: FieldHintProps): import("react").JSX.Element | null;
+/** Props for `FieldError`. */
+export interface FieldErrorProps extends ComponentPropsWithRef<"p"> {
+    /**
+     * Wrap the message in a persistent `role="alert"` live region so it is
+     * announced when it appears. Off by default (see `Field`'s `announceError`).
+     */
+    announce?: boolean;
+}
+/**
+ * Error message for a Field, with a leading decorative error icon so the
+ * state isn't conveyed by color alone. Takes the Field's error id and
+ * registers itself; controls reference it only while the Field is invalid.
+ * Renders nothing when empty (except the live region when `announce` is on).
+ */
+export declare function FieldError({ announce, className, children, ...props }: FieldErrorProps): import("react").JSX.Element | null;
+/** Props for `Field`. */
+export interface FieldProps extends FieldCommonProps, Omit<ComponentPropsWithRef<"div">, "id"> {
+    /**
+     * id for the control. The label's `htmlFor` points here, and controls read
+     * it from context. Generated with `useId` when omitted. (The wrapper `div`
+     * gets no id.)
+     */
+    id?: string;
+    /**
+     * `vertical` (default): label above the control. `horizontal`: label to the
+     * left, falling back to vertical when the Field is narrower than 30rem
+     * (a container query, so it adapts to its column, not the viewport).
+     */
+    orientation?: Orientation;
+    /** Content at the end of the label row, e.g. a "Forgot password?" link. */
+    labelAction?: ReactNode;
+    /**
+     * Content at the end of the hint row, e.g. a character counter "12/280".
+     * It is not wired to the control; if it must be announced, give it its own
+     * polite live region or mention the limit in `hint`.
+     */
+    counter?: ReactNode;
+    /** The control (Input, Select, ...). It reads ids and state with `useFieldControl`. */
+    children?: ReactNode;
+}
+/**
+ * Wraps one form control with a label, hint, and error message, and wires
+ * them together: `<label for>`, `aria-describedby`, `aria-invalid`,
+ * `aria-errormessage`, `required`, and `disabled` all flow to the control
+ * through `FieldContext`.
+ */
+export declare function Field({ label, labelVisuallyHidden, hint, error, invalid: invalidProp, required, disabled, readOnly, size, id, requiredIndicator, optionalIndicator, announceError, orientation, labelAction, counter, className, children, ...rest }: FieldProps): import("react").JSX.Element;
+/** Props for `FieldProvider`. */
+export interface FieldProviderProps {
+    /** id for the control. Generated when omitted. */
+    id?: string;
+    /** Invalid state. Controls set `aria-invalid` and reference a mounted `FieldError`. */
+    invalid?: boolean;
+    /** Required. */
+    required?: boolean;
+    /** Disabled. */
+    disabled?: boolean;
+    /** Read-only. */
+    readOnly?: boolean;
+    /** Size shared with controls. */
+    size?: Size;
+    /** Your own layout: `FieldLabel`, the control, `FieldHint`, `FieldError`, anywhere inside. */
+    children?: ReactNode;
+}
+/**
+ * Provides `FieldContext` without rendering any markup, for fully custom
+ * layouts built from `FieldLabel`, `FieldHint`, and `FieldError`. The hint
+ * and error register themselves, so the control's `aria-describedby` and
+ * `aria-errormessage` stay correct wherever they are placed.
+ */
+export declare function FieldProvider({ id, invalid, required, disabled, readOnly, size, children, }: FieldProviderProps): import("react").JSX.Element;
+/** Props for `Fieldset`. */
+export interface FieldsetProps extends FieldCommonProps, ComponentPropsWithRef<"fieldset"> {
+    /**
+     * Visually hidden text added to the legend when `required`, because a group
+     * has no native `required` that screen readers announce for the legend.
+     * Localize it here.
+     */
+    requiredText?: string;
+    /** The group of controls (native radios / checkboxes, RadioGroup, CheckBoxGroup). */
+    children?: ReactNode;
+}
+/**
+ * Group mode of Field: a `<fieldset>` with a `<legend>`, for a set of related
+ * controls (RadioGroup, CheckBoxGroup, or native radios and checkboxes).
+ * Provides `FieldContext` with `isGroup: true`, so group controls label
+ * themselves with the legend's id. Native `disabled` on the fieldset disables
+ * every descendant control. The hint sits under the legend (read before the
+ * options); the error sits after the controls.
+ */
+export declare function Fieldset({ label, labelVisuallyHidden, hint, error, invalid: invalidProp, required, disabled, readOnly, size, requiredIndicator, optionalIndicator, requiredText, announceError, className, children, "aria-describedby": describedByProp, ...rest }: FieldsetProps): import("react").JSX.Element;
+export {};

package/dist/components/forms/Field/Field.mjs

@@ -0,0 +1,277 @@
+import { cx as e } from "../../../utils/cx.mjs";
+import { VisuallyHidden as t } from "../../utilities/VisuallyHidden/VisuallyHidden.mjs";
+import { ErrorIcon as n } from "../../primitives/Icon/icons.mjs";
+import { FieldContext as r, useFieldContext as i } from "./FieldContext.mjs";
+import a from "./Field.module.css.mjs";
+import { createContext as o, useCallback as s, useContext as c, useId as l, useLayoutEffect as u, useMemo as d, useState as f } from "react";
+import { Fragment as p, jsx as m, jsxs as h } from "react/jsx-runtime";
+//#region src/components/forms/Field/Field.tsx
+var g = o(null), _ = (e) => e != null && e !== !1 && e !== "";
+function v(e) {
+	let [t, n] = f({
+		hint: 0,
+		error: 0
+	}), r = s((e) => (n((t) => ({
+		...t,
+		[e]: t[e] + 1
+	})), () => n((t) => ({
+		...t,
+		[e]: t[e] - 1
+	}))), []);
+	return {
+		parts: d(() => ({
+			hintId: `${e}-hint`,
+			errorId: `${e}-error`,
+			register: r
+		}), [e, r]),
+		counts: t
+	};
+}
+function y(e, t) {
+	let n = c(g)?.register;
+	u(() => {
+		if (t && n) return n(e);
+	}, [
+		t,
+		e,
+		n
+	]);
+}
+var b = {
+	sm: a.sizeSm,
+	md: a.sizeMd,
+	lg: a.sizeLg
+};
+function x({ required: e, requiredIndicator: t, optionalIndicator: n }) {
+	return e ? t === !1 || t === null ? null : /* @__PURE__ */ m("span", {
+		className: a.requiredIndicator,
+		"aria-hidden": "true",
+		children: t === void 0 || t === !0 ? "*" : t
+	}) : _(n) ? /* @__PURE__ */ m("span", {
+		className: a.optionalIndicator,
+		children: n === !0 ? "(optional)" : n
+	}) : null;
+}
+var S = "input:not([type=\"hidden\"]), select, textarea, button, meter, output, progress";
+function C({ required: t, requiredIndicator: n, optionalIndicator: r, size: o, className: s, children: c, ...l }) {
+	let d = i(), p = t ?? d?.required ?? !1, g = o ?? d?.size ?? "md", _ = d && !d.isGroup ? d.controlId : void 0, [v, y] = f(!0);
+	return u(() => {
+		let e = _ ? document.getElementById(_) : null;
+		y(!e || e.matches(S));
+	}, [_]), /* @__PURE__ */ h("label", {
+		htmlFor: v ? _ : void 0,
+		id: d?.labelId,
+		...l,
+		className: e(a.label, b[g], d?.disabled && a.labelDisabled, s),
+		children: [c, /* @__PURE__ */ m(x, {
+			required: p,
+			requiredIndicator: n,
+			optionalIndicator: r
+		})]
+	});
+}
+function w({ className: t, children: n, ...r }) {
+	let i = c(g), o = _(n);
+	return y("hint", o), o ? /* @__PURE__ */ m("p", {
+		id: i?.hintId,
+		...r,
+		className: e(a.hint, t),
+		children: n
+	}) : null;
+}
+function T({ announce: t = !1, className: r, children: i, ...o }) {
+	let s = c(g), l = _(i);
+	y("error", l);
+	let u = l ? /* @__PURE__ */ h("p", {
+		id: s?.errorId,
+		...o,
+		className: e(a.error, r),
+		children: [/* @__PURE__ */ m(n, {
+			size: "sm",
+			className: a.errorIcon
+		}), /* @__PURE__ */ m("span", { children: i })]
+	}) : null;
+	return t ? /* @__PURE__ */ m("div", {
+		role: "alert",
+		className: a.alertRegion,
+		children: u
+	}) : u;
+}
+function E({ label: n, labelVisuallyHidden: i = !1, hint: o, error: s, invalid: c, required: u = !1, disabled: f = !1, readOnly: y = !1, size: x, id: S, requiredIndicator: E, optionalIndicator: D, announceError: O = !1, orientation: k = "vertical", labelAction: A, counter: j, className: M, children: N, ...P }) {
+	let F = l(), { parts: I, counts: L } = v(F), R = _(s), z = c ?? R, B = R && z, V = _(o), H = _(j), U = V || L.hint > 0, W = B || L.error > 0, G = d(() => ({
+		controlId: S ?? `${F}-control`,
+		labelId: `${F}-label`,
+		hintId: U ? I.hintId : void 0,
+		errorId: W ? I.errorId : void 0,
+		invalid: z,
+		required: u,
+		disabled: f,
+		readOnly: y,
+		size: x,
+		isGroup: !1
+	}), [
+		S,
+		F,
+		U,
+		W,
+		I,
+		z,
+		u,
+		f,
+		y,
+		x
+	]), K = /* @__PURE__ */ m(C, {
+		requiredIndicator: E,
+		optionalIndicator: D,
+		children: n
+	}), q = _(A);
+	return /* @__PURE__ */ m(r.Provider, {
+		value: G,
+		children: /* @__PURE__ */ m(g.Provider, {
+			value: I,
+			children: /* @__PURE__ */ m("div", {
+				...P,
+				"data-orientation": k,
+				"data-invalid": z || void 0,
+				"data-disabled": f || void 0,
+				className: e(a.field, k === "horizontal" && a.horizontal, x && b[x], M),
+				children: /* @__PURE__ */ h("div", {
+					className: a.layout,
+					children: [i ? /* @__PURE__ */ h(p, { children: [/* @__PURE__ */ m(t, { children: K }), q && /* @__PURE__ */ m("div", {
+						className: e(a.labelRow, a.labelRowActionOnly),
+						children: /* @__PURE__ */ m("span", {
+							className: a.labelAction,
+							children: A
+						})
+					})] }) : /* @__PURE__ */ h("div", {
+						className: a.labelRow,
+						children: [K, q && /* @__PURE__ */ m("span", {
+							className: a.labelAction,
+							children: A
+						})]
+					}), /* @__PURE__ */ h("div", {
+						className: a.body,
+						children: [
+							N,
+							(V || H) && /* @__PURE__ */ h("div", {
+								className: a.hintRow,
+								children: [V && /* @__PURE__ */ m(w, { children: o }), H && /* @__PURE__ */ m("span", {
+									className: a.counter,
+									children: j
+								})]
+							}),
+							(B || O) && /* @__PURE__ */ m(T, {
+								announce: O,
+								children: B ? s : null
+							})
+						]
+					})]
+				})
+			})
+		})
+	});
+}
+function D({ id: e, invalid: t = !1, required: n = !1, disabled: i = !1, readOnly: a = !1, size: o, children: s }) {
+	let c = l(), { parts: u, counts: f } = v(c), p = d(() => ({
+		controlId: e ?? `${c}-control`,
+		labelId: `${c}-label`,
+		hintId: f.hint > 0 ? u.hintId : void 0,
+		errorId: f.error > 0 ? u.errorId : void 0,
+		invalid: t,
+		required: n,
+		disabled: i,
+		readOnly: a,
+		size: o,
+		isGroup: !1
+	}), [
+		e,
+		c,
+		f.hint,
+		f.error,
+		u,
+		t,
+		n,
+		i,
+		a,
+		o
+	]);
+	return /* @__PURE__ */ m(r.Provider, {
+		value: p,
+		children: /* @__PURE__ */ m(g.Provider, {
+			value: u,
+			children: s
+		})
+	});
+}
+function O({ label: n, labelVisuallyHidden: i = !1, hint: o, error: s, invalid: c, required: u = !1, disabled: f = !1, readOnly: y = !1, size: S, requiredIndicator: C, optionalIndicator: E, requiredText: D = "required", announceError: O = !1, className: k, children: A, "aria-describedby": j, ...M }) {
+	let N = l(), { parts: P, counts: F } = v(N), I = _(s), L = c ?? I, R = I && L, z = _(o), B = z || F.hint > 0, V = R || F.error > 0, H = `${N}-label`, U = d(() => ({
+		controlId: `${N}-control`,
+		labelId: H,
+		hintId: B ? P.hintId : void 0,
+		errorId: V ? P.errorId : void 0,
+		invalid: L,
+		required: u,
+		disabled: f,
+		readOnly: y,
+		size: S,
+		isGroup: !0
+	}), [
+		N,
+		H,
+		B,
+		V,
+		P,
+		L,
+		u,
+		f,
+		y,
+		S
+	]), W = [
+		j,
+		B ? P.hintId : void 0,
+		L && V ? P.errorId : void 0
+	].filter(Boolean).join(" ") || void 0, G = /* @__PURE__ */ h(p, { children: [
+		n,
+		/* @__PURE__ */ m(x, {
+			required: u,
+			requiredIndicator: C,
+			optionalIndicator: E
+		}),
+		u && /* @__PURE__ */ h(t, { children: [
+			" (",
+			D,
+			")"
+		] })
+	] });
+	return /* @__PURE__ */ m(r.Provider, {
+		value: U,
+		children: /* @__PURE__ */ m(g.Provider, {
+			value: P,
+			children: /* @__PURE__ */ h("fieldset", {
+				...M,
+				disabled: f,
+				"aria-describedby": W,
+				"data-invalid": L || void 0,
+				"data-disabled": f || void 0,
+				className: e(a.fieldset, S && b[S], k),
+				children: [/* @__PURE__ */ m("legend", {
+					id: H,
+					className: e(a.label, a.legend, b[S ?? "md"], f && a.labelDisabled, i && a.legendHidden),
+					children: i ? /* @__PURE__ */ m(t, { children: G }) : G
+				}), /* @__PURE__ */ h("div", {
+					className: a.groupBody,
+					children: [
+						z && /* @__PURE__ */ m(w, { children: o }),
+						A,
+						(R || O) && /* @__PURE__ */ m(T, {
+							announce: O,
+							children: R ? s : null
+						})
+					]
+				})]
+			})
+		})
+	});
+}
+//#endregion
+export { E as Field, T as FieldError, w as FieldHint, C as FieldLabel, D as FieldProvider, O as Fieldset };

package/dist/components/forms/Field/Field.module.css.cjs.js

@@ -0,0 +1 @@
+var e=`_sizeSm_ygpyp_19`,t=`_sizeMd_ygpyp_27`,n=`_sizeLg_ygpyp_35`,r=`_field_ygpyp_47`,i=`_layout_ygpyp_61`,a=`_labelRow_ygpyp_77`,o=`_labelRowActionOnly_ygpyp_97`,s=`_label_ygpyp_77`,c=`_labelDisabled_ygpyp_123`,l=`_requiredIndicator_ygpyp_133`,u=`_optionalIndicator_ygpyp_143`,d=`_labelAction_ygpyp_167`,f=`_body_ygpyp_179`,p=`_hintRow_ygpyp_193`,m=`_hint_ygpyp_193`,h=`_counter_ygpyp_225`,g=`_error_ygpyp_247`,_=`_errorIcon_ygpyp_271`,v=`_alertRegion_ygpyp_285`,y=`_groupBody_ygpyp_291`,b=`_horizontal_ygpyp_305`,x=`_fieldset_ygpyp_363`,S=`_legend_ygpyp_383`,C=`_legendHidden_ygpyp_393`,w={sizeSm:e,sizeMd:t,sizeLg:n,field:r,layout:i,labelRow:a,labelRowActionOnly:o,label:s,labelDisabled:c,requiredIndicator:l,optionalIndicator:u,labelAction:d,body:f,hintRow:p,hint:m,counter:h,error:g,errorIcon:_,alertRegion:v,groupBody:y,horizontal:b,fieldset:x,legend:S,legendHidden:C};exports.alertRegion=v,exports.body=f,exports.counter=h,exports.default=w,exports.error=g,exports.errorIcon=_,exports.field=r,exports.fieldset=x,exports.groupBody=y,exports.hint=m,exports.hintRow=p,exports.horizontal=b,exports.label=s,exports.labelAction=d,exports.labelDisabled=c,exports.labelRow=a,exports.labelRowActionOnly=o,exports.layout=i,exports.legend=S,exports.legendHidden=C,exports.optionalIndicator=u,exports.requiredIndicator=l,exports.sizeLg=n,exports.sizeMd=t,exports.sizeSm=e;

package/dist/components/forms/Field/Field.module.css.mjs

@@ -0,0 +1,29 @@
+//#region src/components/forms/Field/Field.module.css
+var e = "_sizeSm_ygpyp_19", t = "_sizeMd_ygpyp_27", n = "_sizeLg_ygpyp_35", r = "_field_ygpyp_47", i = "_layout_ygpyp_61", a = "_labelRow_ygpyp_77", o = "_labelRowActionOnly_ygpyp_97", s = "_label_ygpyp_77", c = "_labelDisabled_ygpyp_123", l = "_requiredIndicator_ygpyp_133", u = "_optionalIndicator_ygpyp_143", d = "_labelAction_ygpyp_167", f = "_body_ygpyp_179", p = "_hintRow_ygpyp_193", m = "_hint_ygpyp_193", h = "_counter_ygpyp_225", g = "_error_ygpyp_247", _ = "_errorIcon_ygpyp_271", v = "_alertRegion_ygpyp_285", y = "_groupBody_ygpyp_291", b = "_horizontal_ygpyp_305", x = "_fieldset_ygpyp_363", S = "_legend_ygpyp_383", C = "_legendHidden_ygpyp_393", w = {
+	sizeSm: e,
+	sizeMd: t,
+	sizeLg: n,
+	field: r,
+	layout: i,
+	labelRow: a,
+	labelRowActionOnly: o,
+	label: s,
+	labelDisabled: c,
+	requiredIndicator: l,
+	optionalIndicator: u,
+	labelAction: d,
+	body: f,
+	hintRow: p,
+	hint: m,
+	counter: h,
+	error: g,
+	errorIcon: _,
+	alertRegion: v,
+	groupBody: y,
+	horizontal: b,
+	fieldset: x,
+	legend: S,
+	legendHidden: C
+};
+//#endregion
+export { v as alertRegion, f as body, h as counter, w as default, g as error, _ as errorIcon, r as field, x as fieldset, y as groupBody, m as hint, p as hintRow, b as horizontal, s as label, d as labelAction, c as labelDisabled, a as labelRow, o as labelRowActionOnly, i as layout, S as legend, C as legendHidden, u as optionalIndicator, l as requiredIndicator, n as sizeLg, t as sizeMd, e as sizeSm };

package/dist/components/forms/Field/FieldContext.cjs.js

@@ -0,0 +1 @@
+let e=require("react");var t=(0,e.createContext)(null);function n(){return(0,e.useContext)(t)}function r(e={},{nativeRequired:t=!0}={}){let r=n(),i=e.invalid??r?.invalid??!1,a=e.required??r?.required??!1,o=e.disabled??r?.disabled??!1,s=e.readOnly??r?.readOnly??!1,c=e.id??(r&&!r.isGroup?r.controlId:void 0),l=[e[`aria-describedby`],r?.hintId,i?r?.errorId:void 0].filter(Boolean).join(` `)||void 0;return{id:c,invalid:i,required:a,disabled:o,readOnly:s,size:e.size??r?.size,ariaProps:{...l?{"aria-describedby":l}:null,...i?{"aria-invalid":!0}:null,...i&&r?.errorId?{"aria-errormessage":r.errorId}:null,...a&&!t?{"aria-required":!0}:null}}}exports.FieldContext=t,exports.useFieldContext=n,exports.useFieldControl=r;

package/dist/components/forms/Field/FieldContext.d.ts

@@ -0,0 +1,74 @@
+import { Size } from '../../../types/common';
+/**
+ * The contract between `Field` (label, hint, error wrapper) and the form
+ * controls inside it (Input, Textarea, Select, CheckBox, RadioGroup, Switch,
+ * Slider, ...). `Field` provides this; controls read it with
+ * `useFieldControl` so labels, descriptions, and error state are wired
+ * automatically. Controls must also work standalone, with no Field around them.
+ */
+export interface FieldContextValue {
+    /** id for the control element (the label's htmlFor points here). */
+    controlId: string;
+    /** id of the visible label (or legend, for groups). */
+    labelId: string;
+    /** id of the hint text, when a hint is rendered. */
+    hintId?: string;
+    /** id of the error message, when an error is rendered. */
+    errorId?: string;
+    /** The field is invalid: controls set aria-invalid and use danger styling. */
+    invalid: boolean;
+    required: boolean;
+    disabled: boolean;
+    readOnly: boolean;
+    /** Size shared with controls that don't set their own. */
+    size?: Size;
+    /**
+     * True when Field renders a fieldset + legend around a group of controls
+     * (RadioGroup, CheckBoxGroup). Group controls then label themselves with
+     * `labelId` instead of taking `controlId`.
+     */
+    isGroup: boolean;
+}
+export declare const FieldContext: import('react').Context<FieldContextValue | null>;
+/** Returns the surrounding Field's context, or null outside a Field. */
+export declare function useFieldContext(): FieldContextValue | null;
+/** Props a control may receive directly; explicit props win over the Field's. */
+export interface FieldControlOverrides {
+    id?: string;
+    invalid?: boolean;
+    required?: boolean;
+    disabled?: boolean;
+    readOnly?: boolean;
+    size?: Size;
+    "aria-describedby"?: string;
+}
+/** Everything a control needs to spread or read after merging with Field. */
+export interface FieldControlProps {
+    id: string | undefined;
+    invalid: boolean;
+    required: boolean;
+    disabled: boolean;
+    readOnly: boolean;
+    size: Size | undefined;
+    /** Spread onto the focusable control element. */
+    ariaProps: {
+        "aria-describedby"?: string;
+        "aria-invalid"?: true;
+        "aria-errormessage"?: string;
+        "aria-required"?: true;
+    };
+}
+/**
+ * Merges a control's own props with the surrounding Field (if any).
+ *
+ * ```tsx
+ * const field = useFieldControl({ id, invalid, required, disabled, readOnly, size, "aria-describedby": describedBy });
+ * <input id={field.id} required={field.required} disabled={field.disabled} {...field.ariaProps} />
+ * ```
+ *
+ * Use native `required` on native inputs; `ariaProps["aria-required"]` is
+ * only set for custom (non-native) controls via `{ nativeRequired: false }`.
+ */
+export declare function useFieldControl(own?: FieldControlOverrides, { nativeRequired }?: {
+    nativeRequired?: boolean;
+}): FieldControlProps;

package/dist/components/forms/Field/FieldContext.mjs

@@ -0,0 +1,29 @@
+import { createContext as e, useContext as t } from "react";
+//#region src/components/forms/Field/FieldContext.ts
+var n = e(null);
+function r() {
+	return t(n);
+}
+function i(e = {}, { nativeRequired: t = !0 } = {}) {
+	let n = r(), i = e.invalid ?? n?.invalid ?? !1, a = e.required ?? n?.required ?? !1, o = e.disabled ?? n?.disabled ?? !1, s = e.readOnly ?? n?.readOnly ?? !1, c = e.id ?? (n && !n.isGroup ? n.controlId : void 0), l = [
+		e["aria-describedby"],
+		n?.hintId,
+		i ? n?.errorId : void 0
+	].filter(Boolean).join(" ") || void 0;
+	return {
+		id: c,
+		invalid: i,
+		required: a,
+		disabled: o,
+		readOnly: s,
+		size: e.size ?? n?.size,
+		ariaProps: {
+			...l ? { "aria-describedby": l } : null,
+			...i ? { "aria-invalid": !0 } : null,
+			...i && n?.errorId ? { "aria-errormessage": n.errorId } : null,
+			...a && !t ? { "aria-required": !0 } : null
+		}
+	};
+}
+//#endregion
+export { n as FieldContext, r as useFieldContext, i as useFieldControl };

package/dist/components/forms/Field/index.d.ts

@@ -0,0 +1,2 @@
+export * from './Field';
+export * from './FieldContext';

package/dist/components/forms/FileUpload/FileUpload.cjs.js

@@ -0,0 +1 @@
+const e=require("../../../i18n/en.cjs.js"),t=require("../../../hooks/useControllableState.cjs.js"),n=require("../../../hooks/useFormReset.cjs.js"),r=require("../../utilities/LocaleProvider/LocaleProvider.cjs.js"),i=require("../../../utils/refs.cjs.js"),a=require("../../../utils/cx.cjs.js"),o=require("../../utilities/VisuallyHidden/VisuallyHidden.cjs.js"),s=require("../../feedback/Spinner/Spinner.cjs.js"),c=require("../../primitives/Button/Button.cjs.js"),l=require("../../primitives/Icon/icons.cjs.js"),u=require("../Field/FieldContext.cjs.js"),d=require("../../feedback/Progress/Progress.cjs.js"),f=require("./FileUpload.module.css.cjs.js");let p=require("react"),m=require("react/jsx-runtime");var h={sm:f.default.sm,md:f.default.md,lg:f.default.lg},g={dropzone:f.default.variantDropzone,button:f.default.variantButton};function _(t,n=e.en.fileUpload.units,r){let i=e=>new Intl.NumberFormat(r).format(e);if(!Number.isFinite(t)||t<0)return`${i(0)} ${n.B}`;if(t<1024)return`${i(Math.round(t))} ${n.B}`;let a=[n.KB,n.MB,n.GB,n.TB],o=t/1024,s=0;for(;o>=1024&&s<a.length-1;)o/=1024,s++;return`${i(o>=10?Math.round(o):Math.round(o*10)/10)} ${a[s]}`}function v(e){return e?e.split(`,`).map(e=>e.trim().toLowerCase()).filter(Boolean):[]}function y(e,t){let n=v(t);if(n.length===0)return!0;let r=e.name.toLowerCase(),i=(e.type||``).toLowerCase();return n.some(e=>e.startsWith(`.`)?r.endsWith(e):e.endsWith(`/*`)?i.startsWith(e.slice(0,-1)):i===e)}var b={"image/jpeg":`JPG`,"image/svg+xml":`SVG`,"text/plain":`TXT`,"application/msword":`DOC`,"application/vnd.openxmlformats-officedocument.wordprocessingml.document":`DOCX`,"application/vnd.ms-excel":`XLS`,"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":`XLSX`};function x(t,n=e.en.fileUpload){let r=n.typeGroups,i=v(t).map(e=>{if(e.startsWith(`.`))return e.slice(1).toUpperCase();if(e.endsWith(`/*`)){let t=e.slice(0,-2);return r[t]??n.typeGroup(t)}return b[e]?b[e]:(e.split(`/`)[1]??e).toUpperCase()}),a=Array.from(new Set(i));if(a.length===0)return``;let o=a.join(`, `);return o.charAt(0).toUpperCase()+o.slice(1)}var S=e=>`${e.name}::${e.size}::${e.lastModified}`,C=e=>(e.type||``).startsWith(`image/`),w=new WeakMap,T=0;function E(e){let t=w.get(e);return t||(t=`file-${++T}`,w.set(e,t)),t}function D(e,t){let n=Intl.ListFormat;return n?new n(t,{type:`conjunction`}).format(e):e.join(`, `)}function ee(){let[e,t]=(0,p.useState)(``),n=(0,p.useRef)(!1);return[e,(0,p.useCallback)(e=>{n.current=!n.current,t(n.current?`${e} `:e)},[])]}function O(e,t){let[n,r]=(0,p.useState)();return(0,p.useEffect)(()=>{if(!t||typeof URL>`u`||typeof URL.createObjectURL!=`function`)return;let n=URL.createObjectURL(e);return r(n),()=>{URL.revokeObjectURL(n),r(void 0)}},[e,t]),n}var k=(e,t)=>{if(!e?.status&&e?.progress==null)return null;if(e.message)return e.message;switch(e.status){case`done`:return t.uploaded;case`error`:return t.uploadFailed;default:return e.progress==null?t.uploading:t.uploadingPercent(Math.round(e.progress))}},te=({file:e,state:t,showThumbnails:n,disabled:i,removeLabel:a,onRemove:o,removeRef:u})=>{let{messages:h,locale:g}=r.useLocale(),v=C(e),[y,b]=(0,p.useState)(!1),x=O(e,n&&v),S=t?.status??(t?.progress==null?void 0:`uploading`),w=k(t,h.fileUpload),T=S===`uploading`&&t?.progress!=null;return(0,m.jsxs)(`li`,{className:f.default.item,"data-status":S,children:[(0,m.jsx)(`span`,{className:f.default.thumb,"aria-hidden":`true`,children:x&&!y?(0,m.jsx)(`img`,{className:f.default.thumbImage,src:x,alt:``,onError:()=>b(!0)}):v?(0,m.jsx)(l.ImageIcon,{size:`md`}):(0,m.jsx)(l.FileIcon,{size:`md`})}),(0,m.jsxs)(`div`,{className:f.default.itemBody,children:[(0,m.jsx)(`span`,{className:f.default.fileName,title:e.name,children:e.name}),(0,m.jsxs)(`span`,{className:f.default.meta,children:[(0,m.jsx)(`span`,{children:_(e.size,h.fileUpload.units,g)}),w&&(0,m.jsxs)(`span`,{className:f.default.status,"data-status":S,children:[S===`done`&&(0,m.jsx)(l.CheckIcon,{size:`sm`}),S===`error`&&(0,m.jsx)(l.ErrorIcon,{size:`sm`}),S===`uploading`&&(0,m.jsx)(s.Spinner,{decorative:!0,size:`xs`}),(0,m.jsx)(`span`,{children:w})]})]}),T&&(0,m.jsx)(d.Progress,{className:f.default.progress,size:`sm`,value:t?.progress,"aria-label":h.fileUpload.progressFor(e.name)})]}),o&&(0,m.jsx)(c.IconButton,{ref:u,className:f.default.remove,variant:`ghost`,tone:`neutral`,size:`sm`,"aria-label":a,disabled:i,onClick:o,children:S===`uploading`?(0,m.jsx)(l.CloseIcon,{size:`sm`}):(0,m.jsx)(l.TrashIcon,{size:`sm`})})]})},A=({files:e,onRemove:t,getFileState:n,showThumbnails:i=!0,disabled:s=!1,removeLabel:c,focusFallback:l,size:u=`md`,className:d,"aria-label":g,..._})=>{let{messages:v,locale:y}=r.useLocale(),b=e=>D(e,y),x=c??v.fileUpload.remove,S=g??v.fileUpload.list,C=(0,p.useRef)([]),w=(0,p.useRef)(null),[T,O]=ee(),k=(n,r)=>{w.current={index:r,length:e.length},t?.(n,r)};(0,p.useLayoutEffect)(()=>{let t=w.current;if(t&&(w.current=null,!(e.length>=t.length))){if(e.length===0){l?.()?.focus();return}C.current[Math.min(t.index,e.length-1)]?.focus()}},[e,l]);let A=e.map((e,t)=>n?.(e,t)),j=(0,p.useRef)(new WeakMap),M=A.map(e=>e?.status??``).join(`|`);return(0,p.useEffect)(()=>{let t=[],n=[];e.forEach((e,r)=>{let i=A[r]?.status,a=j.current.get(e);i!==a&&((a!==void 0||j.current.has(e))&&(i===`done`&&t.push(e.name),i===`error`&&n.push(e.name)),j.current.set(e,i))});let r=[];t.length&&r.push(v.fileUpload.announceUploaded(b(t))),n.length&&r.push(v.fileUpload.announceFailed(b(n))),r.length&&O(r.join(` `))},[e,M,O]),(0,m.jsxs)(m.Fragment,{children:[e.length>0&&(0,m.jsx)(`ul`,{..._,"aria-label":S,className:a.cx(f.default.list,h[u],d),children:e.map((e,n)=>(0,m.jsx)(te,{file:e,state:A[n],showThumbnails:i,disabled:s,removeLabel:x(e.name),onRemove:t?()=>k(e,n):void 0,removeRef:e=>{C.current[n]=e}},E(e)))}),(0,m.jsx)(o.VisuallyHidden,{role:`status`,children:T})]})};function j(e,t,n,r,i){let a=e=>_(e,r.units,i),{accept:o,multiple:s=!1,maxFiles:c,maxSize:l,minSize:u,validator:d}=n,f=[],p=[],m=new Set(s?t.map(S):[]),h=s?c??1/0:1,g=s?t.length:0,v=x(o,r);for(let t of e){let e=[];if(y(t,o)||e.push(v?r.typeNotAcceptedUse(v):r.typeNotAccepted),l!=null&&t.size>l&&e.push(r.tooLarge(a(l))),u!=null&&t.size<u&&e.push(r.tooSmall(a(u))),m.has(S(t))&&e.push(r.duplicate),e.length===0&&d){let n=d(t);n&&e.push(n)}e.length===0&&g+f.length>=h&&e.push(s?r.tooMany(h):r.onlyOne),e.length?p.push({file:t,errors:e}):(f.push(t),m.add(S(t)))}return{accepted:f,rejections:p}}var M=e=>Array.from(e.dataTransfer?.types??[]).includes(`Files`),ne=Object.assign(({accept:e,multiple:s=!1,maxFiles:d,maxSize:v,minSize:y,validator:b,value:S,defaultValue:C,onValueChange:w,onReject:T,onFileRemove:D,disabled:O,invalid:k,name:te,required:ne,size:re,variant:N=`dropzone`,children:P,prompt:ie,hint:ae,browseLabel:oe,showList:se=!0,showRejections:ce=!0,showThumbnails:le=!0,getFileState:ue,inputRef:de,buttonRef:fe,id:pe,className:me,style:he,"aria-describedby":ge,"aria-label":F,"aria-labelledby":_e,...I})=>{let{messages:L,locale:ve}=r.useLocale(),ye=e=>_(e,L.fileUpload.units,ve),R=(0,p.useId)(),z=`${R}-hint`,be=`${R}-prompt`,xe=`${R}-browse`,Se=`${R}-rejections`,Ce=`${R}-required`,we=`${R}-input`,B=u.useFieldContext(),[V,Te]=(0,p.useState)([]),H=ae===void 0?[[x(e,L.fileUpload),v==null?``:s?L.fileUpload.upToEach(ye(v)):L.fileUpload.upTo(ye(v))].filter(Boolean).join(` `),s&&d!=null?L.fileUpload.maxFiles(d):``].filter(Boolean).map(e=>`${e}.`).join(` `)||null:ae,Ee=H!==null&&H!==!1&&H!==``,De=ce&&V.length>0,U=u.useFieldControl({id:pe,invalid:k,required:ne,disabled:O,size:re,"aria-describedby":[ge,Ee&&!P?z:void 0,De?Se:void 0].filter(Boolean).join(` `)||void 0}),W=U.size??`md`,G=U.disabled,[K,q]=t.useControllableState({value:S,defaultValue:C??[],onChange:w});n.useFormReset(()=>U.id?document.getElementById(U.id):null,()=>q(C??[]),S===void 0);let J=(0,p.useRef)(K);J.current=K;let[Oe,ke]=ee(),[Ae,Y]=(0,p.useState)(!1),X=(0,p.useRef)(0),Z=(0,p.useRef)(null),Q=(0,p.useRef)(null),je=(0,p.useCallback)(e=>{Z.current=e,i.assignRef(de,e)},[de]),Me=(0,p.useCallback)(e=>{Q.current=e,i.assignRef(fe,e)},[fe]),$=(0,p.useCallback)(e=>{let t=Z.current;if(t)try{if(typeof DataTransfer>`u`)throw Error(`unsupported`);let n=new DataTransfer;e.forEach(e=>n.items.add(e)),t.files=n.files}catch{e.length===0&&(t.value=``)}},[]);(0,p.useEffect)(()=>{$(K)},[K,$]);let Ne=(0,p.useCallback)(()=>{if(G)return;let e=Z.current;e&&(e.value=``,e.click())},[G]);(0,p.useEffect)(()=>{let e=Z.current;if(!e)return;let t=()=>$(J.current);return e.addEventListener(`cancel`,t),()=>e.removeEventListener(`cancel`,t)},[$]);let Pe=t=>{if(G||t.length===0)return;let n=J.current,r=j(t,n,{accept:e,multiple:s,maxFiles:d,maxSize:v,minSize:y,validator:b},L.fileUpload,ve);r.accepted.length&&q(s?[...n,...r.accepted]:r.accepted),Te(r.rejections),r.rejections.length&&T?.(r.rejections);let i=r.accepted.length,a=r.rejections.length,o=L.fileUpload.announceAdded(i,a);a===1&&i===0&&(o+=` ${r.rejections[0].file.name}: ${r.rejections[0].errors.join(` `)}`),ke(o)},Fe=e=>{let t=Array.from(e.target.files??[]);Pe(t),requestAnimationFrame(()=>$(J.current))},Ie=e=>{let t=J.current.filter(t=>t!==e);q(t),D?.(e),ke(`${e.name} removed.`)},Le=()=>{X.current=0,Y(!1)},Re=e=>{M(e)&&(e.preventDefault(),X.current+=1,G||Y(!0))},ze=e=>{M(e)&&(e.preventDefault(),e.dataTransfer.dropEffect=G?`none`:`copy`)},Be=e=>{M(e)&&(X.current=Math.max(0,X.current-1),X.current===0&&Y(!1))},Ve=e=>{M(e)&&(e.preventDefault(),Le(),!G&&Pe(Array.from(e.dataTransfer.files??[])))},He=[xe,B&&!B.isGroup?B.labelId:void 0].filter(Boolean).join(` `),Ue=[U.ariaProps[`aria-describedby`],U.required?Ce:void 0].filter(Boolean).join(` `)||void 0,We=oe??(N===`button`?L.fileUpload.uploadFiles:L.fileUpload.browseFiles),Ge=W,Ke=(0,m.jsx)(c.Button,{ref:Me,id:U.id,className:f.default.browse,variant:N===`button`?`outline`:`solid`,size:Ge,startIcon:N===`button`?(0,m.jsx)(l.UploadIcon,{size:`sm`}):void 0,disabled:G,"aria-labelledby":He,"aria-describedby":Ue,"aria-invalid":U.ariaProps[`aria-invalid`],"aria-errormessage":U.ariaProps[`aria-errormessage`],"aria-controls":we,onClick:Ne,children:(0,m.jsx)(`span`,{id:xe,children:We})}),qe=ie??(s?L.fileUpload.dropFiles:L.fileUpload.dropFile),Je=typeof P==`function`?P({dragging:Ae,disabled:G,openPicker:Ne}):P,Ye=Ee?(0,m.jsx)(`p`,{id:z,className:f.default.hint,children:H}):null,Xe=_e??(B&&!F?B.labelId:void 0),Ze=!!(F||Xe),Qe=(0,p.useCallback)(()=>Q.current,[]),$e=(0,p.useMemo)(()=>K,[K]);return(0,m.jsxs)(`div`,{...I,role:Ze?`group`:I.role,"aria-label":F,"aria-labelledby":Xe,className:a.cx(f.default.root,h[W],g[N],U.invalid&&f.default.invalid,G&&f.default.disabled,me),style:he,"data-size":W,"data-variant":N,"data-dragging":Ae||void 0,"data-disabled":G||void 0,"aria-disabled":G||void 0,children:[(0,m.jsx)(`input`,{ref:je,id:we,className:f.default.nativeInput,type:`file`,name:te,accept:e,multiple:s,required:U.required,disabled:G,tabIndex:-1,"aria-hidden":`true`,onChange:Fe,onInvalid:()=>Q.current?.focus()}),U.required&&(0,m.jsx)(o.VisuallyHidden,{id:Ce,children:L.fileUpload.required}),N===`dropzone`?(0,m.jsxs)(`div`,{className:f.default.dropzone,onDragEnter:Re,onDragOver:ze,onDragLeave:Be,onDrop:Ve,children:[(0,m.jsx)(`span`,{className:f.default.iconBadge,"aria-hidden":`true`,children:(0,m.jsx)(l.UploadIcon,{size:W===`lg`?`xl`:W===`sm`?`sm`:`lg`})}),(0,m.jsx)(`div`,{className:f.default.text,children:Je??(0,m.jsxs)(m.Fragment,{children:[(0,m.jsx)(`p`,{id:be,className:f.default.prompt,children:qe}),Ye]})}),Ke]}):(0,m.jsxs)(`div`,{className:f.default.buttonRow,children:[Ke,Je??Ye]}),De&&(0,m.jsxs)(`div`,{id:Se,className:f.default.rejections,children:[(0,m.jsxs)(`div`,{className:f.default.rejectionsHeader,children:[(0,m.jsx)(l.ErrorIcon,{size:`sm`}),(0,m.jsx)(`p`,{className:f.default.rejectionsTitle,children:L.fileUpload.rejected(V.length)}),(0,m.jsx)(c.IconButton,{className:f.default.rejectionsDismiss,variant:`ghost`,tone:`neutral`,size:`sm`,"aria-label":L.fileUpload.dismissErrors,onClick:()=>{Te([]),Q.current?.focus()},children:(0,m.jsx)(l.CloseIcon,{size:`sm`})})]}),(0,m.jsx)(`ul`,{className:f.default.rejectionList,children:V.map(({file:e,errors:t},n)=>(0,m.jsxs)(`li`,{className:f.default.rejection,children:[(0,m.jsx)(`span`,{className:f.default.rejectionName,children:e.name}),(0,m.jsx)(`span`,{className:f.default.rejectionReason,children:t.join(` `)})]},`${E(e)}-${n}`))})]}),se&&(0,m.jsx)(A,{files:$e,size:W,disabled:G,showThumbnails:le,getFileState:ue,onRemove:Ie,focusFallback:Qe}),(0,m.jsx)(o.VisuallyHidden,{role:`status`,children:Oe})]})},{List:A});exports.FileUpload=ne,exports.FileUploadList=A,exports.describeAccept=x,exports.fileMatchesAccept=y,exports.formatFileSize=_;