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

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

@@ -0,0 +1,160 @@
+# Checkbox Group
+
+Checkbox groups allow users to make more than one choice in a set of related options.
+
+> **Component:** `import { IressCheckboxGroup } from '@iress-oss/ids-components'`
+> **Storybook:** [Checkbox Group in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-checkbox-group--docs)
+
+## Quick Start
+
+```tsx
+import { IressCheckboxGroup } from '@iress-oss/ids-components';
+
+<IressCheckboxGroup name="preferences" />
+```
+
+import {
+  ComponentExample,
+  ComponentOverview,
+} from '@iress-oss/ids-storybook-config';
+
+## Examples
+
+### Checkbox children
+
+Individual checkboxes can be passed directly into `IressCheckboxGroup`.
+
+**Note:** The `mapCheckboxGroupOptions` helper function, originally used to map options to `IressCheckbox` components, is now deprecated. Instead, you can use `array.map` to map the options to `IressCheckbox` components.
+
+```tsx
+<IressCheckboxGroup name="let-them-eat-cake" />
+```
+
+[View "CheckboxChildren" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-checkbox-group--checkbox-children)
+
+### Default checked
+
+The default checked state of the checkbox children should always be set using the `defaultValue` prop (not directly on the checkbox component).
+
+The `defaultValue` prop can contain an array of strings, numbers or booleans.
+
+[View "DefaultChecked" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-checkbox-group--default-checked)
+
+### Changing the checked state
+
+The `value` prop can be updated if you need to change the checked state without interacting with the checkboxes.
+
+For example, if you want to clear down the selected options:
+
+```tsx
+<CheckboxGroupUsingState />
+```
+
+[View "Controlled" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-checkbox-group--controlled)
+
+### Layout
+
+The `layout` prop controls how the checkbox group is displayed and can have three basic layouts:
+
+- **Stack (Default):** Checkboxes are laid out vertically. Labels are only as wide as their text.
+- **Block:** Same as Stack, but labels take up the full width of the container.
+- **Inline:** Checkboxes are laid out horizontally. Labels are only as wide as their text.
+
+```tsx
+<IressText>
+<h3>block</h3>
+<IressCheckboxGroup layout="block" />
+<h3>inline</h3>
+<IressCheckboxGroup layout="inline" />
+<h3>stack</h3>
+<IressCheckboxGroup layout="stack" />
+</IressText>
+```
+
+[View "Layout" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-checkbox-group--layout)
+
+### Hidden checkboxes
+
+You can use the `hiddenCheckbox` prop to create custom checkboxes. When enabled, the actual checkbox will be visually hidden, allowing you to create more interesting controls. The checked state will be shown by the label's border, which is thicker when the checkbox is checked.
+
+When `hiddenCheckbox` is enabled, the label will have no padding. Padding can be added by using an `IressPanel`.
+
+```tsx
+<IressField
+label="I'd like to discuss the following with my financial adviser:"
+hint="Select all that apply"
+>
+<IressCheckboxGroup>...</IressCheckboxGroup>
+</IressField>
+```
+
+[View "HiddenCheckboxes" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-checkbox-group--hidden-checkboxes)
+
+### Laying out custom checkboxes
+
+The checkbox group's `layout` prop gives you some default options to help control the layout of your controls. But sometimes you need more granular control, which you can achieve with a bit of custom CSS.
+
+The example below uses CSS grid to give us evenly spaced / sized checkboxes, which will wrap on to new lines as the screen size reduces. The grid wrapper element is a div that wraps around the `<IressCheckbox>` elements, as shown by the dashed border. Use the grab handle in the bottom right-hand corner of the grid wrapper to see how the controls change size to respond to the container's width.
+
+```tsx
+<IressField
+label="I'd like to discuss the following with my financial adviser:"
+hint="Select all that apply"
+>
+<IressCheckboxGroup>
+<div
+style={{
+display: 'grid',
+gridTemplateColumns: 'repeat(auto-fit, minmax(240px, 1fr))',
+gridAutoRows: '1fr',
+gridGap: '16px',
+width: '100%',
+padding: '0.5rem',
+border: '1px dashed hsl(43deg 100% 45%)',
+resize: 'horizontal',
+overflow: 'auto',
+}}
+>
+...
+</div>
+</IressCheckboxGroup>
+</IressField>
+```
+
+[View "CustomCheckboxGroupLayout" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-checkbox-group--custom-checkbox-group-layout)
+
+### Read only
+
+The `readOnly` prop changes how the checkbox group is rendered. It will only render the children that are checked (alongside a hidden input that contains the `value` if it was set), otherwise it not be rendered.
+
+It is understandable that this may not be the desired behavior for all use cases. If you need a checkbox group that is not editable, but still visible, simply do not set the `readOnly` prop and set the `value` prop instead.
+
+```tsx
+<IressCheckboxGroup readOnly />
+```
+
+[View "ReadOnly" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-checkbox-group--read-only)
+
+### Touch
+
+The `touch` prop adds the button-like border and padding to checkbox.
+
+```tsx
+<IressCheckboxGroup variant="touch" />
+```
+
+[View "Touch" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-checkbox-group--touch)
+
+## Props
+
+- **Type:** `IressCheckboxGroupProps`
+- **Type declarations:** `@iress-oss/ids-components/dist/components/CheckboxGroup/CheckboxGroup.d.ts`
+
+```typescript
+import type { IressCheckboxGroupProps } from '@iress-oss/ids-components';
+```
+
+
+---
+
+*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)*

