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

package/.ai/components/modal.md

@@ -0,0 +1,256 @@
+# Modal
+
+Modals gather information, complete a subtask, or provide additional information without losing the context of an underlying page.
+
+> **Component:** `import { IressModal } from '@iress-oss/ids-components'`
+> **Storybook:** [Modal in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-modal--docs)
+
+## Quick Start
+
+```tsx
+import { IressModal } from '@iress-oss/ids-components';
+
+<IressModal heading="Modal Header" />
+```
+
+import {
+  ComponentExample,
+  ComponentOverview,
+} from '@iress-oss/ids-storybook-config';
+
+## Controlling the modal
+
+### Using the `show` property
+
+You can use state to control the modal by setting the `show` property to `true` or `false`. To sync your state with the modal, you can use the `onShowChange` prop, which is normally passed the set function from `useState`.
+
+```tsx
+<ModalUsingState />
+```
+
+[View "ShowWithState" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-modal--show-with-state)
+
+### Using the `IressModalProvider`
+
+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.
+
+To use, wrap your `<App/>` or the component that you want to use the `useModal` hook with `<IressModalProvider />`.
+
+```tsx
+<AppWithModalProvider {...args.modal} />
+```
+
+[View "Provider" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-provider--provider)
+
+## Behaviour
+
+- No other interaction on the main page can be accessed while a modal is active. A backdrop covers the content beneath so that the content beneath cannot be interacted with.
+- Clicking on the the backdrop closes the modal and returns the focus to the triggering element.
+- When the modal is active the body is set to overflow: hidden to stop any scrolling of the underlying page. Scrolling should then only be possible on the modal wrapper.
+- By default there are 3 ways to dismiss the modal; click X in the header; press ESC on a keyboard; click anywhere on the backdrop. It is also recommended that consumers add a Cancel or Close button to the modal's footer slot if required.
+
+## Examples
+
+### Heading
+
+The `heading` prop can be used to set a heading for the modal. This will be rendered in the header of the modal, and will be announced by screen readers when the modal is opened.
+
+```tsx
+<IressModal heading="Modal heading" />
+```
+
+[View "Heading" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-modal--heading)
+
+### Footer slot
+
+Content to appear underneath the main content. Usually used for extra controls like buttons etc.
+
+```tsx
+<IressModal>
+  Normal modal content
+</IressModal>
+```
+
+[View "FooterSlot" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-modal--footer-slot)
+
+### Fixed footer
+
+The `fixedFooter` prop can be used to set the footer to be fixed to the bottom of the modal. This is often useful when there is a lot of content in the main area that you would like to scroll underneath the footer content.
+
+**Note:** Also works without footer content.
+
+> [!WARNING]
+> **Using with popovers and tooltips**
+>
+> The fixed footer variant of IressModal prevents content from overflowing the
+>   modal. This can cause layout issues when using with components that use
+>   popovers (for example IressCombobox), especially when these components sit at
+>   the end of the modal&apos;s content. If you encounter these issues, try using
+>   a modal without a fixed footer. Normal modals allow content to overflow, which
+>   should fix the issue.
+
+```tsx
+<IressModal fixedFooter />
+```
+
+[View "FixedFooter" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-modal--fixed-footer)
+
+### Size
+
+The `size` prop can be set to `sm`, `md` or `lg`. It defaults to `md`.
+
+Below is a guide on when to use which size.
+
+```tsx
+<ModalSizes />
+```
+
+[View "Size" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-modal--size)
+
+### Responsive size
+
+The `size` prop no longer accepts responsive values directly, instead you must use the `width` styling prop to set responsive sizes.
+
+The `width` prop can take an object that takes five key/value pairs that correlate with the IDS breakpoints.
+
+If you set a responsive `width`, the modal becomes full width on screens smaller than the value you specified. For example, if you want to create a large modal on medium screens and above:
+
+```tsx
+  <IressModal size="lg" width={{ md: 'overlay.lg' }}>
+```
+
+[View "ResponsiveSize" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-modal--responsive-size)
+
+### 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`.
+
+**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.
+
+```tsx
+const { showModal } = useModal();
+
+    return (
+      <IressStack gap="md">
+        <IressButton onClick={() => showModal('disable-backdrop-click')} fluid>
+          Disable backdrop click
+        </IressButton>
+        <IressModal
+          {...args}
+          id="disable-backdrop-click"
+          disableBackdropClick
+        />
+
+        <IressButton onClick={() => showModal('no-close-button')} fluid>
+          No close button (please provide one, if you decide to hide the close
+          button)
+        </IressButton>
+        <IressModal
+          {...args}
+          id="no-close-button"
+          noCloseButton
+          footer={
+            <IressButton onClick={() => showModal('no-close-button', false)}>
+              Close
+            </IressButton>
+          }
+        />
+
+        <IressButton onClick={() => showModal('both')} fluid>
+          Both (If you hide the close button, ensure you provide another way to
+          close the modal)
+        </IressButton>
+        <IressModal
+          {...args}
+          id="both"
+          disableBackdropClick
+          noCloseButton
+          footer={
+            <IressButton onClick={() => showModal('both', false)}>
+              Close
+            </IressButton>
+          }
+        />
+      </IressStack>
+    );
+```
+
+[View "DisableClosing" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-modal--disable-closing)
+
+## Migrating to version 5
+
+### Adding the provider
+
+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.
+
+```tsx
+const App = () => <IressModalProvider>Rest of app here</IressModalProvider>;
+```
+
+### Testing
+
+In version 5, modals are rendered conditionally, meaning they will not be available in the DOM until they are shown. This means that you will need to update your tests to account for this, as you cannot interact with its contents until it is shown, unlike in version 4.
+
+See below for an example in version 4 and version 5.
+
+```tsx
+<DiffViewer
+allowModeChange
+oldValue={`import { render, waitFor, screen } from '@testing-library/react';
+import { idsFireEvent, componentLoad } from '@iress/ids-react-test-utils';
+
+test('opening and closing a modal', async () => {
+await componentLoad([
+'modal-trigger',
+'modal',
+]);
+
+const trigger = screen.getByTestId('modal-trigger');
+const modal = screen.getByTestId('modal');
+
+// In version 4, you can already interact with the modal here as its in the DOM at this stage.
+
+// activate modal
+idsFireEvent.click(trigger);
+await waitFor(() => expect(modal).toBeVisible());
+
+// close modal
+const closeButton = screen.getByTestId('modal__close-button');
+idsFireEvent.click(closeButton);
+await waitFor(() => expect(modal).not.toBeVisible());
+});`}
+newValue={`import { render, screen, waitForElementToBeRemoved } from '@testing-library/react';
+import { userEvent } from '@testing-library/user-event';
+
+test('opening and closing a modal', async () => {
+const trigger = screen.getByRole('button', { name: /open modal/i });
+
+// activate modal
+await userEvent.click(trigger);
+const modal = await screen.findByRole('dialog');
+
+// In version 5, you can only interact with the modal once it has been loaded here.
+
+// close modal
+const closeButton = screen.getByRole('button', { name: /close/i });
+await userEvent.click(closeButton);
+await waitForElementToBeRemoved(modal);
+});`}
+/>
+```
+
+[View "V5ModalDiff" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-modal--v5modal-diff)
+
+## Props
+
+- **Type:** `IressModalProps`
+- **Type declarations:** `@iress-oss/ids-components/dist/components/Modal/Modal.d.ts`
+
+```typescript
+import type { IressModalProps } from '@iress-oss/ids-components';
+```
+
+
+---
+
+*View interactive examples: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-modal--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-modal--docs)*

