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

package/.ai/guides/styling-props-layout.md

@@ -0,0 +1,172 @@
+# Layout
+
+> **Guide:** `@iress-oss/ids-components`
+> **Storybook:** [Layout in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_styling-props-layout--docs)
+
+These are all styling props related to modifying layout.
+
+## `alignSelf`
+
+The `alignSelf` prop allows you to override the alignItems value set by a parent flex container for individual components. This is useful when you want to adjust the alignment of a single item without affecting the entire container.
+
+```tsx
+<IressStack gap="md" horizontalAlign="center">
+<IressPanel bg="alt">First panel (no alignSelf)</IressPanel>
+<IressPanel bg="colour.primary.surface" alignSelf={alignSelf}>
+Panel with alignSelf prop
+</IressPanel>
+<IressPanel bg="alt">Third panel (no alignSelf)</IressPanel>
+</IressStack>
+```
+
+[View "alignSelf" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_styling-props-layout--align-self)
+
+## `flex="1"`
+
+The `flex="1"` prop is used to make a component grow and fill available space in a flex container. Setting `flex` to `1` allows the component to take up one unit of available space, ensuring consistent behavior across components.
+
+Note: We only allow `1` as a value to maintain design consistency.
+
+```tsx
+<IressStack gap="md" horizontalAlign="center" style={{ height: 400 }}>
+<IressPanel bg="alt">First panel (no flex)</IressPanel>
+<IressPanel>
+{children ?? (
+<>
+{args.flex
+? 'Panel with flex set to 1, so it will fill the available space.'
+: 'This panel is not set to flex, so it will only take up the space it needs.'}
+</>
+)}
+</IressPanel>
+<IressPanel bg="alt">Third panel (no flex)</IressPanel>
+</IressStack>
+```
+
+[View "flex1" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_styling-props-layout--flex1)
+
+## `hideFrom` and `hideBelow`
+
+The `hideFrom` and `hideBelow` props allow you to hide content from both visual users and screen readers at different breakpoints. This is useful when certain content is not relevant on smaller screens, and you want to ensure that screen reader users have the same experience as visual users.
+
+```tsx
+<IressLayout hideFrom="lg">
+  Only on mobile screens
+</IressLayout>
+```
+
+[View "hideFrom" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_styling-props-layout--hide-from)
+```tsx
+<IressLayout hideBelow="lg">
+  Only on large screens
+</IressLayout>
+```
+
+[View "hideBelow" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_styling-props-layout--hide-below)
+
+## `scrollable`
+
+The scrollable prop enables scrolling behavior for an element when its content
+overflows its bounds. It sets the `overflow` CSS property to `auto`, allowing
+scrollbars to appear as needed. The scrollbar has been styled to match the
+design system.
+
+You can set the value to `true` to enable scrolling on both axes, or specify `'x'` or `'y'` to restrict scrolling to a single axis.
+
+```tsx
+<IressCard px="sm">
+<IressPanel>
+<h1>History of Iress</h1>
+
+<p>
+<strong>Iress Limited</strong> (originally “Iress Market Technology”)
+is an Australian-based software company that provides technology
+solutions to the financial services industry. Its clients span sectors
+including wealth management, financial advice, trading, investment
+management, mortgages, and superannuation.
+</p>
+
+<section>
+<h2>Early Years (1993 – 2000)</h2>
+<p>
+Iress was founded in <strong>1993</strong> in Melbourne, Australia.
+The company's initial product offerings focused on market data and
+trading software for financial institutions and professionals
+needing live pricing and analytics tools.
+</p>
+<p>
+In <strong>2000</strong>, Iress listed on the{' '}
+<strong>Australian Stock Exchange (ASX)</strong> under the ticker{' '}
+<strong>IRE</strong>, signaling its growth beyond market data
+services.
+</p>
+</section>
+</IressPanel>
+</IressCard>
+),
+};
+
+export const stretch: Story = {
+...alignSelf,
+args: {
+stretch: true,
+},
+render: ({ children, ...args }) => (
+<IressContainer bg="alt" py="xl" px="xl" borderRadius="none" fluid>
+<IressRow gutter="xl" verticalAlign="stretch">
+<IressCol>
+<IressPanel>
+{children ?? (
+<>
+{args.stretch
+? 'Panel is set to stretch, so it will fill the available space.'
+: 'This panel is not set to stretch, so it will only take up the space it needs.'}
+</>
+)}
+</IressPanel>
+</IressCol>
+<IressCol>
+<IressPanel>
+<h1>History of Iress</h1>
+
+<p>
+<strong>Iress Limited</strong> (originally “Iress Market
+Technology”) is an Australian-based software company that provides
+technology solutions to the financial services industry. Its
+clients span sectors including wealth management, financial
+advice, trading, investment management, mortgages, and
+superannuation.
+</p>
+
+<section>
+<h2>Early Years (1993 – 2000)</h2>
+<p>
+Iress was founded in <strong>1993</strong> in Melbourne,
+Australia. The company's initial product offerings focused on
+market data and trading software for financial institutions and
+professionals needing live pricing and analytics tools.
+</p>
+<p>
+In <strong>2000</strong>, Iress listed on the{' '}
+<strong>Australian Stock Exchange (ASX)</strong> under the
+ticker <strong>IRE</strong>, signaling its growth beyond market
+data services.
+</p>
+</section>
+</IressPanel>
+</IressCol>
+</IressRow>
+</IressContainer>
+```
+
+[View "scrollable" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_styling-props-layout--scrollable)
+
+## `stretch`
+
+The `stretch` prop is used to stretch a component to fill the available space. It is used in components such as `IressPanel` to ensure each column in a layout takes up the same amount of space.
+
+[View "stretch" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_styling-props-layout--stretch)
+
+---
+
+*View in Storybook: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_styling-props-layout--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_styling-props-layout--docs)*

