@recursica/mui-adapter 0.19.0 → 0.21.0

package/src/components/TimePicker/TimePicker.tsx

@@ -1,10 +1,259 @@
-import React from "react";
-import "./TimePicker.module.css";
-import { type RecursicaTimePickerProps } from "@recursica/adapter-common";
+import React, { forwardRef, useEffect, useState } from "react";
+import { LocalizationProvider } from "@mui/x-date-pickers/LocalizationProvider";
+import { AdapterDayjs } from "@mui/x-date-pickers/AdapterDayjs";
+import {
+  TimePicker as MuiTimePicker,
+  type TimePickerProps as MuiTimePickerProps,
+} from "@mui/x-date-pickers/TimePicker";
+import dayjs, { type Dayjs } from "dayjs";
+import customParseFormat from "dayjs/plugin/customParseFormat";
+import { type ReadOnlyControlProps } from "@recursica/adapter-common";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import { type RecursicaFormControlWrapperProps } from "../FormControlWrapper/FormControlWrapper";
+import { WithReadOnlyWrapper } from "../ReadOnlyField/WithReadOnlyWrapper";
+import { BareDropdown } from "../Dropdown/BareDropdown";
+import styles from "./TimePicker.module.css";
 
-export type TimePickerProps = React.HTMLAttributes<HTMLDivElement> &
-  RecursicaTimePickerProps;
+import { type RecursicaTimePickerProps as BaseRecursicaTimePickerProps } from "@recursica/adapter-common";
 
