@iress-oss/ids-components 6.2.2 → 6.4.0

package/.ai/components/modal.md

@@ -148,7 +148,12 @@ When `status` is set:
 
 ### Disable closing
 
-For instances where you require the user's full attention and you want to ensure they continue the current task before closing the modal, you can disable the backdrop and escape key using `disableBackdropClick` and/or hide the close button using `noCloseButton`.
+For instances where you require the user's full attention and you want to
+ensure they continue the current task before closing the modal, you can use
+`disableBackdropClick={true}` to disable backdrop clicks while still allowing
+Escape key dismissal. If you need to disable both backdrop clicks and Escape
+dismissal, set `disableBackdropClick="no-esc"`. You can also hide the close
+button using `noCloseButton`.
 
 **Note:** As these options remove the default handling of the closing the modal, please ensure you provide a clear way for the user to close the modal.
 

package/.ai/components/select.md

@@ -79,6 +79,28 @@ The user experience slightly changes as well. Instead of displaying the options
 
 No filtering is done for asynchronous options, you must filter the options yourself using the query. However, the results are automatically highlighted based on the query when rendered in the UI.
 
+If you need to constrain or annotate the visible search field, use
+`searchInputProps` to pass supported passive input props to the internal async
+search input. This is useful for cases such as enforcing a maximum query length
+without recreating the built-in search UI via `renderOptions`.
+
+Supported `searchInputProps` keys are:
+`className`, `data-testid`, `inputMode`, `maxLength`, `minLength`, `pattern`,
+and `spellCheck`.
+
+Do not use `searchInputProps` for interactive or controlled input behaviour
+such as `value`, `onChange`, `placeholder`, `aria-label`, `disabled`,
+`readOnly`, or refs. `IressSelect` keeps the async combobox query state,
+placeholder text, and accessibility labelling under its own control. Only use
+`renderOptions` when you need to replace the full built-in async options UI.
+
+```tsx
+<IressSelect
+  options={searchOptions}
+  searchInputProps={{ maxLength: 100 }}
+/>
+```
+
 ```tsx
 <SelectAsync />
 ```

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/.ai/skills/ui-translation.md

@@ -28,7 +28,7 @@ Translate natural language UI descriptions into IDS (Iress Design System) compon
 | Description              | IDS Component                       | Example                                                                                                                        |
 | ------------------------ | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
 | Labelled text input      | `IressField` + `IressInput`         | See Form example below                                                                                                         |
-| Select dropdown (static or async) | `IressField` + `IressSelect` | `<IressField label="Country"><IressSelect>...</IressSelect></IressField>` — supports static options and async loading via an `options` function |
+| Select dropdown (static or async) | `IressField` + `IressSelect` | `<IressField label="Country"><IressSelect>...</IressSelect></IressField>` — supports static options and async loading via an `options` function. For async search field constraints or annotations, prefer `searchInputProps` (`className`, `data-testid`, `inputMode`, `maxLength`, `minLength`, `pattern`, `spellCheck`) instead of rebuilding the UI with `renderOptions`. |
 | Freetext input with suggestions  | `IressField` + `IressAutocomplete` | `<IressField label="Search"><IressAutocomplete /></IressField>` — allows any text input; suggestions are optional |
 | Currency input           | `IressField` + `IressInputCurrency` | `<IressField label="Amount"><IressInputCurrency /></IressField>`                                                               |
 | Checkbox                 | `IressCheckbox`                     | `<IressCheckbox value="agree">I agree</IressCheckbox>`                                                                         |
@@ -40,7 +40,7 @@ Translate natural language UI descriptions into IDS (Iress Design System) compon
 
 ### Select vs Autocomplete Decision Guide
 
-- **Need to restrict to valid options?** → `IressSelect` — supports static options and async loading via an `options` function. Use this for most selection use cases. Always read the component doc to understand filtering behaviour for your use case.
+- **Need to restrict to valid options?** → `IressSelect` — supports static options and async loading via an `options` function. For async selects, `searchInputProps` is only for safe passive search-input attributes; `IressSelect` still controls query state, placeholder text, and accessibility labels. Use this for most selection use cases. Always read the component doc to understand filtering behaviour for your use case.
 - **Need freetext with optional suggestions?** → `IressAutocomplete` — allows any text input; suggestions are offered but not enforced.
 
 ## Layout
