@recursica/mui-adapter 0.19.1 → 0.21.1

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 (156) hide show
  1. package/CHANGELOG.md +28 -0
  2. package/dist/index.d.ts +2874 -2
  3. package/dist/mui-adapter.cjs +89 -58
  4. package/dist/mui-adapter.cjs.map +1 -1
  5. package/dist/mui-adapter.css +1 -1
  6. package/dist/mui-adapter.js +26163 -8727
  7. package/dist/mui-adapter.js.map +1 -1
  8. package/package.json +8 -2
  9. package/src/components/Box/USAGE.md +1 -1
  10. package/src/components/Button/BUTTON_IMPLEMENTATION_NOTES.md +22 -0
  11. package/src/components/Button/Button.module.css +10 -7
  12. package/src/components/Button/Button.tsx +4 -0
  13. package/src/components/Button/USAGE.md +1 -13
  14. package/src/components/Card/USAGE.md +1 -13
  15. package/src/components/Container/USAGE.md +1 -1
  16. package/src/components/Dropdown/BareDropdown.tsx +135 -0
  17. package/src/components/Dropdown/Dropdown.tsx +16 -0
  18. package/src/components/Grid/USAGE.md +6 -10
  19. package/src/components/Loader/USAGE.md +1 -23
  20. package/src/components/Menu/USAGE.md +0 -7
  21. package/src/components/Pagination/USAGE.md +0 -6
  22. package/src/components/Panel/USAGE.md +1 -58
  23. package/src/components/Stepper/USAGE.md +0 -7
  24. package/src/components/Tabs/USAGE.md +0 -7
  25. package/src/components/TimePicker/TIMEPICKER_IMPLEMENTATION_NOTES.md +68 -0
  26. package/src/components/TimePicker/TimePicker.module.css +213 -37
  27. package/src/components/TimePicker/TimePicker.stories.tsx +119 -4
  28. package/src/components/TimePicker/TimePicker.tsx +257 -8
  29. package/src/components/TimePicker/USAGE.md +27 -2
  30. package/src/components/Tree/IMPLEMENTATION_NOTES.md +28 -1
  31. package/src/components/Tree/Tree.module.css +114 -69
  32. package/src/components/Tree/Tree.stories.tsx +13 -0
  33. package/src/components/Tree/Tree.tsx +99 -32
  34. package/src/components/Tree/USAGE.md +18 -2
  35. package/src/index.ts +1 -0
  36. package/dist/src/OverStyling.d.ts +0 -1
  37. package/dist/src/Version.d.ts +0 -1
  38. package/dist/src/components/Accordion/Accordion.d.ts +0 -77
  39. package/dist/src/components/Accordion/index.d.ts +0 -1
  40. package/dist/src/components/AssistiveElement/AssistiveElement.d.ts +0 -7
  41. package/dist/src/components/AssistiveElement/index.d.ts +0 -1
  42. package/dist/src/components/Autocomplete/Autocomplete.d.ts +0 -24
  43. package/dist/src/components/Autocomplete/index.d.ts +0 -1
  44. package/dist/src/components/Avatar/Avatar.d.ts +0 -25
  45. package/dist/src/components/Avatar/index.d.ts +0 -1
  46. package/dist/src/components/Badge/Badge.d.ts +0 -25
  47. package/dist/src/components/Badge/index.d.ts +0 -1
  48. package/dist/src/components/Box/Box.d.ts +0 -8
  49. package/dist/src/components/Box/index.d.ts +0 -1
  50. package/dist/src/components/Breadcrumb/Breadcrumb.d.ts +0 -20
  51. package/dist/src/components/Breadcrumb/index.d.ts +0 -1
  52. package/dist/src/components/Button/Button.d.ts +0 -37
  53. package/dist/src/components/Button/index.d.ts +0 -1
  54. package/dist/src/components/Card/Card.d.ts +0 -81
  55. package/dist/src/components/Card/index.d.ts +0 -1
  56. package/dist/src/components/Checkbox/Checkbox.d.ts +0 -14
  57. package/dist/src/components/Checkbox/CheckboxGroup.d.ts +0 -29
  58. package/dist/src/components/Checkbox/index.d.ts +0 -5
  59. package/dist/src/components/Chip/Chip.d.ts +0 -21
  60. package/dist/src/components/Chip/index.d.ts +0 -1
  61. package/dist/src/components/Container/Container.d.ts +0 -5
  62. package/dist/src/components/Container/index.d.ts +0 -1
  63. package/dist/src/components/DatePicker/DatePicker.d.ts +0 -20
  64. package/dist/src/components/DatePicker/index.d.ts +0 -1
  65. package/dist/src/components/Dropdown/Dropdown.d.ts +0 -24
  66. package/dist/src/components/Dropdown/index.d.ts +0 -1
  67. package/dist/src/components/FileInput/FileInput.d.ts +0 -3
  68. package/dist/src/components/FileInput/index.d.ts +0 -1
  69. package/dist/src/components/FileUpload/FileUpload.d.ts +0 -3
  70. package/dist/src/components/FileUpload/index.d.ts +0 -1
  71. package/dist/src/components/Flex/Flex.d.ts +0 -5
  72. package/dist/src/components/Flex/index.d.ts +0 -1
  73. package/dist/src/components/FormControlLayout/FormControlLayout.d.ts +0 -6
  74. package/dist/src/components/FormControlLayout/index.d.ts +0 -1
  75. package/dist/src/components/FormControlWrapper/FormControlWrapper.d.ts +0 -11
  76. package/dist/src/components/FormControlWrapper/index.d.ts +0 -1
  77. package/dist/src/components/Grid/Grid.d.ts +0 -12
  78. package/dist/src/components/Grid/index.d.ts +0 -1
  79. package/dist/src/components/Group/Group.d.ts +0 -5
  80. package/dist/src/components/Group/index.d.ts +0 -1
  81. package/dist/src/components/HoverCard/HoverCard.d.ts +0 -29
  82. package/dist/src/components/HoverCard/index.d.ts +0 -1
  83. package/dist/src/components/Label/Label.d.ts +0 -7
  84. package/dist/src/components/Label/index.d.ts +0 -1
  85. package/dist/src/components/Link/Link.d.ts +0 -20
  86. package/dist/src/components/Link/index.d.ts +0 -1
  87. package/dist/src/components/Loader/Loader.d.ts +0 -5
  88. package/dist/src/components/Loader/index.d.ts +0 -1
  89. package/dist/src/components/Menu/Menu.d.ts +0 -54
  90. package/dist/src/components/Menu/index.d.ts +0 -1
  91. package/dist/src/components/Modal/Modal.d.ts +0 -78
  92. package/dist/src/components/Modal/index.d.ts +0 -1
  93. package/dist/src/components/NumberInput/NumberInput.d.ts +0 -24
  94. package/dist/src/components/NumberInput/index.d.ts +0 -1
  95. package/dist/src/components/Pagination/Pagination.d.ts +0 -23
  96. package/dist/src/components/Pagination/Pagination.icons.d.ts +0 -8
  97. package/dist/src/components/Pagination/index.d.ts +0 -1
  98. package/dist/src/components/Panel/Panel.d.ts +0 -52
  99. package/dist/src/components/Panel/index.d.ts +0 -1
  100. package/dist/src/components/Radio/Radio.d.ts +0 -13
  101. package/dist/src/components/Radio/RadioGroup.d.ts +0 -9
  102. package/dist/src/components/Radio/index.d.ts +0 -2
  103. package/dist/src/components/ReadOnlyField/ReadOnlyBooleanField.d.ts +0 -5
  104. package/dist/src/components/ReadOnlyField/ReadOnlyField.d.ts +0 -5
  105. package/dist/src/components/ReadOnlyField/ReadOnlySwitchField.d.ts +0 -5
  106. package/dist/src/components/ReadOnlyField/ReadOnlyTextField.d.ts +0 -8
  107. package/dist/src/components/ReadOnlyField/WithReadOnlyWrapper.d.ts +0 -28
  108. package/dist/src/components/ReadOnlyField/index.d.ts +0 -2
  109. package/dist/src/components/SegmentedControl/SegmentedControl.d.ts +0 -32
  110. package/dist/src/components/SegmentedControl/index.d.ts +0 -1
  111. package/dist/src/components/Slider/Slider.d.ts +0 -30
  112. package/dist/src/components/Slider/index.d.ts +0 -1
  113. package/dist/src/components/Stack/Stack.d.ts +0 -5
  114. package/dist/src/components/Stack/index.d.ts +0 -1
  115. package/dist/src/components/Stepper/Stepper.d.ts +0 -97
  116. package/dist/src/components/Stepper/index.d.ts +0 -1
  117. package/dist/src/components/Switch/Switch.d.ts +0 -10
  118. package/dist/src/components/Switch/SwitchGroup.d.ts +0 -24
  119. package/dist/src/components/Switch/index.d.ts +0 -2
  120. package/dist/src/components/Table/Table.d.ts +0 -154
  121. package/dist/src/components/Table/index.d.ts +0 -1
  122. package/dist/src/components/Tabs/Tabs.d.ts +0 -57
  123. package/dist/src/components/Tabs/index.d.ts +0 -1
  124. package/dist/src/components/Text/Text.d.ts +0 -20
  125. package/dist/src/components/Text/index.d.ts +0 -1
  126. package/dist/src/components/TextArea/TextArea.d.ts +0 -24
  127. package/dist/src/components/TextArea/index.d.ts +0 -1
  128. package/dist/src/components/TextField/TextField.d.ts +0 -24
  129. package/dist/src/components/TextField/index.d.ts +0 -1
  130. package/dist/src/components/TimePicker/TimePicker.d.ts +0 -4
  131. package/dist/src/components/TimePicker/index.d.ts +0 -1
  132. package/dist/src/components/Timeline/Timeline.d.ts +0 -16
  133. package/dist/src/components/Timeline/TimelineItem.d.ts +0 -29
  134. package/dist/src/components/Timeline/index.d.ts +0 -2
  135. package/dist/src/components/Title/Title.d.ts +0 -21
  136. package/dist/src/components/Title/index.d.ts +0 -1
  137. package/dist/src/components/Toast/Toast.d.ts +0 -32
  138. package/dist/src/components/Toast/index.d.ts +0 -1
  139. package/dist/src/components/Tooltip/Tooltip.d.ts +0 -28
  140. package/dist/src/components/Tooltip/index.d.ts +0 -1
  141. package/dist/src/components/TransferList/TransferList.d.ts +0 -4
  142. package/dist/src/components/TransferList/index.d.ts +0 -1
  143. package/dist/src/components/Tree/Tree.d.ts +0 -13
  144. package/dist/src/components/Tree/index.d.ts +0 -1
  145. package/dist/src/components/Typography/Typography.d.ts +0 -38
  146. package/dist/src/components/Typography/index.d.ts +0 -1
  147. package/dist/src/components/index.d.ts +0 -50
  148. package/dist/src/index.d.ts +0 -91
  149. package/dist/src/types/index.d.ts +0 -6
  150. package/dist/src/utils/ColorSchemeWrapper.d.ts +0 -3
  151. package/dist/src/utils/RequireAccessibleLabel.d.ts +0 -1
  152. package/dist/src/utils/copyToClipboard.d.ts +0 -8
  153. package/dist/src/utils/filterStylingProps.d.ts +0 -29
  154. package/dist/src/utils/index.d.ts +0 -1
  155. package/dist/vite.config.d.ts +0 -2
  156. package/dist/vitest.workspace.d.ts +0 -2
