@iress-oss/ids-components 6.0.0-alpha.3 → 6.0.0-alpha.30

package/.ai/components/toaster.md

@@ -0,0 +1,101 @@
+# Toaster
+
+Toaster provide users with important, time-sensitive information.
+
+> **Component:** `import { IressToaster } from '@iress-oss/ids-components'`
+> **Storybook:** [Toaster in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-toaster--docs)
+
+## Quick Start
+
+```tsx
+import { IressToaster } from '@iress-oss/ids-components';
+
+<IressToaster />
+```
+
+import {
+  ComponentExample,
+  ComponentOverview,
+} from '@iress-oss/ids-storybook-config';
+
+## Usage
+
+To use the toaster, wrap your `<App/>` or the component that you want to use the toasts within with `<IressToasterProvider />`. This provides the context for the `useToaster` hook, which is used to trigger toasts in your application.
+
+You can use the `success`, `info` and `error` methods from the hook to trigger toasts in your application.
+
+```tsx
+<SimpleToasterExample />
+```
+
+[View "Provider" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-toaster--provider)
+
+### Closing toasts via the provider
+
+If you want to dismiss a toast programmatically, you can use the `close` method from the `useToaster` hook. This method takes a toast ID as an argument, which is returned when you create a toast using the `useToaster` hook.
+
+```tsx
+<CloseToastViaProvider />
+```
+
+[View "Close" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-toaster--close)
+
+## Examples
+
+### Status
+
+The toast offers three status that set a distinctive colour and icon. They can be set using the `status` prop. Their different use cases are described here.
+
+```tsx
+<ToastStatuses />
+```
+
+[View "Statuses" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-toaster--statuses)
+
+### Timeout
+
+By default, toasts will time out after six seconds, after which they will animate out of view. This can be customised using the `timeout` prop when created using the `useToaster` hook.
+
+Timeouts must be set in milliseconds; as an example, if you want a timeout of five seconds, set the timeout to 5000.
+
+```tsx
+<ToasterTimeout />
+```
+
+[View "Timeout" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-toaster--timeout)
+
+### Position
+
+By default, the `IressToasterProvider`'s `position` is set to `bottom-end`, but there may be occasions when you need toasts to appear in a different part of the screen. This can be controlled with the `position` prop on the `IressToasterProvider` component, or as the first argument to `useToaster`. There are 6 positions to choose from.
+
+**Note:** The toast position should be consistent based on context, so users can find them easily.
+
+```tsx
+<ToasterPositionExamples />
+```
+
+[View "Position" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-toaster--position)
+
+## Migrating from version 4 and below
+
+### Adding the provider
+
+For your components to work as previously, you will need to set up the `IressToasterProvider` at the root of your application. This will allow you to use the `useToaster` hook to trigger toasts from anywhere in your application using the status and props of the toast.
+
+```tsx
+const App = () => <IressToasterProvider>Rest of app here</IressToasterProvider>;
+```
+
+## Props
+
+- **Type:** `ToasterProps`
+- **Type declarations:** `@iress-oss/ids-components/dist/components/Toaster/Toaster.d.ts`
+
+```typescript
+import type { ToasterProps } from '@iress-oss/ids-components';
+```
+
+
+---
+
+*View interactive examples: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-toaster--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-toaster--docs)*

package/.ai/components/toggle.md

