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

package/.ai/components/spinner.md

@@ -0,0 +1,68 @@
+# Spinner
+
+Spinners notify the user that a task is being processed. They indicate that the app is busy, and should be used when the user has to wait for more than a few seconds.
+
+> **Component:** `import { IressSpinner } from '@iress-oss/ids-components'`
+> **Storybook:** [Spinner in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-spinner--docs)
+
+## Quick Start
+
+```tsx
+import { IressSpinner } from '@iress-oss/ids-components';
+
+<IressSpinner screenreaderText="Loading..." />
+```
+
+import {
+  ComponentExample,
+  ComponentOverview,
+} from '@iress-oss/ids-storybook-config';
+
+## Examples
+
+### Standalone
+
+When using the spinner on its own, you can define the `screenreaderText` prop to provide context to screen readers.
+
+```tsx
+<IressSpinner screenreaderText="Making magic happen..." />
+```
+
+[View "Standalone" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-spinner--standalone)
+
+### Chatty variant
+
+The chatty variant displays an animated "typing" indicator with three dots. This is commonly used in chat interfaces to show that another user or system is currently typing a message.
+
+```tsx
+<IressSpinner variant="chatty" screenreaderText="User is typing..." />
+```
+
+[View "Chatty" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-spinner--chatty)
+
+### Message
+
+You can display a message alongside the spinner. In this case, you do not need to define the `screenreaderText` prop, as you have a visible message to the user telling them what is happening.
+
+```tsx
+<IressInline gap="sm" verticalAlign="middle">
+<IressSpinner color="colour.neutral.70" />
+<IressText color="colour.neutral.70">Making magic happen...</IressText>
+</IressInline>
+```
+
+[View "Message" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-spinner--message)
+
+## Props
+
+- **Type:** `IressSpinnerProps`
+- **Type declarations:** `@iress-oss/ids-components/dist/components/Spinner/Spinner.d.ts`
+
+```typescript
+import type { IressSpinnerProps } from '@iress-oss/ids-components';
+```
+
+
+---
+
+*View interactive examples: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-spinner--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-spinner--docs)*

package/.ai/components/stack.md

@@ -0,0 +1,121 @@
+# Stack
+
+Use IressStack to control vertical spacing between content with consistent present values.
+
+> **Component:** `import { IressStack } from '@iress-oss/ids-components'`
+> **Storybook:** [Stack in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-stack--docs)
+
+## Quick Start
+
+```tsx
+import { IressStack } from '@iress-oss/ids-components';
+
+<IressStack gap="spacing.1">
+  even
+</IressStack>
+```
+
+import {
+  ComponentExample,
+  ComponentOverview,
+} from '@iress-oss/ids-storybook-config';
+
+## Examples
+
+### Gap
+
+Vertical spacing is applied to the direct children of the `IressStack` component. The amount of spacing is controlled by the gap prop which accepts from `spacing.0` to `spacing.10`.
+
+#### What happened to `gutter`?
+
+The previous `gutter` prop has been replaced by `gap`, which uses the latest set of spacing tokens. In terms of how it is used to space items inside the `IressStack` component, it is now directly mapped to the [CSS gap property](https://developer.mozilla.org/en-US/docs/Web/CSS/gap), which may change how your application is spaced. For most cases, there should be no change.
+
+```tsx
+<IressStack gap="spacing.4">
+{SPACING_TOKENS.map((spacing) => (
+<IressText key={spacing}>
+<h2>{spacing}</h2>
+<IressStack gap={spacing as never} />
+</IressText>
+))}
+</IressStack>
+```
+
+[View "Gap" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-stack--gap)
+
+### Responsive gap
+
+The `gap` prop can take an object that takes five key/value pairs that correlate with the IDS breakpoints.
+
+```tsx
+<IressStack gap="spacing.4">
+<IressPanel>
+<p>
+Current breakpoint: <CurrentBreakpoint />.
+</p>
+<p>
+<code>gap=&#123;{JSON.stringify(args.gap)}&#125;</code>
+</p>
+</IressPanel>
+<IressStack />
+</IressStack>
+```
+
+[View "ResponsiveGap" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-stack--responsive-gap)
+
+### Inline children
+
+The stack component will treat the direct children as a block element. If you want to wrap some items to display them inline, wrap them with `IressInline`.
+
+In the example below: `IressButton` are inline because of wrapped by `IressInline`.
+
+```tsx
+<IressStack gap="spacing.4">
+  inlineChildren
+</IressStack>
+```
+
+[View "InlineChildren" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-stack--inline-children)
+
+### Lists
+
+`IressStack` can also apply gap between the list items by using the new `element` (e.g. `ul`) prop.
+
+```tsx
+<IressStack gap="spacing.7" element="ul">
+  list
+</IressStack>
+```
+
+[View "Lists" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-stack--lists)
+
+### Vertical alignment
+
+The `verticalAlign` prop controls how content is positioned vertically within the stack. It accepts six values: `top`, `middle`, `bottom`, `between`, `around`, and `evenly`.
+
+Use `top`, `middle`, or `bottom` to align items within the available space, and `between`, `around`, or `evenly` to distribute extra vertical space between items (similar to `space-between`, `space-around`, and `space-evenly` in CSS flexbox).
+
+```tsx
+<IressText>
+<h2>{args.verticalAlign}</h2>
+<IressPanel style={{ height: '1000px' }}>
+<IressStack stretch />
+</IressPanel>
+</IressText>
+```
+
+[View "VerticalAlign" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-stack--vertical-align)
+
+## Props
+
+- **Type:** `IressStackProps`
+- **Type declarations:** `@iress-oss/ids-components/dist/components/Stack/Stack.d.ts`
+
+```typescript
+import type { IressStackProps } from '@iress-oss/ids-components';
+```
+
+
+---
+
+*View interactive examples: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-stack--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-stack--docs)*