@@ -189,7 +189,7 @@ When you need to find the right IDS component for a UI element, read references/
 | Description              | IDS Component                       | Example                                                                                                                        |
 | ------------------------ | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
 | Labelled text input      | `IressField` + `IressInput`         | See Form example below                                                                                                         |
-| Select dropdown (static or async) | `IressField` + `IressSelect` | `<IressField label="Country"><IressSelect>...</IressSelect></IressField>` — supports static options and async loading via an `options` function |
+| Select dropdown (static or async) | `IressField` + `IressSelect` | `<IressField label="Country"><IressSelect>...</IressSelect></IressField>` — supports static options and async loading via an `options` function. For async search field constraints or annotations, prefer `searchInputProps` (`className`, `data-testid`, `inputMode`, `maxLength`, `minLength`, `pattern`, `spellCheck`) instead of rebuilding the UI with `renderOptions`. |
 | Freetext input with suggestions  | `IressField` + `IressAutocomplete` | `<IressField label="Search"><IressAutocomplete /></IressField>` — allows any text input; suggestions are optional |
 | Currency input           | `IressField` + `IressInputCurrency` | `<IressField label="Amount"><IressInputCurrency /></IressField>`                                                               |
 | Checkbox                 | `IressCheckbox`                     | `<IressCheckbox value="agree">I agree</IressCheckbox>`                                                                         |
@@ -201,7 +201,7 @@ When you need to find the right IDS component for a UI element, read references/
 
 ### Select vs Autocomplete Decision Guide
 
-- **Need to restrict to valid options?** → `IressSelect` — supports static options and async loading via an `options` function. Use this for most selection use cases. Always read the component doc to understand filtering behaviour for your use case.
+- **Need to restrict to valid options?** → `IressSelect` — supports static options and async loading via an `options` function. For async selects, `searchInputProps` is only for safe passive search-input attributes; `IressSelect` still controls query state, placeholder text, and accessibility labels. Use this for most selection use cases. Always read the component doc to understand filtering behaviour for your use case.
 - **Need freetext with optional suggestions?** → `IressAutocomplete` — allows any text input; suggestions are offered but not enforced.
 
 ## Layout

package/dist/Autocomplete-CfNw4UXr.js