@@ -0,0 +1,127 @@
+# Toggle
+
+Toggles allow users to turn things on or off. When toggled, the associated change happens straight away.
+
+> **Component:** `import { IressToggle } from '@iress-oss/ids-components'`
+> **Storybook:** [Toggle in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-toggle--docs)
+
+## Quick Start
+
+```tsx
+import { IressToggle } from '@iress-oss/ids-components';
+
+<IressToggle defaultChecked={false} hiddenLabel={false} layout="inline">
+  Toggle
+</IressToggle>
+```
+
+import {
+  ComponentExample,
+  ComponentOverview,
+} from '@iress-oss/ids-storybook-config';
+
+## Usage
+
+Toggles are typically on / off switches, similar to a household light switch. They allow users to choose between two mutually exclusive options, and will always have a default value.
+
+The `IressToggle` component should only be used for actions that happen immediately, for example switching a device's WiFi connection on or off.
+
+> [!WARNING]
+> **Don't use Toggles in forms**
+>
+> Toggles shouldn’t be used as part of a form as they don’t have the correct
+>   semantics, and won’t submit a value when the form data is submitted. If you
+>   need a toggleable component in a form, use a checkbox or radio group instead.
+
+### Labels
+
+Toggles should always have a label, which is set via its `children`.
+
+```tsx
+<IressToggle defaultChecked={false} hiddenLabel={false} layout="inline">
+  Toggle
+</IressToggle>
+```
+
+[View "Default" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-toggle--default)
+
+### Hidden labels
+
+Labels can be hidden via the `hiddenLabel` prop; this will hide the label from view, but it'll still be available to screen reader users.
+
+```tsx
+<IressToggle hiddenLabel />
+```
+
+[View "HiddenLabel" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-toggle--hidden-label)
+
+### Checked
+
+The on / off state of the toggle can be controlled by setting the `checked` prop (for controlled components). If you want an uncontrolled component, you can set the `defaultChecked` prop instead to set it checked by default.
+
+```tsx
+<ControlledToggle />
+```
+
+[View "Checked" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-toggle--checked)
+
+### Layout
+
+The `layout` prop allows you to control the position of the label in relation to the control. The default layout is `inline`, but you can also choose the following options:',
+
+- `inline-between` similar to inline, but this positions the label and control at opposite ends of their container
+- `inline-reverse` renders the label after the control instead of before the control
+- `stack` positions the label above the control
+
+```tsx
+<IressStack gap="lg">
+<IressText>
+<h3>inline</h3>
+<IressPanel bg="alt">
+<IressToggle layout="inline">
+Toggle
+</IressToggle>
+</IressPanel>
+</IressText>
+<IressText>
+<h3>inline-between</h3>
+<IressPanel bg="alt">
+<IressToggle layout="inline-between" checked>
+Toggle
+</IressToggle>
+</IressPanel>
+</IressText>
+<IressText>
+<h3>inline-reverse</h3>
+<IressPanel bg="alt">
+<IressToggle layout="inline-reverse">
+Toggle
+</IressToggle>
+</IressPanel>
+</IressText>
+<IressText>
+<h3>stack</h3>
+<IressPanel bg="alt">
+<IressToggle layout="stack" checked>
+Toggle
+</IressToggle>
+</IressPanel>
+</IressText>
+</IressStack>
+```
+
+[View "Layout" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-toggle--layout)
+
+## Props
+
+- **Type:** `IressToggleProps`
+- **Type declarations:** `@iress-oss/ids-components/dist/components/Toggle/Toggle.d.ts`
+
+```typescript
+import type { IressToggleProps } from '@iress-oss/ids-components';
+```
+
+
+---
+
+*View interactive examples: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-toggle--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-toggle--docs)*

package/.ai/components/tooltip.md

