@iress-oss/ids-components 6.0.0-alpha.39 → 6.0.0-alpha.40

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/.ai/guides/styling-props-accessibility.md +26 -1
  2. package/.ai/skills/figma-to-ids.md +8 -0
  3. package/.ai/skills/ui-doctor.md +8 -4
  4. package/.ai/skills/ui-translation.md +42 -33
  5. package/.ai/skills/version-migration.md +9 -1
  6. package/dist/interfaces.d.ts +16 -3
  7. package/dist/patterns/Shadow/Shadow.js +1 -1
  8. package/dist/style.css +1 -1
  9. package/dist/styled-system/types/prop-type.d.ts +1 -1
  10. package/package.json +1 -1
package/.ai/guides/styling-props-accessibility.md CHANGED
@@ -9,7 +9,22 @@ These are all styling props related to screen readers and accessibility. They al
9
9
 
10
10
  The `focusable` prop allows you to set the focus state of a component. This is useful for components that need to be interactive via keyboard, but are not necessarily a button or input.
11
11
 
12
- It can be set to `true` to enable focus styles when the element is focused using keyboard navigation, or `within` to show focus styles when an element within is focused.
12
+ It accepts the following values:
13
+
14
+ | Value | Description |
15
+ | ---------------------- | -------------------------------------------------------------- |
16
+ | `'true'` | Standard focus-visible ring on the element itself |
17
+ | `'within'` | Focus ring when the element or any of its children are focused |
18
+ | `'inset'` | Inset focus ring inside the element |
19
+ | `'has-button'` | Focus ring delegated from a child button |
20
+ | `'has-input'` | Focus ring delegated from a child input, textarea, or select |
21
+ | `'has-switch'` | Focus ring delegated from a child switch |
22
+ | `'label-after'` | Focus ring applied to the adjacent label |
23
+ | `'expander-activator'` | Focus ring for expander/activator elements |
24
+ | `'select-activator'` | Focus ring for select activator elements |
25
+ | `'slider'` | Focus ring for range slider thumbs |
26
+ | `'group'` | Focus ring triggered by a parent `.group` container |
27
+ | `'within:inset'` | Inset focus ring when a child element is focused |
13
28
 
14
29
  ```tsx
15
30
  <IressAccessibility focusable tabIndex={0}>
@@ -19,6 +34,16 @@ It can be set to `true` to enable focus styles when the element is focused using
19
34
 
20
35
  [View "focusable" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_styling-props-accessibility--focusable)
21
36
 
37
+ ### Inset focus ring
38
+
39
+ ```tsx
40
+ <IressAccessibility focusable="inset" tabIndex={0} p="spacing.4" bg="colour.neutral.20">
41
+ This element uses an inset focus ring, which renders inside the element boundary.
42
+ </IressAccessibility>
43
+ ```
44
+
45
+ [View "focusableInset" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_styling-props-accessibility--focusable-inset)
46
+
22
47
  ## `srOnly`
23
48
 
24
49
  The `srOnly` prop allows you to set a component to be only visible on screen readers. It is used to ensure the screen reader has context of the screen to help the user understand the tasks required of them.
package/.ai/skills/figma-to-ids.md CHANGED
@@ -11,6 +11,12 @@ Translate Figma design properties and structures into IDS (Iress Design System)
11
11
  3. **Extract tokens** — Convert Figma design values to IDS design token references
12
12
  4. **Generate code** — Produce clean React/TypeScript with proper IDS imports
13
13
 
14
+ > **Important:** IDS v6 is currently in alpha. Install with the `@alpha` tag:
15
+ >
16
+ > ```bash
17
+ > npm install @iress-oss/ids-components@alpha
18
+ > ```
19
+
14
20
  ## Figma Component → IDS Component Mapping
15
21
 
16
22
  ### Auto-Layout → Layout Components
@@ -132,6 +138,8 @@ IDS base spacing unit = 4px (0.25rem). Map Figma pixel values:
132
138
  | Body / SM Strong (Inter 12px/600) | `typography.body.sm.strong` | `<IressText size="sm" weight="strong">` |
133
139
  | Code (Space 16px/400) | `typography.code` | `<IressText element="code">` |
134
140
 
141
+ > **Tip:** When translating Figma frames that contain mixed or unstructured text (e.g. CMS content, markdown, rich text blocks), wrap the content in `IressText` and nest native HTML elements (`<p>`, `<strong>`, `<a>`, `<ul>`, etc.) inside it. This is an allowed pattern that lets `IressText` apply consistent typography while preserving the original content structure.
142
+
135
143
  ## Translation Examples
136
144
 
137
145
  ### Figma: Login Form Frame
package/.ai/skills/ui-doctor.md CHANGED
@@ -155,8 +155,8 @@ Check that the application follows these core IDS principles:
155
155
 
156
156
  - **IressProvider must wrap the application root** — Required for fonts, CSS variables, and theming
157
157
  - **The IDS component CSS must be imported** — `@iress-oss/ids-components/dist/style.css` contains all component styles
158
- - Users only need to install `@iress-oss/ids-components` — the tokens are bundled within the component library and do not need to be installed separately
159
- - If using design tokens directly in application code (for custom styling), users should additionally install `@iress-oss/ids-tokens` and import `@iress-oss/ids-tokens/build/css-vars.css`
158
+ - Users only need to install `@iress-oss/ids-components@alpha` — the tokens are bundled within the component library and do not need to be installed separately. **IDS v6 is currently in alpha**, so the `@alpha` tag is required (e.g. `npm install @iress-oss/ids-components@alpha`)
159
+ - If using design tokens directly in application code (for custom styling), users should additionally install `@iress-oss/ids-tokens@alpha` and import `@iress-oss/ids-tokens/build/css-vars.css`
160
160
 
161
161
  ```typescript
