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

package/.ai/components/table.md

@@ -0,0 +1,356 @@
+# Table
+
+Data driven component for displaying tabular data.
+
+> **Component:** `import { IressTable } from '@iress-oss/ids-components'`
+> **Storybook:** [Table in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-table--docs)
+
+## Quick Start
+
+```tsx
+import { IressTable } from '@iress-oss/ids-components';
+
+<IressTable caption="Data table" />
+```
+
+import {
+  ComponentExample,
+  ComponentOverview,
+} from '@iress-oss/ids-storybook-config';
+
+## Usage
+
+### Automatic columns
+
+To get started, the `IressTable` component only requires the `caption` and `rows` props to be set.
+
+- `caption` a string describing what the table is displaying (required for accessibility, it can be visually hidden by setting the `hiddenCaption` prop).
+- `rows` are an array of objects, each object represents a row in the table. The table will use the key of the first object to determine the columns, automatically made human readable if the key is camel case, snake case or kebab case.
+
+```tsx
+<IressTable caption="My investments" />
+```
+
+[View "AutomaticColumns" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-table--automatic-columns)
+
+### Custom columns
+
+For more control over the columns, the `columns` prop can be used to define the columns. This accepts an array of `TableColumn` objects.
+
+Each array item represents a key in the objects in your `rows` prop. If one of the keys in your `rows` prop is not defined in the `columns` prop, it will not be displayed in the table.
+
+```tsx
+<TableCustomColumns />
+```
+
+[View "CustomColumns" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-table--custom-columns)
+
+### Column API
+
+These are the configuration options available for each column.
+
+**Note:** The `id` prop has been removed. The `key` is always used for the id of the table cell, alongside its row index.
+
+```ts
+export interface TableColumn<TRow extends object, TVal = unknown> {
+  /**
+   * Aligns the content of the cell.
+   * @default left
+   */
+  align?: TableColumnAligns;
+
+  /**
+   * The currency code to prefix to the value if `format` is set to currency.
+   * @default $
+   */
+  currencyCode?: string;
+
+  /**
+   * When set to true, a divider will be rendered after the column.
+   */
+  divider?: boolean;
+
+  /**
+   * Formats the cell content.
+   * To use the in-built formatters, set this to: string, number, date, currency, percent.
+   * Use a custom formatter by passing a function that returns a ReactNode.
+   */
+  format?: TableCellFormats | ((value: TVal, row?: TRow) => ReactNode);
+
+  /**
+   * The unique key for the column.
+   */
+  key: string;
+
+  /**
+   * The label for the column header.
+   */
+  label?: ReactNode;
+
+  /**
+   * When set to true, the column will be sortable.
+   * Setting it to either `asc` or `desc` will set the initial sort order.
+   */
+  sort?: boolean | SortDirection;
+
+  /**
+   * Text to be read by a screen reader when a column is sortable (but not currently sorted).
+   * @default sortable
+   */
+  sortableText?: string;
+
+  /**
+   * The width of the column.
+   */
+  width?: string;
+}
+```
+
+## Examples
+
+### Formats
+
+The table component provides some basic formatting. This is controlled by the `format` property of the `TableColumn` object.
+
+- `date`: the value (which can be a Date object, timestamp or a ISO8601 formatted string) will be formatted to render as DD/MM/YYYY.
+- `currency`: the value (which should be a number or a string containing a number) is formatted with the `currencyCode` (also a prop on `TableColumn` which defaults to `$`) prepended to the number (formatted to 2 decimal places). Currency formatted columns are automatically right aligned for readability.
+- `percent`: the value (which should be a number or a string containing a number) is formatted as a percentage (multiplied by 100 and rounded to 2 decimal places).
+- `number`: the number format aligns the number to the right, and converts strings to a number.
+- `shortDate`: the value (which can be a Date object, timestamp or a ISO8601 formatted string) will be formatted to render as DD MMM YYYY.
+- `isoDateTime`: the value (which can be a Date object, timestamp or a ISO8601 formatted string) will be formatted to render as YYYY-MM-DD HH:mm:ss (Timezone)
+- `relativeTime`: the value (which can be a Date object, timestamp or a ISO8601 formatted string) will be formatted to render as a relative time (eg. 2 days ago, 3 hours ago, etc). It will fallback to the `shortDate` format if the date is more than one week in the past.
+
+To completely customise it, you can also send in a function that returns a ReactNode. It has two parameters, the original value and the row it is connected to.
+
+```tsx
+<TableFormats />
+```
+
+[View "Formats" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-table--formats)
+
+### Sorting
+
+Sorting can be enabled on a column by setting the `sort` property of the `TableColumn` to true. It can also be set to `asc` or `desc` if you would like it to initally sort in a certain direction.
+
+The sort button has some visually hidden text for screenreaders to signify that the column is sortable. If you need to change this (ie. for translation purposes), it can be done with the `sortableText` column option which defaults to: sortable.
+
+```tsx
+<TableSorting />
+```
+
+[View "Sorting" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-table--sorting)
+
+### Custom sorting logic
+
+By default, sorting is automatically inferred from the raw column values.
+
+If you need to customise the sorting logic, you can use the `sortFn` property of the `TableColumn`. It accepts one of the following values:
+
+- A `string` referencing a built-in sort function: `alphanumeric`, `alphanumericCaseSensitive`, `text`, `textCaseSensitive`, `datetime` and `basic`. To understand how they work, visit the [Tanstack Table documentation](https://tanstack.com/table/v8/docs/api/features/sorting/#sorting-functions).
+- A custom sort function that takes two arguments: `a` and `b`, which are the two rows being compared. It should return `-1`, `0` or `1` depending on the comparison.
+
+```tsx
+<TableSortingFn {...(args as object)} />
+```
+
+[View "CustomSortingLogic" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-table--custom-sorting-logic)
+
+### Width
+
+The width of a column is controlled by the `width` property on the `TableColumn` object. It takes a string so it can be set to a pixel value or a percentage.
+
+When the table exceeds the width of the container, a horizontal scrollbar is triggered. This makes it possible to view larger tables on mobile devices.
+
+[View "Width" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-table--width)
+
+### Alignment
+
+Columns can be aligned using the `align` property on the `TableColumn` object. Columns can be aligned to the left, right or center.
+
+Currency and number formats are automatically right aligned to make the values easier to compare, but this can be overriden by setting the `align` property.
+
+[View "Alignment" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-table--alignment)
+
+### Dividers
+
+As a general rule we don't add vertical column borders to our tables. Sometimes though, it can be useful to add a vertical divider between columns to help group content and create visual separation.
+
+To add a vertical divider you can set the `divider` prop in the `TableColumn` to true. This will add a vertical border to the end of the column.
+
+[View "Dividers" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-table--dividers)
+
+### Highlight on hover
+
+This can be enabled by setting the `hover` prop. This will bring attention to the row the user is hovering over, allowing users to focus on the relationship between the columns of a specific row.
+
+```tsx
+<IressTable hover />
+```
+
+[View "HighlightOnHover" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-table--highlight-on-hover)
+
+### Scope
+
+`scope` defaults to row, which means the first cell in the row will be a `<th>`. When it is set to col the first cell in the row will be a `<td>`.
+
+```tsx
+<IressTable scope="col" />
+```
+
+[View "Scope" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-table--scope)
+
+### Hidden header
+
+For very simple tabular data, you have the option to hide the table header with the `hiddenHeader` prop. When this is set to true, the table header will not be rendered.
+
+```tsx
+<IressTable hiddenHeader />
+```
+
+[View "HiddenHeader" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-table--hidden-header)
+
+### Rich rows (JSX)
+
+The `rows` prop allows you to use `ReactNodes` as the value of a cell. This can be useful for adding rich content to a cell, such as links, buttons or icons.
+
+**Note:** If you are using the `sort` property, the sorting may not work properly with rich content. If this happens, either remove the `sort` property or use the `format` prop on the column to set a custom formatter.
+
+```tsx
+<IressTable caption="My rich investments" />
+```
+
+[View "RichRows" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-table--rich-rows)
+
+### Empty state
+
+You can provide the table with some content to display when there is no row data by using the `empty` prop.
+
+This is reliant on `columns` prop to provide the information for the table header. If `columns` is not provided and there is no row data the table will not render.
+
+```tsx
+<IressTable empty="This table has no data" />
+```
+
+[View "EmptyState" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-table--empty-state)
+
+### Static table
+
+If you don't need all the fancy features of the table component, but would still like a styled table, you can use the `children` prop.
+
+It accepts any of the table sub-elements. To ensure best display, please make use of the `thead` and `tbody` tags.
+
+**Note:** Only the `caption`, `hiddenCaption`, `hiddenHeader` and `hover` props are supported when using `children` to render a table.
+
+```tsx
+<IressTable caption="My investments" />
+```
+
+[View "Static" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-table--static)
+
+### Row props
+
+You can customise the rows by passing in a `rowProps` object or function. It accepts a map of table row props that can be passed to a `tr` element, or a function that accepts the row data currently being rendered, and returns a map of table props.
+
+[View "RowProps" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-table--row-props)
+
+### Compact
+
+The `compact` prop can be used to reduce the padding around the table cells and reduce the font size. This can be useful when you have a lot of data to display and allow users to see as many columns as possible.
+
+```tsx
+<IressTable scope="col" compact alternate removeRowBorders />
+```
+
+[View "Compact" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-table--compact)
+
+## `IressTableBody`
+
+In some cases you may have a table with multiple groups of rows inside it, however the columns are the same. For these cases, you can use the `IressTableBody` component.
+
+```tsx
+<TableGroupedRows />
+```
+
+[View "Body" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-table-body--body)
+
+## `IressTableFormattedValue`
+
+`IressTableFormattedValue` is the component used to format the table columns when the `format` property is not a render function.
+
+It has been exposed so you can use it in your own components to format values in the same way as the table component.
+
+```tsx
+<IressTable
+caption="IressTableFormattedValue"
+rows={[
+{
+mode: 'string',
+example: <IressTableFormattedValue value="string" format="string" />,
+},
+{
+mode: 'number',
+example: <IressTableFormattedValue value="10000" format="number" />,
+},
+{
+mode: 'date',
+example: (
+<IressTableFormattedValue
+value={new Date('2025-11-14')}
+format="date"
+/>
+),
+},
+{
+mode: 'shortDate',
+example: (
+<IressTableFormattedValue
+value={new Date('2025-11-14')}
+format="shortDate"
+/>
+),
+},
+{
+mode: 'isoDateTime',
+example: (
+<IressTableFormattedValue
+value={new Date('2025-11-14')}
+format="isoDateTime"
+/>
+),
+},
+{
+mode: 'relativeTime',
+example: (
+<IressTableFormattedValue
+value={fourDaysAgo}
+format="relativeTime"
+/>
+),
+},
+{
+mode: 'currency',
+example: <IressTableFormattedValue value={10000} format="currency" />,
+},
+{
+mode: 'percent',
+example: <IressTableFormattedValue value={50} format="percent" />,
+},
+]}
+/>
+```
+
+[View "FormattedValue" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-table-formatted-value--formatted-value)
+
+## Props
+
+- **Type:** `IressTableProps`
+- **Type declarations:** `@iress-oss/ids-components/dist/components/Table/Table.d.ts`
+
+```typescript
+import type { IressTableProps } from '@iress-oss/ids-components';
+```
+
+
+---
+
+*View interactive examples: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-table--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-table--docs)*