@@ -0,0 +1,190 @@
+# Tooltip
+
+A component that shows concise, informative text about an element when focussed upon, hovered over or on a long touch.
+
+> **Component:** `import { IressTooltip } from '@iress-oss/ids-components'`
+> **Storybook:** [Tooltip in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-tooltip--docs)
+
+## Quick Start
+
+```tsx
+import { IressTooltip } from '@iress-oss/ids-components';
+
+<IressTooltip tooltipText="Hello! This is a really long tooltip to try and see if it goes behind the scrollbar" />
+```
+
+import {
+  ComponentExample,
+  ComponentOverview,
+} from '@iress-oss/ids-storybook-config';
+
+## Usage
+
+The content that will be displayed in the tooltip is passed using the `tooltipText` prop.
+
+This content can only be plain text; there is no parsing of any markup or styling. This is by design as we do not allow complex structures in a tooltip as they are meant to be concise, informative pieces of text.
+
+Text content will wrap on to a new line if it exceeds the tooltip's maximum width. You can also manually format your content into multiple lines by passing an array of strings into the `tooltipText` prop.
+
+```tsx
+<div style={{ paddingTop: '30px' }}>
+<IressInline gap="md">
+<IressTooltip tooltipText="Single line Hello! This is a really long tooltip to try and see if it goes behind the scrollbar"
+>
+<IressButton>Single line</IressButton>
+</IressTooltip>
+<IressTooltip tooltipText={['This tooltip', 'has multiple lines']}
+>
+<IressButton>Multi line</IressButton>
+</IressTooltip>
+</IressInline>
+</div>
+```
+
+[View "TooltipText" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-tooltip--tooltip-text)
+
+## Behaviour
+
+The behaviour of tooltips varies according to how they're shown:
+
+- When a pointer is moved over the activator the tooltip will be shown, and will remain visible for a short period of time after the pointer has moved away (500ms is the default time)
+- If the activator receives keyboard focus the tooltip will be visible. The tooltip will hide immediately after the focus moves away from the activator.
+- If the user long presses on the activator (on a touch device). The tooltip will remain visible until the user taps somewhere else on the screen
+
+If the user activates a tooltip via a pointing device and then moves the pointer over the tooltip, it will remain on screen until the pointer is moved away. This is for accessibility purposes where a user may be using magnifying software for example.
+
+## Accessibility
+
+The WCAG guidelines for content that is displayed on hover or focus can be found here: [WCAG 2.1 - 1.4.13 (AA)](https://www.w3.org/TR/WCAG21/#content-on-hover-or-focus).
+
+Other things to keep in mind:
+
+- For best accessibility, you should only use tooltips on focusable items (eg. `IressButton` and `IressMenuItem`), allowing them to be seen when navigating to the tooltip activator by keyboard
+
+**Notes:**
+
+- If the text you wish to display is more than a handful of words then
+  consider using an IressModal with an information button.
+- Tooltips must not be used for help text as they are not immediately visible
+  to the user. We suggest adding hint text to assist the user when filling out
+  forms.
+- Also think about placement using the align prop. The tooltip should not
+  obscure any critical screen content. Another reason to keep them short.
+
+## Examples
+
+### Align
+
+The tooltip can be aligned in one of 12 positions relative to the activator element.
+
+The tooltip's position will change dynamically based on the amount of space available in its container window, so that it doesn't overflow the edge. For example, if the tooltip is about to scroll off the top of the screen, it will change its position to bottom. Likewise with left and right scrolling.
+
+```tsx
+<div style={{ padding: '80px 150px' }}>
+<IressStack gap="md">
+<IressInline horizontalAlign="center" gap="sm">
+<IressTooltip align="top-start">
+<IressButton>Top Start</IressButton>
+</IressTooltip>
+<IressTooltip align="top">
+<IressButton>Top</IressButton>
+</IressTooltip>
+<IressTooltip align="top-end">
+<IressButton>Top End</IressButton>
+</IressTooltip>
+</IressInline>
+<IressInline horizontalAlign="between">
+<IressStack gap="sm">
+<IressInline horizontalAlign="left">
+<IressTooltip align="left-start">
+<IressButton>Left Start</IressButton>
+</IressTooltip>
+</IressInline>
+<IressInline horizontalAlign="left">
+<IressTooltip align="left">
+<IressButton>Left</IressButton>
+</IressTooltip>
+</IressInline>
+<IressInline horizontalAlign="left">
+<IressTooltip align="left-end">
+<IressButton>Left End</IressButton>
+</IressTooltip>
+</IressInline>
+</IressStack>
+<IressStack gap="sm">
+<IressInline horizontalAlign="right">
+<IressTooltip align="right-start">
+<IressButton>Right Start</IressButton>
+</IressTooltip>
+</IressInline>
+<IressInline horizontalAlign="right">
+<IressTooltip align="right">
+<IressButton>Right</IressButton>
+</IressTooltip>
+</IressInline>
+<IressInline horizontalAlign="right">
+<IressTooltip align="right-end">
+<IressButton>Right End</IressButton>
+</IressTooltip>
+</IressInline>
+</IressStack>
+</IressInline>
+<IressInline horizontalAlign="center" gap="sm">
+<IressTooltip align="bottom-start">
+<IressButton>Bottom Start</IressButton>
+</IressTooltip>
+<IressTooltip align="bottom">
+<IressButton>Bottom</IressButton>
+</IressTooltip>
+<IressTooltip align="bottom-end">
+<IressButton>Bottom End</IressButton>
+</IressTooltip>
+</IressInline>
+</IressStack>
+</div>
+```
+
+[View "Align" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-tooltip--align)
+
+### Delay
+
+The `delay` prop requires a number that is the number of milliseconds that pass after the activator has received a `mouseEnter` event and the display of the tooltip.
+
+```tsx
+<div style={{ paddingTop: '30px' }}>
+<IressInline horizontalAlign="center" gap="sm">
+<IressTooltip delay={0}>
+<IressButton>0ms (no delay)</IressButton>
+</IressTooltip>
+<IressTooltip>
+<IressButton>500ms (default)</IressButton>
+</IressTooltip>
+
+<IressTooltip delay={2000}>
+<IressButton>2000ms</IressButton>
+</IressTooltip>
+</IressInline>
+</div>
+```
+
+[View "Delay" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-tooltip--delay)
+
+### The title attribute
+
+The component will not make any provision for existing title HTML attributes. If one exists, it will be activated along with the tooltip, potentially overlaying it making it difficult to ascertain the information being imparted. The title could also contain different content to the tooltip increasing the chance of confusing the end user.
+
+We suggest removing the title attribute on elements that will use tooltip.
+
+## Props
+
+- **Type:** `IressTooltipProps`
+- **Type declarations:** `@iress-oss/ids-components/dist/components/Tooltip/Tooltip.d.ts`
+
+```typescript
+import type { IressTooltipProps } from '@iress-oss/ids-components';
+```
+
+
+---
+
+*View interactive examples: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-tooltip--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-tooltip--docs)*