@@ -10,6 +10,8 @@ This document describes how to integrate and use the `TimePicker` component in y
10
10
  import { TimePicker } from "@recursica/mui-adapter";
11
11
  ```
12
12
 
13
+ `TimePicker` requires `@mui/x-date-pickers` (optional peer dependency) to be installed alongside `@mui/material`. See [SETUP.md](../../../SETUP.md).
14
+
13
15
  ---
14
16
 
15
17
  ## 2. Basic Example
@@ -19,10 +21,26 @@ import React from "react";
19
21
  import { TimePicker } from "@recursica/mui-adapter";
20
22
 
21
23
  export default function Demo() {
22
- return <TimePicker label="Select Time" placeholder="Pick a time" />;
24
+ return <TimePicker label="Select Time" />;
23
25
  }
24
26
  ```
25
27
 
28
+ `TimePicker`'s value is a plain `"HH:mm"` string (matching `@recursica/mantine-adapter`'s convention) — always 24-hour. Pass `withSeconds` to add a seconds segment (`"HH:mm:ss"`), and `minTime`/`maxTime` (in the same string format) to bound the allowed range.
29
+
30
+ ```tsx
31
+ <TimePicker
32
+ label="Precise Time"
33
+ withSeconds
34
+ minTime="09:00:00"
35
+ maxTime="17:00:00"
36
+ onChange={(value) => console.log(value)} // "HH:mm:ss" | null
37
+ />
38
+ ```
39
+
40
+ > [!IMPORTANT] > **Recursica-specific behavior:** `TimePicker` always renders a 12-hour field with a dedicated AM/PM `Dropdown`-style selector next to it — a deviation from `@mui/x-date-pickers`'s own default (24-hour, or a single field with an inline meridiem section) and **not configurable**. There is no prop to switch to a plain 24-hour field; this is the only way the component operates.
41
+
42
+ The AM/PM control visually matches Recursica's `Dropdown` component exactly, rather than a plain native `<select>`.
43
+
26
44
  ---