package/.ai/components/tag.md

@@ -0,0 +1,93 @@
+# Tag
+
+Tags represent individual units in a group of selected items.
+
+> **Component:** `import { IressTag } from '@iress-oss/ids-components'`
+> **Storybook:** [Tag in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-tag--docs)
+
+## Quick Start
+
+```tsx
+import { IressTag } from '@iress-oss/ids-components';
+
+<IressTag>
+  Label
+</IressTag>
+```
+
+import {
+  ComponentExample,
+  ComponentOverview,
+} from '@iress-oss/ids-storybook-config';
+
+## When to use
+
+Use tags for **categorization and selection** where users need to interact with items:
+
+- Displaying selected items in multi-select interfaces
+- Managing email recipients or domains
+- Showing applied filters that can be removed
+- Categorizing content with removable labels
+- Any scenario where users need to add or remove items from a collection
+
+Tags are **interactive** - they can be clicked and deleted by users.
+
+**Not sure?** If you need to display status or highlight information without user interaction, use [Badge](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-badge--docs) instead.
+
+## Usage
+
+### Clickable tags
+
+Tags can be made clickable by passing an `onClick` handler. This will apply hover styles to the tag to indicate it is clickable.
+
+```tsx
+<IressTag>
+  Tag
+</IressTag>
+```
+
+[View "ClickableTag" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-tag--clickable-tag)
+
+### Deleting tags
+
+The delete button will not automatically remove the tag from the screen. Instead it will trigger the `onDelete` event. Use this event within your app to handle the display of tags.
+
+The text a screen reader will announce defaults to "Delete" but can be changed using the `deleteButtonText` prop.
+
+```tsx
+<TagDeletion />
+```
+
+[View "DeletingTags" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-tag--deleting-tags)
+
+### Custom button
+
+You can completely override the delete button by passing a custom component to the `deleteButton` prop.
+
+[View "CustomButton" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-tag--custom-button)
+
+## IressTagInput
+
+`IressTagInput` allows you to manage multiple tags, and is often used for managing email addresses, domains or other simple metadata that does not have to be selected from a list.
+
+If you need to manage tags that are selected from a existing list, use `IressSelect` with the `multiple` prop.
+
+```tsx
+<IressTagInput placeholder="Type and hit enter to add a tag" tagLimit={999} />
+```
+
+[View "TagInput" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-tag-input--tag-input)
+
+## Props
+
+- **Type:** `IressTagProps`
+- **Type declarations:** `@iress-oss/ids-components/dist/components/Tag/Tag.d.ts`
+
+```typescript
+import type { IressTagProps } from '@iress-oss/ids-components';
+```
+
+
+---
+
+*View interactive examples: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-tag--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-tag--docs)*