package/.ai/components/validation-message.md

@@ -0,0 +1,100 @@
+# Validation message
+
+A validation message is used to inform the user of the status of a form input. If there are multiple messages, they can be combined using the IressValidationSummary component.
+
+> **Component:** `import { IressValidationMessage } from '@iress-oss/ids-components'`
+> **Storybook:** [Validation message in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-validation-message--docs)
+
+## Quick Start
+
+```tsx
+import { IressValidationMessage } from '@iress-oss/ids-components';
+
+<IressValidationMessage>
+  Validation message
+</IressValidationMessage>
+```
+
+import {
+  ComponentExample,
+  ComponentOverview,
+} from '@iress-oss/ids-storybook-config';
+
+## Examples
+
+### Status
+
+Validation status is controlled by the status prop. It defaults to `error`.
+
+```tsx
+<IressStack>
+{STATUSES.map((status) => (
+<IressValidationMessage key={status} status={status}>
+{messages[status]}
+</IressValidationMessage>
+))}
+</IressStack>
+```
+
+[View "Status" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-validation-message--status)
+
+### Prefix
+
+You can add a prefix to the message. If not provided, it uses the `status` prop to determine the prefix.
+
+It is hidden by default, but can be shown by setting the `visiblePrefix` prop to `true`.
+
+```tsx
+<IressStack>
+{STATUSES.map((status) => (
+<IressValidationMessage key={status} status={status}>
+{messages[status]}
+</IressValidationMessage>
+))}
+</IressStack>
+```
+
+[View "Prefix" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-validation-message--prefix)
+
+### Link to target
+
+You can use the `linkToTarget` prop to link the message to a specific target in the DOM. This is useful to take the user to a specific part of the form when they click on the message.
+
+```tsx
+<IressStack gap="md">
+<IressStack>
+{STATUSES.map((status) => (
+<IressValidationMessage key={status}
+status={status}
+linkToTarget={args.linkToTarget ?? ''}
+>
+{messages[status]}
+</IressValidationMessage>
+))}
+</IressStack>
+<IressDivider />
+<IressInput id={args.linkToTarget} />
+</IressStack>
+```
+
+[View "LinkToTarget" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-validation-message--link-to-target)
+
+## `IressValidationSummary`
+
+Messages can be passed programmatically as a `ValidationMessageObj[]` using the `messages` prop of the `IressValidationSummary` component.
+
+[View "ValidationSummary" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-validation-summary--validation-summary)
+
+## Props
+
+- **Type:** `IressValidationMessageProps`
+- **Type declarations:** `@iress-oss/ids-components/dist/components/ValidationMessage/ValidationMessage.d.ts`
+
+```typescript
+import type { IressValidationMessageProps } from '@iress-oss/ids-components';
+```
+
+
+---
+
+*View interactive examples: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-validation-message--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-validation-message--docs)*