package/.ai/guides/styling-props-radius.md

@@ -0,0 +1,39 @@
+# Radius
+
+> **Guide:** `@iress-oss/ids-components`
+> **Storybook:** [Radius in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_styling-props-radius--docs)
+
+These are all styling props related to changing the radius of a component
+affects the visual softness and perceived friendliness of the interface,
+influencing the overall user experience.
+
+## `borderRadius`
+
+The `borderRadius` prop allows you to change the border radius of any component. It should be used sparingly, and often used when creating custom components that are not part of the design system, however you still want to retain the look and feel of the rest of the system.
+
+```tsx
+<IressInput
+borderRadius={borderRadius}
+px="spacing.4"
+py="spacing.2"
+placeholder="Search everything"
+/>
+```
+
+[View "borderRadius" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_styling-props-radius--border-radius)
+
+### Removing border radius
+
+In some cases you may need to remove the border-radius to achieve design requirements. This can be done using `radius.000` or `none`.
+
+```tsx
+<IressPanel borderRadius={borderRadius} bg="alt">
+No radius here
+</IressPanel>
+```
+
+[View "noBorderRadius" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_styling-props-radius--no-border-radius)
+
+---
+
+*View in Storybook: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_styling-props-radius--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_styling-props-radius--docs)*

package/.ai/guides/styling-props-reference.md

