@iress-oss/ids-components 6.2.2 → 6.3.0

package/.ai/patterns/form.md

@@ -530,6 +530,38 @@ Some use cases:
 
 [View "ValidationSummary" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_patterns-form--validation-summary)
 
+### Controlling screen reader announcements
+
+By default, `IressFormValidationSummary` uses `role="alert"` (an assertive live region), which causes screen readers to interrupt the user and read out the entire error list immediately. When using `mode="onBlur"`, a new error is added every time the user leaves a field — this can be disruptive.
+
+You have two options for a less intrusive experience:
+
+**Option 1 — Polite announcements via `aria-live`**
+
+Pass `aria-live="polite"` and `role="status"` to `IressFormValidationSummary` to switch to a polite live region. Screen readers will wait for a pause in user activity before announcing changes.
+
+```tsx
+<IressForm mode="onBlur">
+  <IressFormValidationSummary aria-live="polite" role="status" srOnly />
+  {/* fields */}
+</IressForm>
+```
+
+**Option 2 — Only announce on submit via `updateErrorSummaryOnSubmit`**
+
+Pass `updateErrorSummaryOnSubmit` to `IressForm` (or `IressHookForm`) to prevent the summary from updating while the user is still filling in the form. The summary will only be populated — and announced — when the form is submitted.
+
+```tsx
+<IressForm mode="onBlur" updateErrorSummaryOnSubmit>
+  {/* fields */}
+</IressForm>
+```
+
+| Approach | When to use |
+|---|---|
+| `aria-live="polite"` on `IressFormValidationSummary` | Real-time feedback is still desirable but should not interrupt the user |
+| `updateErrorSummaryOnSubmit` on `IressForm` | Errors should only be announced once the user tries to submit |
+
 ## Migration to version 5 and beyond
 
 The previous form components contained a lot of logic to translate the HTML5 validation API to a format that matched the design system’s guidelines. This allowed users to use the default props of input such as `pattern` and `required`, and be assured that the `IressField` would display errors accordingly.

package/dist/{Autocomplete-CzdfUGYJ.js → Autocomplete-ZqkibVwt.js}