-export const TimePicker: React.FC<TimePickerProps> = (props) => {
-  return <div {...props}>TimePicker</div>;
-};
+// Required for dayjs's 2-arg `dayjs(value, format)` string-parsing signature used by `toDayjs`
+// below — without this, dayjs silently ignores the format string and falls back to native `Date`
+// parsing, which fails on a bare "HH:mm" time string (no date component) and returns an Invalid
+// Date. This went unnoticed until a real initial `value`/`defaultValue` needed parsing (every
+// interactive test before that produced Dayjs objects directly from the field's own onChange,
+// never exercising this path).
+dayjs.extend(customParseFormat);
+
+const TIME_FORMAT_SECONDS = "HH:mm:ss";
+const TIME_FORMAT_MINUTES = "HH:mm";
+const AM_PM_DATA = [
+  { value: "AM", label: "AM" },
+  { value: "PM", label: "PM" },
+];
+
+/** Parses a Recursica "HH:mm" / "HH:mm:ss" string into a Dayjs instance, or undefined if not set. */
+function toDayjs(value: string | undefined): Dayjs | undefined {
+  if (!value) return undefined;
+  const format = value.length > 5 ? TIME_FORMAT_SECONDS : TIME_FORMAT_MINUTES;
+  return dayjs(value, format);
+}
+
+/**
+ * Formats an "HH:mm"/"HH:mm:ss" 24-hour value as a 12-hour + AM/PM string for read-only display
+ * (e.g. "14:30" -> "2:30 PM") — the raw 24-hour string was being shown as-is in read-only mode,
+ * with no AM/PM, unlike the interactive composite. Returns undefined if not parseable.
+ */
+function formatReadOnlyTime(value: string | undefined): string | undefined {
+  const parsed = toDayjs(value);
+  if (!parsed) return value;
+  return parsed.format(value && value.length > 5 ? "h:mm:ss A" : "h:mm A");
+}
+
+export interface RecursicaTimePickerProps
+  extends Omit<
+      MuiTimePickerProps,
+      | "value"
+      | "defaultValue"
+      | "onChange"
+      | "minTime"
+      | "maxTime"
+      | "views"
+      | "format"
+      | "style"
+    >,
+    Pick<
+      RecursicaFormControlWrapperProps,
+      | "label"
+      | "error"
+      | "required"
+      | "id"
+      | "assistiveText"
+      | "assistiveWithIcon"
+      | "formLayout"
+      | "labelSize"
+      | "labelAlignment"
+      | "labelOptionalText"
+      | "labelWithEditIcon"
+      | "onLabelEditClick"
+    >,
+    ReadOnlyControlProps,
+    BaseRecursicaTimePickerProps {
+  /** Selected time as an "HH:mm" (or "HH:mm:ss" with `withSeconds`) string, matching the mantine-adapter convention. */
+  value?: string;
+  /** Uncontrolled initial time as an "HH:mm" (or "HH:mm:ss" with `withSeconds`) string. */
+  defaultValue?: string;
+  /** Fires with the new time as an "HH:mm" (or "HH:mm:ss" with `withSeconds`) string, or `null` if cleared. */
+  onChange?: (value: string | null) => void;
+  /** Caller-provided inline style, passed through to the FormControlWrapper root. */
+  style?: React.CSSProperties;
+}
+
+export type TimePickerProps = RecursicaOverStyled<RecursicaTimePickerProps>;
+
+export const TimePicker = forwardRef<HTMLDivElement, TimePickerProps>(
+  function TimePicker(props, ref) {
+    const {
+      overStyled = false,
+      formLayout = "stacked",
+
+      // Label & Wrapper Maps
+      labelSize,
+      labelAlignment,
+      labelOptionalText,
+      labelWithEditIcon,
+      onLabelEditClick,
+
+      label,
+      assistiveText,
+      assistiveWithIcon,
+      error,
+      required,
+      id,
+      className,
+      style,
+      disabled,
+      readOnly,
+      readOnlyComponent,
+      emptyValueComponent,
+      value,
+      defaultValue,
+      onChange,
+      withSeconds,
+      minTime,
+      maxTime,
+      ...rest
+    } = props;
+
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+
+    // Internal full 24-hour value. Needed (unlike every other component in this adapter) because
+    // the time field and the AM/PM BareDropdown both mutate the same conceptual value — see
+    // TIMEPICKER_IMPLEMENTATION_NOTES.md.
+    const [internalValue, setInternalValue] = useState<Dayjs | null>(
+      () => toDayjs(value) ?? toDayjs(defaultValue) ?? null,
+    );
+
+    useEffect(() => {
+      if (value !== undefined) {
+        setInternalValue(toDayjs(value) ?? null);
+      }
+    }, [value]);
+
+    const isPM = internalValue ? internalValue.hour() >= 12 : false;
+
+    const wrapperClass = className
+      ? `${styles.layoutOverride} ${className}`
+      : styles.layoutOverride;
+
+    const emitChange = (next: Dayjs | null) => {
+      setInternalValue(next);
+      onChange?.(
+        next
+          ? next.format(withSeconds ? TIME_FORMAT_SECONDS : TIME_FORMAT_MINUTES)
+          : null,
+      );
+    };
+
+    const handleFieldChange = (next: Dayjs | null) => {
+      emitChange(next);
+    };
+
+    const handleMeridiemChange = (next: string | null) => {
+      if (!internalValue || !next) return;
+      const wantsPM = next === "PM";
+      const currentHour = internalValue.hour();
+      const currentlyPM = currentHour >= 12;
+      if (wantsPM === currentlyPM) return;
+      const nextHour = wantsPM ? currentHour + 12 : currentHour - 12;
+      emitChange(internalValue.hour(nextHour));
+    };
+
+    return (
+      <WithReadOnlyWrapper
+        ref={ref}
+        className={wrapperClass}
+        style={style as React.CSSProperties}
+        controlMaxWidth={undefined}
+        controlMinWidth={undefined}
+        overStyled={overStyled as true}
+        formLayout={formLayout}
+        labelSize={labelSize}
+        labelAlignment={labelAlignment}
+        labelOptionalText={labelOptionalText}
+        labelWithEditIcon={labelWithEditIcon}
+        onLabelEditClick={onLabelEditClick}
+        label={label}
+        assistiveText={assistiveText}
+        assistiveWithIcon={assistiveWithIcon}
+        error={error}
+        required={required}
+        id={id}
+        readOnly={readOnly}
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        readOnlyComponent={readOnlyComponent as any}
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        emptyValueComponent={(emptyValueComponent as any) || undefined}
+        readOnlyType="text"
+        readOnlyValue={formatReadOnlyTime(
+          value !== undefined ? value : defaultValue,
+        )}
+        readOnlyNativeProps={props}
+        activeComponent={
+          /* Naked field execution safely decoupled from MUI X's own label/error macro handling.
+             format="hh:mm" is always on (12-hour digits, no native meridiem section) — this is the
+             only way this component operates, not a user choice. The AM/PM BareDropdown next to it
+             is the only AM/PM control; see TIMEPICKER_IMPLEMENTATION_NOTES.md. */
+          <div className={styles.root} data-error={error ? "true" : undefined}>
+            <LocalizationProvider dateAdapter={AdapterDayjs}>
+              <MuiTimePicker
+                value={internalValue}
+                onChange={handleFieldChange}
+                disabled={disabled}
+                format={`hh:${withSeconds ? "mm:ss" : "mm"}`}
+                views={
+                  withSeconds
+                    ? ["hours", "minutes", "seconds"]
+                    : ["hours", "minutes"]
+                }
+                minTime={toDayjs(minTime)}
+                maxTime={toDayjs(maxTime)}
+                // No icon/open-picker button: time-picker's own token schema has no icon slot (see
+                // EXEMPTIONS above), and the popup clock/list view this button opens isn't styled
+                // to Recursica tokens anyway (see TIMEPICKER_IMPLEMENTATION_NOTES.md) — showing an
+                // affordance to open an unstyled popup would be worse than not showing one. Typing
+                // directly into the field's masked hour/minute segments is the only interaction.
+                slots={{ openPickerButton: () => null }}
+                slotProps={{
+                  field: {
+                    className: styles.field,
+                  },
+                }}
+                {...(sanitizedProps as unknown as Partial<MuiTimePickerProps>)}
+              />
+            </LocalizationProvider>
+            <BareDropdown
+              overStyled
+              className={styles.amPmSelect}
+              // Dropdown.module.css's own .root sets width: 100% (correct for a standalone
+              // Dropdown filling its form-control column) — overStyled lets us override just the
+              // width via inline style, keeping every other Recursica style (border, colors,
+              // padding) intact. See TIMEPICKER_IMPLEMENTATION_NOTES.md.
+              style={{ width: "fit-content" }}
+              data={AM_PM_DATA}
+              value={isPM ? "PM" : "AM"}
+              onChange={handleMeridiemChange}
+              disabled={disabled}
+              error={!!error}
+              aria-label="AM or PM"
+            />
+          </div>
+        }
+      />
+    );
+  },
+);
+
+TimePicker.displayName = "TimePicker";