package/.ai/guides/foundations-accessibility.md

@@ -0,0 +1,38 @@
+# Accessibility
+
+> **Guide:** `@iress-oss/ids-components`
+> **Storybook:** [Accessibility in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_foundations-accessibility--docs)
+
+Accessibility is everyone's responsibility. It ensures that all users, regardless of their abilities or disabilities, can access and interact with our components effectively. This document outlines the key practices for building accessible components we follow within IDS.
+
+Please note: The default behaviour of our components is to be accessible, but it is the responsibility of the product to ensure that they are used correctly in accessibile context, or any modifications made to them do not compromise accessibility.
+
+## Interaction Patterns
+
+### Keyboard Navigation
+
+- Support standard keyboard shortcuts (Tab, Arrow keys, Enter, Space, Escape)
+- Implement proper focus order and visual focus indicators
+- Provide keyboard alternatives for mouse-only interactions
+- Follow established ARIA patterns for complex widgets
+
+### Touch Interactions
+
+- Provide adequate touch target sizes
+- Implement touch-friendly spacing between interactive elements
+- Support gesture-based interactions where appropriate
+- Ensure consistent behaviour across device types
+
+### Loading and Feedback
+
+- Use appropriate loading patterns based on context:
+  - **Page**: Full page loading states
+  - **Component**: Local loading within sections
+  - **Button**: Inline loading for form submissions
+  - **Validate**: Server-side validation feedback
+- Provide clear success and error feedback
+- Use progressive enhancement for better perceived performance
+
+---
+
+*View in Storybook: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_foundations-accessibility--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_foundations-accessibility--docs)*

package/.ai/guides/foundations-consistency.md

@@ -0,0 +1,45 @@
+# Using components consistently
+
+> **Guide:** `@iress-oss/ids-components`
+> **Storybook:** [Using components consistently in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_foundations-using-components-consistently--docs)
+
+## Buttons
+
+- **Primary**: Limit to one per view for main call-to-action
+- **Secondary**: Use for secondary actions
+- **Tertiary**: Extra affordance between secondary actions
+- **Link**: Button styled as link (avoid with icon-only content)
+- **Danger**: Destructive actions requiring extra confirmation
+- **Positive/Negative**: Financial transactions (buy/sell)
+
+## Forms
+
+- Always use `IressField` wrapper for proper label, hint, and error placement
+- Provide clear validation feedback with appropriate error messages
+- Use consistent input sizing based on expected content length
+- Implement proper form state management and accessibility
+
+## Navigation
+
+- Use semantic HTML5 navigation elements
+- Provide skip links for keyboard users
+- Implement proper ARIA labelling for navigation sections
+- Ensure consistent navigation patterns across applications
+
+## Data Display
+
+- Use semantic table structures with proper headers
+- Provide clear visual hierarchy in data presentations
+- Implement consistent sorting and filtering patterns
+- Use appropriate loading states for data-heavy components
+
+## Modals and Overlays
+
+- Reserve modals for critical tasks requiring full attention
+- Provide multiple dismissal methods (backdrop, escape key, close button)
+- Implement proper focus management and restoration
+- Use slideouts for supplementary tasks where underlying content needs visibility
+
+---
+
+*View in Storybook: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_foundations-using-components-consistently--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_foundations-using-components-consistently--docs)*

package/.ai/guides/foundations-content.md

@@ -0,0 +1,22 @@
+# Content
+
+> **Guide:** `@iress-oss/ids-components`
+> **Storybook:** [Content in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_foundations-content--docs)
+
+## Microcopy Guidelines
+
+- Use clear, concise language that matches user mental models
+- Provide helpful error messages with actionable guidance
+- Implement consistent tone of voice across all interface text
+- Use progressive disclosure for complex information
+
+## Iconography
+
+- Use icons consistently with established meanings
+- Provide screen reader text for meaningful icons
+- Avoid using icons as the sole means of communication
+- Maintain consistent icon sizing and alignment
+
+---
+
+*View in Storybook: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_foundations-content--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_foundations-content--docs)*