@recursica/mantine-adapter 0.36.0 → 0.38.0

package/src/components/Tree/IMPLEMENTATION_NOTES.md

@@ -4,14 +4,42 @@
 
 - **`elementProps` already carries the important behavioral wiring.** Mantine's `renderNode` payload includes an `elementProps` object with `onClick` (combined expand+select handler, respecting `expandOnClick`/`selectOnClick`), `data-selected`, `data-value`, and `data-hovered` (set on keyboard/mouse hover via Mantine's internal `hoveredNode` state). We spread these directly onto our own `.row` div rather than reimplementing click/keyboard behavior — only the `className` is overridden with our own token-driven class.
 
-- **The chevron is a decorative element inside the same clickable row, not a separate `<button>`.** The design tokens include a `button-node-gap` token (implying a "button" next to the node label in Figma), but structurally the whole row is already the click target via `elementProps.onClick` (which correctly bundles Mantine's `expandOnClick`/`selectOnClick` logic). Making the chevron its own nested interactive `<button>` inside an `<li>` that Mantine already treats as keyboard-focusable (`tabIndex`, arrow-key handling in `TreeNode.tsx`) would create nested-focusable-element accessibility problems for no real benefit. `button-node-gap` is used as the CSS `gap` between the (decorative) chevron and the label inside `.row` instead.
+- **UPDATED (Matt Massey, 2026-08-08): the chevron is now a real `Button`, superseding the two notes below.** Forge's real design shows the chevron following Button's own styling rules (`variant="text"` `size="small"`) — see the new entry near the end of this file for the full swap and why it doesn't reopen the nested-focusable-element concern the original decision (kept below for history) was worried about.
+- ~~The chevron is a decorative element inside the same clickable row, not a separate `<button>`.~~ The design tokens include a `button-node-gap` token (implying a "button" next to the node label in Figma), but structurally the whole row is already the click target via `elementProps.onClick` (which correctly bundles Mantine's `expandOnClick`/`selectOnClick` logic). Making the chevron its own nested interactive `<button>` inside an `<li>` that Mantine already treats as keyboard-focusable (`tabIndex`, arrow-key handling in `TreeNode.tsx`) would create nested-focusable-element accessibility problems for no real benefit. `button-node-gap` is used as the CSS `gap` between the (decorative) chevron and the label inside `.row` instead.
 
-- **No dedicated icon-color/icon-size token exists for Tree.** The expand chevron is an inline SVG using `stroke="currentColor"`, sized at `1em` (relative to the row's own tokened `font-size`). This means it automatically tracks whichever text-color token (selected/unselected) is active on `.row` — no new token was invented, and no hardcoded color was used.
+- ~~No dedicated icon-color/icon-size token exists for Tree.~~ The expand chevron is an inline SVG using `stroke="currentColor"`, sized at `1em` (relative to the row's own tokened `font-size`). This means it automatically tracks whichever text-color token (selected/unselected) is active on `.row` — no new token was invented, and no hardcoded color was used.
 
-- **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.** Re-verified against both the compiled `recursica_variables_scoped.css` and the raw `recursica_ui-kit.json` (synced the same day) — the `tree` schema genuinely has no `icon-color` property anywhere (only `background-color`/`border-color`/`text-color` per selection state, and neither references any red/`core-colors.alert` palette), and `button-node-gap` resolves to `brand.dimensions.general.sm` = 4px, which is exactly what `.row`'s `gap` uses. This was confirmed _not_ to be a mapping bug on our side. Most likely explanation: the chevron in the Figma source isn't bound to a variable at all (Forge previews commonly flag unbound properties in a warning color), and/or its real icon asset has different intrinsic spacing than our hand-drawn placeholder glyph. 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 rather than a hardcoded guess.
+- **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 genuinely has no `icon-color` property anywhere, and `button-node-gap` resolves to `brand.dimensions.general.sm` = 4px, exactly what `.row`'s `gap` uses — confirmed not a mapping bug on our side, just the wrong mental model (a hand-drawn glyph instead of an actual Button).
 
 - **`--level-offset` override needs `!important`.** Mantine's `Tree` computes each node's indent via a `--level-offset` CSS variable, resolved internally through its `createVarsResolver` mechanism and applied as a scoped rule on the root `<ul>` (same category of override as `Timeline`'s `--mantine-spacing-xl` / `--tl-line-width`). We override it on `.root` with `!important` to reliably beat Mantine's own generated rule regardless of stylesheet insertion order, rather than passing a `levelOffset` prop from TSX (which would mean setting a design-token value from TSX, against `COMPONENT_DEV_GUIDE.md`'s "no custom properties set from TSX for styling" rule).
 
 - **`onSelectedChange` is a Recursica addition, not a Mantine API.** Mantine's `useTree()` controller tracks `selectedState` but has no change callback of its own. We watch `tree.selectedState` with a `useEffect` and fire `onSelectedChange` when it changes. This is a behavioral callback, not a design-token reactivity concern, so it doesn't conflict with `COMPONENT_DEV_GUIDE.md §7`'s rule against using `useEffect` for token/styling reactivity.
 
 - **Deliberately not implemented (no tokens back them):** checkbox/indeterminate node state (Mantine's `Tree` supports `checkNode`/`isNodeIndeterminate`, 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 Mantine's `TreeNodeData` either). If either is needed later, it needs a token/schema addition first, not a component-level workaround.
+
+- **Keyboard nav (Matt Massey, 2026-08-08): arrow up/down already worked — only the focus ring was missing.** Mantine's own `TreeNode` already implements full roving-tabindex keyboard navigation (`ArrowUp`/`ArrowDown` move focus between rows, `ArrowLeft`/`ArrowRight` collapse/expand, `Space` toggles) — confirmed via reading `TreeNode.mjs` directly and verifying with Playwright that focus genuinely moves between rows on `ArrowDown`. The reason it looked broken: DOM focus lands on `.node` (the `<li role="treeitem">`), and neither `.node` nor `.row` had any focus style at all (`outline: none`, no box-shadow) — so keyboard navigation was invisible, and only `Space`/`ArrowLeft`/`ArrowRight` were noticeable at all, since those also cause a visible expand/collapse side effect. Fixed by adding a `:focus-visible` box-shadow ring (same tokens as every other focusable component), 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.
+
+- **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. Swapped `ExpandGlyph`'s plain `<span>` wrapper for a real `<Button icon={<ExpandGlyph/>} tabIndex={-1} aria-hidden="true" .../>`:
+
+  - **Doesn't reopen the nested-focusable-element concern** the original (now-struck-through) decision above was worried about: 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 `Button`/`UnstyledButton` don't call `stopPropagation()` on click, so clicking the chevron still bubbles up to the row's existing `elementProps.onClick` and triggers expand/collapse exactly as before — no `onClick` needed on the embedded Button itself.
+  - **Rendered for every row, including leaves**, so every row reserves identical layout space; `.row:not([data-has-children]) .expandButton { visibility: hidden; }` hides it on leaf rows without needing to duplicate Button's own size tokens for a placeholder.
+  - **Rotation targets the glyph directly, not Button's internals**: `ExpandGlyph`'s `<svg>` carries its own `styles.expandGlyph` class, targeted via `.row[data-expanded] .expandGlyph` — a plain descendant-combinator selector that reaches the glyph regardless of how deeply `Button` nests it internally (`Button`'s own `.iconWrapper` isn't reachable from `Tree.module.css` at all — CSS Modules don't expose a stable cross-file class name for it, unlike Mantine's own `mantine-*` global classes).
+  - **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.
+  - **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 `Dropdown.tsx`/`BareDropdown.tsx` had. In mui-adapter this was fully visible (the chevron rendered in MUI's own default blue, since `Button-module__root` — and therefore every `[data-variant]` color rule — was missing entirely). In mantine-adapter it happened to be masked: Mantine's `classNames={{root: ...}}` object prop is separate from the plain `className` string and unaffected by the bug, so `Button-module__root` still applied via that path — but the underlying bug was there too, and is now fixed in both.
+
+- **Expand/collapse and select made fully independent (Matt Massey, 2026-08-10), superseding the click-bubbling behavior described above.** Previously the chevron was purely decorative and let clicks bubble up to the row's combined expand+select handler; 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 the now ill-fitting `expandOnClick`/`selectOnClick` props entirely (per point 5 of that request) — the pattern is fixed, not configurable.
+
+  - **Click**: `<MantineTree>` is now called with fixed `expandOnClick={false}` `selectOnClick={true}` (so `elementProps.onClick`, spread onto `.row`, only ever selects), and the embedded chevron `Button` now has its own `onClick` that calls `event.stopPropagation()` (so the click never also reaches `.row`'s select handler) and `tree.toggleExpanded(node.value)` directly via the controller — using `tree`/`node`, both already present in `renderNode`'s payload.
+  - **Enter/Space**: Mantine's `TreeNode` has no `Enter` handling and only wires `Space` to `toggleExpanded` (`expandOnSpace`, now passed as `false`) — no select-on-key behavior exists in the library at all, and the key handler lives on the `<li role="treeitem">` itself, unreachable through `renderNode`'s `elementProps`. Added a native `keydown` listener on the tree's root `<ul>` (merged via `useMergedRef` with the forwarded `ref`) that calls `tree.select(value)` on `Enter`/`Space`, reading the focused node's value off `event.target`'s own `data-value` (already set there by Mantine). `ArrowLeft`/`ArrowRight` needed no changes — Mantine's own handling already only calls `controller.expand`/`collapse`, never `select`.
+  - **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` is read directly off `renderNode`'s own `selected` payload field and applied to `.label` itself (no need to also spread `elementProps`'s copy there); `data-hovered`/`:hover` are still only observable on `.row` (from `elementProps`), so those states reach `.label` via `.row:hover .label`/`.row[data-hovered] .label` descendant selectors instead. The focus ring (added in the entry above) already targeted `.label` only, so it needed no further change.
+
+- **Three follow-on fixes to the label-scoping work above (Matt Massey, 2026-08-10):**
+
+  - **Selected/hover chip was full-row width, not label width.** `.label` had `flex: 1 1 auto` — the `1` flex-grow stretched it to fill `.row`'s entire remaining width (button 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` (no grow, same shrink/basis) so the chip sizes to its own content, matching Forge.
+  - **Focusing an expanded parent drew the ring on every descendant label too.** `.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.
+  - No MUI-style leftover "default selected background" issue existed here — Mantine's own `Tree` has no default row styling of its own once a custom `renderNode` is supplied (see the very first entry in this file), so there was nothing to neutralize on this side.
+
+- **Whole-tree `disabled` (Matt Massey, 2026-08-10), added to support a `Disabled` story.** Mantine's `Tree`/`useTree`/`TreeNode` have no `disabled` concept anywhere in their API, unlike `@mui/x-tree-view` (which already had per-item `disabled` plumbing sitting mostly unused — see mui-adapter's own note on this). Per-node disabling still isn't exposed (no token, no `disabled` field on `RecursicaTreeNode` — same reasoning as the existing "Deliberately not implemented" entry above), only a single whole-tree toggle.
+  - **Mouse**: `selectOnClick={!disabled}` reuses Mantine's own flag for row clicks. The chevron `Button`'s `onClick` bypasses that flag entirely (calls `tree.toggleExpanded` directly), so it needs its own explicit `if (disabled) return;` guard. `.root[data-disabled] { pointer-events: none; }` is a second, CSS-only backstop covering both at once — belt-and-suspenders, not strictly required given the two guards above, but consistent with how little the library gives us to rely on here.
+  - **Keyboard**: our own `Enter`/`Space` → `select` listener (added in the entry above) just checks `disabled` at the top now. `ArrowLeft`/`ArrowRight` expand/collapse is baked into Mantine's own `TreeNode.handleKeyDown`, on the `<li>` itself, with no prop to disable it — the only reachable way to block it is a _second_, capture-phase `keydown` listener on the tree root that unconditionally calls `stopPropagation()` when disabled. Since capture fires before the event ever reaches its target (the focused `<li>`), this keeps Mantine's internal handler — and our own bubble-phase listener on the same root — from ever running, without needing to fork `TreeNode`.
+  - **Visual**: `opacity: var(--recursica_brand_states_disabled)` on `.root` — the generic disabled token, same convention used everywhere else in the design system for components without a dedicated disabled token (no `tree`-specific one exists). A selected node's chip stays visible underneath, just dimmed along with everything else, per Matt's ask to verify that combination looks right.

package/src/components/Tree/Tree.module.css

@@ -1,11 +1,15 @@
 /* HARDCODED VALUES:
  * - list-style/margin/padding resets on .root/.subtree: layout resets, no corresponding
  *   design tokens (structural, not visual design values).
- * - .expandIcon size (1em) and rotation transition: no dedicated icon-size/icon-color token
- *   exists for Tree; the glyph is drawn with `currentColor` so it always tracks the row's
- *   already-tokened text color, and sized relative to the row's own font-size.
+ * - .expandGlyph's rotation transition (150ms ease): no dedicated timing token exists for Tree;
+ *   the glyph itself is sized/colored entirely by Button's own "text"/"small" tokens now, not a
+ *   hand-drawn size/color like the previous plain-SVG implementation.
  * - Hover overlay uses the generic --recursica_brand_states_hover_* tokens (same technique as
  *   Menu/Accordion/Button): Tree has no component-specific hover tokens of its own.
+ *
+ * NOTE: the row's box model (padding/border/font/color/background) lives entirely on `.label`,
+ * not `.row` — the highlighted "chip" (hover/selected/focus) covers only the label, never the
+ * expand button. `.row` itself is a plain flex layout container (indentation + button-node-gap).
  */
 
 .root {
@@ -25,6 +29,16 @@
   ) !important;
 }
 
+/* Whole-tree `disabled` (no per-node concept — see RecursicaTreeProps.ts). `pointer-events: none`
+   blocks every mouse interaction tree-wide in one rule (row clicks, chevron clicks); keyboard is
+   separately blocked in Tree.tsx, since pointer-events has no effect on Tab/Enter/Space/arrows.
+   Uses the generic disabled opacity token, same convention as every other disabled component in
+   the design system (no tree-specific disabled token exists). */
+.root[data-disabled] {
+  opacity: var(--recursica_brand_states_disabled);
+  pointer-events: none;
+}
+
 .subtree {
   margin: 0;
   padding: 0;
@@ -36,11 +50,33 @@
 
 .node {
   /* Mantine's own base class already resets margin/padding/list-style and sets cursor:pointer
-     on this <li>; it also holds the subtree as a second child, so all row-level visual styling
-     (box model, colors, typography) lives on .row instead, not here. */
+     on this <li>; it also holds the subtree as a second child, so all node-level visual styling
+     (box model, colors, typography) lives on .label instead, not here. */
   position: relative;
 }
 
+/* Mantine's roving-tabindex keyboard navigation (arrow up/down moves focus between rows, left/
+   right expand/collapse, matching the WAI-ARIA treeitem pattern) already works out of the box —
+   but with no visible indicator, it looked broken. DOM focus lands on this <li> (.node), not the
+   visible row box, so the ring is drawn on .label instead — the "node" content area, deliberately
+   excluding the expand Button, which never shows a focus state of its own (it's not independently
+   focusable at all: tabIndex={-1}). */
+.node:focus-visible {
+  outline: none;
+}
+/* `> .row` (child combinator), not a plain descendant selector: a node's own `.row` is always a
+   direct child of its `.node` <li>, while every descendant node's `.row` (inside the nested
+   `.subtree` <ul>) is not — without the `>`, focusing a parent node drew the ring on every
+   expanded descendant's label too, since they're all still descendants of the focused `.node`. */
+.node:focus-visible > .row .label {
+  box-shadow:
+    0 0 0 var(--recursica_brand_states_focus_border-size)
+      var(--recursica_brand_states_focus_color),
+    0 0 var(--recursica_brand_states_focus_blur)
+      var(--recursica_brand_states_focus_margin)
+      var(--recursica_brand_states_focus_color);
+}
+
 .row {
   position: relative;
   box-sizing: border-box;
@@ -49,6 +85,39 @@
   cursor: pointer;
   margin-left: var(--label-offset, 0px);
   gap: var(--recursica_ui-kit_components_tree_properties_button-node-gap);
+}
+
+/* The expand Button is always rendered (even for leaf nodes, which have nothing to toggle) so
+   every row reserves identical layout space — hidden via visibility (not display) on leaf rows so
+   the label stays aligned across the whole tree without duplicating Button's own size tokens. */
+.expandButton {
+  position: relative;
+  z-index: 1;
+  flex-shrink: 0;
+}
+.row:not([data-has-children]) .expandButton {
+  visibility: hidden;
+}
+
+.expandGlyph {
+  color: inherit;
+}
+.row[data-has-children] .expandGlyph {
+  transition: transform 150ms ease;
+}
+.row[data-expanded] .expandGlyph {
+  transform: rotate(90deg);
+}
+
+.label {
+  position: relative;
+  z-index: 1;
+  /* Sized to its own content, not stretched to fill the row's remaining width — the
+     hover/selected/focus "chip" should cover just the label, not the full row width. */
+  flex: 0 1 auto;
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
   padding: var(--recursica_ui-kit_components_tree_properties_vertical-padding)
     var(--recursica_ui-kit_components_tree_properties_horizontal-padding);
   border-style: solid; /* HARDCODE: structural border rule; thickness/color are tokened */
@@ -93,24 +162,28 @@
   );
 }
 
-/* Hover overlay via ::after pseudo-element (same technique as Menu/Accordion) */
-.row::after {
+/* Hover overlay via ::after pseudo-element (same technique as Menu/Accordion), scoped to the
+   label's own box so hover never visually covers the expand button. `.label`'s `position:
+   relative` + `z-index: 1` above already forms a stacking context, so `z-index: -1` here paints
+   the overlay behind the label's real text content within that context, not behind `.label`
+   itself. */
+.label::after {
   content: "";
   position: absolute;
   inset: 0;
   border-radius: inherit;
-  z-index: 0;
+  z-index: -1;
   pointer-events: none;
   background-color: var(--recursica_brand_states_hover_color);
   opacity: 0;
   transition: opacity 150ms ease;
 }
-.row:hover::after,
-.row[data-hovered]::after {
+.row:hover .label::after,
+.row[data-hovered] .label::after {
   opacity: var(--recursica_brand_states_hover_opacity);
 }
 
-.row[data-selected] {
+.label[data-selected] {
   font-family: var(
     --recursica_ui-kit_components_tree_variants_selection-states_selected_properties_text_font-family
   );
@@ -146,32 +219,3 @@
     --recursica_ui-kit_components_tree_variants_selection-states_selected_properties_colors_border-color
   );
 }
-
-.expandIcon {
-  position: relative;
-  z-index: 1;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  flex-shrink: 0;
-  width: 1em;
-  height: 1em;
-  color: inherit;
-}
-
-.row[data-has-children] .expandIcon {
-  transition: transform 150ms ease;
-}
-.row[data-expanded] .expandIcon {
-  transform: rotate(90deg);
-}
-
-.label {
-  position: relative;
-  z-index: 1;
-  color: inherit;
-  font: inherit;
-  letter-spacing: inherit;
-  text-decoration: inherit;
-  text-transform: inherit;
-}

package/src/components/Tree/Tree.stories.tsx

@@ -80,6 +80,19 @@ export const MultipleSelection: StoryObj<typeof Tree> = {
   ),
 };
 
+/** Whole tree disabled, with a node pre-selected so the selected chip's styling under the
+ * disabled dimming can be checked alongside unselected rows. */
+export const Disabled: StoryObj<typeof Tree> = {
+  render: () => (
+    <Tree
+      data={sampleData}
+      initialExpandedValues={["documents"]}
+      initialSelectedValues={["documents/resume.pdf"]}
+      disabled
+    />
+  ),
+};
+
 /** Demonstrates the component nested inside a non-default layer — the one case where an
  * explicit `<Layer>` wrap belongs in a story (see COMPONENT_STORYBOOK_GUIDE.md §9). */
 export const LayerOne: StoryObj<typeof Tree> = {

package/src/components/Tree/Tree.tsx

@@ -5,22 +5,27 @@ import {
   getTreeExpandedState,
   type RenderTreeNodePayload,
 } from "@mantine/core";
+import { useMergedRef } from "@mantine/hooks";
 import {
   filterStylingProps,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import { type RecursicaTreeProps } from "@recursica/adapter-common";
+import { Button } from "../Button/Button";
 import styles from "./Tree.module.css";
 
 export type TreeProps = RecursicaOverStyled<
   RecursicaTreeProps & Omit<React.ComponentPropsWithoutRef<"ul">, "children">
 >;
 
-/** Simple chevron glyph; rotates via `[data-expanded]` in CSS. Uses `currentColor` so it
- * always matches the row's tokened text color — Tree has no dedicated icon-color token. */
+/** Simple chevron glyph; rotates via the row's `[data-expanded]` in CSS (`.row[data-expanded]
+ * .expandGlyph`) — this reaches the glyph regardless of how deeply `Button` nests it internally,
+ * since it's a plain descendant-combinator selector, not dependent on Button's own DOM structure.
+ * Uses `currentColor` so it always matches Button's own tokened icon color for the "text" variant. */
 function ExpandGlyph() {
   return (
     <svg
+      className={styles.expandGlyph}
       viewBox="0 0 16 16"
       width="1em"
       height="1em"
@@ -36,25 +41,56 @@ function ExpandGlyph() {
   );
 }
 
-function renderTreeNode({
-  node,
-  hasChildren,
-  expanded,
-  elementProps,
-}: RenderTreeNodePayload) {
-  return (
-    <div
-      {...elementProps}
-      className={styles.row}
-      data-has-children={hasChildren || undefined}
-      data-expanded={hasChildren && expanded ? true : undefined}
-    >
-      <span className={styles.expandIcon} aria-hidden="true">
-        {hasChildren && <ExpandGlyph />}
-      </span>
-      <span className={styles.label}>{node.label}</span>
-    </div>
-  );
+/** Curried so the fixed-shape `renderNode` callback (Mantine controls its signature) can still
+ * close over `disabled`, which isn't part of `RenderTreeNodePayload`. */
+function createRenderTreeNode(disabled: boolean) {
+  return function renderTreeNode({
+    node,
+    hasChildren,
+    expanded,
+    selected,
+    tree,
+    elementProps,
+  }: RenderTreeNodePayload) {
+    return (
+      <div
+        {...elementProps}
+        className={styles.row}
+        data-has-children={hasChildren || undefined}
+        data-expanded={hasChildren && expanded ? true : undefined}
+      >
+        {/* The only element that toggles expand/collapse on click — independent of selection,
+            which `elementProps.onClick` (spread onto `.row` above) handles for the rest of the
+            row. Stops propagation so the click never also reaches `.row`'s own handler and
+            selects the node. Never independently focusable/tab-stoppable (tabIndex={-1},
+            aria-hidden), so the row stays the only focusable element and this button never
+            shows its own focus state. Always rendered, even for leaf nodes, so every row
+            reserves the same layout space; CSS hides it (visibility, not display) when there
+            are no children to toggle. Guards `disabled` itself (not just via the CSS
+            `pointer-events: none` on `.root`) since this handler bypasses Mantine's own
+            `expandOnClick`/`selectOnClick` flags entirely by calling `tree.toggleExpanded`
+            directly. */}
+        <Button
+          overStyled
+          variant="text"
+          size="small"
+          icon={<ExpandGlyph />}
+          aria-label="Toggle subtree"
+          aria-hidden="true"
+          tabIndex={-1}
+          className={styles.expandButton}
+          onClick={(event) => {
+            event.stopPropagation();
+            if (disabled) return;
+            tree.toggleExpanded(node.value);
+          }}
+        />
+        <span className={styles.label} data-selected={selected || undefined}>
+          {node.label}
+        </span>
+      </div>
+    );
+  };
 }
 
 /**
@@ -64,6 +100,11 @@ function renderTreeNode({
  * Wraps Mantine's `Tree` with a fully custom node renderer so every visual aspect (row box
  * model, selected/unselected colors and typography, indent, item spacing) comes from
  * Recursica's `tree` design tokens rather than Mantine's defaults.
+ *
+ * **Interaction pattern (fixed, not prop-configurable):** expand/collapse and select are
+ * independent — the chevron button toggles a node's subtree only, clicking the rest of a row
+ * (or pressing `Enter`/`Space`) selects it only, and `ArrowLeft`/`ArrowRight` toggle expansion
+ * only. See `RecursicaTreeProps` for the full breakdown.
  */
 export const Tree = forwardRef<HTMLUListElement, TreeProps>(function Tree(
   {
@@ -72,8 +113,7 @@ export const Tree = forwardRef<HTMLUListElement, TreeProps>(function Tree(
     initialExpandedValues,
     initialSelectedValues,
     multiple = false,
-    expandOnClick = true,
-    selectOnClick = true,
+    disabled = false,
     onNodeExpand,
     onNodeCollapse,
     onSelectedChange,
@@ -99,6 +139,53 @@ export const Tree = forwardRef<HTMLUListElement, TreeProps>(function Tree(
     onSelectedChange?.(tree.selectedState);
   }, [tree.selectedState, onSelectedChange]);
 
+  // `Enter`/`Space` select the focused node. Mantine's own `TreeNode` only wires this for
+  // `Space`, and only as an expand toggle (`expandOnSpace`, disabled below) — it has no
+  // select-on-key behavior and no `Enter` handling at all, and its key handler lives on the
+  // `<li role="treeitem">` itself (not reachable through `renderNode`'s `elementProps`), so this
+  // is added as a native listener on the tree root instead. `tree.select` is referentially
+  // stable (Mantine wraps it in `useCallback` with no deps), so this effect only re-runs when
+  // `disabled` actually changes.
+  const rootRef = React.useRef<HTMLUListElement>(null);
+  useEffect(() => {
+    const root = rootRef.current;
+    if (!root) return;
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (disabled) return;
+      if (event.key !== "Enter" && event.key !== " ") return;
+      const treeItem = (event.target as HTMLElement).closest<HTMLElement>(
+        '[role="treeitem"]',
+      );
+      const value = treeItem?.dataset.value;
+      if (!value) return;
+      event.preventDefault();
+      tree.select(value);
+    };
+    root.addEventListener("keydown", handleKeyDown);
+    return () => root.removeEventListener("keydown", handleKeyDown);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [tree.select, disabled]);
+
+  // When disabled, block every keydown at the capture phase — before it can reach either the
+  // listener above or Mantine's own internal per-node keydown handling (`ArrowLeft`/`ArrowRight`
+  // expand/collapse, baked into `TreeNode` itself with no prop to disable it). A capture-phase
+  // `stopPropagation` here keeps the event from ever reaching its target, so neither listener
+  // fires — this is the only reachable way to block Mantine's internal handling for a component
+  // with no `disabled` concept of its own. Mouse clicks are separately blocked via `pointer-
+  // events: none` in CSS (`.root[data-disabled]`); this effect only needs to cover keyboard.
+  useEffect(() => {
+    const root = rootRef.current;
+    if (!root || !disabled) return;
+    const blockAllKeydown = (event: KeyboardEvent) => {
+      event.preventDefault();
+      event.stopPropagation();
+    };
+    root.addEventListener("keydown", blockAllKeydown, { capture: true });
+    return () =>
+      root.removeEventListener("keydown", blockAllKeydown, { capture: true });
+  }, [disabled]);
+  const mergedRef = useMergedRef(ref, rootRef);
+
   const classNameProp = (sanitizedProps as Record<string, unknown>)
     .className as string | undefined;
   const rootClass = classNameProp
@@ -107,12 +194,14 @@ export const Tree = forwardRef<HTMLUListElement, TreeProps>(function Tree(
 
   return (
     <MantineTree
-      ref={ref}
+      ref={mergedRef}
       data={data}
       tree={tree}
-      expandOnClick={expandOnClick}
-      selectOnClick={selectOnClick}
-      renderNode={renderTreeNode}
+      expandOnClick={false}
+      selectOnClick={!disabled}
+      expandOnSpace={false}
+      renderNode={createRenderTreeNode(disabled)}
+      data-disabled={disabled || undefined}
       classNames={{
         root: rootClass,
         node: styles.node,

package/src/components/Tree/USAGE.md

@@ -57,7 +57,24 @@ Each node needs a unique `value` and a `label`. Any node with a `children` array
 
 - `initialExpandedValues` accepts an array of node values, or `"*"` to start with every node expanded.
 - `multiple` allows more than one node to be selected at once (default: single-select).
-- `expandOnClick` / `selectOnClick` (both default `true`) control whether clicking a row toggles its expansion and/or selection.
+
+### Interaction pattern
+
+Expanding/collapsing and selecting are independent, fixed interactions (not prop-configurable):
+
+- Clicking the expand/collapse chevron toggles that node's subtree only — it never selects.
+- Clicking anywhere else on a row selects it — it never toggles expansion.
+- `Enter`/`Space` on a focused node selects it, even if the node has children.
+- `ArrowLeft`/`ArrowRight` expand/collapse the focused node only, without changing selection.
+- `ArrowUp`/`ArrowDown` move focus between rows.
+
+### Disabled
+
+```tsx
+<Tree data={data} initialSelectedValues={["1.1"]} disabled />
+```
+
+`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).
 
 ---
 

package/src/index.ts

@@ -175,4 +175,5 @@ export type {
   RecursicaSwitchGroupProps,
   RecursicaTextAreaProps,
   RecursicaTextFieldProps,
+  RecursicaTimePickerProps,
 } from "./components";