package/.ai/components/styled.md

@@ -0,0 +1,214 @@
+# Styled
+
+The IressStyled component provides an unopinionated wrapper that gives you direct access to all supported styling properties. Use it when you need custom styling without creating a dedicated component or writing custom CSS.
+
+> **Component:** `import { IressStyled } from '@iress-oss/ids-components'`
+> **Storybook:** [Styled in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-styled--docs)
+
+## Quick Start
+
+```tsx
+import { IressStyled } from '@iress-oss/ids-components';
+
+<IressStyled p="spacing.4" bg="colour.neutral.20" borderRadius="radius.2">
+  This is styled content using Panda CSS
+</IressStyled>
+```
+
+import {
+  ComponentExample,
+  ComponentOverview,
+} from '@iress-oss/ids-storybook-config';
+
+## Usage
+
+### The `element` prop
+
+With the `element` prop you can select which HTML element the component should render as. It renders as a `div` by default, but can be set to any standard HTML element like `section`, `article`, `aside`, `nav`, `main`, `header`, `footer`, or `span`.
+
+This allows you to maintain proper semantic HTML structure while applying custom styling.
+
+```tsx
+<IressStack gap="spacing.3">
+<IressStyled element="section"
+p="spacing.4"
+bg="colour.neutral.20"
+borderRadius="radius.2"
+>
+<IressText element="h3">Section Element</IressText>
+<IressText>This is rendered as a section element.</IressText>
+</IressStyled>
+
+<IressStyled element="article"
+p="spacing.4"
+bg="colour.neutral.20"
+borderRadius="radius.2"
+>
+<IressText element="h3">Article Element</IressText>
+<IressText>This is rendered as an article element.</IressText>
+</IressStyled>
+
+<IressStyled element="aside"
+p="spacing.4"
+bg="colour.neutral.20"
+borderRadius="radius.2"
+>
+<IressText element="h3">Aside Element</IressText>
+<IressText>This is rendered as an aside element.</IressText>
+</IressStyled>
+
+<IressStyled element="nav"
+p="spacing.4"
+bg="colour.neutral.20"
+borderRadius="radius.2"
+>
+<IressText element="h3">Nav Element</IressText>
+<IressText>This is rendered as a nav element.</IressText>
+</IressStyled>
+</IressStack>
+```
+
+[View "Elements" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-styled--elements)
+
+### Styling props
+
+You can apply any of the styling props supported by the design system.
+
+[View supported styling props](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_styling-props-reference--docs#reference)
+
+#### Spacing
+
+Use spacing tokens to control padding and margin. The spacing system provides consistent values from `spacing.0` to `spacing.10`.
+
+```tsx
+<IressStack gap="spacing.3">
+<IressStyled p="spacing.2"
+bg="colour.neutral.20"
+borderRadius="radius.2"
+>
+<IressText>Small padding (spacing.2)</IressText>
+</IressStyled>
+
+<IressStyled p="spacing.4"
+bg="colour.neutral.20"
+borderRadius="radius.2"
+>
+<IressText>Medium padding (spacing.4)</IressText>
+</IressStyled>
+
+<IressStyled p="spacing.6"
+bg="colour.neutral.20"
+borderRadius="radius.2"
+>
+<IressText>Large padding (spacing.6)</IressText>
+</IressStyled>
+
+<IressStyled m="spacing.4"
+p="spacing.4"
+bg="colour.system.info.surface"
+borderRadius="radius.2"
+>
+<IressText>With margin (spacing.4)</IressText>
+</IressStyled>
+</IressStack>
+```
+
+[View "Spacing" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-styled--spacing)
+
+#### Colors
+
+Apply design system color tokens to set background colors, text colors, and border colors. Use semantic color tokens like `colour.system.info.surface` for consistent theming.
+
+```tsx
+<IressStack gap="spacing.3">
+<IressStyled p="spacing.4"
+bg="colour.system.info.surface"
+color="colour.system.info.text"
+borderRadius="radius.2"
+>
+<IressText>Info color scheme</IressText>
+</IressStyled>
+
+<IressStyled p="spacing.4"
+bg="colour.system.success.surface"
+color="colour.system.success.text"
+borderRadius="radius.2"
+>
+<IressText>Success color scheme</IressText>
+</IressStyled>
+
+<IressStyled p="spacing.4"
+bg="colour.system.warning.surface"
+color="colour.system.warning.text"
+borderRadius="radius.2"
+>
+<IressText>Warning color scheme</IressText>
+</IressStyled>
+
+<IressStyled p="spacing.4"
+bg="colour.system.danger.surface"
+color="colour.system.danger.text"
+borderRadius="radius.2"
+>
+<IressText>Danger color scheme</IressText>
+</IressStyled>
+</IressStack>
+```
+
+[View "Colors" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-styled--colors)
+
+#### Complex compositions
+
+Combine multiple styling properties to create rich, semantic HTML structures. The component provides full access to Panda CSS props for maximum flexibility.
+
+```tsx
+<IressStyled maxWidth="2/12"
+m="auto"
+p="spacing.5"
+bg="colour.neutral.10"
+borderRadius="radius.4"
+>
+<IressStyled mb="spacing.4">
+<IressIcon
+name="info"
+color="colour.system.info.text"
+textStyle="typography.heading.4"
+/>
+<IressText element="h2" textStyle="typography.heading.3">
+Complex Styled Component
+</IressText>
+</IressStyled>
+
+<IressText element="p" mb="spacing.3">
+The <code>IressStyled</code> component provides full access to Panda CSS
+styling props, allowing you to create complex layouts and designs
+without writing custom CSS.
+</IressText>
+
+<IressStyled p="spacing.4" bg="colour.neutral.20" borderRadius="radius.2">
+<IressText>
+This example demonstrates combining multiple styling properties to
+create a rich, semantic HTML structure with custom styling.
+</IressText>
+</IressStyled>
+</IressStyled>
+```
+
+[View "Complex" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-styled--complex)
+
+## When to use
+
+- **Custom layouts**: When you need to create a unique layout that doesn't match existing components
+- **Semantic HTML**: When you need to use specific HTML elements with custom styling
+- **Quick prototyping**: For rapid development without creating dedicated styled components
+- **One-off designs**: When a design pattern doesn't warrant creating a reusable component
+
+## When not to use
+
+- **Repeated patterns**: If you're using the same styling multiple times, create a dedicated component instead
+- **Simple spacing**: Use layout components like `IressStack` or `IressInline` for simple spacing needs
+- **Typography**: Use `IressText` for text styling with semantic elements
+
+---
+
+*View interactive examples: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-styled--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-styled--docs)*