27
45
 
28
46
  ## 3. Design System Integration
@@ -31,6 +49,13 @@ All Recursica components in the `@recursica/mui-adapter` package adhere strictly
31
49
 
32
50
  > [!IMPORTANT]
33
51
  >
34
- > - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
52
+ > - **Anti-override protection**: Rogue style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
35
53
  > - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
36
54
  > - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.
55
+ > - **Known limitation**: the closed field is fully token-driven; the open clock/list dropdown currently renders with MUI's default styling (no Figma token spec exists for it yet).
56
+
57
+ ---
58
+
59
+ ## 4. Read-Only Mode
60
+
61
+ Pass `readOnly` to render the current value as static text, matching every other Recursica form control. The value is formatted as 12-hour + AM/PM (e.g. `"14:30"` displays as `"2:30 PM"`).
@@ -18,4 +18,31 @@
18
18
 
19
19
  - **Deliberately not implemented (no tokens back them):** checkbox/indeterminate node state (`@mui/x-tree-view` supports `checkboxSelection`, but the Figma UI Kit's `tree` tokens only define `selected`/`unselected`, not a checked state) and per-node `disabled` (no token, and no `disabled` field in `RecursicaTreeNode`). Matches the mantine-adapter implementation's same decision.
20
20
 
21
- - **KNOWN GAP (2026-08-06): Forge's own preview shows a red chevron with more chevron-to-label spacing than what's currently implemented here.** Same finding as the mantine-adapter implementation (see its `IMPLEMENTATION_NOTES.md`) — re-verified against both the compiled `recursica_variables_scoped.css` and the raw `recursica_ui-kit.json` (synced the same day): the `tree` schema has no `icon-color` property at all, and `button-node-gap` (used as `.row`'s `gap`) resolves to exactly 4px. Not a mapping bug on our side. Needs a Forge/design follow-up (a bound icon-color variable and a confirmed intended gap value) before this can be fixed with a real token.
21
+ - **RESOLVED (2026-08-08) — KNOWN GAP (2026-08-06): Forge's own preview shows a red chevron with more chevron-to-label spacing than what's currently implemented here.** Explained by the Button swap below: Forge's chevron is Button's own "text" variant color (Recursica's red/alert-adjacent brand color), not a `tree`-namespace icon-color token — there never was a missing token to find. Re-verified against both the compiled `recursica_variables_scoped.css` and the raw `recursica_ui-kit.json` at the time: the `tree` schema has no `icon-color` property at all, and `button-node-gap` (used as `.row`'s `gap`) resolves to exactly 4px — confirmed not a mapping bug on our side, just the wrong mental model (a hand-drawn glyph instead of an actual Button).
22
+
23
+ - **Keyboard nav (Matt Massey, 2026-08-08): arrow up/down already worked — only the focus ring was missing.** `@mui/x-tree-view`'s own `useTreeItem` already implements full WAI-ARIA roving-tabindex keyboard navigation — confirmed via Playwright that focus genuinely moves between rows on `ArrowDown`. The reason it looked broken: DOM focus lands on `.node` (the same `<li role="treeitem">` `TreeItemRoot` renders as), and `.row`'s only focus-related rule reset MUI's own focused-state _background color_ back to the unselected default — no replacement focus indicator was ever added. Fixed by adding the same `:focus-visible` box-shadow ring every other focusable component uses, keyed off `.node:focus-visible` since that's where DOM focus actually lands. Originally drawn on `.row` (the whole button+label box); see the next entry for why it now targets `.label` only.
24
+
25
+ - **Chevron → `Button` (Matt Massey, 2026-08-08).** Forge's real design uses an actual `Button` (`variant="text"` `size="small"`, icon-only) for the expand/collapse chevron, not a hand-drawn glyph — see the resolved "KNOWN GAP" above. `ExpandGlyph`/`CollapseGlyph`/`EndGlyph` (the three `slots.expandIcon`/`collapseIcon`/`endIcon` components MUI's `TreeItemIcon` picks between based on row state) now all delegate to a shared `ExpandToggleButton`, which renders a real `<Button icon={<ChevronGlyph/>} tabIndex={-1} aria-hidden="true" .../>`:
26
+
27
+ - **Doesn't reopen any nested-focusable-element concern**: the embedded Button is never independently focusable or tab-stoppable (`tabIndex={-1}`) and is hidden from assistive tech (`aria-hidden`) — the row (`.node`) stays the single focusable/interactive element. Confirmed MUI's `ButtonBase` doesn't call `stopPropagation()` on click, so clicking the chevron still bubbles up to `TreeItemContent`'s existing click handling and triggers expand/collapse exactly as before — no `onClick` needed on the embedded Button itself.
28
+ - **Rendered for every row, including leaves** (`EndGlyph` → `ExpandToggleButton hidden`), so every row reserves identical layout space; a `.expandButtonHidden { visibility: hidden; }` class hides it on leaf rows without needing to duplicate Button's own size tokens for a placeholder. `.iconContainer`'s old hardcoded `width: 1em` (sized for the previous plain-SVG glyph) was removed so the real Button can size itself from its own tokens.
29
+ - **Rotation targets the glyph directly, not Button's internals**: `ChevronGlyph`'s `<svg>` carries its own `styles.chevron`/`styles.chevronExpanded` classes directly, not reached through Button's DOM at all — `Button`'s own `.iconWrapper` isn't reachable from `Tree.module.css` in the first place (CSS Modules don't expose a stable cross-file class name for it, unlike MUI's own stable `Mui*` global classes used elsewhere in this file).
30
+ - **Focus ring narrowed to `.label` only, excluding the Button** (Matt: "the focus ring for an item should be around just the node, not including the chevron button" / "the chevron button should not have a focus state"). `.label` was given `flex: 1 1 auto; height: 100%` so the ring still reads as a clean box covering the row's remaining width, not a tight text-only outline.
31
+ - **Found and fixed a real, separate bug while embedding this**: `Button.tsx` (both adapters) explicitly sets `className={finalClass}` (merging `styles.root` with any caller className) but then spreads `{...sanitizedProps}` _after_ it — and `sanitizedProps` still contains the original, unmodified `className` key, since it was only _read_, never deleted. The later spread silently overwrote `finalClass` with just the caller's own class whenever one was passed (e.g. `styles.expandButton` here) — exact same bug class as this adapter's own `Dropdown.tsx`/`BareDropdown.tsx` had. This was fully visible here: the chevron rendered in MUI's own default blue (`MuiButton-colorPrimary`), since `Button-module__root` — and therefore every `[data-variant]` color rule — was missing from the DOM entirely. Confirmed mantine-adapter had the identical bug in its own `Button.tsx`, just masked there by a separate `classNames={{root: ...}}` object prop unaffected by the overwrite — fixed in both regardless.
32
+
33
+ - **Expand/collapse and select made fully independent (Matt Massey, 2026-08-10), superseding the "approximated, not exact" `expandOnClick`/`selectOnClick` mapping described above.** Matt clarified the real requirement: the button must be the _only_ way to expand/collapse on click, a row click must _only_ select, `Enter`/`Space` must _only_ select (never expand, even on a node with children), and `ArrowLeft`/`ArrowRight` must _only_ expand/collapse (never select) — letting a user toggle a subtree open without ever changing selection, and vice versa. Removed `expandOnClick`/`selectOnClick` entirely (per point 5 of that request), since the old approximation problem disappears once the pattern is fixed rather than configurable.
34
+
35
+ - **Click**: `expansionTrigger` is now unconditionally `"iconContainer"` (previously `expandOnClick ? "content" : "iconContainer"`). That alone wasn't enough: `@mui/x-tree-view`'s `createContentHandleClick` (wired onto `TreeItemContent`/`.row`) calls `interactions.handleSelection` on _any_ click that reaches it — including a click on the icon container, since it's a DOM descendant of the content and the icon container's own click handler never stops propagation. `CustomTreeItem` now wraps `getIconContainerProps()`'s `onClick` with `event.stopPropagation()` before delegating to it, so an icon-container click still expands/collapses (via the library's own `createIconContainerHandleClick`) but never bubbles up to also select.
36
+ - **Enter**: `@mui/x-tree-view`'s own keyboard plugin expands an expandable node on `Enter` and only falls back to selecting when the node has no children — not what we need (`Enter` must always select). `Space` already selects unconditionally by default, so it needed no change. Overrode just `Enter` via `getRootProps({..., onKeyDown: handleRootKeyDown})`: `useTreeItem`'s `createRootHandleKeyDown` runs any externally-supplied `onKeyDown` _before_ its own internal handling and skips that internal handling entirely if the external handler sets `event.defaultMuiPrevented = true` — the library's documented extension point for exactly this kind of override, not an undocumented hack. `handleRootKeyDown` calls `interactions.handleSelection` (from `useTreeItemUtils`, the same hook `useTreeItem` uses internally) directly. `ArrowLeft`/`ArrowRight` needed no changes — the built-in handling already only calls `store.expansion.setItemExpansion`, never touches selection.
37
+ - **Background/focus scoped to the label, not the whole node** (Matt: "The focus/background color should be on the node's label, not the entire node"): moved every visual property (padding, border, font, unselected/selected colors, hover overlay) off `.row` and onto `.label` — `.row` is now a plain flex layout container (indentation + `button-node-gap` only). `data-selected`/`data-focused` are still only set on `.row` (via `getContentProps()`), so the selected-state rule now reads `.row[data-selected] .label` (a descendant selector) instead of styling `.row` directly; same for the hover overlay (`.row:hover .label::after`). The focus ring (added in the entry above) already targeted `.label` only, so it needed no further change.
38
+
39
+ - **Three follow-on fixes to the label-scoping work above (Matt Massey, 2026-08-10):**
40
+
41
+ - **Selected/hover chip was full-row width, not label width, in both adapters.** `.label` had `flex: 1 1 auto` — the `1` flex-grow stretched it to fill `.row`'s entire remaining width (icon container aside), so the highlighted chip visually covered the whole row even though the _properties_ were correctly scoped to `.label`. Changed to `flex: 0 1 auto`, but that alone wasn't enough here (unlike mantine-adapter): `@mui/x-tree-view`'s own `.MuiTreeItem-label` sets a literal `width: 100%`, which a flex-basis change can't beat since it's a direct `width` declaration, not a sizing default. Added an explicit `width: auto` to `.label` to override it.
42
+ - **Focusing an expanded parent drew the ring on every descendant label too, in both adapters.** `.node:focus-visible .label` is a plain descendant selector — every child node's `.label` (inside the nested `.subtree` `<ul>`) is _also_ a descendant of the focused parent's `.node` `<li>`, at any depth, so the ring matched all of them at once. Fixed by scoping to `.node:focus-visible > .row .label`: `.row` is always a direct child of its own `.node`, but never of an ancestor `.node` (those reach it through the intervening `.subtree` `<ul>` and nested `<li>` instead) — the `>` combinator excludes every one of them.
43
+ - **MUI-only: a leftover default selected background was still showing through.** `@mui/x-tree-view`'s own `TreeItemContent` ships a built-in selected tint (`rgba(25, 118, 210, 0.08)`, and a separate, higher-specificity `rgba(25, 118, 210, 0.2)` for the `[data-selected][data-focused]` combination specifically) that the earlier `.row:hover, .row[data-focused] { background-color: transparent; }` neutralizer never covered. Added `.row[data-selected]` to that neutralizer — but the `[data-selected][data-focused]` compound needed its _own_ explicit rule too: MUI's equivalent compound selector has higher specificity (two attribute selectors plus its own class) than a single-attribute `.row[data-selected]` rule, so it kept winning regardless of source order until matched with an equally-specific `.row[data-selected][data-focused]` rule on our side.
44
+
45
+ - **Whole-tree `disabled` (Matt Massey, 2026-08-10), added to support a `Disabled` story.** Unlike mantine-adapter (which has zero `disabled` concept anywhere in its `Tree` API — see its own note on this), `@mui/x-tree-view` already had per-item `disabled` plumbing sitting mostly dormant here: `CustomTreeItem` already destructured `disabled` off `UseTreeItemParameters`, and `.row[data-disabled] { opacity: ...; cursor: auto; }` already existed in `Tree.module.css` — just with no way for a caller to actually set it, since `RecursicaTreeNode` has no `disabled` field (and still doesn't; per-node disabling remains unexposed, same reasoning as the existing "Deliberately not implemented" entry above).
46
+ - **Implementation**: `isItemDisabled={disabled ? () => true : undefined}` passed to `<RichTreeView>` — marking every item disabled at once, reusing the library's own per-item mechanism rather than inventing a parallel one. `interactions.handleExpansion`/`handleSelection` (used by both the icon container's click handling and our own `Enter`-key override) already check `status.disabled` internally and no-op, so nothing in `CustomTreeItem` needed an extra guard.
47
+ - **Visual**: the pre-existing `.row[data-disabled]` rule now actually activates. Verified a pre-selected node's chip stays visible underneath the dimming (`.row[data-selected] .label` and `.row[data-disabled]` are independent, non-conflicting selectors — one styles `.label`, the other dims the whole `.row` via `opacity`), per Matt's ask to check that combination.
48
+ - **Found while verifying**: disabled rows still showed the hover tint (`.label::after` opacity) on mouse-over — MUI's own disabled checks block the actual select/expand _action_ on click, but `:hover` is pure CSS with nothing stopping it. Added `pointer-events: none` to `.row[data-disabled]`, matching mantine-adapter's `.root[data-disabled]` (tree-wide there; per-row here, since MUI's disabled state is inherently per-item even when every item is disabled at once by the same whole-tree prop).
@@ -1,13 +1,17 @@
1
1
  /* HARDCODED VALUES:
2
2
  * - list-style/margin/padding resets on .root/.subtree/.node: layout resets, no corresponding
3
3
  * design tokens (structural, not visual design values).
4
- * - .chevron size (1em) and rotation: no dedicated icon-size/icon-color token exists for Tree;
5
- * the glyph is drawn with `currentColor` so it always tracks the row's already-tokened text
6
- * color, and sized relative to the row's own font-size.
4
+ * - .chevron rotation timing (150ms ease): no dedicated timing token exists for Tree; the glyph
5
+ * itself is sized/colored entirely by Button's own "text"/"small" tokens now, not a hand-drawn
6
+ * size/color like the previous plain-SVG implementation.
7
7
  * - Hover overlay uses the generic --recursica_brand_states_hover_* tokens (same technique as
8
8
  * Menu/Accordion/Button): Tree has no component-specific hover tokens of its own.
9
- * - .row's padding-left keeps MUI's own depth-based indentation formula (base + indent * depth)
10
- * but substitutes our own horizontal-padding token as the base instead of MUI's theme spacing.
9
+ * - .row's padding-left keeps MUI's own depth-based indentation formula (indent * depth), just
10
+ * without the horizontal-padding base — that base now lives on .label instead (see below).
11
+ *
12
+ * NOTE: the row's box model (padding/border/font/color/background) lives entirely on `.label`,
13
+ * not `.row` — the highlighted "chip" (hover/selected/focus) covers only the label, never the
14
+ * expand button. `.row` itself is a plain flex layout container (indentation + button-node-gap).
11
15
  */
12
16
 
13
17
  .root {
@@ -42,6 +46,28 @@
42
46
  list-style: none;
43
47
  }
44
48
 
49
+ /* @mui/x-tree-view's roving-tabindex keyboard navigation (arrow up/down moves focus between
50
+ rows, left/right expand/collapse, matching the WAI-ARIA treeitem pattern) already works out of
51
+ the box — but with no visible indicator, it looked broken. DOM focus lands on this <li> (.node),
52
+ not the visible row box, so the ring is drawn on .label instead — the "node" content area,
53
+ deliberately excluding the expand Button, which never shows a focus state of its own (it's not
54
+ independently focusable at all: tabIndex={-1}). */
55
+ .node:focus-visible {
56
+ outline: none;
57
+ }
58
+ /* `> .row` (child combinator), not a plain descendant selector: a node's own `.row` is always a
59
+ direct child of its `.node` <li>, while every descendant node's `.row` (inside the nested
60
+ `.subtree` <ul>) is not — without the `>`, focusing a parent node drew the ring on every
61
+ expanded descendant's label too, since they're all still descendants of the focused `.node`. */
62
+ .node:focus-visible > .row .label {
63
+ box-shadow:
64
+ 0 0 0 var(--recursica_brand_states_focus_border-size)
65
+ var(--recursica_brand_states_focus_color),
66
+ 0 0 var(--recursica_brand_states_focus_blur)
67
+ var(--recursica_brand_states_focus_margin)
68
+ var(--recursica_brand_states_focus_color);
69
+ }
70
+
45
71
  .row {
46
72
  position: relative;
47
73
  box-sizing: border-box;
@@ -50,22 +76,77 @@
50
76
  width: 100%;
51
77
  cursor: pointer;
52
78
  gap: var(--recursica_ui-kit_components_tree_properties_button-node-gap);
53
-
54
- padding-top: var(
55
- --recursica_ui-kit_components_tree_properties_vertical-padding
56
- );
57
- padding-bottom: var(
58
- --recursica_ui-kit_components_tree_properties_vertical-padding
59
- );
60
- padding-right: var(
61
- --recursica_ui-kit_components_tree_properties_horizontal-padding
62
- );
63
79
  padding-left: calc(
64
- var(--recursica_ui-kit_components_tree_properties_horizontal-padding) +
65
- var(--TreeView-itemChildrenIndentation, 0px) *
66
- var(--TreeView-itemDepth, 0)
80
+ var(--TreeView-itemChildrenIndentation, 0px) * var(--TreeView-itemDepth, 0)
67
81
  );
82
+ }
68
83
 
84
+ /* Neutralize MUI's own hover/focused/selected background-color changes (see TreeItemContent's
85
+ defaults in @mui/x-tree-view, e.g. its built-in `rgba(25, 118, 210, 0.08)` selected tint) so
86
+ only the Recursica hover overlay and selected styling on .label below control the look; .row
87
+ itself carries no background-color of its own to fall back to now. The `[data-selected]
88
+ [data-focused]` compound needs its own rule: MUI's own equivalent compound selector has higher
89
+ specificity (2 attributes + its class) than a single-attribute `.row[data-selected]` rule
90
+ would, so it would otherwise still win regardless of source order. */
91
+ .row:hover,
92
+ .row[data-focused],
93
+ .row[data-selected],
94
+ .row[data-selected][data-focused] {
95
+ background-color: transparent;
96
+ }
97
+
98
+ .row[data-disabled] {
99
+ opacity: var(--recursica_brand_states_disabled);
100
+ cursor: auto;
101
+ /* MUI's own disabled checks already block select/expand on click, but hover is pure CSS —
102
+ without this, a disabled row still showed the hover tint (.label::after opacity) on mouse-
103
+ over, misleadingly suggesting it's interactive. Matches mantine-adapter's `.root[data-
104
+ disabled] { pointer-events: none; }`, just scoped per-row instead of tree-wide, since MUI's
105
+ disabled state is a per-item concept even when driven by our own whole-tree prop. */
106
+ pointer-events: none;
107
+ }
108
+
109
+ .iconContainer {
110
+ position: relative;
111
+ z-index: 1;
112
+ display: flex;
113
+ align-items: center;
114
+ justify-content: center;
115
+ flex-shrink: 0;
116
+ color: inherit;
117
+ }
118
+
119
+ /* The expand Button is always rendered (even for leaf nodes, which have nothing to toggle) so
120
+ every row reserves identical layout space — hidden via visibility (not display) on leaf rows so
121
+ the label stays aligned across the whole tree without duplicating Button's own size tokens. */
122
+ .expandButton {
123
+ flex-shrink: 0;
124
+ }
125
+ .expandButtonHidden {
126
+ visibility: hidden;
127
+ }
128
+
129
+ .chevron {
130
+ transition: transform 150ms ease;
131
+ }
132
+ .chevronExpanded {
133
+ transform: rotate(90deg);
134
+ }
135
+
136
+ .label {
137
+ position: relative;
138
+ z-index: 1;
139
+ /* Sized to its own content, not stretched to fill the row's remaining width — the
140
+ hover/selected/focus "chip" should cover just the label, not the full row width.
141
+ `width: auto` is required in addition to `flex: 0 1 auto`: MuiTreeItem's own default
142
+ `.MuiTreeItem-label` sets a literal `width: 100%`, which a flex-basis alone can't beat. */
143
+ flex: 0 1 auto;
144
+ width: auto;
145
+ box-sizing: border-box;
146
+ display: flex;
147
+ align-items: center;
148
+ padding: var(--recursica_ui-kit_components_tree_properties_vertical-padding)
149
+ var(--recursica_ui-kit_components_tree_properties_horizontal-padding);
69
150
  border-style: solid; /* HARDCODE: structural border rule; thickness/color are tokened */
70
151
  border-width: var(--recursica_ui-kit_components_tree_properties_border-size);
71
152
  border-radius: var(
@@ -108,36 +189,33 @@
108
189
  );
109
190
  }
110
191
 
111
- /* Neutralize MUI's own hover/focused background-color changes (see TreeItemContent's defaults
112
- in @mui/x-tree-view) so only the Recursica hover overlay below controls the hover look. */
113
- .row:hover,
114
- .row[data-focused] {
115
- background-color: var(
116
- --recursica_ui-kit_components_tree_variants_selection-states_unselected_properties_colors_background-color
117
- );
118
- }
119
-
120
- /* Hover overlay via ::after pseudo-element (same technique as Menu/Accordion) */
121
- .row::after {
192
+ /* Hover overlay via ::after pseudo-element (same technique as Menu/Accordion), scoped to the
193
+ label's own box so hover never visually covers the expand button. `.label`'s `position:
194
+ relative` + `z-index: 1` above already forms a stacking context, so `z-index: -1` here paints
195
+ the overlay behind the label's real text content within that context, not behind `.label`
196
+ itself. */
197
+ .label::after {
122
198
  content: "";
123
199
  position: absolute;
124
200
  inset: 0;
125
201
  border-radius: inherit;
126
- z-index: 0;
202
+ z-index: -1;
127
203
  pointer-events: none;
128
204
  background-color: var(--recursica_brand_states_hover_color);
129
205
  opacity: 0;
130
206
  transition: opacity 150ms ease;
131
207
  }
132
- .row:hover::after {
208
+ .row:hover .label::after {
133
209
  opacity: var(--recursica_brand_states_hover_opacity);
134
210
  }
135
211
 
136
- /* Selected row state — written after the hover/focus resets above so it wins the equal-
137
- specificity tie via source order, including when hovered/focused while selected. */
138
- .row[data-selected],
139
- .row[data-selected]:hover,
140
- .row[data-selected][data-focused] {
212
+ /* Selected state — read off `.row`'s own `data-selected`/`data-focused` (set by
213
+ `getContentProps()`), applied to `.label`. Written after the hover/focus reset above so it
214
+ wins the equal-specificity tie via source order, including when hovered/focused while
215
+ selected. */
216
+ .row[data-selected] .label,
217
+ .row[data-selected]:hover .label,
218
+ .row[data-selected][data-focused] .label {
141
219
  font-family: var(
142
220
  --recursica_ui-kit_components_tree_variants_selection-states_selected_properties_text_font-family
143
221
  );
@@ -173,36 +251,3 @@
173
251
  --recursica_ui-kit_components_tree_variants_selection-states_selected_properties_colors_border-color
174
252
  );
175
253
  }
176
-
177
- .row[data-disabled] {
178
- opacity: var(--recursica_brand_states_disabled);
179
- cursor: auto;
180
- }
181
-
182
- .iconContainer {
183
- position: relative;
184
- z-index: 1;
185
- width: 1em;
186
- display: flex;
187
- align-items: center;
188
- justify-content: center;
189
- flex-shrink: 0;
190
- color: inherit;
191
- }
192
-
193
- .chevron {
194
- transition: transform 150ms ease;
195
- }
196
- .chevronExpanded {
197
- transform: rotate(90deg);
198
- }
199
-
200
- .label {
201
- position: relative;
202
- z-index: 1;
203
- color: inherit;
204
- font: inherit;
205
- letter-spacing: inherit;
206
- text-decoration: inherit;
207
- text-transform: inherit;
208
- }
@@ -80,6 +80,19 @@ export const MultipleSelection: StoryObj<typeof Tree> = {
80
80
  ),
81
81
  };
82
82
 
83
+ /** Whole tree disabled, with a node pre-selected so the selected chip's styling under the
84
+ * disabled dimming can be checked alongside unselected rows. */
85
+ export const Disabled: StoryObj<typeof Tree> = {
86
+ render: () => (
87
+ <Tree
88
+ data={sampleData}
89
+ initialExpandedValues={["documents"]}
90
+ initialSelectedValues={["documents/resume.pdf"]}
91
+ disabled
92
+ />
93
+ ),
94
+ };
95
+
83
96
  /** Demonstrates the component nested inside a non-default layer — the one case where an
84
97
  * explicit `<Layer>` wrap belongs in a story (see COMPONENT_STORYBOOK_GUIDE.md §9). */
85
98
  export const LayerOne: StoryObj<typeof Tree> = {
@@ -4,7 +4,7 @@ import {
4
4
  useTreeItem,
5
5
  type UseTreeItemParameters,
6
6
  } from "@mui/x-tree-view/useTreeItem";
7
- import { useTreeItemModel } from "@mui/x-tree-view/hooks";
7
+ import { useTreeItemModel, useTreeItemUtils } from "@mui/x-tree-view/hooks";
8
8
  import { TreeItemProvider } from "@mui/x-tree-view/TreeItemProvider";
9
9
  import {
10
10
  TreeItemRoot,
@@ -22,6 +22,7 @@ import {
22
22
  type RecursicaTreeProps,
23
23
  type RecursicaTreeNode,
24
24
  } from "@recursica/adapter-common";
25
+ import { Button } from "../Button/Button";
25
26
  import styles from "./Tree.module.css";
26
27
 
27
28
  export type TreeProps = RecursicaOverStyled<
@@ -40,13 +41,16 @@ function collectAllValues(nodes: RecursicaTreeNode[]): string[] {
40
41
  return values;
41
42
  }
42
43
 
43
- /** Simple chevron glyph; MUI renders a different component for expanded vs collapsed rather
44
- * than one rotating icon (unlike Mantine's `[data-expanded]` approach), so collapseIcon carries
45
- * its own rotated variant. Both use `currentColor` — no dedicated icon-color token exists. */
46
- function ExpandGlyph() {
44
+ /** Chevron glyph; rendered inside a `Button` below. MUI renders a different component for
45
+ * expanded vs collapsed rather than one rotating icon (unlike Mantine's `[data-expanded]`
46
+ * approach), so `rotated` picks the CSS class that applies the rotation. Uses `currentColor` so
47
+ * it matches Button's own tokened icon color for the "text" variant. */
48
+ function ChevronGlyph({ rotated }: { rotated?: boolean }) {
47
49
  return (
48
50
  <svg
49
- className={styles.chevron}
51
+ className={
52
+ rotated ? `${styles.chevron} ${styles.chevronExpanded}` : styles.chevron
53
+ }
50
54
  viewBox="0 0 16 16"
51
55
  width="1em"
52
56
  height="1em"
@@ -61,29 +65,47 @@ function ExpandGlyph() {
61
65
  </svg>
62
66
  );
63
67
  }
64
- function CollapseGlyph() {
68
+
69
+ /** Never independently focusable/tab-stoppable (tabIndex={-1}, aria-hidden) — expand/collapse is
70
+ * driven by the surrounding `TreeItemIconContainer`'s own click handling (see `CustomTreeItem`),
71
+ * not by this Button itself, so the row stays the only focusable element and the button never
72
+ * shows its own focus state. Rendered for every row, including leaf items, so row alignment
73
+ * stays consistent; `hidden` (visibility, not display) is used for leaf rows instead of omitting
74
+ * the button, so the layout space is reserved without duplicating Button's own size tokens. */
75
+ function ExpandToggleButton({
76
+ rotated,
77
+ hidden,
78
+ }: {
79
+ rotated?: boolean;
80
+ hidden?: boolean;
81
+ }) {
65
82
  return (
66
- <svg
67
- className={`${styles.chevron} ${styles.chevronExpanded}`}
68
- viewBox="0 0 16 16"
69
- width="1em"
70
- height="1em"
71
- fill="none"
72
- stroke="currentColor"
73
- strokeWidth="2"
74
- strokeLinecap="round"
75
- strokeLinejoin="round"
83
+ <Button
84
+ overStyled
85
+ variant="text"
86
+ size="small"
87
+ icon={<ChevronGlyph rotated={rotated} />}
88
+ aria-label="Toggle subtree"
76
89
  aria-hidden="true"
77
- >
78
- <path d="M5 3l5 5-5 5" />
79
- </svg>
90
+ tabIndex={-1}
91
+ className={
92
+ hidden
93
+ ? `${styles.expandButton} ${styles.expandButtonHidden}`
94
+ : styles.expandButton
95
+ }
96
+ />
80
97
  );
81
98
  }
99
+ function ExpandGlyph() {
100
+ return <ExpandToggleButton />;
101
+ }
102
+ function CollapseGlyph() {
103
+ return <ExpandToggleButton rotated />;
104
+ }
82
105
  /** Rendered for leaf items so the icon-container box (and therefore row alignment) stays
83
- * consistent whether or not a row has an expand chevron, matching the mantine-adapter
84
- * implementation's always-present `.expandIcon` span. */
106
+ * consistent whether or not a row has an expand chevron. */
85
107
  function EndGlyph() {
86
- return <span aria-hidden="true" />;
108
+ return <ExpandToggleButton hidden />;
87
109
  }
88
110
 
89
111
  interface CustomTreeItemProps extends UseTreeItemParameters {
@@ -111,14 +133,43 @@ const CustomTreeItem = forwardRef<HTMLLIElement, CustomTreeItemProps>(
111
133
  status,
112
134
  } = useTreeItem({ id, itemId, children, label, disabled, rootRef: ref });
113
135
 
136
+ // Exposes the same select/expand actions `useTreeItem`'s internal keyboard-navigation plugin
137
+ // uses, so we can override just the `Enter` key below without reimplementing selection.
138
+ const { interactions } = useTreeItemUtils({ itemId, children });
139
+
114
140
  const item = useTreeItemModel<RecursicaTreeNode>(itemId);
115
141
 
142
+ const iconContainerProps = getIconContainerProps({
143
+ className: styles.iconContainer,
144
+ });
145
+
146
+ // `Enter` selects the focused node, full stop — never expands it, unlike
147
+ // `@mui/x-tree-view`'s own default (which expands an expandable node on `Enter` and only
148
+ // falls back to selecting leaf nodes). Setting `defaultMuiPrevented` is the documented
149
+ // extension point `createRootHandleKeyDown` checks before running its own handling, so this
150
+ // fully replaces rather than races the built-in behavior. `Space` already selects-only by
151
+ // default, so it needs no override.
152
+ const handleRootKeyDown = (
153
+ event: React.KeyboardEvent<HTMLLIElement> & {
154
+ defaultMuiPrevented?: boolean;
155
+ },
156
+ ) => {
157
+ if (event.key !== "Enter") return;
158
+ event.preventDefault();
159
+ event.defaultMuiPrevented = true;
160
+ // `handleSelection` only reads modifier keys (shiftKey/ctrlKey/metaKey) off the event and
161
+ // forwards it on for focus bookkeeping — its `React.MouseEvent` type is narrower than
162
+ // necessary for what it actually uses, so a KeyboardEvent works fine at runtime here.
163
+ interactions.handleSelection(event as unknown as React.MouseEvent);
164
+ };
165
+
116
166
  return (
117
167
  <TreeItemProvider {...getContextProviderProps()}>
118
168
  <TreeItemRoot
119
169
  {...getRootProps({
120
170
  ...rest,
121
171
  className: `${styles.node} ${className ?? ""}`,
172
+ onKeyDown: handleRootKeyDown,
122
173
  })}
123
174
  >
124
175
  <TreeItemContent
@@ -126,7 +177,15 @@ const CustomTreeItem = forwardRef<HTMLLIElement, CustomTreeItemProps>(
126
177
  status={status}
127
178
  >
128
179
  <TreeItemIconContainer
129
- {...getIconContainerProps({ className: styles.iconContainer })}
180
+ {...iconContainerProps}
181
+ // Stops the click from also reaching `TreeItemContent`'s own click handler, which
182
+ // otherwise selects on *any* click inside it (including the icon container) once
183
+ // `expansionTrigger` is `"iconContainer"` — the button must expand/collapse
184
+ // without ever selecting.
185
+ onClick={(event) => {
186
+ event.stopPropagation();
187
+ iconContainerProps.onClick(event);
188
+ }}
130
189
  >
131
190
  <TreeItemIcon status={status} />
132
191
  </TreeItemIconContainer>
@@ -152,6 +211,11 @@ const CustomTreeItem = forwardRef<HTMLLIElement, CustomTreeItemProps>(
152
211
  * Wraps `@mui/x-tree-view`'s `RichTreeView` with a fully custom item renderer so every visual
153
212
  * aspect (row box model, selected/unselected colors and typography, indent, item spacing)
154
213
  * comes from Recursica's `tree` design tokens rather than MUI's defaults.
214
+ *
215
+ * **Interaction pattern (fixed, not prop-configurable):** expand/collapse and select are
216
+ * independent — the chevron button toggles a node's subtree only, clicking the rest of a row
217
+ * (or pressing `Enter`/`Space`) selects it only, and `ArrowLeft`/`ArrowRight` toggle expansion
218
+ * only. See `RecursicaTreeProps` for the full breakdown.
155
219
  */
156
220
  export const Tree = forwardRef<HTMLUListElement, TreeProps>(function Tree(
157
221
  {
@@ -160,8 +224,7 @@ export const Tree = forwardRef<HTMLUListElement, TreeProps>(function Tree(
160
224
  initialExpandedValues,
161
225
  initialSelectedValues,
162
226
  multiple = false,
163
- expandOnClick = true,
164
- selectOnClick = true,
227
+ disabled = false,
165
228
  onNodeExpand,
166
229
  onNodeCollapse,
167
230
  onSelectedChange,
@@ -195,12 +258,16 @@ export const Tree = forwardRef<HTMLUListElement, TreeProps>(function Tree(
195
258
  multiple ? (initialSelectedValues ?? []) : initialSelectedValues?.[0]
196
259
  }
197
260
  multiSelect={multiple}
198
- // MUI has no separate expandOnClick/selectOnClick toggles; `expansionTrigger` controls
199
- // whether clicking the row content (vs only the icon container) also expands/collapses.
200
- // `selectOnClick={false}` has no exact MUI equivalent (selection always follows content
201
- // clicks unless disabled entirely) — see IMPLEMENTATION_NOTES.md.
202
- expansionTrigger={expandOnClick ? "content" : "iconContainer"}
203
- disableSelection={!selectOnClick}
261
+ // Whole-tree `disabled` reuses `@mui/x-tree-view`'s own per-item `isItemDisabled` — marking
262
+ // every item disabled at once — rather than a bespoke mechanism, since MUI already handles
263
+ // blocking click/keyboard select/expand and dimming (`.row[data-disabled]` in
264
+ // Tree.module.css) for disabled items internally.
265
+ isItemDisabled={disabled ? () => true : undefined}
266
+ // Fixed, not prop-driven: only the icon container (the chevron button) expands/collapses
267
+ // on click; clicking anywhere else on the row selects instead. `CustomTreeItem` additionally
268
+ // stops the icon container's click from also bubbling into the content's own selection
269
+ // handler — see IMPLEMENTATION_NOTES.md.
270
+ expansionTrigger="iconContainer"
204
271
  onItemExpansionToggle={(_event, itemId, isExpanded) => {
205
272
  if (isExpanded) onNodeExpand?.(itemId);
206
273
  else onNodeCollapse?.(itemId);
@@ -60,7 +60,24 @@ Each node needs a unique `value` and a `label`. Any node with a `children` array
60
60
 
61
61
  - `initialExpandedValues` accepts an array of node values, or `"*"` to start with every node expanded.
62
62
  - `multiple` allows more than one node to be selected at once (default: single-select).
63
- - `expandOnClick` (default `true`) controls whether clicking a row's content also expands/collapses it (vs. only clicking its chevron); `selectOnClick` (default `true`) controls whether selection is enabled at all. See **Known Constraints** below for how these map onto the underlying library.
63
+
64
+ ### Interaction pattern
65
+
66
+ Expanding/collapsing and selecting are independent, fixed interactions (not prop-configurable):
67
+
68
+ - Clicking the expand/collapse chevron toggles that node's subtree only — it never selects.
69
+ - Clicking anywhere else on a row selects it — it never toggles expansion.
70
+ - `Enter`/`Space` on a focused node selects it, even if the node has children.
71
+ - `ArrowLeft`/`ArrowRight` expand/collapse the focused node only, without changing selection.
72
+ - `ArrowUp`/`ArrowDown` move focus between rows.
73
+
74
+ ### Disabled
75
+
76
+ ```tsx
77
+ <Tree data={data} initialSelectedValues={["1.1"]} disabled />
78
+ ```
79
+
80
+ `disabled` disables the whole tree — no expand/collapse or select via click or keyboard, dimmed to the standard disabled opacity. A pre-selected node stays visibly selected, just dimmed along with the rest. There's no per-node disabled state (see **Known Constraints** below).
64
81
 
65
82
  ---
66
83
 
@@ -78,6 +95,5 @@ All Recursica components in the `@recursica/mui-adapter` package adhere strictly
78
95
 
79
96
  ## 5. Known Constraints
80
97
 
81
- - **`expandOnClick`/`selectOnClick` are approximated, not exact.** `@mui/x-tree-view` doesn't expose the same two independent toggles Mantine's `Tree` does. `expandOnClick` maps to MUI's `expansionTrigger` (`"content"` vs `"iconContainer"`); `selectOnClick={false}` maps to `disableSelection` (which disables selection entirely, rather than only suppressing it on a content click while leaving some other path to select). See `IMPLEMENTATION_NOTES.md`.
82
98
  - No checkbox/multi-check styling is exposed — `@mui/x-tree-view` supports checkbox selection, but Recursica's `tree` design tokens don't yet define a checked visual state, so it isn't part of the Recursica API.
83
99
  - No per-node `disabled` state — the Figma UI Kit tokens don't define one, and `RecursicaTreeNode` has no `disabled` field either.
package/src/index.ts CHANGED
@@ -183,5 +183,6 @@ export type {
183
183
  RecursicaSliderProps,
184
184
  RecursicaTextAreaProps,
185
185
  RecursicaTextFieldProps,
186
+ RecursicaTimePickerProps,
186
187
  RecursicaToastProps,
187
188
  } from "./components";
@@ -1 +0,0 @@
1
- export declare const OverStylingInfo: () => import("react/jsx-runtime").JSX.Element;
@@ -1 +0,0 @@
1
- export declare const VersionInfo: () => import("react/jsx-runtime").JSX.Element;