@iress-oss/ids-components 6.0.0-alpha.41 → 6.0.0-alpha.43

package/.ai/components/alert.md

@@ -15,10 +15,21 @@ import { IressAlert } from '@iress-oss/ids-components';
 </IressAlert>
 ```
 
-import {
-  ComponentOverview,
-  ComponentExample,
-} from '@iress-oss/ids-storybook-config';
+## Usage
+
+### When to use
+
+- **Form validation**: Display errors or warnings near the relevant form section
+- **Page-level status**: Inform users about the state of the current page (e.g. "This record is read-only")
+- **Informational banners**: Provide tips, guidance, or announcements inline with content
+- **Persistent warnings**: Messages that should remain visible until the condition changes
+
+### When not to use
+
+- **Transient confirmations** of completed actions (e.g. "Saved") — use [IressToaster](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-toaster--docs) instead
+- **Tasks requiring user decisions** before continuing — use [IressModal](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-modal--docs) instead
+
+For a full comparison of feedback components, see the [Feedback pattern](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_patterns-feedback--docs).
 
 ## Examples
 

package/.ai/components/autocomplete-recipes.md

@@ -2,14 +2,8 @@
 
 Autocomplete component documentation.
 
-> **Component:** `@iress-oss/ids-components`
 > **Storybook:** [Recipes in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-autocomplete--docs)
 
-import {
-  ComponentExample,
-  ComponentApi,
-} from '@iress-oss/ids-storybook-config';
-
 > [!NOTE]
 > **Experimental**
 >

package/.ai/components/autocomplete.md

@@ -13,11 +13,6 @@ import { IressAutocomplete } from '@iress-oss/ids-components';
 <IressAutocomplete />
 ```
 
-import {
-  ComponentOverview,
-  ComponentExample,
-} from '@iress-oss/ids-storybook-config';
-
 ## Usage
 
 The `IressAutocomplete` element extends `IressInput` with additional functionality to provide suggestions to the user as they type.