package/.ai/components/checkbox.md

@@ -0,0 +1,153 @@
+# Checkbox
+
+Checkboxes are used to let a user select one or more options for a limited number of choices. Also, works as a child of IressCheckboxGroup
+
+> **Component:** `import { IressCheckbox } from '@iress-oss/ids-components'`
+> **Storybook:** [Checkbox in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-checkbox--docs)
+
+## Quick Start
+
+```tsx
+import { IressCheckbox } from '@iress-oss/ids-components';
+
+<IressCheckbox>
+  A checkbox
+</IressCheckbox>
+```
+
+import {
+  ComponentExample,
+  ComponentOverview,
+} from '@iress-oss/ids-storybook-config';
+
+## Usage
+
+### Checked
+
+For single checkboxes in controlled mode the `checked` prop sets the checked state.
+
+When used as part of an `IressCheckboxGroup`, the `checked` prop will be ignored. Instead, the `value` prop on the `IressCheckboxGroup` will determine the checked state of each checkbox. See the [checkbox group documentation](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-checkboxgroup--docs) for more details.
+
+```tsx
+<IressCheckbox checked>
+  A checkbox which is checked and in controlled mode
+</IressCheckbox>
+```
+
+[View "Checked" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-checkbox--checked)
+
+### Default Checked
+
+For single checkboxes in uncontrolled mode the `defaultChecked` prop sets the default checked state.
+
+```tsx
+<IressCheckbox defaultChecked>
+  A checkbox which is initially checked
+</IressCheckbox>
+```
+
+[View "DefaultChecked" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-checkbox--default-checked)
+
+### Indeterminate
+
+The `indeterminate` prop sets the checkbox appearance to an indeterminate dash until it is clicked. It has no impact on the checkbox behavior beyond this purely visual indicator.
+
+```tsx
+<IressCheckbox indeterminate>
+  A checkbox which is initially in an indeterminate state
+</IressCheckbox>
+```
+
+[View "Indeterminate" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-checkbox--indeterminate)
+
+### Hidden Label
+
+It is very rare to want to render a checkbox without a visible label. However, one case where you might want to is within tables.
+
+When using a checkbox without a visible label, you must supply a label and apply the `hiddenLabel` property to still be accessible by screen readers.
+
+It is also important to not hide the table headers.
+
+```tsx
+<IressTable
+caption="List of investments"
+columns={[
+{
+format: (value: boolean) => (
+<IressCheckbox defaultChecked={value} />
+),
+key: 'select',
+label: 'Select',
+sort: true,
+},
+{ key: 'name', label: 'Name' },
+{ key: 'date', label: 'Date' },
+{ key: 'cost', label: 'Cost' },
+]}
+rows={[
+{
+select: false,
+name: 'Artemis Fund Managers Limited',
+date: '2019-09-23',
+cost: 23898.12,
+},
+{
+select: true,
+name: 'CASH.CASH',
+date: '2020-06-28',
+cost: 49751.43,
+},
+]}
+/>
+```
+
+[View "WithTableData" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-checkbox--with-table-data)
+
+### Read only
+
+The `readOnly` prop changes how the checkbox is rendered. It will only render if the checkbox is checked (alongside a hidden input that contains the `value` if it was set), otherwise it will not be rendered.
+
+It is understandable that this may not be the desired behavior for all use cases. If you need a checkbox that is not editable, but still visible, simply do not set the `readOnly` prop and set the `checked` prop instead.
+
+```tsx
+<IressStack>
+<IressCheckbox defaultChecked />
+<IressCheckbox />
+</IressStack>
+```
+
+[View "ReadOnly" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-checkbox--read-only)
+
+### Variants
+
+The checkbox component has multiple variants that can be used to change the appearance of the checkbox. The `variant` prop can be set to `default`, `card`, or `touch`. The default variant is `default`.
+
+- `card` variant is used to display the checkbox as a card, which is useful when the checkbox needs to contain more information than just a label. It is used in the `IressCheckboxGroup` component when the `variant` prop is set to `card`.
+- `touch` variant is used to display the checkbox with a larger touch target, which is useful for mobile devices. It is used in the `IressCheckboxGroup` component when the `variant` prop is set to `touch`.
+
+```tsx
+<IressStack gap="lg">
+<IressCheckbox variant="card" heading="Widget">
+A description of the widget
+</IressCheckbox>
+<IressCheckbox variant="touch">
+Touch variant
+</IressCheckbox>
+</IressStack>
+```
+
+[View "Variants" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-checkbox--variants)
+
+## Props
+
+- **Type:** `IressCheckboxProps`
+- **Type declarations:** `@iress-oss/ids-components/dist/components/Checkbox/Checkbox.d.ts`
+
+```typescript
+import type { IressCheckboxProps } from '@iress-oss/ids-components';
+```
+
+
+---
+
+*View interactive examples: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-checkbox--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-checkbox--docs)*