package/.ai/components/text.md

@@ -0,0 +1,195 @@
+# Text
+
+The IressText component allows you to set typographic styles either on one element, or a block on HTML elements.
+
+> **Component:** `import { IressText } from '@iress-oss/ids-components'`
+> **Storybook:** [Text in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-text--docs)
+
+## Quick Start
+
+```tsx
+import { IressText } from '@iress-oss/ids-components';
+
+<IressText />
+```
+
+import {
+  ComponentExample,
+  ComponentOverview,
+} from '@iress-oss/ids-storybook-config';
+
+## Usage
+
+### The `element` prop
+
+With the `element` prop you can select which HTML element you would like the text component to render as.
+
+It renders as a `div` by default, but can also be set to any standard typography element.
+
+```tsx
+<IressStack gap="spacing.1">
+{TEXT_ELEMENTS.map((element) => (
+<IressText key={element} element={element}>
+This is a {element} element.
+</IressText>
+))}
+</IressStack>
+```
+
+[View "Element" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-text--element)
+
+### The `textStyle` prop
+
+The `textStyle` prop (previously `variant`) allows you alter the default styling of the element that it selected.
+
+For example, in order to maintain the semantic structure of headings, you may need to style a `h2` element like a `h4`. Or you may want to style your heading using one of our display text formats.
+
+```tsx
+<IressStack gap="md">
+{TEXT_STYLES.map((variant) => (
+<IressText key={variant} textStyle={variant}>
+This is the {variant} text style.
+</IressText>
+))}
+</IressStack>
+```
+
+[View "Variant" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-text--variant)
+
+### The `color` prop
+
+The `color` prop (previously `mode`) can be used to set the colour of the text to these predefined mode colours: Body, Muted, Primary, Info, Success, Warning, Danger, Positive and Negative.
+
+```tsx
+<IressStack gap="md">
+{COLOR_TOKENS.map((mode) => (
+<IressText key={mode} color={mode}>
+This is {mode} mode.
+</IressText>
+))}
+<IressText color="colour.primary.text">
+Nested text mode demonstration:{' '}
+<IressText>
+I am nested, and return to the original colour
+</IressText>
+</IressText>
+</IressStack>
+```
+
+[View "Mode" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-text--mode)
+
+### The `textAlign` prop
+
+The `textAlign` prop (previously `align`) can be used to set the text's alignment.
+
+```tsx
+<IressStack gap="md">
+<IressText textAlign="left">
+...
+</IressText>
+<IressText textAlign="center">
+...
+</IressText>
+<IressText textAlign="right">
+...
+</IressText>
+<IressText textAlign="justify">
+...
+</IressText>
+<IressText textAlign="inherit">
+...
+</IressText>
+</IressStack>
+```
+
+[View "Align" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-text--align)
+
+## Behaviour
+
+### Block of typographic content
+
+If you just need to style a block of typography content, you can just wrap the entire block of HTML with the text component.
+
+```tsx
+<IressText maxWidth="container.md" mx="auto" px="spacing.2">
+<h2>History</h2>
+<h3>Founding and Early Years (1993 - 2000)</h3>
+<p>
+<a href="https://iress.com" target="_blank">
+Iress Limited (ASX: IRE)
+</a>{' '}
+was founded in 1993 in Melbourne, Australia, as a provider of financial
+market data and trading software. Initially, the company focused on
+delivering technology solutions for stockbrokers and traders, providing
+real-time market data, order management, and trading execution tools.
+</p>
+<h3>Expansion and IPO (2001 - 2010)</h3>
+<p>
+In 2001, Iress went public, listing on the Australian Securities
+Exchange (ASX). This move provided the company with capital to expand
+its operations and invest in new technologies. During this period, Iress
+expanded its services beyond trading platforms to include financial
+planning software, portfolio management, and wealth management
+solutions. The company also started expanding internationally, entering
+markets such as the UK, Canada, New Zealand, and South Africa, through
+organic growth and acquisitions.
+</p>
+<h3>Global Growth and Acquisitions (2011 - 2020)</h3>
+<p>
+Between 2011 and 2020, Iress continued its global expansion through
+acquisitions and product diversification. Key acquisitions included:
+</p>
+<ul>
+<li>
+Avelo (2013): Strengthened its presence in the UK financial services
+market.
+</li>
+<li>
+Pulse Software (2014): Added financial advice solutions to its
+portfolio.
+</li>
+<li>
+INET BFA (2016): Expanded its reach into South Africa’s financial
+market.
+</li>
+<li>
+OneVue (2020): Enhanced its superannuation and investment
+administration capabilities.
+</li>
+</ul>
+<p>
+During this period, Iress also expanded into mortgage lending technology
+and digital financial services, adapting to the increasing demand for
+automation and efficiency in financial markets.
+</p>
+<h3>Recent Developments (2021 - Present)</h3>
+<p>
+In 2021, Iress announced a strategic review of its business, focusing on
+streamlining operations and improving profitability. The company also
+experienced leadership changes, including new CEO appointments to drive
+digital transformation.{' '}
+</p>
+<p>
+Iress has continued to innovate with cloud-based solutions, artificial
+intelligence (AI), and data analytics, catering to financial
+institutions, brokers, and wealth management firms globally.
+</p>
+<pre>Some code in here</pre>
+</IressText>
+```
+
+[View "TypographicBlock" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-text--typographic-block)
+
+## Props
+
+- **Type:** `IressTextProps`
+- **Type declarations:** `@iress-oss/ids-components/dist/components/Text/Text.d.ts`
+
+```typescript
+import type { IressTextProps } from '@iress-oss/ids-components';
+```
+
+
+---
+
+*View interactive examples: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-text--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-text--docs)*