@redis-ui/components 51.9.0 → 51.9.2

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.
package/README.md CHANGED
@@ -97,7 +97,7 @@ function MyPage() {
97
97
  ## Documentation
98
98
 
99
99
  - **Storybook**: live examples, props tables and composition guides for the components: https://redislabsdev.github.io/redis-ui/
100
- - **Agent skill**: `skills/redis-ui-components` ships in this package, with a reference for nearly every component (`Skeleton` and `TreeView` are still missing). See [Redis UI Skills](https://github.com/redislabsdev/redis-ui#redis-ui-skills) to link it into your project.
100
+ - **Agent skill**: `skills/redis-ui-components` ships in this package, with a reference for every component except the deprecated `Skeleton` (some low-level helpers aren't covered). See [Redis UI Skills](https://github.com/redislabsdev/redis-ui#redis-ui-skills) to link it into your project.
101
101
  - **Release notes**: [GitHub Releases](https://github.com/redislabsdev/redis-ui/releases)
102
102
 
103
103
  ## Contributing
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@redis-ui/components",
3
3
  "license": "UNLICENSED",
4
- "version": "51.9.0",
4
+ "version": "51.9.2",
5
5
  "type": "module",
6
6
  "sideEffects": false,
7
7
  "repository": "git@github.com:redislabsdev/redis-ui.git",
@@ -27,13 +27,62 @@ import { EditIcon, DeleteIcon, iconVariants, type IconVariant } from '@redis-ui/
27
27
  import { RedisLogoDarkMinIcon } from '@redis-ui/icons/multicolor';
28
28
  ```
29
29
 
30
+ ## Setup and themes
31
+
32
+ An app needs this once, at its root. Without the theme provider components render incorrectly, and without `TooltipProvider` every `Tooltip` (and components that render tooltips, such as `MoreInfoIcon`, `Chip`, `KeyValueList`) throws.
33
+
34
+ ```tsx
35
+ import 'modern-normalize/modern-normalize.css';
36
+ import '@redis-ui/styles/normalized-styles.css';
37
+ import '@redis-ui/styles/fonts.css'; // fonts-next.css with themesNext
38
+ import { ThemeProvider } from 'styled-components';
39
+ import { CommonStyles, themes } from '@redis-ui/styles';
40
+ import { TooltipProvider } from '@redis-ui/components';
41
+
42
+ <ThemeProvider theme={themes.light}>
43
+ <CommonStyles />
44
+ <TooltipProvider>
45
+ <App />
46
+ </TooltipProvider>
47
+ </ThemeProvider>;
48
+ ```
49
+
50
+ Before adding providers, check whether the app already mounts them (they usually live in the app's root component).
51
+
52
+ **Theme bundles** — `@redis-ui/styles` exports two, each with `light` and `dark`:
53
+
54
+ | Bundle | Fonts file | Use for |
55
+ |---|---|---|
56
+ | `themes` | `fonts.css` | The current (classic) Redis brand |
57
+ | `themesNext` | `fonts-next.css` | The next brand, used by the Redis Ultra console |
58
+
59
+ - Use the bundle the app already uses; never mix bundles in one app. Code under an Ultra surface uses `themesNext`.
60
+ - Components are the same for both bundles; only their look changes. Never wrap an individual component in its own `ThemeProvider` — it inherits the app's theme.
61
+ - Light/dark switching: replace `ThemeProvider` with `SwitchableModeThemeProvider` (`lightTheme`, `darkTheme`, `storageKey`, optional `allowSystemThemeMode` / `defaultThemeMode`) and render `ThemeModeSwitch` (see [ThemeModeSwitch](./references/ThemeModeSwitch.md)).
62
+
63
+ **Styling with tokens** — read values from the theme instead of hard-coding them, so custom UI follows both bundles and both modes:
64
+
65
+ ```tsx
66
+ import styled from 'styled-components';
67
+ import { useTheme } from '@redis-ui/styles';
68
+
69
+ const Panel = styled.div`
70
+ padding: ${({ theme }) => theme.core.space.space400};
71
+ background: ${({ theme }) => theme.semantic.color.background.neutral100};
72
+ `;
73
+
74
+ const { mode } = useTheme(); // 'light' | 'dark'
75
+ ```
76
+
77
+ `theme.core` holds the scales (`space`, `font`, `icon`, `shadow`, `zIndex`, `motion`, `focus`), `theme.semantic.color` the colors by role (`text`, `background`, `border`, `icon`), and `theme.components` the per-component tokens. `normalized-styles.css` sets the root font size to `62.5%`, so `rem` values are on a 10px base (`space400` = `3.2rem` = 32px).
78
+
30
79
  ## Key Patterns
31
80
 
32
81
  - **Composition**: Many components support a `Compose` pattern for advanced customization (e.g., `Select.Compose`, `Section.Compose`). Check the component reference for compose examples.
33
82
  - **Compound Components**: Some components use `Object.assign` to attach sub-components (e.g., `Button.Icon`, `Modal.Content`, `Tabs.TabBar`). These sub-components share internal React context with their parent, so they must be rendered inside it.
34
83
  - **Layouts**: Use `FlexGroup` and `FlexItem` for flex layouts instead of raw `div` with inline styles. `FlexGroup` supports `gap`, `direction`, `align`, `justify`, and `wrap` props. For 2-D layouts (tracks that line up across both axes) use `Grid`. All layout boxes share `padding`/`margin`/sizing props via `BoxProps`. See the Layout references.
35
84
  - **Typography**: Use `Typography.Heading`, `Typography.Body`, and `Typography.Code` for all text rendering instead of raw `<span>`, `<p>`, or `<h1>`–`<h6>` elements. See the [Typography](./references/Typography.md) reference.
36
- - **Theming**: Components use `styled-components` and access theme via `useTheme()` from `@redis-ui/styles`.
85
+ - **Theming**: Components read everything from the `styled-components` theme (see [Setup and themes](#setup-and-themes)). Use `useTheme()` from `@redis-ui/styles` and theme tokens in custom styles instead of hard-coded values.
37
86
  - **ForwardRef**: Most components support `ref` forwarding.
38
87
 
39
88
  ## Important
@@ -124,6 +173,7 @@ Always check the relevant component reference before using a component. The refe
124
173
  - [Filters](./references/Filters.md)
125
174
  - [SearchBar](./references/SearchBar.md)
126
175
  - [TableHeading](./references/TableHeading.md)
176
+ - [TreeView](./references/TreeView.md)
127
177
 
128
178
  ### Misc
129
179
 
@@ -1,6 +1,6 @@
1
1
  # Pagination
2
2
 
3
- Compound pagination primitives for rendering page navigation, page selection, page-size selection, and derived status labels. The repo exercises this API through the table pagination docs; there is no standalone `Pagination` story folder.
3
+ Compound pagination primitives for rendering page navigation, page selection, page-size selection, and derived status labels. There is no ready-made component: compose the parts you need inside `Pagination.Compose`, which holds the state. `Table` from `@redis-ui/table` already includes pagination; use `Pagination` directly for paginated content that isn't a table.
4
4
 
5
5
  ## Import
6
6
 
@@ -73,7 +73,7 @@ import { Pagination } from '@redis-ui/components';
73
73
  ## Sub-components
74
74
 
75
75
  - `Pagination.Compose` - Provides `PaginationContext` and default navigation/validation handlers.
76
- - `Pagination.Bar` - Layout container for the pagination row.
76
+ - `Pagination.Bar` - Layout container for the pagination row. It adds no spacing between groups. Add a `gap` (e.g. a styled `Pagination.Bar` using the theme spacing scale) when placing several groups side by side.
77
77
  - `Pagination.Group` - Flex wrapper for grouping pagination controls.
78
78
  - `Pagination.Split` - Spacer primitive that pushes adjacent groups apart.
79
79
  - `Pagination.InfoLabel` - Renders derived pagination state text.
@@ -85,10 +85,148 @@ import { Pagination } from '@redis-ui/components';
85
85
 
86
86
  ## Examples
87
87
 
88
- ### Table Composition
88
+ The examples share these helpers (story fixtures for a list of 230 items):
89
89
 
90
- > There is no standalone `Pagination` story folder. The only story-backed usage lives in the table pagination docs, where `Table` layers additional grouping wrappers around these pagination primitives.
91
- > The `PageSizeGroup`, `PageNavGroup`, and `PageSelectGroup` wrappers in that example belong to the table docs, not the standalone `Pagination` export.
90
+ ```tsx
91
+ import { useState } from 'react';
92
+ import { Pagination, PaginationState } from '@redis-ui/components';
93
+
94
+ const TOTAL_ITEMS = 230;
95
+
96
+ const itemsLabel = ({ pageIndex, pageSize, totalItemCount = 0 }: PaginationState) => {
97
+ const from = totalItemCount === 0 ? 0 : pageIndex * pageSize + 1;
98
+ const to = Math.min((pageIndex + 1) * pageSize, totalItemCount);
99
+
100
+ return `${from}–${to} of ${totalItemCount} items`;
101
+ };
102
+
103
+ const pageLabel = ({ pageIndex, pageCount }: PaginationState) =>
104
+ `Page ${pageIndex + 1} of ${pageCount}`;
105
+
106
+ const usePaginationState = (initialPageSize = 25) => {
107
+ const [pageIndex, setPageIndex] = useState(0);
108
+ const [pageSize, setPageSize] = useState(initialPageSize);
109
+
110
+ return {
111
+ pageIndex,
112
+ pageSize,
113
+ pageCount: Math.ceil(TOTAL_ITEMS / pageSize),
114
+ totalItemCount: TOTAL_ITEMS,
115
+ onPageChange: setPageIndex,
116
+ onPageSizeChange: (size: number) => {
117
+ setPageSize(size);
118
+ setPageIndex(0);
119
+ }
120
+ };
121
+ };
122
+ ```
123
+
124
+ ### Default
125
+
126
+ > A complete pagination bar: item count, page size, first/previous/next/last buttons and a page selector.
127
+ > This is the same layout `Table` uses for its built-in pagination. `Pagination.Bar` has no spacing between
128
+ > groups, so the bar here adds a `gap` from the theme spacing scale.
129
+
130
+ ```tsx
131
+ import styled from 'styled-components';
132
+
133
+ const SpacedBar = styled(Pagination.Bar)`
134
+ gap: ${({ theme }) => theme.core.space.space200};
135
+ `;
136
+
137
+ const state = usePaginationState();
138
+
139
+ <Pagination.Compose {...state}>
140
+ <SpacedBar>
141
+ <Pagination.InfoLabel renderer={itemsLabel} />
142
+ <Pagination.Split />
143
+ <Pagination.Group>
144
+ <Pagination.PageSizeSelect.Label>Items per page:</Pagination.PageSizeSelect.Label>
145
+ <Pagination.PageSizeSelect />
146
+ </Pagination.Group>
147
+ <Pagination.Group>
148
+ <Pagination.NavigationButton navType="first" />
149
+ <Pagination.NavigationButton navType="prev" />
150
+ <Pagination.InfoLabel renderer={pageLabel} />
151
+ <Pagination.NavigationButton navType="next" />
152
+ <Pagination.NavigationButton navType="last" />
153
+ </Pagination.Group>
154
+ <Pagination.Group>
155
+ <Pagination.PageSelect.Label>Page</Pagination.PageSelect.Label>
156
+ <Pagination.PageSelect />
157
+ </Pagination.Group>
158
+ </SpacedBar>
159
+ </Pagination.Compose>
160
+ ```
161
+
162
+ ### Minimal
163
+
164
+ > Use only the parts you need. Here: previous/next buttons around the current page.
165
+ > `PageSizeSelect` (and its label) render nothing when `onPageSizeChange` isn't provided.
166
+
167
+ ```tsx
168
+ const state = usePaginationState(10);
169
+
170
+ <Pagination.Compose {...state} onPageSizeChange={undefined}>
171
+ <Pagination.Bar>
172
+ <Pagination.Group>
173
+ <Pagination.NavigationButton navType="prev" />
174
+ <Pagination.InfoLabel renderer={pageLabel} />
175
+ <Pagination.NavigationButton navType="next" />
176
+ </Pagination.Group>
177
+ </Pagination.Bar>
178
+ </Pagination.Compose>
179
+ ```
180
+
181
+ ### CustomPageSizes
182
+
183
+ > `pageSizes` sets the page size options (default `[10, 25, 50, 100]`). The current `pageSize` is always included.
184
+
185
+ ```tsx
186
+ const state = usePaginationState(20);
187
+
188
+ <Pagination.Compose {...state}>
189
+ <Pagination.Bar>
190
+ <Pagination.InfoLabel renderer={itemsLabel} />
191
+ <Pagination.Split />
192
+ <Pagination.Group>
193
+ <Pagination.PageSizeSelect.Label>Show</Pagination.PageSizeSelect.Label>
194
+ <Pagination.PageSizeSelect pageSizes={[20, 40, 80]} />
195
+ </Pagination.Group>
196
+ </Pagination.Bar>
197
+ </Pagination.Compose>
198
+ ```
199
+
200
+ ### UnknownTotal
201
+
202
+ > When the total isn't known (e.g. cursor-based APIs), override the validation callbacks.
203
+ > Here, the next button is enabled while the server reports more pages.
204
+
205
+ ```tsx
206
+ const [pageIndex, setPageIndex] = useState(0);
207
+ const hasMore = pageIndex < 4;
208
+
209
+ <Pagination.Compose
210
+ pageIndex={pageIndex}
211
+ pageSize={25}
212
+ pageCount={pageIndex + (hasMore ? 2 : 1)}
213
+ onPageChange={setPageIndex}
214
+ getCanGoNextPage={() => hasMore}
215
+ >
216
+ <Pagination.Bar>
217
+ <Pagination.Group>
218
+ <Pagination.NavigationButton navType="prev" />
219
+ <Pagination.InfoLabel renderer={({ pageIndex: index }) => `Page ${index + 1}`} />
220
+ <Pagination.NavigationButton navType="next" />
221
+ </Pagination.Group>
222
+ </Pagination.Bar>
223
+ </Pagination.Compose>
224
+ ```
225
+
226
+ ### Table composition
227
+
228
+ > From the table pagination docs: `Table.Pagination` wraps these same primitives with table-specific grouping
229
+ > wrappers (`PageSizeGroup`, `PageNavGroup`, `PageSelectGroup`), which are not part of the standalone `Pagination` export.
92
230
 
93
231
  ```tsx
94
232
  import { Table } from '@redis-ui/table';
@@ -145,7 +283,8 @@ const renderTotalPageCount: PaginationInfoLabelProps['renderer'] = ({ pageCount
145
283
 
146
284
  ## Notes
147
285
 
148
- - Pagination is handled internally when the pagination prop is not provided.
149
- - Pagination state can be controlled externally using the pagination prop.
150
- - For manual pagination, `manualPagination` must be `true` and `totalRowCount` must be provided.
151
- - Pagination can be used in empty tables.
286
+ - `Pagination` is controlled: keep `pageIndex` (zero-based) and `pageSize` in state and update them from `onPageChange` / `onPageSizeChange`.
287
+ - The displayed `pageIndex` is clamped to `0..pageCount - 1`, but `onPageChange` isn't called for that, so reset or recalculate `pageIndex` when `pageSize` or the item count changes.
288
+ - `PageSizeSelect` and `PageSizeSelect.Label` render nothing without `onPageSizeChange`.
289
+ - When the total is unknown, override `getCanGoNextPage` (and the other `getCan*` callbacks) instead of deriving them from `pageCount`.
290
+ - For tables, prefer `Table`'s built-in pagination (see the `redis-ui-table` skill's Pagination reference).
@@ -0,0 +1,191 @@
1
+ # TreeView
2
+
3
+ A hierarchical list of checkable items (for example tables and their columns). Checking a parent checks its descendants; a parent with some checked descendants is shown as indeterminate. Disabled items are exempt from this automatic propagation (see Notes). `TreeView` renders a whole tree from `TreeNodes` data; `TreeView.Compose` and `TreeView.Item` let you build the tree by hand.
4
+
5
+ ## Import
6
+
7
+ ```tsx
8
+ import { TreeView, type TreeNodes, type TreeNode } from '@redis-ui/components';
9
+ ```
10
+
11
+ ## Props
12
+
13
+ | Prop | Type | Default | Description |
14
+ |------|------|---------|-------------|
15
+ | data | `TreeNodes` | required | The tree, keyed by item id (see `TreeNode` below) |
16
+ | onChange | `(treeNodes: TreeNodes, changedNode?: TreeNode, newChecked?: CheckedType) => void` | required | Called with the updated tree, the item that changed and its new checked state. `TreeView` is controlled — store the tree from this callback |
17
+ | searchValue | `string` | - | Filters items by label (case-insensitive). A matching item stays visible with its whole subtree; other items stay visible only if a descendant matches. Only changes after mount are applied (see Notes) |
18
+ | defaultCollapsed | `boolean` | `false` | Render every item collapsed initially |
19
+ | other `div` props | `React.HTMLAttributes<HTMLDivElement>` | - | Passed to the tree container (e.g. `style`, `className`) |
20
+
21
+ ### `TreeNode`
22
+
23
+ | Field | Type | Description |
24
+ |------|------|-------------|
25
+ | label | `string` | Item label, also used by `searchValue` |
26
+ | checked | `boolean \| 'indeterminate'` | Checked state. Set it (at least to `false`) on items with `descendants`, so `fixInitialTreeNodes` can derive it from the children |
27
+ | disabled | `boolean` | Disables the item's checkbox |
28
+ | icon | `IconType` | Icon shown before the label |
29
+ | descendants | `TreeNodes` | Child items |
30
+ | id | `string` | Item id; assigned by `TreeView.fixInitialTreeNodes` when missing |
31
+ | hidden | `boolean` | Set by search; you normally don't set it yourself |
32
+
33
+ `TreeNodes` is `{ [key: string]: TreeNode }`.
34
+
35
+ ## Sub-components
36
+
37
+ - `TreeView.Compose` - Tree container for composing items manually. Accepts `div` props.
38
+ - `TreeView.Item` - A complete item: header (expand button and checkbox with `label`, `checked`, `onCheckedChange`, `disabled`, `icon`) and an expander for its `children`. Accepts `defaultCollapsed`.
39
+ - `TreeView.Item.Compose` - Item wrapper that holds the item's expanded and checked state. Accepts `defaultCollapsed`.
40
+ - `TreeView.Item.Header` - The item's row.
41
+ - `TreeView.Item.ExpandButton` - Toggles the item's expander.
42
+ - `TreeView.Item.Checkbox` - The item's checkbox; takes `label`, `icon` and checkbox props.
43
+ - `TreeView.Item.Expander` - Container for the item's sub-items, shown when the item is expanded.
44
+ - `TreeView.fixInitialTreeNodes(treeNodes)` - Returns a copy with an `id` on every item and fixed checked states: a parent with `checked: true` checks all its descendants, and a parent with `checked: false` becomes `true`, `false` or `'indeterminate'` from its children. Use it for the initial state. Give every item with `descendants` an explicit `checked` (`false` when nothing is selected): the helper derives a parent's state from its children only when the parent's `checked` is `false`, and leaves parents with no `checked` unchanged. Limitation: a child whose state is `'indeterminate'` counts as checked, so a `checked: false` parent whose children are all `'indeterminate'` becomes `true`. When a parent should be partly selected, set it to `'indeterminate'` yourself, since the helper leaves `'indeterminate'` parents unchanged.
45
+ - `TreeView.deepCopyTreeNodes(treeNodes)` - Deep copy, for updating state immutably.
46
+ - `TreeView.transferChecked(newTree, oldTree)` - Copies checked states from `oldTree` into `newTree` by key, e.g. when the tree data is reloaded.
47
+
48
+ ## Examples
49
+
50
+ `smallData` and `genMockTreeData` are story fixtures: a small three-level tree, and a generated `tables × columns` tree.
51
+
52
+ ### Basic Usage
53
+
54
+ ```tsx
55
+ import { useState } from 'react';
56
+ import { TreeView } from '@redis-ui/components';
57
+
58
+ const [data, setData] = useState(() => TreeView.fixInitialTreeNodes(smallData));
59
+
60
+ <TreeView data={data} onChange={setData} />;
61
+ ```
62
+
63
+ ### Search
64
+
65
+ > Pass `searchValue` to filter the tree by label (case-insensitive). A matching item stays visible with its whole subtree; any other item stays visible only if one of its descendants matches.
66
+
67
+ ```tsx
68
+ import { useState } from 'react';
69
+ import { SearchInput, TreeView } from '@redis-ui/components';
70
+
71
+ const [data, setData] = useState(() => TreeView.fixInitialTreeNodes(smallData));
72
+ const [search, setSearch] = useState<string>('');
73
+
74
+ <>
75
+ <SearchInput placeholder="Search TreeView..." onChange={setSearch} value={search} />
76
+ <TreeView data={data} onChange={setData} searchValue={search} />
77
+ </>;
78
+ ```
79
+
80
+ ### DefaultCollapsed
81
+
82
+ > Items are expanded by default. Set `defaultCollapsed` to render every item collapsed initially — useful for large trees.
83
+
84
+ ```tsx
85
+ const [data, setData] = useState(() => TreeView.fixInitialTreeNodes(smallData));
86
+
87
+ <TreeView data={data} onChange={setData} defaultCollapsed />;
88
+ ```
89
+
90
+ ### ChangedNode
91
+
92
+ > `onChange` receives the whole updated tree, plus the node that changed and its new checked state — handy when you only need to react to the changed item.
93
+
94
+ ```tsx
95
+ import { useState } from 'react';
96
+ import { CheckedType, TreeNode, TreeNodes, TreeView } from '@redis-ui/components';
97
+
98
+ const [data, setData] = useState(() => TreeView.fixInitialTreeNodes(smallData));
99
+ const [lastChange, setLastChange] = useState('Check or uncheck an item');
100
+
101
+ const handleChange = (newData: TreeNodes, changedNode?: TreeNode, newChecked?: CheckedType) => {
102
+ setData(newData);
103
+
104
+ if (changedNode) {
105
+ setLastChange(`${changedNode.label} → ${String(newChecked)}`);
106
+ }
107
+ };
108
+
109
+ <>
110
+ <TreeView data={data} onChange={handleChange} />
111
+ <span>Last change: {lastChange}</span>
112
+ </>;
113
+ ```
114
+
115
+ ### BigData
116
+
117
+ > TreeView handles large trees (here 50 tables × 10 columns). Constrain its height so it scrolls.
118
+
119
+ The story wraps the tree in a fixed-height container that scrolls (`StoryBigTreeSection`: `min-width: 30rem; overflow-y: auto;` with a fixed height). `TreeView` doesn't scroll by itself, and `maxHeight: '100%'` only works inside a parent with a set height:
120
+
121
+ ```tsx
122
+ const [data, setData] = useState<TreeNodes>(() => genMockTreeData(50, 10));
123
+
124
+ <div style={{ height: '60vh', minWidth: '30rem', overflowY: 'auto' }}>
125
+ <TreeView data={data} onChange={setData} style={{ maxHeight: '100%' }} />
126
+ </div>;
127
+ ```
128
+
129
+ ### ComposingTreeView
130
+
131
+ > TreeView can be composed by adding items manually.
132
+ >
133
+ > You will have to manage state logic by handling `onCheckedChange` event of the `TreeView.Item`.
134
+ >
135
+ > Make sure to use `TreeView.fixInitialTreeNodes(initialData)` to fix any inconsistencies regarding the checked state in the initial data.
136
+
137
+ ```tsx
138
+ import { useState } from 'react';
139
+ import { CheckedType, TreeNode, TreeNodes, TreeView } from '@redis-ui/components';
140
+
141
+ const renderComposedItems = (
142
+ list: TreeNodes | undefined,
143
+ onItemChange: (item: TreeNode, checked: CheckedType) => void
144
+ ) =>
145
+ list
146
+ ? Object.entries(list).map(([key, item]) => (
147
+ <TreeView.Item key={key} {...item} onCheckedChange={(checked) => onItemChange(item, checked)}>
148
+ {renderComposedItems(item.descendants, onItemChange)}
149
+ </TreeView.Item>
150
+ ))
151
+ : null;
152
+
153
+ const [data, setData] = useState(() => TreeView.fixInitialTreeNodes(smallData));
154
+
155
+ const handleItemChange = (item: TreeNode, checked: CheckedType) => {
156
+ item.checked = checked;
157
+ setData(TreeView.deepCopyTreeNodes(data));
158
+ };
159
+
160
+ <TreeView.Compose>{renderComposedItems(data, handleItemChange)}</TreeView.Compose>;
161
+ ```
162
+
163
+ ### ComposingItem
164
+
165
+ > `TreeView.Item` consists of `Header` and `Expander`. `Header` presents current item and can have `ExpandButton` and `Checkbox` with label. `Expander` contains all sub items of the current item.
166
+
167
+ ```tsx
168
+ <TreeView.Compose>
169
+ <TreeView.Item.Compose>
170
+ <TreeView.Item.Header>
171
+ <TreeView.Item.ExpandButton />
172
+ <TreeView.Item.Checkbox label="Label" />
173
+ </TreeView.Item.Header>
174
+ <TreeView.Item.Expander>
175
+ Expander content
176
+ <TreeView.Item.Compose>Add Subitems here</TreeView.Item.Compose>
177
+ </TreeView.Item.Expander>
178
+ </TreeView.Item.Compose>
179
+ </TreeView.Compose>
180
+ ```
181
+
182
+ ## Notes
183
+
184
+ - `TreeView` is controlled: keep the tree in state and update it from `onChange`.
185
+ - Initialize state with `TreeView.fixInitialTreeNodes(data)` to fix most parent and child checked-state inconsistencies. Give every item with `descendants` an explicit `checked` (`false` when nothing is selected): the helper derives a parent's state from its children only when the parent's `checked` is `false`, and leaves parents with no `checked` unchanged.
186
+ - Limitation: a child whose state is `'indeterminate'` counts as checked, so a `checked: false` parent whose children are all `'indeterminate'` becomes `true`. When a parent should be partly selected, set it to `'indeterminate'` yourself, since the helper leaves `'indeterminate'` parents unchanged.
187
+ - When composing manually, handle `onCheckedChange` on each `TreeView.Item` and update state immutably with `TreeView.deepCopyTreeNodes`.
188
+ - `defaultCollapsed` only sets the initial expanded state; users can still expand and collapse items.
189
+ - Limitation: the filter is only applied when `searchValue` changes after the tree has mounted. A `searchValue` that is already set on the first render (for example a query restored from the URL) isn't applied. To start with a query, render with `''` and set it in an effect after mount. Replacing `data` while a query is active also shows the new tree unfiltered until `searchValue` changes again.
190
+ - Disabled items are exempt from this automatic propagation while the tree is in use. Checking or unchecking a parent doesn't change its disabled descendants, and a disabled parent doesn't update when its children change (disabled children still count toward their enabled parent's state). `fixInitialTreeNodes` is the exception: it checks all descendants of a `checked: true` parent, including disabled ones.
191
+ - `TreeView` doesn't scroll on its own: put large trees in a container with a fixed height and `overflow-y: auto`.
@@ -35,7 +35,7 @@ Typography.Base also inherits standard `HTMLAttributes<HTMLElement>` props, exce
35
35
  | component | `'p' \| 'span' \| 'div'` | `'p'` | Element used to render the body text |
36
36
  | size | `'XL' \| 'L' \| 'M' \| 'S' \| 'XS' \| 'auto'` | `'M'` | Body text size |
37
37
  | variant | `'regular' \| 'semiBold' \| 'italic'` | `'regular'` | Font style/weight variant |
38
- | color | `TypographyColor` | - | Theme typography color token |
38
+ | color | `'primary' \| 'secondary' \| 'notice' \| 'success' \| 'attention' \| 'danger' \| 'upsell' \| 'informative'` | - | Semantic text color from the theme (`TypographyColor`; the list is exported as `typographyColors`) |
39
39
 
40
40
  Typography.Body inherits all `Typography.Base` props.
41
41
 
@@ -45,7 +45,7 @@ Typography.Body inherits all `Typography.Base` props.
45
45
  |------|------|---------|-------------|
46
46
  | size | `'S' \| 'M' \| 'L'` | `'L'` | Inline code size |
47
47
  | variant | `'regular' \| 'semiBold'` | `'regular'` | Font weight variant |
48
- | color | `TypographyColor` | - | Theme typography color token |
48
+ | color | `'primary' \| 'secondary' \| 'notice' \| 'success' \| 'attention' \| 'danger' \| 'upsell' \| 'informative'` | - | Semantic text color from the theme (`TypographyColor`; the list is exported as `typographyColors`) |
49
49
 
50
50
  Typography.Code inherits all `Typography.Base` props and always renders as `<code>`.
51
51
 
@@ -54,7 +54,7 @@ Typography.Code inherits all `Typography.Base` props and always renders as `<cod
54
54
  | Prop | Type | Default | Description |
55
55
  |------|------|---------|-------------|
56
56
  | size | `'XXL' \| 'XL' \| 'L' \| 'M' \| 'S' \| 'XS'` | `'XL'` | Heading size and semantic level mapping |
57
- | color | `TypographyColor` | - | Theme typography color token |
57
+ | color | `'primary' \| 'secondary' \| 'notice' \| 'success' \| 'attention' \| 'danger' \| 'upsell' \| 'informative'` | - | Semantic text color from the theme (`TypographyColor`; the list is exported as `typographyColors`) |
58
58
  | variant | `'bold' \| 'semiBold'` | - | Font weight variant |
59
59
  | component | `'p' \| 'span' \| 'div' \| 'h1' \| 'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6'` | `'div'` | Element used to render the heading |
60
60