@@ -0,0 +1,305 @@
+# Styling props
+
+> **Guide:** `@iress-oss/ids-components`
+> **Storybook:** [Styling props in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_styling-props-styling-props--docs)
+
+This page lists all the custom styling properties available in our components,
+which design tokens they are mapped to and which CSS properties they affect.
+
+Styling properties are the recommended way of customising components for your needs, as they ensure your styles are compatible when any theme is applied to your application. If you need further customisation, you can use regular CSS and reference the tokens directly.
+
+These replace the utility classes and internal component tokens provided by previous versions of the design system.
+
+## Reference
+
+[View "Reference" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_styling-props-reference--reference)
+
+---
+
+## Responsive
+
+Props marked responsive can accept either a single value that affects all breakpoints, or a responsive object map that sets a different value based on breakpoint.
+
+```tsx
+<IressPanel p="xs" /> // applies extra small padding to all breakpoints
+<IressPanel p={{ base: 'lg', md: 'sm' }} /> // applies large padding by default, and changes to small padding once on medium sized screens.
+```
+
+## `iressCss`
+
+In some cases you may need to apply styling props to a non-IDS component. You can do this by using the `iressCss` prop, which accepts an object of styling props and returns a string of class names that can be applied to any element.
+
+This will also work without JSX, allowing you to apply styling props to any element in your application.
+
+```tsx
+<div className={iressCss({ p: 'xs', bg: 'colour.primary.surface' })}>
+  This div has extra small padding and a primary background colour.
+</div>
+```
+
+## `IressStyled`
+
+The `IressStyled` component is a flexible wrapper that gives you direct access to all styling props. Use it when you need custom styling without creating a dedicated component or writing custom CSS.
+
+```tsx
+<IressStyled p="xs" bg="colour.primary.surface">
+  This div has extra small padding and a primary background colour.
+</IressStyled>
+```
+
+## Migrating from version 5
+
+### Utility classes
+
+If you have been using the utility classes from previous versions of IDS (eg. `iress-p--xs`), you will need to replace them with the new styling props. The utility classes are no longer supported in version 6.
+
+```tsx
+<DiffViewer oldValue={`<IressPanel className="iress-m--sm" />`}
+newValue={`<IressPanel m="sm" />`}
+/>
+```
+
+[View "MigratingFromUtilities" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_styling-props-reference--migrating-from-utilities)
+
+---
+
+### Internal component tokens
+
+If you have been using the internal component tokens (eg. `--iress-background-color`), you will need to replace them with the new styling props. The internal component tokens are no longer supported in version 6.
+
+#### Note
+
+- Not every single internal component token has a direct mapping to a styling prop. For example, things like border width are no longer customisable. This helps ensure a consistent and accessible experience for all applications no matter the theme that is applied to them.
+- Styling props only allow token values, not custom values (eg. `colour.system.status.danger` is allowed but not `red`). This is to ensure that the styling props are theme agnostic and can be used with any theme. If you need to use a custom value, you can use custom CSS or inline styles.
+
+```tsx
+<DiffViewer oldValue={`<IressPanel style={{ '--iress-background-color': 'var(--iress-g-success-color)' }} />`}
+newValue={`<IressPanel bg="colour.system.success.fill" />`}
+/>
+```
+
+[View "MigratingFromInternalTokens" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_styling-props-reference--migrating-from-internal-tokens)
+
+---
+
+## Best Practices
+
+### When to use styling props
+
+Styling props should be your **first choice** for customizing components in most cases. They provide:
+
+- **Theme compatibility**: Automatically work with any theme
+- **Type safety**: TypeScript ensures you use valid tokens
+- **Consistency**: Design tokens enforce the design system's visual language
+- **Accessibility**: Semantic color tokens maintain proper contrast ratios
+- **Maintainability**: Changes to design tokens automatically update all usages
+
+**✅ Use styling props when:**
+
+- Customizing IDS components (`IressPanel`, `IressButton`, `IressText`, etc.)
+- Applying spacing, colors, or typography that exist in the design system
+- Building new features that should follow the design system
+- Creating reusable layouts and patterns
+
+### When to use `iressCss()`
+
+The `iressCss()` function is useful for applying styling props to **non-IDS components** or when you need to combine styling props programmatically.
+
+**✅ Use `iressCss()` when:**
+
+- Styling third-party library components that don't accept styling props
+- Applying styling props to native HTML elements (`<div>`, `<section>`, etc.)
+- Building complex, reusable style combinations
+- Working outside of JSX (e.g., in vanilla JavaScript)
+
+```tsx
+// ✅ CORRECT - Using iressCss for non-IDS component
+<ThirdPartyComponent
+  className={iressCss({ p: 'md', bg: 'colour.primary.surface' })}
+>
+  Content
+</ThirdPartyComponent>
+
+// ✅ CORRECT - Using iressCss with native HTML
+<div className={iressCss({ display: 'flex', gap: 'sm' })}>
+  Flexbox layout with design system spacing
+</div>
+```
+
+### When to use CSS-in-JS
+
+If you're using a CSS-in-JS library (like styled-components, emotion, or vanilla-extract), use the **`cssVars` object from `@iress-oss/ids-tokens`** to reference design tokens.
+
+**✅ Use CSS-in-JS with `cssVars` when:**
+
+- Building custom components with a CSS-in-JS library
+- Creating complex styling logic that needs JavaScript
+- Working with third-party CSS-in-JS frameworks
+- Need programmatic access to token values
+
+```tsx
+
+// ✅ CORRECT - Using cssVars in CSS-in-JS
+const StyledComponent = styled.div`
+  padding: ${cssVars.spacing[400]}; /* md spacing */
+  background-color: ${cssVars.colour.primary.fill};
+  color: ${cssVars.colour.primary.onFill};
+  font-family: ${cssVars.typography.fontFamily.body};
+`;
+
+// ❌ INCORRECT - Hardcoded values in CSS-in-JS
+const BadComponent = styled.div`
+  padding: 16px;
+  background-color: #13213f;
+  color: #ffffff;
+`;
+```
+
+### When to use custom CSS
+
+Custom CSS should be **reserved for edge cases** where styling props and `iressCss()` don't meet your needs.
+
+**✅ Use custom CSS when:**
+
+- Implementing complex selectors (`:hover:not(.disabled)`, `> * + *`)
+- Working with pseudo-elements (`::before`, `::after`)
+- Creating animations and transitions
+- Styling custom components with unique design requirements
+- Using CSS features not available in styling props (e.g., `grid-template-areas`)
+
+**Important**: Even in custom CSS, prefer referencing design tokens via CSS variables:
+
+```css
+.custom-component {
+  /* ✅ CORRECT - Reference tokens in custom CSS */
+  padding: var(--spacing-4); /* md spacing */
+  background-color: var(--colour-primary-fill);
+
+  /* ❌ INCORRECT - Hardcoded values */
+  padding: 16px;
+  background-color: #13213f;
+}
+```
+
+### Decision guide
+
+Use this flowchart to choose the right approach:
+
+1. **Is it an IDS component?**
+   - Yes → Use styling props (``)
+   - No → Go to step 2
+
+2. **Does it need design system styling?**
+   - Yes → Use `iressCss()` (`className={iressCss({ p: 'md' })}`)
+   - No → Go to step 3
+
+3. **Are you using a CSS-in-JS library?**
+   - Yes → Use `cssVars` from `@iress-oss/ids-tokens`
+   - No → Go to step 4
+
+4. **Does it need complex selectors or CSS features?**
+   - Yes → Use custom CSS with CSS variable references
+   - No → Reconsider if styling props or `iressCss()` can work
+
+## Common Anti-Patterns
+
+Avoid these common mistakes when styling components:
+
+### ❌ Using inline styles instead of styling props
+
+**Problem**: Inline styles bypass the design system, making code non-themeable and inconsistent.
+
+```tsx
+// ❌ INCORRECT - Inline styles with hardcoded values
+<IressPanel style={{ padding: '16px', backgroundColor: '#F5F5F5' }}>
+  Content
+</IressPanel>
+
+// ✅ CORRECT - Styling props with tokens
+<IressPanel p="md" bg="colour.neutral.10">
+  Content
+</IressPanel>
+```
+
+**Why this matters**: Inline styles won't respond to theme changes, breaking the visual consistency of your application.
+
+### ❌ Hardcoded colors instead of semantic tokens
+
+**Problem**: Hardcoded color values don't adapt to different themes and may fail accessibility standards.
+
+```tsx
+// ❌ INCORRECT - Hardcoded hex colors
+<IressText style={{ color: '#000000' }}>Primary text</IressText>
+<IressPanel style={{ backgroundColor: '#13213F', color: '#FFFFFF' }}>
+  Featured content
+</IressPanel>
+
+// ✅ CORRECT - Semantic color tokens
+<IressText color="colour.primary.text">Primary text</IressText>
+<IressPanel bg="colour.primary.fill" color="colour.primary.onFill">
+  Featured content
+</IressPanel>
+```
+
+**Why this matters**: Semantic tokens like `colour.primary.fill` and `colour.primary.onFill` are guaranteed to have proper contrast and automatically adapt to theme changes.
+
+### ❌ Using className for basic styling
+
+**Problem**: Adding custom classes for basic spacing/colors adds unnecessary CSS and bypasses the design system.
+
+```tsx
+// ❌ INCORRECT - Custom class for basic styling
+<IressPanel className="my-custom-padding">
+  Content
+</IressPanel>
+
+// CSS file:
+.my-custom-padding {
+  padding: 24px;
+}
+
+// ✅ CORRECT - Styling prop with token
+<IressPanel p="lg">
+  Content
+</IressPanel>
+```
+
+**Why this matters**: Styling props are more maintainable, type-safe, and ensure consistency. Custom classes should only be used for complex styling needs.
+
+### ❌ Arbitrary spacing values
+
+**Problem**: Using spacing values outside the design system's scale creates inconsistency.
+
+```tsx
+// ❌ INCORRECT - Arbitrary spacing value
+<IressPanel style={{ padding: '17px' }}>
+  Content
+</IressPanel>
+
+// ✅ CORRECT - Design system spacing scale
+<IressPanel p="md"> {/* 16px */}
+  Content
+</IressPanel>
+
+// ✅ ALSO CORRECT - If you need more, use the next step
+<IressPanel p="lg"> {/* 24px */}
+  Content
+</IressPanel>
+```
+
+**Why this matters**: The spacing scale (`xs`, `sm`, `md`, `lg`, `xl`) creates visual rhythm and consistency. Stick to the scale unless you have a very specific edge case.
+
+### When hardcoded values ARE acceptable
+
+There are rare cases where hardcoded values are acceptable:
+
+- **One-off edge cases** that don't fit the design system (after discussion with design team)
+- **Third-party library constraints** where styling props can't be applied
+- **Gradual migration** from legacy code (with a plan to refactor)
+- **Prototyping** (with the expectation to use tokens in production)
+
+Even in these cases, document why the exception exists and plan to revisit it.
+
+---
+
+*View in Storybook: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_styling-props-styling-props--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_styling-props-styling-props--docs)*