package/src/components/TimePicker/USAGE.md

@@ -10,6 +10,8 @@ This document describes how to integrate and use the `TimePicker` component in y
 import { TimePicker } from "@recursica/mui-adapter";
 ```
 
+`TimePicker` requires `@mui/x-date-pickers` (optional peer dependency) to be installed alongside `@mui/material`. See [SETUP.md](../../../SETUP.md).
+
 ---
 
 ## 2. Basic Example
@@ -19,10 +21,26 @@ import React from "react";
 import { TimePicker } from "@recursica/mui-adapter";
 
 export default function Demo() {
-  return <TimePicker label="Select Time" placeholder="Pick a time" />;
+  return <TimePicker label="Select Time" />;
 }
 ```
 
+`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.
+
+```tsx
+<TimePicker
+  label="Precise Time"
+  withSeconds
+  minTime="09:00:00"
+  maxTime="17:00:00"
+  onChange={(value) => console.log(value)} // "HH:mm:ss" | null
+/>
+```
+
+> [!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.
+
+The AM/PM control visually matches Recursica's `Dropdown` component exactly, rather than a plain native `<select>`.
+
 ---
 
 ## 3. Design System Integration
@@ -31,6 +49,13 @@ All Recursica components in the `@recursica/mui-adapter` package adhere strictly
 
 > [!IMPORTANT]
 >
-> - **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.
+> - **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.
 > - **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.
 > - **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.
+> - **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).
+
+---
+
+## 4. Read-Only Mode
+
+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"`).

package/src/components/Tree/IMPLEMENTATION_NOTES.md

@@ -18,4 +18,31 @@
 
 - **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.
 
-- **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.
+- **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).
+
+- **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.
+
+- **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" .../>`:
+
+  - **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.
+  - **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.
+  - **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).
+  - **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 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.
+
+- **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.
+
+  - **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.
+  - **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.
+  - **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.
+
+- **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, 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.
+  - **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.
+  - **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.
+
+- **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).
+  - **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.
+  - **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.
+  - **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).

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