package/.ai/components/col.md

@@ -0,0 +1,285 @@
+# Col
+
+Used in conjunction with the IressRow component to layout page content
+
+> **Component:** `import { IressCol } from '@iress-oss/ids-components'`
+> **Storybook:** [Col in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-col--docs)
+
+## Quick Start
+
+```tsx
+import { IressCol } from '@iress-oss/ids-components';
+
+<IressCol numberOfColumns={2} />
+```
+
+import {
+  ComponentExample,
+  ComponentOverview,
+} from '@iress-oss/ids-storybook-config';
+
+## Examples
+
+### Auto-sized
+
+When no column widths are specified the `IressCol` component will render equal width columns.
+
+```tsx
+<IressStack gap="spacing.4">
+<IressRow {...row}>
+<IressCol {...column}>
+<IressPlaceholder>1 of 2</IressPlaceholder>
+</IressCol>
+<IressCol {...column}>
+<IressPlaceholder>2 of 2</IressPlaceholder>
+</IressCol>
+</IressRow>
+<IressRow {...row}>
+<IressCol {...column}>
+<IressPlaceholder>1 of 3</IressPlaceholder>
+</IressCol>
+<IressCol {...column}>
+<IressPlaceholder>2 of 3</IressPlaceholder>
+</IressCol>
+<IressCol {...column}>
+<IressPlaceholder>3 of 3</IressPlaceholder>
+</IressCol>
+</IressRow>
+</IressStack>
+```
+
+[View "AutoSized" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-col--auto-sized)
+
+### Span
+
+The `span` prop controls the number of grid columns the component should span.
+
+If no `span` is provided it will default to `auto` which will make the column either fill the remaining space in the row (when used with a col number) or size evenly when used with other columns set to auto sizing.
+
+```tsx
+<IressStack gap="spacing.4">
+<IressRow {...row}>
+<IressCol {...column} span="12">
+<IressPlaceholder>12</IressPlaceholder>
+</IressCol>
+</IressRow>
+<IressRow {...row}>
+<IressCol {...column} span="1">
+<IressPlaceholder>1</IressPlaceholder>
+</IressCol>
+<IressCol {...column}>
+<IressPlaceholder>11</IressPlaceholder>
+</IressCol>
+</IressRow>
+<IressRow {...row}>
+<IressCol {...column} span="2">
+<IressPlaceholder>2</IressPlaceholder>
+</IressCol>
+<IressCol {...column}>
+<IressPlaceholder>10</IressPlaceholder>
+</IressCol>
+</IressRow>
+<IressRow {...row}>
+<IressCol {...column} span="3">
+<IressPlaceholder>3</IressPlaceholder>
+</IressCol>
+<IressCol {...column}>
+<IressPlaceholder>9</IressPlaceholder>
+</IressCol>
+</IressRow>
+<IressRow {...row}>
+<IressCol {...column} span="4">
+<IressPlaceholder>4</IressPlaceholder>
+</IressCol>
+<IressCol {...column}>
+<IressPlaceholder>8</IressPlaceholder>
+</IressCol>
+</IressRow>
+<IressRow {...row}>
+<IressCol {...column} span="5">
+<IressPlaceholder>5</IressPlaceholder>
+</IressCol>
+<IressCol {...column}>
+<IressPlaceholder>7</IressPlaceholder>
+</IressCol>
+</IressRow>
+<IressRow {...row}>
+<IressCol {...column} span="6">
+<IressPlaceholder>6</IressPlaceholder>
+</IressCol>
+<IressCol {...column}>
+<IressPlaceholder>6</IressPlaceholder>
+</IressCol>
+</IressRow>
+</IressStack>
+```
+
+[View "Span" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-col--span)
+
+### Responsive span
+
+The `span` prop can take an object that takes five key/value pairs that correlate with the IDS breakpoints. Any missing keys will fall back to the value defined for the next smallest key.
+
+**Note:** If a `span` prop is provided an object but no value is given for `xs` it will default to `12`. This means that columns will be full width on screen sizes below the sizes you've specified.
+
+```tsx
+<IressStack gap="spacing.4">
+<IressPanel>
+Current breakpoint: <CurrentBreakpoint />.
+</IressPanel>
+
+<IressRow {...row}>
+{columns.map((column, index) => (
+<IressCol {...columnProps} {...column} key={index}>
+<IressPlaceholder>
+<IressText textAlign="center">
+Column {index + 1}
+<br />
+{column.span && JSON.stringify(column.span)}
+</IressText>
+</IressPlaceholder>
+</IressCol>
+))}
+</IressRow>
+</IressStack>
+```
+
+[View "ResponsiveSpan" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-col--responsive-span)
+
+### Offset
+
+The `offset` prop controls the amount of grid columns to offset.
+
+```tsx
+<IressStack gap="spacing.4">
+<IressRow {...row}>
+<IressCol {...column} offset="1">
+<IressPlaceholder>1</IressPlaceholder>
+</IressCol>
+</IressRow>
+<IressRow {...row}>
+<IressCol {...column} offset="2">
+<IressPlaceholder>2</IressPlaceholder>
+</IressCol>
+</IressRow>
+<IressRow {...row}>
+<IressCol {...column} offset="3">
+<IressPlaceholder>3</IressPlaceholder>
+</IressCol>
+</IressRow>
+<IressRow {...row}>
+<IressCol {...column} offset="4">
+<IressPlaceholder>4</IressPlaceholder>
+</IressCol>
+</IressRow>
+<IressRow {...row}>
+<IressCol {...column} offset="5">
+<IressPlaceholder>5</IressPlaceholder>
+</IressCol>
+</IressRow>
+<IressRow {...row}>
+<IressCol {...column} offset="6">
+<IressPlaceholder>6</IressPlaceholder>
+</IressCol>
+</IressRow>
+<IressRow {...row}>
+<IressCol {...column} offset="7">
+<IressPlaceholder>7</IressPlaceholder>
+</IressCol>
+</IressRow>
+<IressRow {...row}>
+<IressCol {...column} offset="8">
+<IressPlaceholder>8</IressPlaceholder>
+</IressCol>
+</IressRow>
+<IressRow {...row}>
+<IressCol {...column} offset="9">
+<IressPlaceholder>9</IressPlaceholder>
+</IressCol>
+</IressRow>
+<IressRow {...row}>
+<IressCol {...column} offset="10">
+<IressPlaceholder>10</IressPlaceholder>
+</IressCol>
+</IressRow>
+<IressRow {...row}>
+<IressCol {...column} offset="11">
+<IressPlaceholder>11</IressPlaceholder>
+</IressCol>
+</IressRow>
+</IressStack>
+```
+
+[View "Offset" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-col--offset)
+
+### Responsive offset
+
+When a `ResponsiveSizing` object is passed into the `offset` prop, the offset will change at the specified breakpoints. It will apply to all breakpoints above the specified breakpoint.
+
+For example, if you specify an offset for `md`, it will apply to `lg`, `xl` and `xxl` as well. If you want to change the offset at a specific breakpoint, you can pass in an object with the breakpoint as the key and the offset as the value.
+
+```tsx
+<IressStack gap="spacing.4">
+<IressPanel>
+Current breakpoint: <CurrentBreakpoint />.
+</IressPanel>
+
+<IressRow {...row}>
+{columns.map((column, index) => (
+<IressCol {...columnProps} {...column} key={index}>
+<IressPlaceholder>
+<IressText textAlign="center">
+Column {index + 1}
+<br />
+{column.offset && JSON.stringify(column.offset)}
+</IressText>
+</IressPlaceholder>
+</IressCol>
+))}
+</IressRow>
+</IressStack>
+```
+
+[View "ResponsiveOffset" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-col--responsive-offset)
+
+### Align self
+
+The `alignSelf` prop controls the vertical alignment of the column (use if column alignment needs to differ from other columns in the row).
+
+```tsx
+<IressContainer>
+<IressRow
+{...row}
+style={{ border: '1px dashed hsl(43deg 100% 45%)', height: '10rem' }}
+>
+<IressCol {...column} alignSelf="start">
+<IressPlaceholder>Start</IressPlaceholder>
+</IressCol>
+<IressCol {...column} alignSelf="center">
+<IressPlaceholder>Center</IressPlaceholder>
+</IressCol>
+<IressCol {...column} alignSelf="end">
+<IressPlaceholder>End</IressPlaceholder>
+</IressCol>
+<IressCol {...column} alignSelf="stretch">
+<IressPlaceholder stretch>Stretch</IressPlaceholder>
+</IressCol>
+</IressRow>
+</IressContainer>
+```
+
+[View "AlignSelf" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-col--align-self)
+
+## Props
+
+- **Type:** `IressColProps`
+- **Type declarations:** `@iress-oss/ids-components/dist/components/Col/Col.d.ts`
+
+```typescript
+import type { IressColProps } from '@iress-oss/ids-components';
+```
+
+
+---
+
+*View interactive examples: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-col--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-col--docs)*