package/.ai/guides/styling-props-sizing.md

@@ -0,0 +1,80 @@
+# Sizing
+
+> **Guide:** `@iress-oss/ids-components`
+> **Storybook:** [Sizing in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_styling-props-sizing--docs)
+
+These are all styling props related to changing the size of a component,
+refining the users expectation of the content and making screens easier to
+scan.
+
+## Overview
+
+The sizing props are a collection of widths that are used throughout the design system. Although they are not part of the design tokens (which is more related to theming), we have exposed them to you to allow you to build consistent user experiences where you may need to deviate from the default props of a component.
+
+The sizes here can be used in the `maxWidth` or `width` prop of any component, but they have been documented here according to their designated component.
+
+## Input widths
+
+Input widths are sizes that suit a specific number of characters. This sets an expectation of what data a user has to enter. The following list is the widths we have created for inputs, and have been designed to be used with `IressInput` but can be used with any component.
+
+- `input.2`: Two character width, usually used for accessor codes
+- `input.4`: Four character width, usually used for CVC, one-time passwords and pin numbers
+- `input.6`: Six character width, usually used for one-time passwords and pin numbers
+- `input.8`: Eight character width
+- `input.10`: Ten character width, usually used for dates
+- `input.12`: Twelve character width
+- `input.16`: Sixteen character width, usually used for credit cards
+
+For variable data entry, you can use percentage widths. These are usually used inside `IressFieldGroup`, and denote a connection between fields with different widths (eg. First name and Last name under Name). In most cases where there is no relationship but you would like to compact the layout to make it easier to scan, and you should use `IressRow` and `IressCol` instead with the `span` prop.
+
+- `input.25perc`: 25% width of parent container
+- `input.50perc`: 50% width of parent container
+- `input.75perc`: 75% width of parent container
+- `input.100perc`: 100% width of parent container
+
+```tsx
+<IressSizing bg="alt" width="input.16">
+  Credit card number wide panel
+</IressSizing>
+```
+
+[View "inputWidths" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_styling-props-sizing--input-widths)
+
+## Container widths
+
+Container widths are sizes that define the maximum width where content is considered easy to read on specific screen ranges. They are used by `IressContainer` to help ensure content is readable no matter the screen size.
+
+In some cases however, you may want to restrain the width even further (for example, single column content is usually easiest to read when it is confined to the centre of the screen). The container widths have been exposed so they can be used in the `maxWidth` prop of your own components.
+
+- `container.xs`: 100% of the screen's width
+- `container.sm`: 520px
+- `container.md`: 740px
+- `container.lg`: 960px
+- `container.xl`: 1160px
+- `container.xxl`: 1160px
+
+```tsx
+<IressContainer bg="alt" fluid maxWidth={maxWidth} width={width} p="xl">
+This container is extra readable cause its maxWidth is set to:{' '}
+<code>
+{typeof maxWidth === 'object'
+? stringifyStorybookArgs(maxWidth)
+: maxWidth}
+</code>
+.
+</IressContainer>
+```
+
+[View "containerWidths" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_styling-props-sizing--container-widths)
+
+## Overlay widths
+
+Overlay widths are sizes that define the width of overlay components such as Modals and Slideouts.
+
+- `overlay.sm`: 368px
+- `overlay.md`: 628px
+- `overlay.lg`: 800px
+
+---
+
+*View in Storybook: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_styling-props-sizing--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_styling-props-sizing--docs)*