package/.ai/components/tab-set.md

@@ -0,0 +1,119 @@
+# Tab Set
+
+Tabs are used to display modular pieces of related data that do not need to be compared or accessed simultaneously.
+
+> **Component:** `import { IressTabSet } from '@iress-oss/ids-components'`
+> **Storybook:** [Tab Set in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-tab-set--docs)
+
+## Quick Start
+
+```tsx
+import { IressTabSet } from '@iress-oss/ids-components';
+
+<IressTabSet />
+```
+
+import {
+  ComponentExample,
+  ComponentOverview,
+} from '@iress-oss/ids-storybook-config';
+
+## Usage
+
+The `IressTabSet` is a wrapper for `IressTab` components to make a up a set of tabs.
+
+### Navigation
+
+You can use the `IressTabSet` component to create tab navigation to control an area of the page, or even navigate between different pages.
+
+[View "TabNavigation" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-tab-set--tab-navigation)
+
+### With `children` prop
+
+Using the `children` prop will automatically inject the content as a tab panel when active, along with appropriate attributes for accessibility, ensuring the tab and its associated panel can be navigated by screenreaders.
+
+[View "Panels" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-tab-set--panels)
+
+## Examples
+
+### Default selected
+
+If you would like to set a tab by default, use the `defaultSelected` prop.
+
+```tsx
+<IressTabSet defaultSelected={1} />
+```
+
+[View "DefaultSelected" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-tab-set--default-selected)
+
+### Controlled
+
+You can use state to control the active tab by setting the `selected` property to which tab you would like to select. This should be the `value` of the tab you would like to select, or if you do not use the `value` prop, it's index.
+
+```tsx
+<TabsUsingState />
+```
+
+[View "Controlled" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-tab-set--controlled)
+
+### Layout
+
+`IressTabSet` controls the layout of the tab buttons. These will always appear at the top of the tab container, and can be aligned to the left (default), centrally or to the right via the `layout` prop.
+
+```tsx
+<IressStack gap="md">
+<IressPanel>
+<IressText element="h2">top-left</IressText>
+<IressTabSet layout="top-left" />
+</IressPanel>
+<IressPanel>
+<IressText element="h2">top-center</IressText>
+<IressTabSet layout="top-center" />
+</IressPanel>
+<IressPanel>
+<IressText element="h2">top-right</IressText>
+<IressTabSet layout="top-right" />
+</IressPanel>
+</IressStack>
+```
+
+[View "Layout" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-tab-set--layout)
+
+### Lazy Loading
+
+Tabs can be lazy loaded via state, allowing you to add/remove tabs as needed.
+
+```tsx
+<TabsLazyLoading />
+```
+
+[View "LazyLoading" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-tab-set--lazy-loading)
+
+### Badges and icons
+
+You can add rich content into the `label` of the `IressTab` to customise the tab further.
+
+Some common examples include:
+
+- Adding a badge to the tab button.
+- Adding icons to the tab button.
+
+Notes:
+
+- For best accessibility, the `IressTab` component will find the first focusable element inside the custom label to add the tab role.
+
+[View "TabsWithBadges" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-tab-set--tabs-with-badges)
+
+## Props
+
+- **Type:** `IressTabSetProps`
+- **Type declarations:** `@iress-oss/ids-components/dist/components/TabSet/TabSet.d.ts`
+
+```typescript
+import type { IressTabSetProps } from '@iress-oss/ids-components';
+```
+
+
+---
+
+*View interactive examples: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-tab-set--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-tab-set--docs)*

