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

package/.ai/components/link.md

@@ -0,0 +1,95 @@
+# Link
+
+A link is used to navigate to another page or location.
+
+> **Component:** `import { IressLink } from '@iress-oss/ids-components'`
+> **Storybook:** [Link in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-link--docs)
+
+## Quick Start
+
+```tsx
+import { IressLink } from '@iress-oss/ids-components';
+
+<IressLink href="//iress.com">
+  IressLink
+</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.
+
+If you provide a `href`, it will render as an `<a />` element. Otherwise it will render as a `<button />` element. This helps ensure it presents the correct role to assistive technologies for the best accessibility.
+
+## When to use
+
+- If you want to include a link alongside static text, use the `IressLink` component.
+- If you want to have a call to action at the start or end of a block of contents, use the `IressButton` component instead.
+
+## Examples
+
+### Loading
+
+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...).
+
+When the loading state is activated, any click events on the link are disabled.
+
+```tsx
+<IressLink loading>
+  Link text
+</IressLink>
+```
+
+[View "Loading" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-link--loading)
+
+### Slot props
+
+Use the slots to correctly position icons or badges inside buttons.
+
+- **Prepend** - Places the element before the text
+- **Append** - Places the element after the text
+
+```tsx
+<IressInline gap="md">
+<IressLink prepend={<IressIcon name="home" />}>
+Prepend icon
+</IressLink>
+
+<IressLink append={<IressIcon name="home" />}>
+Append icon
+</IressLink>
+</IressInline>
+```
+
+[View "Slots" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-link--slots)
+
+### Element
+
+You can use the `element` prop to render a custom component as the link. This is useful for rendering a component from a third-party library, such as `react-router-dom`.
+
+```tsx
+<RoutingLink />
+```
+
+[View "Element" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-link--element)
+
+## Props
+
+- **Type:** `IressLinkProps`
+- **Type declarations:** `@iress-oss/ids-components/dist/components/Link/Link.d.ts`
+
+```typescript
+import type { IressLinkProps } from '@iress-oss/ids-components';
+```
+
+
+---
+
+*View interactive examples: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-link--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-link--docs)*

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

@@ -0,0 +1,140 @@
+# Menu Item
+
+Menu items are headings, buttons and dividers used inside an `IressMenu`
+
+> **Component:** `import { IressMenuItem } from '@iress-oss/ids-components'`
+> **Storybook:** [Menu Item in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-menu-item--docs)
+
+## Quick Start
+
+```tsx
+import { IressMenuItem } from '@iress-oss/ids-components';
+
+<IressMenuItem>
+  Menu item
+</IressMenuItem>
+```
+
+import {
+  ComponentExample,
+  ComponentOverview,
+} from '@iress-oss/ids-storybook-config';
+
+## Examples
+
+### Selected
+
+The `IressMenuItem` can be set to selected using the `selected` prop.
+
+**Note:** If you are using `IressMenu` with a `role` of `listbox`, you should use the `defaultSelected` or `selected` prop on the `IressMenu` to set the selected state of its `<IressMenuItem />` children, as the `selected` prop will be ignored.
+
+```tsx
+<IressMenuItem selected />
+```
+
+[View "Selected" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-menu-item--selected)
+
+### Value
+
+A menu item can have a unique value set to it, used to determine its selected state in a `IressMenu` component with a `role` of `listbox`. The value is not visible to end users.
+
+```tsx
+<IressMenu role="listbox">
+<IressMenuItem />
+</IressMenu>
+```
+
+[View "Value" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-menu-item--value)
+
+### `canToggle`
+
+When `canToggle` is set to true, the menu item can be toggled between selected and unselected states. This only works in a `IressMenu` component with a `role` of `listbox`.
+
+```tsx
+<IressMenuItem canToggle />
+```
+
+[View "CanToggle" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-menu-item--can-toggle)
+
+### Prepend and append
+
+You can prepend and append content to a menu item using the `prepend` and `append` props.
+
+[View "PrependAndAppend" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-menu-item--prepend-and-append)
+
+### Multi-select menus
+
+Inside a `IressMenu` with a `role` of `listbox` and the `multiSelect` prop set to true, the menu item will display with a checkbox.
+
+```tsx
+<IressMenu role="listbox" multiSelect>
+<IressMenuItem />
+<IressMenuItem />
+</IressMenu>
+```
+
+[View "MultiSelect" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-menu-item--multi-select)
+
+### Element
+
+You can use the `element` prop to render a custom component inside the menu item. This is useful for rendering a component from a third-party library, such as `react-router-dom`.
+
+```tsx
+<RoutingLinkMenu />
+```
+
+[View "Element" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-menu-item--element)
+
+### Divider
+
+When `divider` is set to true, the menu item will render with a bottom border.
+
+```tsx
+<IressMenuItem divider>
+  Menu item with divider
+</IressMenuItem>
+```
+
+[View "Divider" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-menu-item--divider)
+
+However, it is recommended to use the `IressMenuDivider` component instead.
+
+[View "Divider" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-menu-divider--divider)
+
+### Heading
+
+You can use the `IressMenuHeading` to render headings within a menu. This adds styling so the appropriate padding is applied.
+
+```tsx
+<IressMenu>
+<IressMenuHeading />
+</IressMenu>
+```
+
+[View "Heading" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-menu-heading--heading)
+
+### Text
+
+You can use the `IressMenuText` to render other text within a menu. This adds styling so the appropriate padding is applied.
+
+```tsx
+<IressMenu>
+<IressMenuText />
+</IressMenu>
+```
+
+[View "Text" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-menu-text--text)
+
+## Props
+
+- **Type:** `IressMenuItemProps`
+- **Type declarations:** `@iress-oss/ids-components/dist/components/Menu/MenuItem/MenuItem.d.ts`
+
+```typescript
+import type { IressMenuItemProps } from '@iress-oss/ids-components';
+```
+
+
+---
+
+*View interactive examples: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-menu-item--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-menu-item--docs)*

package/.ai/components/menu.md

@@ -0,0 +1,285 @@
+# Menu
+
+A menu can display grouped action buttons, navigation items or headings.
+
+> **Component:** `import { IressMenu } from '@iress-oss/ids-components'`
+> **Storybook:** [Menu in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-menu--docs)
+
+## Quick Start
+
+```tsx
+import { IressMenu } from '@iress-oss/ids-components';
+
+<IressMenu />
+```
+
+import {
+  ComponentExample,
+  ComponentOverview,
+} from '@iress-oss/ids-storybook-config';
+
+## Usage
+
+### Basic
+
+`IressMenuDivider`, `IressMenuHeading`, `IressMenuItem` and `IressMenuText` should be supplied as `children` of the menu.
+
+- `IressMenuDivider` can be used to display a divider, it supports all of the props of `hr`. It will adjust according to the menu's role and layout.
+- `IressMenuHeading` is used to display headings. It supports all of the props of `IressText` and will adjust according to the menu's role and layout.
+- `IressMenuItem` is used to display an interactive item. If provided a `href` prop will render the item as a link, otherwise it will render as a button.
+- `IressMenuText` can be used to display other non-interactive text. It supports all of the props of `IressText`.
+
+```tsx
+<IressMenu defaultSelected={5}>
+  basic
+</IressMenu>
+```
+
+[View "Basic" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-menu--basic)
+
+### Complex
+
+`IressMenuItem`, `IressMenuHeading` and `IressMenuText` support `prepend`, `divider` and `append` slots, to allow you to create complex menu items.
+
+Note: Instead of using the `divider` prop on `IressMenuItem`, you can use `IressMenuDivider` to separate items. This gives you more control over where the divider sits.
+
+```tsx
+<IressMenu maxWidth="input.25%">
+  complex
+</IressMenu>
+```
+
+[View "Complex" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-menu--complex)
+
+## Examples
+
+### Secondary navigation
+
+When the `href` prop is set on `IressMenuItem`, it will render as a link.
+
+When rendering a set of links for navigation purposes (as a secondary nav in this example) make sure you wrap the `IressMenu` in a nav element and set the menu's `role` prop to list.
+
+```tsx
+<nav aria-label="Secondary">
+<IressMenu />
+</nav>
+```
+
+[View "SecondaryNavigation" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-menu--secondary-navigation)
+
+### Headings
+
+Using the `IressMenuHeading` component, you can create headings within the menu. Simply set the `element` or `textStyle` prop to your desired heading level.
+
+```tsx
+<IressMenu>
+  headings
+</IressMenu>
+```
+
+[View "Headings" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-menu--headings)
+
+### Dividers
+
+When the `divider` prop is set, the `IressMenuItem`, `IressMenuHeading` and `IressMenuText` will render a bottom border.
+
+In situations where a bottom border will not work, you can also use `IressMenuDivider` inside the menu to separate items.
+
+```tsx
+<IressMenu>
+  dividers
+</IressMenu>
+```
+
+[View "Dividers" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-menu--dividers)
+
+### Fluid menus
+
+By setting the `fluid` prop on the menu component, the menu will stretch to the width of its containing element.
+
+```tsx
+<IressMenu fluid />
+```
+
+[View "Fluid" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-menu--fluid)
+
+### Layout
+
+The `layout` prop comes with three options:
+
+- `stack` (default) - menu items will stack on top of each other
+- `inline` - menu items will be inline
+- `inline-equal-width` - menu items will be inline and have equal width
+
+```tsx
+<IressStack gap="lg">
+<IressText>
+<h3>Stack (default)</h3>
+<IressMenu layout="stack" />
+</IressText>
+<IressText>
+<h3>Inline</h3>
+<IressMenu layout="inline" />
+</IressText>
+<IressText>
+<h3>Inline Equal Width</h3>
+<IressMenu layout="inline-equal-width" />
+</IressText>
+</IressStack>
+```
+
+[View "Layout" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-menu--layout)
+
+### Text wrapping
+
+By default, menu item text will wrap on to the next line when it exceeds the menu width. Using the `noWrap` prop, you set the menu item text to not wrap.
+
+```tsx
+<IressInline>
+<IressMenu width="input.12">
+<IressMenuItem>Menu item with some text that wraps</IressMenuItem>
+</IressMenu>
+<IressMenu width="input.12" noWrap>
+<IressMenuItem>Non wrapping menu item with some text</IressMenuItem>
+</IressMenu>
+</IressInline>
+```
+
+[View "NoWrap" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-menu--no-wrap)
+
+### Slot props
+
+`IressMenuItem`, `IressMenuHeading` and `IressMenuText` provide `prepend` and `append` props to position content either before or after its content.
+
+```tsx
+<IressMenu role="menu">
+  slots
+</IressMenu>
+```
+
+[View "SlotProps" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-menu--slot-props)
+
+### Roles
+
+The `role` prop that comes with the menu component not only changes the aria-role of the menu to allow it to be easily recognised in screen readers, but also changes how the menu is interacted with.
+
+There are four roles supported:
+
+- `list` (default): The menu is treated as a list of items. Child menu subcomponents render with the `listitem` role where appropriate. The user navigates using the `tab` key.
+- `menu`: The menu is treated as a menu of items. Child menu subcomponents render with the `menuitem` role where appropriate. The user navigates using `arrow` keys.
+- `listbox`: The menu is treated as a list of selectable items, similar to a `<select />`. Child menu subcomponents render with the `option` role where appropriate. The user navigates using `arrow` keys.
+
+**Note:** When menu is used as a child of popover, the `type` that is set on popover will be applied to menu (so you don't need to set it twice).
+
+#### List
+
+The default role for the menu component is `list`. It is most often used for navigation and its items can be navigated (using the keyboard) with the `tab` key.
+
+```tsx
+<IressMenu defaultSelected={5}>
+  basic
+</IressMenu>
+```
+
+[View "ListRole" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-menu--list-role)
+
+#### Menu
+
+The `menu` role is used when the items in the menu has an action that performs a task in the application. The items can be navigated (using the keyboard) with the `arrow` keys, depending on the layout.
+
+```tsx
+<IressMenu role="menu" />
+```
+
+[View "MenuRole" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-menu--menu-role)
+
+#### Listbox
+
+The `listbox` role is used for lists from which a user may select one or more items.
+
+A value is supplied to `IressMenuButton` (like you would with an option element inside a select) and a `onChange` event is emitted with the selected value(s) whenever the selection is changed by the user.
+
+Set the `multiSelect` prop to true for a multi-selectable listbox.
+
+```tsx
+<IressMenu role="listbox">
+  selectable
+</IressMenu>
+```
+
+[View "ListboxRole" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-menu--listbox-role)
+
+### Variants
+
+The `variant` prop can be used to change the style of the menu to suit different contexts. There are two variants:
+
+- Not defined - for use inside popovers, side menus and navigation
+- `subdraw` - for use with navigation drawers, it adds an arrow icon to the end of menu items to indicate that they will open a sub-menu.
+- `radio` - for use when you want the menu item to have a radio mark style indicator (only supports single select listbox role)
+
+```tsx
+<IressStack gap="lg">
+<IressMenu variant="radio" />
+<IressMenu variant="subdraw" maxWidth="input.12" />
+<IressMenu variant="side" maxWidth="input.12" />
+<IressMenu variant="side" maxWidth="input.12" numbered />
+<IressMenu children={MENU_CHILDREN_OPTIONS.groupedIcons}
+variant="rail"
+/>
+</IressStack>
+```
+
+[View "Variants" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-menu--variants)
+
+### Menu Groups
+
+`IressMenuGroup` can be used to group related menu items together under a common label.
+
+#### Default (Inline)
+
+By default, `IressMenuGroup` renders the label as a non-focusable heading with the children displayed inline below it.
+
+```tsx
+<IressMenu>
+  <IressMenuGroup label="Recent Files">
+    <IressMenuItem>Document.pdf</IressMenuItem>
+    <IressMenuItem>Spreadsheet.xlsx</IressMenuItem>
+  </IressMenuGroup>
+</IressMenu>
+```
+
+#### Subdraw Variant
+
+When `variant="subdraw"` is set, the group label becomes a clickable menu item that opens a fly-over submenu containing the group's children. This is useful for organizing large menus into collapsible sections.
+
+```tsx
+<IressMenu>
+  <IressMenuGroup label="More Options" variant="subdraw">
+    <IressMenuItem>Option 1</IressMenuItem>
+    <IressMenuItem>Option 2</IressMenuItem>
+    <IressMenuItem>Option 3</IressMenuItem>
+  </IressMenuGroup>
+</IressMenu>
+```
+
+The subdraw variant:
+
+- Renders the label as a `IressMenuItem` with a chevron icon
+- Opens a popover submenu when clicked
+- Supports proper ARIA attributes (`aria-haspopup`, `aria-expanded`)
+- Can be nested for multi-level submenus
+- Closes on Escape key or click outside
+
+## Props
+
+- **Type:** `IressMenuProps`
+- **Type declarations:** `@iress-oss/ids-components/dist/components/Menu/Menu.d.ts`
+
+```typescript
+import type { IressMenuProps } from '@iress-oss/ids-components';
+```
+
+
+---
+
+*View interactive examples: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-menu--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-menu--docs)*