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

package/.ai/components/button.md

@@ -0,0 +1,326 @@
+# Button
+
+A button is a clickable item used to perform an action.
+
+> **Component:** `import { IressButton } from '@iress-oss/ids-components'`
+> **Storybook:** [Button in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-button--docs)
+
+## Quick Start
+
+```tsx
+import { IressButton } from '@iress-oss/ids-components';
+
+<IressButton>
+  Button
+</IressButton>
+```
+
+import {
+  ComponentOverview,
+  ComponentExample,
+} from '@iress-oss/ids-storybook-config';
+
+## Examples
+
+### Modes
+
+The `mode` prop controls the visual appearance and priority of the button.
+
+- **Primary:** Use for the main call to action. Limit to one per view.
+- **Secondary:** Use for secondary calls to action.
+- **Tertiary:** Use when you need extra affordance between your secondary actions.
+- **Quaternary:** Use for less prominent actions, often used for preference toggles (eg. Collapse all).
+- **Muted:** Use for less prominent actions, often in toolbars or inline with headings. Mainly used for icon-only buttons.
+
+```tsx
+<IressInline gap="md">
+<IressButton mode="primary">
+Primary button
+</IressButton>
+<IressButton mode="secondary">
+Secondary button
+</IressButton>
+<IressButton mode="tertiary">
+Tertiary button
+</IressButton>
+<IressButton mode="quaternary">
+Quaternary button
+</IressButton>
+<IressButton mode="muted" icon="share">
+Share
+</IressButton>
+</IressInline>
+```
+
+[View "Mode" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-button--mode)
+
+### Status
+
+The `status` prop allows you to apply a visual status to the button.
+
+- **Success:** Usually used to indicate an action that should be perceived as positive, such as "Confirm" or "Buy".
+- **Danger:** Use for destructive actions, such as "Delete" or "Remove". Also used for actions that are perceived as negative, such as "Cancel" or "Sell".
+
+```tsx
+<IressStack gap="md">
+<IressInline gap="md">
+<IressButton mode="primary" status="success">
+Primary button
+</IressButton>
+<IressButton mode="secondary" status="success">
+Secondary button
+</IressButton>
+<IressButton mode="tertiary" status="success">
+Tertiary button
+</IressButton>
+<IressButton mode="quaternary" status="success">
+Quaternary button
+</IressButton>
+<IressButton
+mode="muted"
+status="success"
+icon="shopping_cart">
+Add to cart
+</IressButton>
+</IressInline>
+<IressInline gap="md">
+<IressButton mode="primary" status="danger">
+Primary button
+</IressButton>
+<IressButton mode="secondary" status="danger">
+Secondary button
+</IressButton>
+<IressButton mode="tertiary" status="danger">
+Tertiary button
+</IressButton>
+<IressButton mode="quaternary" status="danger">
+Quaternary button
+</IressButton>
+<IressButton mode="muted" status="danger" icon="delete">
+Delete
+</IressButton>
+</IressInline>
+</IressStack>
+```
+
+[View "Status" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-button--status)
+
+### Types
+
+The `type` property controls the behaviour of the button. It defaults to `button`, which is the best option for most situations, but can also be set to `submit` or `reset`. `submit` should be used for buttons that submit forms, and `reset` should be used if the button clears form data and resets the form to its original state.
+
+**Please note:** this differs from a standard HTML button element, where the `type` defaults to submit.
+
+```tsx
+<IressInline gap="md">
+<IressButton type="button">
+button
+</IressButton>
+<IressButton type="submit">
+submit
+</IressButton>
+<IressButton type="reset">
+reset
+</IressButton>
+</IressInline>
+```
+
+[View "Types" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-button--types)
+
+### 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 button are disabled.
+
+```tsx
+<IressInline gap="md">
+<IressButton mode="primary">
+...
+</IressButton>
+<IressButton mode="secondary">
+...
+</IressButton>
+<IressButton mode="tertiary">
+...
+</IressButton>
+<IressButton mode="quaternary">
+...
+</IressButton>
+<IressButton mode="muted">
+<IressIcon name="edit" />
+</IressButton>
+</IressInline>
+```
+
+[View "Loading" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-button--loading)
+
+### Buttons as links
+
+The `href` prop allows you to create a link that looks like a button. When set, the component will render an HTML anchor element instead of an HTML button element. This can be useful when you want to increase the target area and visual weight of a link, without changing the markup.
+
+A good example of this is the Next and Previous links in a wizard layout. These should be HTML links (to tells the user that navigation will occur when clicked) but styling them as buttons makes them more prominent.
+
+You can also use the link specific props `target` and `rel`.
+
+```tsx
+<IressButton href="https://www.iress.com/" rel="opener noreferrer" target="_blank">
+  This is a link (anchor tag)
+</IressButton>
+```
+
+[View "ButtonsAsLinks" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-button--buttons-as-links)
+
+### Delete confirmation
+
+> [!WARNING]
+> **Make sure that the user understands the consequences of clicking the button**
+>
+> You may want to add a confirmation step to prevent accidental data loss if the
+>   action is irreversible.
+
+The confirmation step should be a modal with a simple message, as with the example below. Use a delete button for the modal's primary call to action, and use a secondary button for the cancel action.
+
+If you're using a heading, ensure that it has an appropriate heading level to match the document structure. You should use a danger variant of the `IressText` element, with the element prop set to the appropriate heading level.
+
+```tsx
+<IressButton status="danger">
+  Delete button with confirm
+</IressButton>
+```
+
+[View "DeleteConfirmation" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-button--delete-confirmation)
+
+### Fluid
+
+If the `fluid` prop is set to true, the button will expand to be 100% of the width of its container.
+
+The `fluid` prop can also be set to a breakpoint size, which means the button will be fluid up until its breakpoint is passed.
+
+```tsx
+<IressInline gap="md">
+<IressText element="p">
+Please resize your screen to see how the fluid value changes. Current
+breakpoint: <CurrentBreakpoint renderLabel="and-above" />.
+</IressText>
+<IressButton fluid>
+Always fluid
+</IressButton>
+<IressButton fluid="md">
+Fluid on xs and sm
+</IressButton>
+</IressInline>
+```
+
+[View "Fluid" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-button--fluid)
+
+### Wrapping text
+
+Button text will wrap on to a new line if there's not enough space for the text to sit on a single line. If you want to prevent the text from wrapping, you can set the `noWrap` prop to `true`.
+
+If your button contains a lot of text, the text may wrap on to more than one line. You can manage this on a case by case basis by setting a minimum width on your button via CSS if you need to.
+
+```tsx
+<IressText style={{ width: 250 }}>
+<p>
+<IressButton>
+Button with lots of text content that will wrap (default behaviour)
+</IressButton>
+</p>
+
+<p>
+<IressButton style={{ minWidth: 300 }}>
+Button with lots of text content and a minimum width set via CSS
+</IressButton>
+</p>
+
+<p>
+<IressButton noWrap>
+Button with lots of text content with the noWrap prop set to true
+</IressButton>
+</p>
+</IressText>
+```
+
+[View "WrappingText" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-button--wrapping-text)
+
+### 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
+
+The iconOnly slot from previous versions of IDS has been deprecated. Please use the default slot instead.
+
+```tsx
+<IressStack gap="md">
+<IressInline gap="md">
+<IressButton prepend={<IressIcon name="home" />}>
+Prepend icon
+</IressButton>
+</IressInline>
+
+<IressInline gap="md">
+<IressButton append={<IressIcon name="home" />}>
+Append icon
+</IressButton>
+
+<IressButton append={<IressPill>+999</IressPill>}>
+Append pill
+</IressButton>
+</IressInline>
+
+<IressInline gap="md">
+<IressButton icon="home">
+Home
+</IressButton>
+</IressInline>
+</IressStack>
+```
+
+[View "Slots" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-button--slots)
+
+### Download button
+
+When a `href` is provided, the `download` prop can be used to indicate that the link should download a file instead of navigating to it. This is useful for links to files such as PDFs or images.
+
+```tsx
+<IressButton download prepend={<IressIcon name="download" />} />
+```
+
+[View "DownloadButton" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-button--download-button)
+
+### Element
+
+You can use the `element` prop to render a custom component as the button. This is useful for rendering a component from a third-party library, such as `react-router-dom`.
+
+```tsx
+<RoutingButton />
+```
+
+[View "Element" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-button--element)
+
+## `IressCloseButton`
+
+`IressCloseButton` is a special variant of `IressButton` that is used to execute a close action. It is used in modals, slideouts, and other components that require a close button.
+
+It has one additional prop, `screenReaderText`, which is used to provide a screen reader only label for the close button.
+
+[View "CloseButton" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-close-button--close-button)
+
+## Props
+
+- **Type:** `IressButtonProps`
+- **Type declarations:** `@iress-oss/ids-components/dist/components/Button/Button.d.ts`
+
+```typescript
+import type { IressButtonProps } from '@iress-oss/ids-components';
+```
+
+
+---
+
+*View interactive examples: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-button--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-button--docs)*