@@ -121,6 +121,7 @@ var x = (e) => typeof e == "object" && !!e && "label" in e, S = (e, t) => {
 			disabled: s,
 			id: c,
 			name: u,
+			onBlur: f,
 			onChange: (e, t) => {
 				d?.(e, t?.value ?? null, t), V(t);
 			},

package/dist/components/Autocomplete/Autocomplete.js

@@ -1,2 +1,2 @@
-import { t as e } from "../../Autocomplete-CzdfUGYJ.js";
+import { t as e } from "../../Autocomplete-ZqkibVwt.js";
 export { e as IressAutocomplete };

package/dist/components/Autocomplete/index.js

@@ -1,4 +1,4 @@
 import { autoComplete as e } from "./Autocomplete.styles.js";
 import { t } from "../../useAutocompleteSearch-BYzUn7Ag.js";
-import { t as n } from "../../Autocomplete-CzdfUGYJ.js";
+import { t as n } from "../../Autocomplete-ZqkibVwt.js";
 export { n as IressAutocomplete, e as autoComplete, t as useAutocompleteSearch };

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

@@ -40,6 +40,12 @@ export type IressFieldProps<E extends 'div' | 'fieldset' = 'div', ELabel extends
      * Validation errors to be displayed above the field, an array of validation messages to be displayed in `IressValidationSummary`.
      */
     errorMessages?: ValidationMessageObj[];
+    /**
+     * ID for the error container element, used to associate the error message with the form control via `aria-describedby`.
+     * When `error` or `errorMessages` are present and `htmlFor` is set, this is automatically derived as `${htmlFor}-error`.
+     * Override only if you need a custom error container ID.
+     */
+    errorId?: string;
     /**
      * Renders the group in a read-only state (no asterisk symbol).
      * Use `'locked'` when the control is read-only due to permissions.
@@ -56,6 +62,6 @@ export type IressFieldProps<E extends 'div' | 'fieldset' = 'div', ELabel extends
     supplementary?: ReactNode;
 };
 export declare const IressField: {
-    ({ children, className, "data-testid": dataTestId, error, errorMessages, hiddenLabel, hint, horizontal, label, labelWidth, required, readOnly, removeErrorMargin, supplementary, ...restProps }: IressFieldProps): import("react/jsx-runtime").JSX.Element;
+    ({ children, className, "data-testid": dataTestId, error, errorId, errorMessages, hiddenLabel, hint, horizontal, label, labelWidth, required, readOnly, removeErrorMargin, supplementary, ...restProps }: IressFieldProps): import("react/jsx-runtime").JSX.Element;
     displayName: string;
 };

package/dist/components/Field/Field.js

@@ -12,57 +12,58 @@ import { FieldHint as u } from "./components/FieldHint.js";
 import { isValidElement as d } from "react";
 import { jsx as f, jsxs as p } from "react/jsx-runtime";
 //#region src/components/Field/Field.tsx
-var m = ({ children: m, className: h, "data-testid": g, error: _, errorMessages: v, hiddenLabel: y, hint: b, horizontal: x, label: S, labelWidth: C, required: w, readOnly: T, removeErrorMargin: E = !1, supplementary: D, ...O }) => {
-	let { htmlFor: k } = O, A;
-	A = k === void 0 && d(m) ? o(m)[0].props.id : k;
-	let j = c.raw({
-		hasError: !!_ || !!v?.length,
-		hasHint: !!b,
-		hiddenLabel: y,
-		horizontal: x,
+var m = ({ children: m, className: h, "data-testid": g, error: _, errorId: v, errorMessages: y, hiddenLabel: b, hint: x, horizontal: S, label: C, labelWidth: w, required: T, readOnly: E, removeErrorMargin: D = !1, supplementary: O, ...k }) => {
+	let { htmlFor: A } = k, j;
+	j = A === void 0 && d(m) ? o(m)[0].props.id : A;
+	let M = !!_ || !!y?.length, N = v ?? (M && j ? `${j}-error` : void 0), P = c.raw({
+		hasError: M,
+		hasHint: !!x,
+		hiddenLabel: b,
+		horizontal: S,
 		multipleFields: !1,
-		removeErrorMargin: E
-	}), [M, N] = n(O), P = !!T, F = () => {
+		removeErrorMargin: D
+	}), [F, I] = n(k), L = !!E, R = () => {
 		let t = /* @__PURE__ */ f(s, {
-			className: e(j.label),
+			className: e(P.label),
 			"data-testid": a(g, "label"),
-			hiddenLabel: y,
-			htmlFor: A,
-			readOnly: T,
-			required: !P && !!w,
-			children: S
+			hiddenLabel: b,
+			htmlFor: j,
+			readOnly: E,
+			required: !L && !!T,
+			children: C
 		});
-		return b ? /* @__PURE__ */ f(u, {
-			hint: b,
-			horizontal: x,
-			hiddenLabel: y,
+		return x ? /* @__PURE__ */ f(u, {
+			hint: x,
+			horizontal: S,
+			hiddenLabel: b,
 			dataTestId: g,
 			children: t
 		}) : t;
 	};
 	return /* @__PURE__ */ p(r.div, {
-		className: t(h, e(j.root, M), i.Field),
-		style: { ...x && C && { gridTemplateColumns: `${C} 1fr` } },
+		className: t(h, e(P.root, F), i.Field),
+		style: { ...S && w && { gridTemplateColumns: `${w} 1fr` } },
 		"data-testid": g,
-		...N,
+		...I,
 		children: [
 			/* @__PURE__ */ f(r.div, {
-				className: e(j.labelContainer),
-				children: F()
+				className: e(P.labelContainer),
+				children: R()
 			}),
 			/* @__PURE__ */ f(r.div, {
-				className: e(j.fieldContainer),
+				className: e(P.fieldContainer),
 				children: /* @__PURE__ */ f("div", {
-					className: e(j.element),
+					className: e(P.element),
 					children: m
 				})
 			}),
 			/* @__PURE__ */ f(l, {
-				className: e(j.footer),
+				className: e(P.footer),
 				"data-testid": a(g, "error"),
 				error: _,
-				errorMessages: v,
-				supplementary: D
+				errorId: N,
+				errorMessages: y,
+				supplementary: O
 			})
 		]
 	});

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

@@ -6,6 +6,10 @@ export interface FieldFooterProps extends IressStyledProps {
      * Validation error to be displayed above the field.
      */
     error?: ReactNode;
+    /**
+     * ID for the error container element, used to associate the error message with the form control via `aria-describedby`.
+     */
+    errorId?: string;
     /**
      * Validation errors to be displayed above the field, an array of validation messages to be displayed in `IressValidationSummary`.
      */
@@ -20,6 +24,6 @@ export interface FieldFooterProps extends IressStyledProps {
     supplementary?: ReactNode;
 }
 export declare const FieldFooter: {
-    ({ className, "data-testid": dataTestId, error, errorMessages, multipleFields, supplementary, ...restProps }: FieldFooterProps): import("react/jsx-runtime").JSX.Element | null;
+    ({ className, "data-testid": dataTestId, error, errorId, errorMessages, multipleFields, supplementary, ...restProps }: FieldFooterProps): import("react/jsx-runtime").JSX.Element | null;
     displayName: string;
 };

package/dist/components/Field/components/FieldFooter.js

@@ -12,31 +12,32 @@ import { jsx as d, jsxs as f } from "react/jsx-runtime";
 var p = (e) => /* @__PURE__ */ d(r, {
 	name: "cancel",
 	...e
-}), m = ({ className: r, "data-testid": m, error: h, errorMessages: g = [], multipleFields: _, supplementary: v, ...y }) => {
-	let b = a({ multipleFields: _ }), x = u(null), S = u(null), C = l(() => !!h || g.length > 0, [h, g.length]);
+}), m = ({ className: r, "data-testid": m, error: h, errorId: g, errorMessages: _ = [], multipleFields: v, supplementary: y, ...b }) => {
+	let x = a({ multipleFields: v }), S = u(null), C = u(null), w = l(() => !!h || _.length > 0, [h, _.length]);
 	return c(() => {
-		if (!x.current || S.current === C) {
-			S.current = C;
+		if (!S.current || C.current === w) {
+			C.current = w;
 			return;
 		}
-		x.current.classList.remove(e({ animationStyle: "field-footer" })), x.current.offsetHeight, S.current = C, x.current.classList.add(e({ animationStyle: "field-footer" }));
-	}, [C]), !v && !C ? null : /* @__PURE__ */ f(n.div, {
-		...y,
-		className: t(r, b.footer),
-		ref: x,
-		children: [C && /* @__PURE__ */ d(s, {
+		S.current.classList.remove(e({ animationStyle: "field-footer" })), S.current.offsetHeight, C.current = w, S.current.classList.add(e({ animationStyle: "field-footer" }));
+	}, [w]), !y && !w ? null : /* @__PURE__ */ f(n.div, {
+		...b,
+		className: t(r, x.footer),
+		ref: S,
+		children: [w && /* @__PURE__ */ d(s, {
+			id: g,
 			itemStyle: { textStyle: "typography.body.sm" },
-			messages: o(g, "message"),
+			messages: o(_, "message"),
 			"data-testid": m,
 			prefix: /* @__PURE__ */ d(p, {
 				"aria-label": "Error: ",
-				className: b.footerIcon
+				className: x.footerIcon
 			}),
 			visiblePrefix: !0,
 			children: h
-		}), !C && /* @__PURE__ */ d(i, {
-			className: b.supplementary,
-			children: v
+		}), !w && /* @__PURE__ */ d(i, {
+			className: x.supplementary,
+			children: y
 		})]
 	});
 };

package/dist/components/Select/Select.js

@@ -1,2 +1,2 @@
-import { n as e } from "../../Autocomplete-CzdfUGYJ.js";
+import { n as e } from "../../Autocomplete-ZqkibVwt.js";
 export { e as IressSelect };

package/dist/components/Select/components/NativeSelect.js

@@ -29,7 +29,7 @@ var f = l(({ className: l, "data-testid": f, options: p, onChange: m, placeholde
 				m?.(e, t);
 			},
 			ref: b,
-			value: o(_?.value ?? _?.label),
+			value: o(_?.value ?? _?.label) ?? "",
 			children: [h !== void 0 && /* @__PURE__ */ u("option", {
 				value: "",
 				children: h

package/dist/components/Select/index.js

@@ -6,7 +6,7 @@ import { IressSelectHeading as i } from "./SelectHeading/SelectHeading.js";
 import { IressSelectMenu as a } from "./SelectMenu/SelectMenu.js";
 import { IressSelectSearchInput as o } from "./SelectSearchInput/SelectSearchInput.js";
 import { nativeSelect as s } from "./components/NativeSelect.styles.js";
-import { n as c } from "../../Autocomplete-CzdfUGYJ.js";
+import { n as c } from "../../Autocomplete-ZqkibVwt.js";
 import { IressSelectBody as l } from "./SelectBody/SelectBody.js";
 import { IressSelectCreate as u } from "./SelectCreate/SelectCreate.js";
 export { c as IressSelect, l as IressSelectBody, u as IressSelectCreate, i as IressSelectHeading, t as IressSelectLabel, a as IressSelectMenu, r as IressSelectSearch, o as IressSelectSearchInput, n as IressSelectTags, s as nativeSelect, e as select };

package/dist/main.js

@@ -66,7 +66,7 @@ import { IressSelectHeading as Ae } from "./components/Select/SelectHeading/Sele
 import { IressSelectMenu as je } from "./components/Select/SelectMenu/SelectMenu.js";
 import { IressSelectSearchInput as Me } from "./components/Select/SelectSearchInput/SelectSearchInput.js";
 import { nativeSelect as Ne } from "./components/Select/components/NativeSelect.styles.js";
-import { n as Pe, t as Fe } from "./Autocomplete-CzdfUGYJ.js";
+import { n as Pe, t as Fe } from "./Autocomplete-ZqkibVwt.js";
 import { IressSelectBody as Ie } from "./components/Select/SelectBody/SelectBody.js";
 import { IressSelectCreate as Le } from "./components/Select/SelectCreate/SelectCreate.js";
 import { avatar as Re } from "./components/Avatar/Avatar.styles.js";

package/dist/patterns/Form/FormField/FormField.d.ts

@@ -55,6 +55,15 @@ export interface FormFieldRenderProps<T extends FieldValues> extends ControllerR
      * ID of the field. It is automatically generated based on the name of the field and its parent form.
      */
     id: string;
+    /**
+     * References the ID of the error message container when the field has a validation error,
+     * so that assistive technologies can associate the error with the control.
+     */
+    'aria-describedby'?: string;
+    /**
+     * Set to `true` when the field has a validation error, indicating an invalid state to assistive technologies.
+     */
+    'aria-invalid'?: boolean;
 }
 /**
  * Props for the `IressFormField` `render` prop, second argument.

package/dist/patterns/Form/FormField/FormField.js

@@ -27,21 +27,26 @@ var f = ({ control: f, defaultValue: p, name: m, render: h, renderSupplementary:
 		m,
 		b
 	]);
-	let O = {
-		...i(w),
-		id: `${S.id}__${m}`
-	}, k = {
+	let O = i(w), k = `${S.id}__${m}-error`, A = !!D && !b, j = {
+		...O,
+		id: `${S.id}__${m}`,
+		...A ? {
+			"aria-describedby": k,
+			"aria-invalid": !0
+		} : {}
+	}, M = {
 		formState: T,
 		fieldState: E
 	};
 	return /* @__PURE__ */ l(t, {
-		errorMessages: D && !b ? [{ message: D }] : void 0,
+		errorMessages: A ? [{ message: D }] : void 0,
 		htmlFor: `${S.id}__${m}`,
 		readOnly: b,
 		required: !!C?.required,
-		supplementary: /* @__PURE__ */ u(c, { children: [g?.(O, k), y] }),
+		supplementary: /* @__PURE__ */ u(c, { children: [g?.(j, M), y] }),
 		...x,
-		children: h(O, k)
+		errorId: k,
+		children: h(j, M)
 	});
 };
 f.displayName = "IressFormField";

package/dist/patterns/Form/FormValidationSummary/FormValidationSummary.d.ts

@@ -13,6 +13,6 @@ export type IressFormValidationSummaryProps = Omit<IressValidationSummaryProps,
  * Validation summary messages based on the form context from react-hook-form
  */
 export declare const IressFormValidationSummary: {
-    ({ actions, children, "data-testid": testId, footer, heading, itemStyle, icon, srOnly, variant, ...restProps }: IressFormValidationSummaryProps): import("react/jsx-runtime").JSX.Element;
+    ({ actions, children, "data-testid": testId, footer, heading, itemStyle, icon, srOnly, variant, role, "aria-live": ariaLive, ...restProps }: IressFormValidationSummaryProps): import("react/jsx-runtime").JSX.Element;
     displayName: string;
 };

package/dist/patterns/Form/FormValidationSummary/FormValidationSummary.js

@@ -13,27 +13,31 @@ var c = e("div", { base: {
 } }, { defaultProps: {
 	role: "alert",
 	tabIndex: -1
-} }), l = ({ actions: e, children: l, "data-testid": u, footer: d, heading: f = /* @__PURE__ */ s("h3", { children: "There was a problem submitting this form" }), itemStyle: p, icon: m, srOnly: h, variant: g, ..._ }) => {
-	let v = o(r);
-	if (!v) throw Error("IressFormValidationSummary must be used within a IressForm");
-	let y = Object.entries(v.errorMessages).filter(([, e]) => !!e);
-	if (y.length === 0 || l) return /* @__PURE__ */ s(c, {
+} }), l = ({ actions: e, children: l, "data-testid": u, footer: d, heading: f = /* @__PURE__ */ s("h3", { children: "There was a problem submitting this form" }), itemStyle: p, icon: m, srOnly: h, variant: g, role: _, "aria-live": v, ...y }) => {
+	let b = o(r);
+	if (!b) throw Error("IressFormValidationSummary must be used within a IressForm");
+	let x = Object.entries(b.errorMessages).filter(([, e]) => !!e);
+	if (x.length === 0 || l) return /* @__PURE__ */ s(c, {
 		"data-testid": u,
 		srOnly: h,
-		ref: v.setFocusOnError,
+		ref: b.setFocusOnError,
+		..._ !== void 0 && { role: _ },
+		...v !== void 0 && { "aria-live": v },
 		children: l
 	});
-	let b = y.map(([e, t]) => {
-		let n = `${v?.id}__${e}`, r = document.getElementById(n), i = r?.labels, o = Array.from(i ?? []), s = r?.closest("fieldset")?.querySelector("legend");
+	let S = x.map(([e, t]) => {
+		let n = `${b?.id}__${e}`, r = document.getElementById(n), i = r?.labels, o = Array.from(i ?? []), s = r?.closest("fieldset")?.querySelector("legend");
 		return {
 			linkToTarget: n,
 			message: `${`${o[0]?.dataset?.name ?? s?.dataset?.name ?? a(e)}: `}${t}`
 		};
 	});
 	return /* @__PURE__ */ s(c, {
-		ref: v.setFocusOnError,
+		ref: b.setFocusOnError,
 		"data-testid": u,
 		srOnly: h,
+		..._ !== void 0 && { role: _ },
+		...v !== void 0 && { "aria-live": v },
 		children: /* @__PURE__ */ s(n, {
 			actions: e,
 			footer: d,
@@ -44,13 +48,13 @@ var c = e("div", { base: {
 			variant: g,
 			multiLine: !0,
 			children: /* @__PURE__ */ s(i, {
-				..._,
+				...y,
 				"data-testid": t(u, "messages"),
 				itemStyle: {
 					"data-testid": t(u, "error"),
 					...p
 				},
-				messages: b
+				messages: S
 			})
 		})
 	});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iress-oss/ids-components",
-  "version": "6.2.2",
+  "version": "6.3.0",
   "description": "Iress React Component Library",
   "license": "Apache-2.0",
   "type": "module",