package/.ai/components/tab.md

@@ -0,0 +1,71 @@
+# Tab
+
+A tab is an interactive element that controls the display of other content, usually a panel
+
+> **Component:** `import { IressTab } from '@iress-oss/ids-components'`
+> **Storybook:** [Tab in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-tab--docs)
+
+## Quick Start
+
+```tsx
+import { IressTab } from '@iress-oss/ids-components';
+
+<IressTab label="Tab" />
+```
+
+import {
+  ComponentExample,
+  ComponentOverview,
+} from '@iress-oss/ids-storybook-config';
+
+## Examples
+
+### Active
+
+The tab can be set to active using the `active` prop.
+
+**Note:** If you are using `IressTabSet`, you should use the `selected` prop on the `IressTabSet` to set the active state of its `<IressTab />` children, as the `active` prop will be ignored.
+
+```tsx
+<IressTab active />
+```
+
+[View "Active" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-tab--active)
+
+### Value
+
+A tab can have a unique value set to it, used to determine its active state in a `IressTabSet` component. The value is not visible to end users.
+
+```tsx
+<IressTabSet>
+<IressTab />
+</IressTabSet>
+```
+
+[View "Value" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-tab--value)
+
+### Panel
+
+A tab can set its `children` when used inside an `IressTabSet` component, and it will render as its panel. If the tab is not used inside an `IressTabSet` component, `children` will not render.
+
+```tsx
+<IressTabSet>
+<IressTab />
+</IressTabSet>
+```
+
+[View "Panel" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-tab--panel)
+
+## Props
+
+- **Type:** `IressTabProps`
+- **Type declarations:** `@iress-oss/ids-components/dist/components/TabSet/Tab/Tab.d.ts`
+
+```typescript
+import type { IressTabProps } from '@iress-oss/ids-components';
+```
+
+
+---
+
+*View interactive examples: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-tab--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-tab--docs)*