162
162
  // ✅ Correct setup — minimum required
@@ -190,7 +190,10 @@ import { IressProvider } from '@iress-oss/ids-components';
190
190
  // Components will render without styles!
191
191
 
192
192
  // ❌ Incorrect — installing tokens separately just for provider setup
193
- yarn add @iress-oss/ids-tokens // Not needed unless using tokens directly
193
+ yarn add @iress-oss/ids-tokens@alpha // Not needed unless using tokens directly
194
+
195
+ // ❌ Incorrect — installing without @alpha tag (will not resolve to v6)
196
+ yarn add @iress-oss/ids-components // Must use @alpha tag
194
197
  ```
195
198
 
196
199
  #### b. Design Token Usage
@@ -325,7 +328,7 @@ Applications should use `IressLoading` for all loading states to ensure consiste
325
328
 
326
329
  #### f. Semantic Component Usage
327
330
 
328
- - **Use `IressText` for all text** — Instead of raw `<p>`, `<span>`, `<h1>`–`<h6>` (unless nested inside `IressText` for styling)
331
+ - **Use `IressText` for all text** — Instead of raw `<p>`, `<span>`, `<h1>`–`<h6>`. Note: nesting native HTML elements (e.g. `<p>`, `<strong>`, `<a>`, `<ul>`) *inside* `IressText` is an allowed pattern for rendering CMS content, markdown output, or other unstructured data sources
329
332
  - **Use `IressAlert` for feedback** — Instead of custom notification/alert components
330
333
  - **Use `IressModal status` for confirmation dialogs** — Instead of custom danger/success/warning confirmation modals. Use the `actions` prop for buttons (`footer` is not available when `status` is set)
331
334
  - **Use `IressIcon` for icons** — Instead of inline SVGs or custom icon components (unless the icon is a hero graphic that doesn't fit the standard icon use case)
@@ -346,6 +349,7 @@ Not every raw HTML element is a violation. The following are **acceptable except
346
349
  | `<form>` wrapping a single action (e.g., search bar) | `IressForm` is best for multi-field forms; standalone search inputs may use `IressAutocomplete` or `IressField` + `IressInput` directly |
347
350
  | `<input type="hidden">` | Not user-facing UI |
348
351
  | Custom components wrapping IDS components internally | App-level abstraction is valid as long as IDS components are used underneath |
352
+ | Native HTML elements nested inside `IressText` | Allowed for rendering CMS content, markdown output, or other unstructured data sources where the content structure is not controlled by the application |
349
353
 
350
354
  **When reporting:** If a potential violation falls into an exception category, note it as "Reviewed — Acceptable Exception" rather than a finding. This prevents false positives and keeps reports actionable.
351
355
 
package/.ai/skills/ui-translation.md CHANGED
@@ -6,6 +6,14 @@ Translate natural language UI descriptions into IDS (Iress Design System) compon
6
6
 
7
7
  ## Setup
8
8
 
9
+ > **Important:** IDS v6 is currently in alpha. Install with the `@alpha` tag:
10
+ >
11
+ > ```bash
12
+ > npm install @iress-oss/ids-components@alpha
13
+ > # If using tokens directly:
14
+ > npm install @iress-oss/ids-tokens@alpha
15
+ > ```
16
+
9
17
  ```tsx