package/.ai/components/card.md

@@ -0,0 +1,254 @@
+# Card
+
+Cards are used to group small, related pieces of information into one digestible unit.
+
+> **Component:** `import { IressCard } from '@iress-oss/ids-components'`
+> **Storybook:** [Card in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-card--docs)
+
+## Quick Start
+
+```tsx
+import { IressCard } from '@iress-oss/ids-components';
+
+<IressCard>
+  I'm a card
+</IressCard>
+```
+
+import {
+  ComponentOverview,
+  ComponentExample,
+} from '@iress-oss/ids-storybook-config';
+
+## Examples
+
+### Simple cards
+
+All slots and props for card are optional. You can create a simple card by adding some content to the default slot.
+
+```tsx
+<IressCard>
+  I'm a simple card
+</IressCard>
+```
+
+[View "Simple" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-card--simple)
+
+### No border
+
+The `noBorder` prop can be used to remove the border from the card, which is useful when you want to de-prioritise a card within another bordered container, such as a card within a sidebar.
+
+```tsx
+<IressCard noBorder />
+```
+
+[View "NoBorder" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-card--no-border)
+
+### Padding
+
+Padding can be controlled using the `p` prop. It can be set to `none`, `sm`, `md` or `lg`. It defaults to `md`.
+
+```tsx
+<IressStack gap="md">
+<IressCard p="none">
+I&rsquo;m a card with no padding
+</IressCard>
+<IressCard p="xs">
+I&rsquo;m a card with xs padding
+</IressCard>
+<IressCard p="sm">
+I&rsquo;m a card with sm padding
+</IressCard>
+<IressCard p="md">
+I&rsquo;m a card with md padding
+</IressCard>
+</IressStack>
+```
+
+[View "Padding" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-card--padding)
+
+### Stretch
+
+The `stretch` prop can be used to stretch the card to fill its container.
+
+```tsx
+<IressRow gutter="md" verticalAlign="stretch">
+<IressCol>
+<IressCard stretch>
+I&rsquo;m a stretched card
+</IressCard>
+</IressCol>
+<IressCol>
+<IressCard>
+I&rsquo;m a card with lots of content. Blah blah blah blah blah blah
+blah blah blah blah blah blah blah blah blah blah blah blah blah blah
+blah blah blah blah blah.
+</IressCard>
+</IressCol>
+</IressRow>
+```
+
+[View "Stretch" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-card--stretch)
+
+### Selected
+
+Setting the `selected` prop highlights the card, usually to allow selection in a list.
+
+```tsx
+<IressCard selected>
+  I'm a selected card
+</IressCard>
+```
+
+[View "Selected" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-card--selected)
+
+## Render props (slots)
+
+If you're coming from v4 or earlier, you might be used to slots. In v5, we've replaced slots with render props which align with the React API. Render props allow you to create a structured layout for your card, while still having the flexibility to add custom content. They are simply functions that return JSX, so you can pass any component you like.
+
+However, please be diligent as the component you use may not fit withing the confines of the `IressCard` layout.
+
+### Prepend
+
+Use the `prepend` prop to add content to the left side of the card.
+
+```tsx
+<IressCardSlots>
+  I'm a card using the prepend render prop
+</IressCardSlots>
+```
+
+[View "Prepend" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-card-slots--prepend)
+
+### Top Right
+
+Use the `topRight` prop to add content to the top right of the card. This is useful for adding a badge, icon, or an actions menu.
+
+```tsx
+<IressCardSlots>
+  I'm a card using the topRight render prop
+</IressCardSlots>
+```
+
+[View "TopRight" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-card-slots--top-right)
+
+### Heading
+
+Use the `heading` prop to add a header to the card. The header can be any component you like, but it is designed to support a simple heading element, optionally wrapped with a link.
+
+**Note:** `headingText` and `headingLevel` props have been replaced with the `heading` render prop to give you more control over the heading element and its content. To use the previous behaviour, you can pass a string which will automatically create a `h2` element, or pass a `h*` element with the text as a child.
+
+```tsx
+<IressCardSlots>
+  I'm a card using the heading render prop
+</IressCardSlots>
+```
+
+[View "Heading" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-card-slots--heading)
+
+### Media
+
+Use the `media` prop to add media to the card. The media can be any component you like, but it is designed to support an image or video.
+
+```tsx
+<IressCardSlots>
+  I'm a card using the media render prop
+</IressCardSlots>
+```
+
+[View "Media" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-card-slots--media)
+
+### Content
+
+Use the `content` prop to add content to the card. The content can be any component you like, but it is designed to support simple text based elements.
+
+[View "Content" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-card-slots--content)
+
+### Footer
+
+Use the `footer` prop to add a footer to the card. The footer can be any component you like, but it is designed to support buttons.
+
+```tsx
+<IressCardSlots>
+  I'm a card using the footer render prop
+</IressCardSlots>
+```
+
+[View "Footer" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-card-slots--footer)
+
+### All slots
+
+You can use all the slots together to create a custom card layout.
+
+```tsx
+<CardAllSlots />
+```
+
+[View "AllSlots" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-card-slots--all-slots)
+
+## Clickable cards
+
+Note: The `clickable` prop has been deprecated in favour of using component variations, or the `onClick` prop.
+
+### Heading only
+
+Since the `heading` prop now renders the component you give it, you have full control over the content of the `heading`. This means you can add pass it a heading with a link.
+
+```tsx
+<IressCardClickable>
+  I'm a card with a clickable heading. NEVER use me when the whole card is clickable.
+</IressCardClickable>
+```
+
+[View "HeadingOnly" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-card-clickable--heading-only)
+
+### Whole card
+
+The whole card can be made clickable by passing an `onClick` prop. All the appropriate styling will be added as well.
+
+It's recommended to add `role="button"` and `tabindex="0"` to the card to make it clear to screen readers that the card is clickable.
+
+```tsx
+<IressCardClickable role="button" tabIndex={0}>
+  I am a card with an onClick handler. Click me to see what happens.
+</IressCardClickable>
+```
+
+[View "WholeCard" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-card-clickable--whole-card)
+
+### Links and Buttons
+
+To simplify the process of making the whole card clickable, you can use the `IressLinkCard` and `IressButtonCard` components. These components look exactly the same as the `IressCard` component, however their base tags are different, allowing you to use them exactly like you would a html link and button.
+
+**Note:** These components replace the `button`, `clickable` and `href` props. You no longer need `button` and `clickable`, as these are automatically inferred. To mimic the `href` prop, simply change the component you are using to `IressLinkCard`.
+
+```tsx
+<IressInline gap="md" horizontalAlign="around">
+  ```tsx
+<IressButtonCard>
+I am a card with a button element
+</IressButtonCard>
+```
+
+[View "ButtonCard" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-card-clickable--button-card)
+  ```tsx
+<IressLinkCard>I am a card with an anchor element</IressLinkCard>
+```
+
+[View "LinkCard" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-card-clickable--link-card)
+</IressInline>
+```
+
+## Props
+
+- **Type:** `IressCardProps`
+- **Type declarations:** `@iress-oss/ids-components/dist/components/Card/Card.d.ts`
+
+```typescript
+import type { IressCardProps } from '@iress-oss/ids-components';
+```
+
+
+---
+
+*View interactive examples: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-card--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-card--docs)*

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

@@ -0,0 +1,20 @@
+# Recipes
+
+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`
+
+You can use `IressCheckboxGroup` and `IressTable` to create a table with checkboxes, allowing the users to select multiple rows.
+
+```tsx
+<CheckboxGroupTable />
+```
+
+[View "Table" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-checkbox-group--table)
+
+---
+
+*View interactive examples: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-checkbox-group--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-checkbox-group--docs)*