package/.ai/components/container.md

@@ -0,0 +1,62 @@
+# Container
+
+IressContainer provides a means to center and horizontally pad your site’s contents.
+
+> **Component:** `import { IressContainer } from '@iress-oss/ids-components'`
+> **Storybook:** [Container in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-container--docs)
+
+## Quick Start
+
+```tsx
+import { IressContainer } from '@iress-oss/ids-components';
+
+<IressContainer />
+```
+
+import {
+  ComponentOverview,
+  ComponentExample,
+} from '@iress-oss/ids-storybook-config';
+
+## Behaviour
+
+The `IressContainer` snaps to fixed max widths at different breakpoints. Those max widths are as follows:
+
+```tsx
+<IressTable
+caption="Container breakpoints"
+rows={BREAKPOINTS.map((breakpoint) => ({
+breakpoint,
+screenWidths: BREAKPOINT_DETAILS[breakpoint].screenWidthRange,
+maxWidth: BREAKPOINT_DETAILS[breakpoint].containerMaxWidth,
+}))}
+/>
+```
+
+[View "BreakpointTable" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-container--breakpoint-table)
+
+## Examples
+
+### Fluid
+
+If you want the `IressContainer` to fill its containing element, you can set the `fluid` prop. Resize the example below to see how the IressContainer is 100% for all screen sizes.
+
+```tsx
+<IressContainer fluid />
+```
+
+[View "Fluid" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-container--fluid)
+
+## Props
+
+- **Type:** `IressContainerProps`
+- **Type declarations:** `@iress-oss/ids-components/dist/components/Container/Container.d.ts`
+
+```typescript
+import type { IressContainerProps } from '@iress-oss/ids-components';
+```
+
+
+---
+
+*View interactive examples: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-container--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-container--docs)*