@@ -0,0 +1,328 @@
+import { t as e } from "./cx-QcEwjve6.js";
+import { GlobalCSSClass as t } from "./enums.js";
+import { idsLogger as n } from "./helpers/utility/idsLogger.js";
+import { IressIcon as r } from "./components/Icon/Icon.js";
+import { IressText as i } from "./components/Text/Text.js";
+import { propagateTestid as a } from "./helpers/utility/propagateTestid.js";
+import { IressSpinner as o } from "./components/Spinner/Spinner.js";
+import { toArray as s } from "./helpers/formatting/toArray.js";
+import { useControlledState as ee } from "./hooks/useControlledState.js";
+import { useResponsiveProps as te } from "./hooks/useResponsiveProps.js";
+import { IressPopover as c } from "./components/Popover/Popover.js";
+import { IressInputPopover as ne } from "./components/Popover/InputPopover/InputPopover.js";
+import { IressAlert as re } from "./components/Alert/Alert.js";
+import { autoComplete as l } from "./components/Autocomplete/Autocomplete.styles.js";
+import { getFormControlValueAsStringIfDefined as ie } from "./helpers/form/getFormControlValueAsStringIfDefined.js";
+import { useNoDefaultValueInForms as ae } from "./patterns/Form/hooks/useNoDefaultValueInForms.js";
+import { IressReadonly as oe } from "./components/Readonly/Readonly.js";
+import { IressInput as u } from "./components/Input/Input.js";
+import { getValueAsEvent as se } from "./helpers/form/getValueAsEvent.js";
+import { t as ce } from "./useAutocompleteSearch-m33c4lI7.js";
+import { AutocompleteInstructions as d } from "./components/Autocomplete/components/AutocompleteInstructions.js";
+import { select as f } from "./components/Select/Select.styles.js";
+import { IressInline as p } from "./components/Inline/Inline.js";
+import { SelectActivator as le } from "./components/Select/components/SelectActivator.js";
+import { IressSelectMenu as m } from "./components/Select/SelectMenu/SelectMenu.js";
+import { SelectOptions as h } from "./components/Select/components/SelectOptions.js";
+import { SelectHiddenInput as ue } from "./components/Select/components/SelectHiddenInput.js";
+import { NativeSelect as de } from "./components/Select/components/NativeSelect.js";
+import { useSelectState as fe } from "./components/Select/hooks/useSelectState.js";
+import { forwardRef as g, useCallback as pe, useEffect as _, useImperativeHandle as me, useMemo as v, useRef as y, useState as b } from "react";
+import { Fragment as he, jsx as x, jsxs as S } from "react/jsx-runtime";
+//#region src/components/Select/Select.tsx
+var C = (e) => typeof e == "object" && !!e && "label" in e, w = (e, t) => {
+	for (let n of t) if (n.children) {
+		let t = w(e, n.children);
+		if (t) return t;
+	} else if (n.value !== void 0 && n.value === e) return n;
+}, T = (e, t) => {
+	if (C(e)) return e;
+	if (typeof t != "function") return w(e, t) ?? (typeof e == "number" ? w(String(e), t) : void 0);
+}, E = (e, t) => {
+	if (e !== void 0) {
+		if (Array.isArray(e)) {
+			let r = e, i = r.map((e) => T(e, t)).filter((e) => e !== void 0);
+			return i.length < r.length && typeof t != "function" && n(`IressSelect: ${r.length - i.length} value(s) could not be resolved to matching options and were dropped.`, "warn"), i;
+		}
+		return T(e, t);
+	}
+}, D = g(({ align: r = "bottom-start", autoHighlight: i = !0, className: a, defaultValue: o, disabled: s, errorText: ee, footer: ne, header: re, id: l, matchActivatorWidth: ie = !0, multiSelect: u, multiSelectLimit: se, name: d, onChange: p, onBlur: m, options: g, native: w, placeholder: T, readOnly: D, renderHiddenInput: O, renderLabel: ge, renderOptions: _e, searchInputProps: k, required: A, type: ve, value: j, virtualFocus: ye, width: M, ...N }, P) => {
+	ae({
+		component: "IressSelect",
+		defaultValue: o
+	});
+	let [F, I] = b(!1), L = F && !s, [R, be] = b(""), z = v(() => E(j, g), [j, g]), B = v(() => E(o, g), [o, g]);
+	_(() => {
+		j !== void 0 && !C(j) && z === void 0 && typeof g == "function" && n("IressSelect: A primitive value was passed but cannot be resolved because options are asynchronous. Pass a LabelValueMeta object instead when using async options, otherwise the component will behave as uncontrolled.", "warn");
+	}, [
+		j,
+		z,
+		g
+	]);
+	let { value: V, setValue: H, getValuesString: U, getLabelsString: W } = fe({
+		component: "IressSelect",
+		defaultValue: B,
+		multiple: u,
+		value: z
+	}), G = y(null), K = y(null), q = y(null), { value: J } = te(typeof w == "string" ? {
+		xs: !0,
+		[w]: !1
+	} : { xs: w }, { disabled: !w }), { append: xe, container: Y, debounceThreshold: Se, initialOptions: X, loadingDelay: Ce, minSearchLength: we, onActivated: Te, onDeactivated: Ee, prepend: De, selectedOptionsText: Oe, ...Z } = N, { debouncedQuery: ke, error: Ae, results: je, stopSearch: Me, loading: Ne, shouldShowInstructions: Pe, shouldShowNoResults: Fe } = ce({
+		debounceThreshold: Se,
+		disabled: !F || !!J,
+		initialOptions: X,
+		loadingDelay: Ce,
+		minSearchLength: we,
+		options: g,
+		query: R
+	});
+	me(P, () => J ? {
+		focus: () => K.current?.focus(),
+		blur: () => K.current?.blur(),
+		input: K.current ?? null
+	} : G.current ? {
+		...G.current,
+		focus: () => G.current?.getActivator()?.focus(),
+		blur: () => G.current?.getActivator()?.blur(),
+		hiddenInput: q.current ?? void 0,
+		input: q.current ?? null
+	} : {
+		hiddenInput: q.current ?? void 0,
+		input: q.current ?? null,
+		focus: () => q.current?.focus(),
+		blur: () => q.current?.blur()
+	}, [J]), _(() => {
+		F ? Te?.() : Ee?.();
+	}, [
+		Te,
+		Ee,
+		F
+	]);
+	let Ie = pe((e) => {
+		if (!m) return;
+		let t = e.currentTarget, n = e.relatedTarget;
+		!F && (!n || !t.contains(n)) && m(e), e.stopPropagation();
+	}, [m, F]);
+	if (D) return /* @__PURE__ */ x(oe, {
+		value: U(),
+		ref: q,
+		variant: D,
+		name: d,
+		disabled: s,
+		required: A,
+		children: W(", ")
+	});
+	if (J) {
+		if (g instanceof Function) throw Error("[IressSelect] The native select does not support asynchronous options. Please provide options as an array.");
+		if (u) throw Error("[IressSelect] The native select does not support multiple selection. Please remove the multiSelect prop or use the non-native select.");
+		return /* @__PURE__ */ x(de, {
+			className: e(a, t.Select),
+			"data-testid": Z["data-testid"],
+			disabled: s,
+			id: l,
+			name: d,
+			onBlur: m,
+			onChange: (e, t) => {
+				p?.(e, t?.value ?? null, t), H(t);
+			},
+			options: g,
+			placeholder: typeof w == "string" ? T ?? "" : T,
+			style: Z.style,
+			value: V,
+			width: M,
+			ref: K
+		});
+	}
+	let Q = typeof g == "function", Le = ye ?? !Q, Re = ve ?? (Q ? void 0 : "listbox"), $ = f({ width: M }), ze = () => {
+		I(!0);
+	}, Be = () => {
+		I(!1), Me();
+	};
+	return /* @__PURE__ */ S(he, { children: [/* @__PURE__ */ x(ue, {
+		"data-testid": Z["data-testid"],
+		getValuesString: U,
+		name: d,
+		renderHiddenInput: O,
+		required: A,
+		value: V,
+		disabled: s,
+		ref: q
+	}), /* @__PURE__ */ x(c, {
+		...Z,
+		activator: /* @__PURE__ */ x(le, {
+			append: xe,
+			async: Q,
+			disabled: s,
+			error: Ae,
+			id: l,
+			loading: Ne,
+			multiSelect: u,
+			multiSelectLimit: se,
+			onChange: p,
+			placeholder: T,
+			popoverContainer: Y,
+			prepend: De,
+			renderLabel: ge,
+			selectedOptionsText: Oe,
+			setValue: H,
+			setShow: I,
+			show: F,
+			value: V
+		}),
+		align: r,
+		className: e(a, $.root, t.Select),
+		container: Y,
+		contentClassName: e($.popoverContent),
+		contentStyle: {
+			...Z.contentStyle,
+			p: "none"
+		},
+		matchActivatorWidth: ie,
+		onActivated: ze,
+		onDeactivated: Be,
+		ref: G,
+		show: L,
+		type: Re,
+		virtualFocus: Le,
+		onBlur: Ie,
+		children: /* @__PURE__ */ S("div", {
+			className: $.wrapper,
+			children: [
+				re,
+				/* @__PURE__ */ x(h, {
+					autoHighlight: i,
+					debouncedQuery: ke,
+					error: Ae,
+					errorText: ee,
+					initialOptions: X,
+					loading: Ne,
+					minSearchLength: we,
+					multiSelect: u,
+					onChange: p,
+					options: g,
+					query: R,
+					renderOptions: _e,
+					results: je,
+					searchInputProps: k,
+					setQuery: be,
+					setShow: I,
+					setValue: H,
+					shouldShowInstructions: Pe,
+					shouldShowNoResults: Fe,
+					show: L,
+					value: V
+				}),
+				ne
+			]
+		})
+	})] });
+});
+D.displayName = "IressSelect";
+//#endregion
+//#region src/components/Autocomplete/Autocomplete.tsx
+var O = g(({ alwaysShowOnFocus: n, append: te = /* @__PURE__ */ x(r, { name: "search" }), autoComplete: c = "off", autoSelect: ae = !0, className: f, clearable: le = !0, "data-testid": h, debounceThreshold: ue, defaultValue: de, errorText: fe = /* @__PURE__ */ x(re, {
+	status: "danger",
+	mb: "none",
+	variant: "full-width",
+	children: "An unknown error occurred. Please contact support if the error persists."
+}), initialOptions: g, loadingDelay: pe, limitDesktop: me = 12, limitMobile: v = 6, minSearchLength: y, noResultsText: C, onChange: w, onClear: T, onFocus: E, options: D, popoverProps: { autoHighlight: O = !1, append: ge, prepend: _e, ...k } = {}, readOnly: A, value: ve, ...j }, ye) => {
+	let [M, N] = b(!1), { value: P, setValue: F } = ee({
+		component: "IressAutocomplete",
+		defaultValue: de,
+		value: ve
+	}), [I, L] = b(!1), { clearError: R, debouncedQuery: be, error: z, loading: B, results: V, startSearch: H, stopSearch: U, shouldShowInstructions: W, shouldShowNoResults: G } = ce({
+		debounceThreshold: ue,
+		initialOptions: g,
+		loadingDelay: pe,
+		minSearchLength: y,
+		options: D,
+		query: ie(P)
+	});
+	if (_(() => {
+		I && !M && V.length > 0 && P && N(!0);
+	}, [
+		V.length,
+		M,
+		I,
+		P
+	]), _(() => {
+		B && I && N(!0);
+	}, [B, I]), _(() => {
+		z && N(!0);
+	}, [z]), A) return /* @__PURE__ */ x(oe, {
+		value: P,
+		variant: A
+	});
+	let K = (e, t) => {
+		w?.(e, t), F(t), L(!!t);
+	}, q = (e) => {
+		T?.(e), F("");
+	}, J = (e) => {
+		E?.(e), g?.length && N(!0);
+	}, xe = (e) => {
+		let t = s(e)?.[0];
+		w?.(se(t?.label), t?.label, t), F(t?.label), N(!1), L(!1);
+	}, Y = () => {
+		(!n || !P) && U(), R(), N(!1), P && L(!1);
+	}, Se = (e) => {
+		j.onKeyDown?.(e), e.key === "ArrowDown" && (!M || !I) && (V.length || H(!0), L(!0), N(!0));
+	}, X = l({ isEmpty: V.length === 0 && !B && !z && !W && !G });
+	return /* @__PURE__ */ S(ne, {
+		...k,
+		activator: /* @__PURE__ */ x(u, {
+			...j,
+			append: te,
+			autoComplete: c,
+			clearable: le,
+			"data-testid": a(h, "input"),
+			onChange: K,
+			onClear: q,
+			onFocus: J,
+			onKeyDown: Se,
+			value: P,
+			ref: ye
+		}),
+		autoHighlight: O,
+		className: e(f, k.className, X.root, t.Autocomplete),
+		contentClassName: e(k.contentClassName, X.popoverContent),
+		contentStyle: k.contentStyle,
+		"data-testid": h,
+		minLength: 0,
+		onActivated: () => (I || n) && N(!0),
+		onDeactivated: Y,
+		show: M,
+		type: "listbox",
+		focusStartIndex: 0,
+		children: [
+			B && !V.length && /* @__PURE__ */ S(p, {
+				gap: "sm",
+				verticalAlign: "middle",
+				p: "spacing.3",
+				children: [/* @__PURE__ */ x(o, { color: "colour.neutral.70" }), /* @__PURE__ */ x(i, {
+					color: "colour.neutral.70",
+					children: "Loading results..."
+				})]
+			}),
+			V.length > 0 && /* @__PURE__ */ S(he, { children: [
+				_e,
+				/* @__PURE__ */ x(m, {
+					changeOnBlur: ae,
+					className: e(X.optionList),
+					"data-testid": a(h, "menu"),
+					items: V,
+					limitDesktop: me,
+					limitMobile: v,
+					onChange: xe,
+					selected: { label: be }
+				}),
+				ge
+			] }),
+			z && fe,
+			W && !z && /* @__PURE__ */ x(d, { minSearchLength: y ?? 1 }),
+			G && !z && C
+		]
+	});
+});
+O.displayName = "IressAutocomplete";
+//#endregion
+export { D as n, O as t };

package/dist/{Button-BY2qzshw.js → Button-x1_YRAyD.js}

@@ -1,9 +1,9 @@
-import { a as e, f as t, l as n, s as r, t as i } from "./css-R34N3rft.js";
+import { a as e, f as t, l as n, s as r, t as i } from "./css-BRrgGHqo.js";
 import { t as a } from "./cx-QcEwjve6.js";
-import { n as o } from "./is-valid-prop-BVyYPT21.js";
+import { n as o } from "./is-valid-prop-CvqUuuBB.js";
 import { GlobalCSSClass as s } from "./enums.js";
 import { IressIcon as c } from "./components/Icon/Icon.js";
-import { t as l } from "./create-recipe-A316lnq3.js";
+import { t as l } from "./create-recipe-BWTPSpll.js";
 import { IressSpinner as u } from "./components/Spinner/Spinner.js";
 import { useButtonGroupItem as d } from "./components/ButtonGroup/hooks/useButtonGroupItem.js";
 import { usePopover as f } from "./components/Popover/hooks/usePopover.js";