package/.ai/components/panel.md

@@ -0,0 +1,49 @@
+# Panel
+
+A panel is used to group related content.
+
+> **Component:** `import { IressPanel } from '@iress-oss/ids-components'`
+> **Storybook:** [Panel in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-panel--docs)
+
+## Quick Start
+
+```tsx
+import { IressPanel } from '@iress-oss/ids-components';
+
+<IressPanel heading="Panel Heading">
+  text
+</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.
+
+[View the API documentation for `IressCard`](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-card--docs)
+
+### When to use
+
+Panels are used to group related content. They can be used to create sections within a page, as well as group lists of items together.
+
+- If you need to display micro-content, use [IressCard](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-card--docs) instead.
+- If you need to add padding or a background to a section of content, use [IressStyled](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-styled--docs) or [styling props](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_styling-props-reference--docs) on the component itself.
+- Otherwise, use `IressPanel` to group related content together.
+
+## Props
+
+- **Type:** `IressPanelProps`
+- **Type declarations:** `@iress-oss/ids-components/dist/components/Panel/Panel.d.ts`
+
+```typescript
+import type { IressPanelProps } from '@iress-oss/ids-components';
+```
+
+
+---
+
+*View interactive examples: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-panel--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-panel--docs)*

package/.ai/components/pill.md

@@ -0,0 +1,83 @@
+# Pill
+
+Pills are used primarily for status updates, notifications and counts.
+
+> **Component:** `import { IressPill } from '@iress-oss/ids-components'`
+> **Storybook:** [Pill in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-pill--docs)
+
+## Quick Start
+
+```tsx
+import { IressPill } from '@iress-oss/ids-components';
+
+<IressPill>
+  Label
+</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:
+
+- Notification counts (e.g., unread messages, pending items)
+- Status indicators (success, warning, danger, info)
+- "New" or "Updated" labels
+- Drawing attention to important information
+- Quick visual highlights that don't require user interaction
+
+Pills are **informational** - they display information but are not meant to be interactive.
+
+**Not sure?** If users need to interact with items (click, delete, or manage selections), use [Tag](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-tag--docs) instead.
+
+## Examples
+
+### Mode
+
+The `mode` prop controls the colour scheme of the badge. Use data palette colours (10-90) for data visualization and non-semantic colour needs, or system status colours (`danger`, `info`, `success`, `warning`) for semantic status indication.
+
+```tsx
+<IressInline gap="sm">
+{BADGE_MODES.map((mode) => (
+<IressPill key={mode} mode={mode}>
+{mode}
+</IressPill>
+))}
+</IressInline>
+```
+
+[View "Mode" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-pill--mode)
+
+### Status
+
+System status colours provide semantic meaning for feedback and state indication. Available options are: `danger`, `info`, `success`, and `warning`.
+
+```tsx
+<IressInline gap="sm">
+{STATUSES.map((status) => (
+<IressPill mode={status} key={status}>
+{status}
+</IressPill>
+))}
+</IressInline>
+```
+
+[View "Status" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-pill--status)
+
+## Props
+
+- **Type:** `IressPillProps`
+- **Type declarations:** `@iress-oss/ids-components/dist/components/Pill/Pill.d.ts`
+
+```typescript
+import type { IressPillProps } from '@iress-oss/ids-components';
+```
+
+
+---
+
+*View interactive examples: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-pill--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-pill--docs)*