10
18
  import '@iress-oss/ids-components/dist/style.css'; // Required — component styles
11
19
  import '@iress-oss/ids-tokens/build/css-vars.css'; // Required if using tokens directly
@@ -108,38 +116,38 @@ function App() {
108
116
 
109
117
  Most IDS components accept styling props for layout adjustments:
110
118
 
111
- | Prop | Purpose | Values |
112
- | -------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
113
- | `alignSelf` | Override flex alignment | `"start"`, `"end"`, `"center"`, `"stretch"` |
114
- | `bg` | Background colour | Colour tokens: `"colour.primary.fill"`, `"colour.neutral.20"`, `"alt"`, etc. |
115
- | `borderRadius` | Border radius | Radius tokens: `"radius.0"` – `"radius.4"`, `"none"` |
116
- | `color` | Text colour | Colour tokens: `"colour.neutral.80"`, `"colour.primary.text"`, etc. |
117
- | `flex` | Flex grow | `"1"` only |
118
- | `focusable` | Apply focus ring | `"true"`, `"within"` |
119
- | `hideFrom` | Hide from breakpoint up | `true`, or breakpoints: `"sm"`, `"md"`, `"lg"`, `"xl"` |
120
- | `hideBelow` | Hide below breakpoint | Breakpoints: `"sm"`, `"md"`, `"lg"`, `"xl"` |
121
- | `maxWidth` | Max width | Size tokens: `"container.sm"`, `"container.md"`, etc. |
122
- | `m` | Margin (all sides) | Spacing tokens: `"xs"` – `"xl"`, `"spacing.1"` – `"spacing.10"`, `"auto"`, negatives (responsive) |
123
- | `mx` | Margin horizontal | Same as `m` (responsive) |
124
- | `my` | Margin vertical | Same as `m` (responsive) |
125
- | `mt` | Margin top | Same as `m` (responsive) |
126
- | `mr` | Margin right | Same as `m` (responsive) |
127
- | `mb` | Margin bottom | Same as `m` (responsive) |
128
- | `ml` | Margin left | Same as `m` (responsive) |
129
- | `noGutter` | Remove last-child bottom margin | `true` / `false` |
130
- | `p` | Padding (all sides) | Spacing tokens: `"xs"` – `"xl"`, `"spacing.1"` – `"spacing.10"` (responsive) |
131
- | `px` | Padding horizontal | Same as `p` (responsive) |
132
- | `py` | Padding vertical | Same as `p` (responsive) |
133
- | `pt` | Padding top | Same as `p` (responsive) |
134
- | `pr` | Padding right | Same as `p` (responsive) |
135
- | `pb` | Padding bottom | Same as `p` (responsive) |
136
- | `pl` | Padding left | Same as `p` (responsive) |
137
- | `scrollable` | Enable overflow scrolling | `true`, `"x"`, `"y"` |
138
- | `srOnly` | Screen-reader only | `true` / `false` (responsive) |
139
- | `stretch` | Fill parent height | `true` / `false` |
140
- | `textAlign` | Text alignment | `"left"`, `"right"`, `"center"`, `"justify"`, `"inherit"` |
141
- | `textStyle` | Typography style | `"typography.body.sm"`, `"typography.body.md"`, `"typography.heading.1"` – `"typography.heading.5"`, `"typography.code"` |
142
- | `width` | Element width | Size tokens: `"input.2"` – `"input.16"`, `"3/12"` – `"12/12"` (grid), `"auto"` (responsive) |
119
+ | Prop | Purpose | Values |
120
+ | -------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
121
+ | `alignSelf` | Override flex alignment | `"start"`, `"end"`, `"center"`, `"stretch"` |
122
+ | `bg` | Background colour | Colour tokens: `"colour.primary.fill"`, `"colour.neutral.20"`, `"alt"`, etc. |
123
+ | `borderRadius` | Border radius | Radius tokens: `"radius.0"` – `"radius.4"`, `"none"` |
124
+ | `color` | Text colour | Colour tokens: `"colour.neutral.80"`, `"colour.primary.text"`, etc. |
125
+ | `flex` | Flex grow | `"1"` only |
126
+ | `focusable` | Apply focus ring | `"true"`, `"within"`, `"within:inset"`, `"inset"`, `"has-button"`, `"has-input"`, `"has-switch"`, `"label-after"`, `"expander-activator"`, `"select-activator"`, `"slider"`, `"group"` |
127
+ | `hideFrom` | Hide from breakpoint up | `true`, or breakpoints: `"sm"`, `"md"`, `"lg"`, `"xl"` |
128
+ | `hideBelow` | Hide below breakpoint | Breakpoints: `"sm"`, `"md"`, `"lg"`, `"xl"` |
129
+ | `maxWidth` | Max width | Size tokens: `"container.sm"`, `"container.md"`, etc. |
130
+ | `m` | Margin (all sides) | Spacing tokens: `"xs"` – `"xl"`, `"spacing.1"` – `"spacing.10"`, `"auto"`, negatives (responsive) |
131
+ | `mx` | Margin horizontal | Same as `m` (responsive) |
132
+ | `my` | Margin vertical | Same as `m` (responsive) |
133
+ | `mt` | Margin top | Same as `m` (responsive) |
134
+ | `mr` | Margin right | Same as `m` (responsive) |
135
+ | `mb` | Margin bottom | Same as `m` (responsive) |
136
+ | `ml` | Margin left | Same as `m` (responsive) |
137
+ | `noGutter` | Remove last-child bottom margin | `true` / `false` |
138
+ | `p` | Padding (all sides) | Spacing tokens: `"xs"` – `"xl"`, `"spacing.1"` – `"spacing.10"` (responsive) |
139
+ | `px` | Padding horizontal | Same as `p` (responsive) |
140
+ | `py` | Padding vertical | Same as `p` (responsive) |
141
+ | `pt` | Padding top | Same as `p` (responsive) |
142
+ | `pr` | Padding right | Same as `p` (responsive) |
143
+ | `pb` | Padding bottom | Same as `p` (responsive) |
144
+ | `pl` | Padding left | Same as `p` (responsive) |
145
+ | `scrollable` | Enable overflow scrolling | `true`, `"x"`, `"y"` |
146
+ | `srOnly` | Screen-reader only | `true` / `false` (responsive) |
147
+ | `stretch` | Fill parent height | `true` / `false` |
148
+ | `textAlign` | Text alignment | `"left"`, `"right"`, `"center"`, `"justify"`, `"inherit"` |
149
+ | `textStyle` | Typography style | `"typography.body.sm"`, `"typography.body.md"`, `"typography.heading.1"` – `"typography.heading.5"`, `"typography.code"` |
150
+ | `width` | Element width | Size tokens: `"input.2"` – `"input.16"`, `"3/12"` – `"12/12"` (grid), `"auto"` (responsive) |
143
151
 
144
152
  ## Translation Examples
145
153
 
@@ -247,4 +255,5 @@ function SettingsPage() {
247
255
  6. **Always include labels** — All form inputs need accessible labels via `IressField`
248
256
  7. **Use status for feedback** — `IressAlert` for inline messages, `IressModal status="danger"` for confirmation dialogs, `status` prop on buttons for danger/success
249
257
  8. **Prefer IDS components** — Use `IressText` instead of raw `<p>`, `IressButton` instead of `<button>`
250
- 9. **Check the component docs** — Read the specific component doc for detailed props and patterns (`node_modules/@iress-oss/ids-components/.ai/components/`)
258
+ 9. **Native elements inside `IressText` are OK** — When rendering CMS content, markdown output, or other unstructured data sources, it is acceptable to nest native HTML elements (e.g. `<p>`, `<strong>`, `<a>`, `<ul>`) inside `IressText`. This lets `IressText` provide consistent typography while allowing flexible inner content structure.
259
+ 10. **Check the component docs** — Read the specific component doc for detailed props and patterns (`node_modules/@iress-oss/ids-components/.ai/components/`)
package/.ai/skills/version-migration.md CHANGED
@@ -1511,10 +1511,17 @@ import { IressButton } from '@iress/components-react';
1511
1511
  // ❌ Old (OUI)
1512
1512
  import { Button, Input } from '@iress/oui';
1513
1513
 
1514
- // ✅ IDS v6
1514
+ // ✅ IDS v6 (install with @alpha tag: npm install @iress-oss/ids-components@alpha)
1515
1515
  import { IressButton, IressInput } from '@iress-oss/ids-components';
1516
1516
  ```
1517
1517
 
1518
+ > **Important:** IDS v6 is currently in alpha. Install with the `@alpha` tag:
1519
+ >
1520
+ > ```bash
1521
+ > npm install @iress-oss/ids-components@alpha
1522
+ > npm install @iress-oss/ids-tokens@alpha # if using tokens directly
1523
+ > ```
1524
+
1518
1525
  ### CSS entry point
1519
1526
 
1520
1527
  ```ts
@@ -2877,6 +2884,7 @@ Don't update when:
2877
2884
  9. **Build**: Production build completes without errors, check bundle size
2878
2885
 
2879
2886
  The validation script checks for:
2887
+
2880
2888
  - Old imports (`@iress/oui`, `@iress/components-react`)
2881
2889
  - Old test utils (`idsFireEvent`, `mockLazyLoadedComponents`)
2882
2890
  - Deprecated props (`variant=`, `isOpen=`, `gutter=`, etc.)
package/dist/interfaces.d.ts CHANGED
@@ -225,9 +225,22 @@ export interface IressCSSProps {
225
225
  */
226
226
  color?: UtilityValues['color'];
227
227
  /**
228
- * The `focusable` prop is used to apply the focus ring when focused. It can be set to `true` to apply focus styles on focus, or `'within'` to apply focus styles when the element or any of its children are focused.
229
- */
230
- focusable?: 'true' | 'within';
228
+ * The `focusable` prop is used to apply the focus ring when focused.
229
+ *
230
+ * - `'true'` — standard focus-visible ring on the element itself
231
+ * - `'within'` — focus ring when the element or any of its children are focused
232
+ * - `'inset'` — inset focus ring inside the element
233
+ * - `'has-button'` — focus ring delegated from a child button
234
+ * - `'has-input'` — focus ring delegated from a child input/textarea/select
235
+ * - `'has-switch'` — focus ring delegated from a child switch
236
+ * - `'label-after'` — focus ring applied to the adjacent label
237
+ * - `'expander-activator'` — focus ring for expander/activator elements
238
+ * - `'select-activator'` — focus ring for select activator elements
239
+ * - `'slider'` — focus ring for range slider thumbs
240
+ * - `'group'` — focus ring triggered by a parent `.group` container
241
+ * - `'within:inset'` — inset focus ring when a child element is focused
242
+ */
243
+ focusable?: 'true' | 'within' | 'within:inset' | 'inset' | 'has-button' | 'has-input' | 'has-switch' | 'label-after' | 'expander-activator' | 'select-activator' | 'slider' | 'group';
231
244
  /**
232
245
  * The `flex` prop is used to set the flex grow property of an element. It allows the element to grow and fill available space in a flex container.
233
246
  *