@@ -1,13 +1,17 @@
 /* HARDCODED VALUES:
  * - list-style/margin/padding resets on .root/.subtree/.node: layout resets, no corresponding
  *   design tokens (structural, not visual design values).
- * - .chevron size (1em) and rotation: 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.
+ * - .chevron rotation timing (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.
- * - .row's padding-left keeps MUI's own depth-based indentation formula (base + indent * depth)
- *   but substitutes our own horizontal-padding token as the base instead of MUI's theme spacing.
+ * - .row's padding-left keeps MUI's own depth-based indentation formula (indent * depth), just
+ *   without the horizontal-padding base — that base now lives on .label instead (see below).
+ *
+ * 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 {
@@ -42,6 +46,28 @@
   list-style: none;
 }
 
+/* @mui/x-tree-view'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;
@@ -50,22 +76,77 @@
   width: 100%;
   cursor: pointer;
   gap: var(--recursica_ui-kit_components_tree_properties_button-node-gap);
-
-  padding-top: var(
-    --recursica_ui-kit_components_tree_properties_vertical-padding
-  );
-  padding-bottom: var(
-    --recursica_ui-kit_components_tree_properties_vertical-padding
-  );
-  padding-right: var(
-    --recursica_ui-kit_components_tree_properties_horizontal-padding
-  );
   padding-left: calc(
-    var(--recursica_ui-kit_components_tree_properties_horizontal-padding) +
-      var(--TreeView-itemChildrenIndentation, 0px) *
-      var(--TreeView-itemDepth, 0)
+    var(--TreeView-itemChildrenIndentation, 0px) * var(--TreeView-itemDepth, 0)
   );
+}
 
+/* Neutralize MUI's own hover/focused/selected background-color changes (see TreeItemContent's
+   defaults in @mui/x-tree-view, e.g. its built-in `rgba(25, 118, 210, 0.08)` selected tint) so
+   only the Recursica hover overlay and selected styling on .label below control the look; .row
+   itself carries no background-color of its own to fall back to now. The `[data-selected]
+   [data-focused]` compound needs its own rule: MUI's own equivalent compound selector has higher
+   specificity (2 attributes + its class) than a single-attribute `.row[data-selected]` rule
+   would, so it would otherwise still win regardless of source order. */
+.row:hover,
+.row[data-focused],
+.row[data-selected],
+.row[data-selected][data-focused] {
+  background-color: transparent;
+}
+
+.row[data-disabled] {
+  opacity: var(--recursica_brand_states_disabled);
+  cursor: auto;
+  /* MUI's own disabled checks already block select/expand on click, but hover is pure CSS —
+     without this, a disabled row still showed the hover tint (.label::after opacity) on mouse-
+     over, misleadingly suggesting it's interactive. Matches mantine-adapter's `.root[data-
+     disabled] { pointer-events: none; }`, just scoped per-row instead of tree-wide, since MUI's
+     disabled state is a per-item concept even when driven by our own whole-tree prop. */
+  pointer-events: none;
+}
+
+.iconContainer {
+  position: relative;
+  z-index: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  color: inherit;
+}
+
+/* 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 {
+  flex-shrink: 0;
+}
+.expandButtonHidden {
+  visibility: hidden;
+}
+
+.chevron {
+  transition: transform 150ms ease;
+}
+.chevronExpanded {
+  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.
+     `width: auto` is required in addition to `flex: 0 1 auto`: MuiTreeItem's own default
+     `.MuiTreeItem-label` sets a literal `width: 100%`, which a flex-basis alone can't beat. */
+  flex: 0 1 auto;
+  width: 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 */
   border-width: var(--recursica_ui-kit_components_tree_properties_border-size);
   border-radius: var(
@@ -108,36 +189,33 @@
   );
 }
 
-/* Neutralize MUI's own hover/focused background-color changes (see TreeItemContent's defaults
-   in @mui/x-tree-view) so only the Recursica hover overlay below controls the hover look. */
-.row:hover,
-.row[data-focused] {
-  background-color: var(
-    --recursica_ui-kit_components_tree_variants_selection-states_unselected_properties_colors_background-color
-  );
-}
-
-/* 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:hover .label::after {
   opacity: var(--recursica_brand_states_hover_opacity);
 }
 
-/* Selected row state — written after the hover/focus resets above so it wins the equal-
-   specificity tie via source order, including when hovered/focused while selected. */
-.row[data-selected],
-.row[data-selected]:hover,
-.row[data-selected][data-focused] {
+/* Selected state — read off `.row`'s own `data-selected`/`data-focused` (set by
+   `getContentProps()`), applied to `.label`. Written after the hover/focus reset above so it
+   wins the equal-specificity tie via source order, including when hovered/focused while
+   selected. */
+.row[data-selected] .label,
+.row[data-selected]:hover .label,
+.row[data-selected][data-focused] .label {
   font-family: var(
     --recursica_ui-kit_components_tree_variants_selection-states_selected_properties_text_font-family
   );
@@ -173,36 +251,3 @@
     --recursica_ui-kit_components_tree_variants_selection-states_selected_properties_colors_border-color
   );
 }
-
-.row[data-disabled] {
-  opacity: var(--recursica_brand_states_disabled);
-  cursor: auto;
-}
-
-.iconContainer {
-  position: relative;
-  z-index: 1;
-  width: 1em;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  flex-shrink: 0;
-  color: inherit;
-}
-
-.chevron {
-  transition: transform 150ms ease;
-}
-.chevronExpanded {
-  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> = {