package/.ai/components/placeholder.md

@@ -0,0 +1,36 @@
+# Placeholder
+
+A placeholder is a UI element that allows you to reserve space for content that has not been created yet, usually used for prototyping.
+
+> **Component:** `import { IressPlaceholder } from '@iress-oss/ids-components'`
+> **Storybook:** [Placeholder in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-placeholder--docs)
+
+## Quick Start
+
+```tsx
+import { IressPlaceholder } from '@iress-oss/ids-components';
+
+<IressPlaceholder heading="Placeholder" width={300} height={300}>
+  This should be a description of the expected content
+</IressPlaceholder>
+```
+
+## Usage
+
+The `IressPlaceholder` component is a **last resort** component, as it provides very little context to the product team and/or user about what content will be placed in the placeholder.
+
+It is recommended to use placeholders that emulate the content that will be placed in the placeholder, such as images or text that is similar to the final content. This will help the product team and/or user understand what to expect in the final product.
+
+## Props
+
+- **Type:** `IressPlaceholderProps`
+- **Type declarations:** `@iress-oss/ids-components/dist/components/Placeholder/Placeholder.d.ts`
+
+```typescript
+import type { IressPlaceholderProps } from '@iress-oss/ids-components';
+```
+
+
+---
+
+*View interactive examples: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-placeholder--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-placeholder--docs)*

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

@@ -0,0 +1,80 @@
+# Recipes
+
+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`
+
+When an `IressMenu` is used inside `IressPopover`, it adds some additional functionality to the popover, including:
+
+- `IressPopover` will automatically close the popover when a menu item is clicked.
+- `IressMenu` will automatically focus the first menu item when the popover is opened.
+
+```tsx
+const [multiSelect, setMultiSelect] = useState(false);
+
+    return (
+      <IressStack gap="md" maxWidth="container.lg" px="lg" mx="auto">
+        {MENU_ROLES.map((role) => (
+          <IressRow gutter="lg" key={role} verticalAlign="middle">
+            <IressCol span={2}>
+              <IressPopover
+                {...args}
+                activator={<IressButton fluid>role={role}</IressButton>}
+                container={document.body}
+                type={role === 'listbox' || role === 'menu' ? role : undefined}
+              >
+                <IressMenu
+                  role={role}
+                  defaultSelected={3}
+                  multiSelect={multiSelect && role === 'listbox'}
+                >
+                  {menuChildren}
+                </IressMenu>
+              </IressPopover>
+            </IressCol>
+            <IressCol>
+              <MenuInPopoverRoleDescription role={role}>
+                {role === 'listbox' && (
+                  <IressToggle
+                    checked={multiSelect}
+                    onChange={() => setMultiSelect(!multiSelect)}
+                  >
+                    Multi-select
+                  </IressToggle>
+                )}
+              </MenuInPopoverRoleDescription>
+            </IressCol>
+          </IressRow>
+        ))}
+      </IressStack>
+    );
+```
+
+[View "WithMenu" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-popover--with-menu)
+
+## Focusable children
+
+If you are using the `listbox` or `menu` type popovers, you will notice that focusable children (with the exception of `IressMenuItem`) are not automatically focusable with the arrow keys. To make them focusable, you will need to embed the focusable children using the `usePopoverItem` hook.
+
+The `usePopoverItem` hook will automatically handle the focus management for you. It has two optional arguments:
+
+- The first argument is the typeahead label of the item you are registering. This will allow it to have a keyboard shortcut to focus the item.
+- The second argument is a virtual node, which is used in `virtualFocus` enabled popovers and `IressInputPopover`, to mimic the `onKeyDown` and `onBlur` events of the original element when the item is virtually focused using `aria-activedescendant`. If not provided, nothing will happen when the element is virtually focused.
+
+The `usePopoverItem` hook returns an object with the following properties:
+
+- `isActiveInPopover`: A boolean that indicates if the item is currently focused in the popover. This can be used to style the item differently when it is focused.
+- `...popoverItemProps`: The rest of the props that you should spread on the focusable element to make it focusable.
+
+```tsx
+<UsePopoverExample />
+```
+
+[View "FocusableChildren" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-popover--focusable-children)
+
+---
+
+*View interactive examples: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-popover--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-popover--docs)*