@@ -263,6 +258,7 @@ We recommend using [Mock Service Worker](https://mswjs.io/) to mock the API call
 
 ```tsx
 // src/mocks/handlers.ts
+import { http, HttpResponse } from 'msw';
 
 export const handlers = [
   // Intercept "GET https://swapi.py4e.com/api/people" requests...
@@ -276,10 +272,13 @@ export const handlers = [
 ];
 
 // src/mocks/node.js
+import { setupServer } from 'msw/node';
+import { handlers } from './handlers';
 
 export const server = setupServer(...handlers);
 
 // src/CustomAutocomplete.test.tsx
+import { server } from './mocks/node';
 
 server.listen();
 

package/.ai/components/button-group.md

@@ -13,11 +13,6 @@ import { IressButtonGroup } from '@iress-oss/ids-components';
 <IressButtonGroup label="Options" />
 ```
 
-import {
-  ComponentExample,
-  ComponentOverview,
-} from '@iress-oss/ids-storybook-config';
-
 ## Usage
 
 Button Group requires some `label` text to describe what the group of buttons represent. The `label` text can be visually hidden (but still read by screenreaders) using the `hiddenLabel` prop.

package/.ai/components/button.md

@@ -15,10 +15,79 @@ import { IressButton } from '@iress-oss/ids-components';
 </IressButton>
 ```
 
-import {
-  ComponentOverview,
-  ComponentExample,
-} from '@iress-oss/ids-storybook-config';
+## Usage
+
+### Avoid using `disabled`
+
+IDS discourages using `disabled` on `IressButton`. Although the native HTML `disabled` attribute is supported via the underlying `<button>`/`<a>` element, it is an anti-pattern that should be avoided because:
+
+- Screen readers skip disabled elements, making them invisible to assistive technology users
+- Users cannot understand why a button is disabled or what they need to do to enable it
+- It creates a poor user experience with no path to resolution
+
+<details>
+<summary>Alternatives by use case</summary>
+
+**"Form is incomplete"** — Keep the submit button enabled. Use `IressForm` with `rules` validation — it will show inline errors on submit and prevent submission until the form is valid.
+
+```tsx
+// ❌ Disabling submit until form is valid
+<IressButton disabled={!isValid} type="submit">Save</IressButton>
+
+// ✅ Let IressForm handle validation on submit
+<IressForm onSubmit={handleSubmit}>
+  <IressFormField
+    name="email"
+    label="Email"
+    rules={{ required: 'Email is required' }}
+    render={(props) => <IressInput {...props} type="email" />}
+  />
+  <IressButton mode="primary" type="submit">Save</IressButton>
+</IressForm>
+```
+
+**"Action is in progress"** — Use the `loading` prop. It shows a spinner, announces the state to screen readers, and automatically prevents duplicate clicks.
+
+```tsx
+// ❌ Disabling during submission
+<IressButton disabled={isSubmitting}>Save</IressButton>
+
+// ✅ Use loading — prevents clicks and communicates state
+<IressButton loading={isSubmitting} mode="primary" type="submit">Save</IressButton>
+```
+
+**"User lacks permission"** — Hide the button entirely, or keep it enabled and show an explanation when clicked.
+
+```tsx
+// ❌ Showing a disabled button the user can never enable
+<IressButton disabled={!canEdit}>Edit</IressButton>;
+
+// ✅ Option A — don't render the button at all
+{
+  canEdit && <IressButton onClick={handleEdit}>Edit</IressButton>;
+}
+
+// ✅ Option B — explain on click
+<IressButton onClick={() => (canEdit ? handleEdit() : showPermissionError())}>
+  Edit
+</IressButton>;
+```
+
+**"Prerequisite step not completed"** — Guide the user to the prerequisite instead of silently disabling.
+
+```tsx
+// ❌ Disabled with no explanation
+<IressButton disabled={!hasSelectedItem}>Delete</IressButton>
+
+// ✅ Explain what's needed
+<IressButton onClick={() => !hasSelectedItem ? showAlert('Select an item first') : confirmDelete()}>
+  Delete
+</IressButton>
+```
+
+**"Destructive action needs confirmation"** — Use `IressModal` with `status="danger"` for a confirmation step.
+
+</details>
 
 ## Examples
 
@@ -131,7 +200,7 @@ reset
 
 Loading buttons give the user an indication something is happening (eg. a form submission or extra content being loaded) after they have been triggered.
 
-The loading state can be activated by setting the `loading` prop to `true` and providing some `loadingText` for screenreaders to announce when in loading state (which defaults to Loading...).
+The loading state can be activated by setting the `loading` prop to `true`. To customise the screen reader announcement, pass a string instead of `true` (e.g. `loading="Submitting…"`). The default announcement is "Loading".
 
 When the loading state is activated, any click events on the button are disabled.
 

package/.ai/components/card.md

@@ -15,11 +15,6 @@ import { IressCard } from '@iress-oss/ids-components';
 </IressCard>
 ```
 
-import {
-  ComponentOverview,
-  ComponentExample,
-} from '@iress-oss/ids-storybook-config';
-
 ## Examples
 
 ### Simple cards

package/.ai/components/checkbox-group-recipes.md

@@ -2,7 +2,6 @@
 
 CheckboxGroup component documentation.
 
-> **Component:** `@iress-oss/ids-components`
 > **Storybook:** [Recipes in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-checkbox-group--docs)
 
 ## Checkboxes inside an `IressTable`

package/.ai/components/checkbox-group.md

@@ -13,11 +13,6 @@ import { IressCheckboxGroup } from '@iress-oss/ids-components';
 <IressCheckboxGroup name="preferences" />
 ```
 
-import {
-  ComponentExample,
-  ComponentOverview,
-} from '@iress-oss/ids-storybook-config';
-
 ## Examples
 
 ### Checkbox children

package/.ai/components/checkbox.md

@@ -15,11 +15,6 @@ import { IressCheckbox } from '@iress-oss/ids-components';
 </IressCheckbox>
 ```
 
-import {
-  ComponentExample,
-  ComponentOverview,
-} from '@iress-oss/ids-storybook-config';
-
 ## Usage
 
 ### Checked

package/.ai/components/col.md

@@ -13,11 +13,6 @@ import { IressCol } from '@iress-oss/ids-components';
 <IressCol numberOfColumns={2} />
 ```
 
-import {
-  ComponentExample,
-  ComponentOverview,
-} from '@iress-oss/ids-storybook-config';
-
 ## Examples
 
 ### Auto-sized

package/.ai/components/container.md

@@ -13,11 +13,6 @@ import { IressContainer } from '@iress-oss/ids-components';
 <IressContainer />
 ```
 
-import {
-  ComponentOverview,
-  ComponentExample,
-} from '@iress-oss/ids-storybook-config';
-
 ## Behaviour
 
 The `IressContainer` snaps to fixed max widths at different breakpoints. Those max widths are as follows:

package/.ai/components/divider.md

@@ -13,11 +13,6 @@ import { IressDivider } from '@iress-oss/ids-components';
 <IressDivider />
 ```
 
-import {
-  ComponentExample,
-  ComponentOverview,
-} from '@iress-oss/ids-storybook-config';
-
 ## Examples
 
 ### Vertical divider

package/.ai/components/expander.md

@@ -15,11 +15,6 @@ import { IressExpander } from '@iress-oss/ids-components';
 </IressExpander>
 ```
 
-import {
-  ComponentExample,
-  ComponentOverview,
-} from '@iress-oss/ids-storybook-config';
-
 ## Accessibility
 
 For Accessibility guidelines refer to

package/.ai/components/field.md

@@ -13,11 +13,6 @@ import { IressField } from '@iress-oss/ids-components';
 <IressField label="First name" />
 ```
 
-import {
-  ComponentExample,
-  ComponentOverview,
-} from '@iress-oss/ids-storybook-config';
-
 ## Examples
 
 ### Label

package/.ai/components/icon.md

@@ -13,11 +13,6 @@ import { IressIcon } from '@iress-oss/ids-components';
 <IressIcon name="home" />
 ```
 
-import {
-  ComponentExample,
-  ComponentOverview,
-} from '@iress-oss/ids-storybook-config';
-
 ## Installation
 
 ### Material Symbols
@@ -26,9 +21,10 @@ From version 6, the `IressIcon` component supports Material Symbols icons from G
 
 #### Option 1: Automatic loading with `IressProvider` (recommended)
 
-If you are already using the `IressProvider` component in your application, no further action is required as the Material Symbols font will be automatically loaded for you as it contains the `IressIconProvider` component.
+If you are already using the `IressProvider` component in your application, no further action is required as the Material Symbols font will be automatically loaded for you as it contains the `IressIconProvider` component. The same applies if you are using `IressShadow`, which includes `IressProvider` internally.
 
 ```tsx
+import { IressProvider } from '@iress-oss/ids-components';
 
 <IressProvider>
   <App />
@@ -46,7 +42,9 @@ The `IressProvider` component takes care of this for you when you use it with th
 
 #### Option 2: Using the `IressIconProvider`
 
-For more simpler applications, you can use the `IressIconProvider` directly.
+For more simpler applications, or if you need to customise the icon provider independently, you can use the `IressIconProvider` directly.
+
+> **Note:** If you are already using `IressProvider` or `IressShadow`, you do not need to add `IressIconProvider` separately — it is already included.
 
 ```tsx
 const [showMoreIcons, setShowMoreIcons] = useState(false);
@@ -243,6 +241,7 @@ If you are using Microfrontends or Web Components that use Shadow DOM, you need
 The easiest way to do this is to use the `IressIconProvider` component with the `container` prop.
 
 ```tsx
+import { IressIconProvider, IressIcon as Icon } from '@iress/ids-components';
 
 <IressIconProvider type="fontawesome" container={shadowRoot}>
   <App />
@@ -256,6 +255,7 @@ The easiest way to do this is to use the `IressIconProvider` component with the
 From version 6, the default icon type is Material Symbols. If you want to make Font Awesome the default icon type, you can wrap your application in the `IressIconProvider` component.
 
 ```tsx
+import { IressIconProvider, IressIcon as Icon } from '@iress/ids-components';
 
 // Export a version of IressIcon that uses Font Awesome by default for typing
 export const IressIcon = Icon<'fontawesome'>;

package/.ai/components/image.md

@@ -13,11 +13,6 @@ import { IressImage } from '@iress-oss/ids-components';
 <IressImage src="https://www.fdcbuilding.com.au/wp-content/webp-express/webp-images/uploads/2020/01/4-1.jpg.webp" alt="Placeholder image" />
 ```
 
-import {
-  ComponentExample,
-  ComponentOverview,
-} from '@iress-oss/ids-storybook-config';
-
 ## Examples
 
 ### MaxWidth

package/.ai/components/inline.md

@@ -15,11 +15,6 @@ import { IressInline } from '@iress-oss/ids-components';
 </IressInline>
 ```
 
-import {
-  ComponentExample,
-  ComponentOverview,
-} from '@iress-oss/ids-storybook-config';
-
 ## Examples
 
 ### Gap

package/.ai/components/input-currency-recipes.md

@@ -2,7 +2,6 @@
 
 InputCurrency component documentation.
 
-> **Component:** `@iress-oss/ids-components`
 > **Storybook:** [Recipes in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-input-currency--docs)
 
 ## Using IressInputCurrency in table

package/.ai/components/input-currency.md

@@ -13,11 +13,6 @@ import { IressInputCurrency } from '@iress-oss/ids-components';
 <IressInputCurrency defaultValue={12345.678} locale="en-AU" currencyCode="AUD" />
 ```
 
-import {
-  ComponentExample,
-  ComponentOverview,
-} from '@iress-oss/ids-storybook-config';
-
 ## Examples
 
 ### Different Locale and CurrencyCode

package/.ai/components/input-recipes.md

@@ -2,7 +2,6 @@
 
 Input component documentation.
 
-> **Component:** `@iress-oss/ids-components`
 > **Storybook:** [Recipes in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-input--docs)
 
 ## Percentage formatting

package/.ai/components/input.md

@@ -13,11 +13,6 @@ import { IressInput } from '@iress-oss/ids-components';
 <IressInput placeholder="Enter your name" />
 ```
 
-import {
-  ComponentExample,
-  ComponentOverview,
-} from '@iress-oss/ids-storybook-config';
-
 ## Examples
 
 ### Types

package/.ai/components/label.md

@@ -15,11 +15,6 @@ import { IressLabel } from '@iress-oss/ids-components';
 </IressLabel>
 ```
 
-import {
-  ComponentExample,
-  ComponentOverview,
-} from '@iress-oss/ids-storybook-config';
-
 ## Examples
 
 ### Required

package/.ai/components/link.md

@@ -15,11 +15,6 @@ import { IressLink } from '@iress-oss/ids-components';
 </IressLink>
 ```
 
-import {
-  ComponentExample,
-  ComponentOverview,
-} from '@iress-oss/ids-storybook-config';
-
 ## Usage
 
 `IressLink` is an alternative to the `IressButton` component, and is used when you want to add interactive text inside a block of static text.

package/.ai/components/menu-item.md

@@ -15,11 +15,6 @@ import { IressMenuItem } from '@iress-oss/ids-components';
 </IressMenuItem>
 ```
 
-import {
-  ComponentExample,
-  ComponentOverview,
-} from '@iress-oss/ids-storybook-config';
-
 ## Examples
 
 ### Selected

package/.ai/components/menu.md

@@ -13,11 +13,6 @@ import { IressMenu } from '@iress-oss/ids-components';
 <IressMenu />
 ```
 
-import {
-  ComponentExample,
-  ComponentOverview,
-} from '@iress-oss/ids-storybook-config';
-
 ## Usage
 
 ### Basic

package/.ai/components/modal.md

@@ -13,12 +13,20 @@ import { IressModal } from '@iress-oss/ids-components';
 <IressModal heading="Modal Header" />
 ```
 
-import {
-  ComponentExample,
-  ComponentOverview,
-} from '@iress-oss/ids-storybook-config';
+## Usage
 
-## Controlling the modal
+### Use a modal when
+
+- Providing supplemental tasks required by the underlying page
+- Providing non-essential information related to the underlying page
+- Content requires full attention
+
+### Avoid using a modal when
+
+- Conveying brief messages about background processes or status changes. Instead use [IressAlert](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-alert--docs) or [IressToaster](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-toaster--docs).
+- The modal content can be incorporated into the page without complicating the page's intent
+
+For a full comparison of feedback components, see the [Feedback pattern](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_patterns-feedback--docs).
 
 ### Using the `show` property
 
@@ -34,6 +42,8 @@ You can use state to control the modal by setting the `show` property to `true`
 
 You can use the `IressModalProvider` to open and close modals from anywhere in your application, as long as the modal has a unique `id`. In this case you would use the `useModal` hook to open and close the modal.
 
+> **Note:** If you are already using `IressProvider` or `IressShadow`, you do not need to add `IressModalProvider` separately — it is already included.
+
 To use, wrap your `<App/>` or the component that you want to use the `useModal` hook with `<IressModalProvider />`.
 
 ```tsx
@@ -206,6 +216,8 @@ const { showModal } = useModal();
 
 For your components to work as previously, you will need to set up the `IressModalProvider` at the root of your application. This will allow you to use the `useModal` hook to open and close modals from anywhere in your application using the ID of the modal.
 
+> **Note:** If you are using `IressProvider` or `IressShadow`, you do not need to add `IressModalProvider` separately — it is already included.
+
 ```tsx
 const App = () => <IressModalProvider>Rest of app here</IressModalProvider>;
 ```

package/.ai/components/panel.md

@@ -15,11 +15,6 @@ import { IressPanel } from '@iress-oss/ids-components';
 </IressPanel>
 ```
 
-import {
-  ComponentExample,
-  ComponentOverview,
-} from '@iress-oss/ids-storybook-config';
-
 ## Usage
 
 `IressPanel` uses `IressCard` under the hood, so it inherits all of the same props and styling options. It is purely a semantic component that provides a more specific name for grouping related content together.

package/.ai/components/pill.md

@@ -15,11 +15,6 @@ import { IressPill } from '@iress-oss/ids-components';
 </IressPill>
 ```
 
-import {
-  ComponentOverview,
-  ComponentExample,
-} from '@iress-oss/ids-storybook-config';
-
 ## When to use
 
 Use pills for **status indication and notifications** where information needs to be highlighted:

package/.ai/components/popover-recipes.md

@@ -2,7 +2,6 @@
 
 Popover component documentation.
 
-> **Component:** `@iress-oss/ids-components`
 > **Storybook:** [Recipes in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-popover--docs)
 
 ## With `IressMenu`

package/.ai/components/popover.md

@@ -15,11 +15,6 @@ import { IressPopover } from '@iress-oss/ids-components';
 </IressPopover>
 ```
 
-import {
-  ComponentExample,
-  ComponentOverview,
-} from '@iress-oss/ids-storybook-config';
-
 ## Usage
 
 ### Activator

package/.ai/components/progress.md

@@ -13,11 +13,6 @@ import { IressProgress } from '@iress-oss/ids-components';
 <IressProgress min={10} max={30} value={20} />
 ```
 
-import {
-  ComponentOverview,
-  ComponentExample,
-} from '@iress-oss/ids-storybook-config';
-
 ## Usage
 
 Progress shows how far through a task or operation you are in a graphical way. The simplest way to use it to set the `value` to specify how much of the task the user has completed, relative to the `max` value (which defaults to 100).

package/.ai/components/provider.md

@@ -22,7 +22,10 @@ The design system provider automates some set-up tasks for you, including:
 
 In most cases, you should wrap the entire application with the `IressProvider` component. This will ensure that the design system is set up correctly and consistently across the application.
 
+> **Note:** `IressProvider` already includes `IressModalProvider`, `IressSlideoutProvider`, `IressToasterProvider`, and `IressIconProvider`. You do not need to add these providers separately when using `IressProvider`. Similarly, `IressShadow` includes `IressProvider` internally, so you do not need any additional providers when using `IressShadow`.
+
 ```tsx
+import { IressProvider } from '@iress-oss/ids-components';
 
 ReactDOM.createRoot(document.getElementById('root')!).render(
   <IressProvider>

package/.ai/components/radio-group.md

@@ -13,11 +13,6 @@ import { IressRadioGroup } from '@iress-oss/ids-components';
 <IressRadioGroup name="survey" />
 ```
 
-import {
-  ComponentExample,
-  ComponentOverview,
-} from '@iress-oss/ids-storybook-config';
-
 ## Examples
 
 ### Radio children

package/.ai/components/radio.md

@@ -15,11 +15,6 @@ import { IressRadio } from '@iress-oss/ids-components';
 </IressRadio>
 ```
 
-import {
-  ComponentExample,
-  ComponentOverview,
-} from '@iress-oss/ids-storybook-config';
-
 ## Examples
 
 ### Checked

package/.ai/components/readonly.md

@@ -13,11 +13,6 @@ import { IressReadonly } from '@iress-oss/ids-components';
 <IressReadonly value="AU" />
 ```
 
-import {
-  ComponentExample,
-  ComponentOverview,
-} from '@iress-oss/ids-storybook-config';
-
 ## Examples
 
 ### Rich Content
@@ -36,6 +31,16 @@ You can make the prepend/append element closer to the input content using the `i
 
 [View "InlineStyle" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-readonly--inline-style)
 
+### Actions
+
+The `actions` prop allows you to add buttons next to the readonly field. These can be used to trigger actions related to the displayed value, such as copying it to the clipboard or opening an edit dialog.
+
+```tsx
+<ReadonlyEditToggle />
+```
+
+[View "Actions" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-readonly--actions)
+
 ## Props
 
 - **Type:** `IressReadonlyProps`

package/.ai/components/row.md

@@ -13,11 +13,6 @@ import { IressRow } from '@iress-oss/ids-components';
 <IressRow gutter="spacing.7" horizontalAlign="left" verticalAlign="top" />
 ```
 
-import {
-  ComponentExample,
-  ComponentOverview,
-} from '@iress-oss/ids-storybook-config';
-
 ## Usage
 
 `IressRow` supports visual hierarchy by allowing you to add multiple columns in your layout, allowing the user to see more content on the screen at the same time.