@recursica/mantine-adapter 0.36.1 → 0.38.0

package/src/components/TimePicker/TimePicker.tsx

@@ -1,9 +1,289 @@
-import React from "react";
-import { type RecursicaTimePickerProps } from "@recursica/adapter-common";
+import React, { forwardRef, useEffect, useRef, useState } from "react";
+import {
+  TimePicker as MantineTimePicker,
+  type TimePickerProps as MantineTimePickerProps,
+} from "@mantine/dates";
+import { type InputWrapperProps } from "@mantine/core";
+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>;
-};
+const AM_PM_DATA = [
+  { value: "AM", label: "AM" },
+  { value: "PM", label: "PM" },
+];
+
+/** Parses an "HH:mm"/"HH:mm:ss" string's hour, or undefined if not set/parseable. */
+function getHour(value: string | undefined): number | undefined {
+  if (!value) return undefined;
+  const hour = parseInt(value.slice(0, 2), 10);
+  return Number.isNaN(hour) ? undefined : hour;
+}
+
+/** Replaces the hour segment of an "HH:mm"/"HH:mm:ss" string, preserving minutes/seconds. */
+function withHour(value: string, hour: number): string {
+  return `${String(hour).padStart(2, "0")}${value.slice(2)}`;
+}
+
+/**
+ * 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 {
+  if (!value) return undefined;
+  const [hourStr, minute, second] = value.split(":");
+  const hour24 = parseInt(hourStr, 10);
+  if (Number.isNaN(hour24) || minute === undefined) return value;
+  const isPM = hour24 >= 12;
+  const hour12 = hour24 % 12 === 0 ? 12 : hour24 % 12;
+  const rest = second !== undefined ? `${minute}:${second}` : minute;
+  return `${hour12}:${rest} ${isPM ? "PM" : "AM"}`;
+}
+
+/**
+ * Simulates a real user interaction on Mantine's own (CSS-hidden) native AM/PM <select>, since it's
+ * a React-controlled element — setting `.value` directly and dispatching a plain DOM event doesn't
+ * trigger React's change handling; using the native property setter first does. See "Why AM/PM is
+ * seeded on mount" in TIMEPICKER_IMPLEMENTATION_NOTES.md.
+ */
+function setNativeSelectValue(el: HTMLSelectElement, value: string): void {
+  const nativeSetter = Object.getOwnPropertyDescriptor(
+    window.HTMLSelectElement.prototype,
+    "value",
+  )?.set;
+  nativeSetter?.call(el, value);
+  el.dispatchEvent(new Event("change", { bubbles: true }));
+}
+
+export interface RecursicaTimePickerProps
+  extends Omit<
+      MantineTimePickerProps,
+      | "size"
+      | "variant"
+      | "radius"
+      | "wrapperProps"
+      | "format"
+      | "min"
+      | "max"
+      // AM/PM is always shown via our own BareDropdown, driving a fixed 12h format — these all
+      // control Mantine's own native (now CSS-hidden) AM/PM select and would be misleading to
+      // expose, since they'd have no visible effect. See TIMEPICKER_IMPLEMENTATION_NOTES.md.
+      | "amPmInputLabel"
+      | "amPmLabels"
+      | "amPmSelectProps"
+      | "amPmRef"
+      // The optional time-presets dropdown isn't wired up; keep the public API to what's supported.
+      | "withDropdown"
+      | "presets"
+      | "maxDropdownContentHeight"
+      | "scrollAreaProps"
+      | "reverseTimeControlsList"
+      | "popoverProps"
+    >,
+    Pick<
+      InputWrapperProps,
+      "label" | "error" | "required" | "withAsterisk" | "id"
+    >,
+    Omit<
+      RecursicaFormControlWrapperProps,
+      "controlMaxWidth" | "controlMinWidth"
+    >,
+    ReadOnlyControlProps,
+    BaseRecursicaTimePickerProps {}
+
+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,
+      withAsterisk,
+      id,
+      className,
+      style,
+      disabled,
+      readOnly,
+      readOnlyComponent,
+      emptyValueComponent,
+      value,
+      defaultValue,
+      onChange,
+      withSeconds,
+      minTime,
+      maxTime,
+      ...rest
+    } = props;
+
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    delete restRecord["size"];
+    delete restRecord["variant"];
+    delete restRecord["radius"];
+
+    // Internal full 24-hour value. Needed because Mantine's TimePicker (hour/minute/second entry)
+    // and our own BareDropdown (AM/PM) both mutate the same conceptual value — see
+    // TIMEPICKER_IMPLEMENTATION_NOTES.md.
+    const [internalValue, setInternalValue] = useState<string | undefined>(
+      () => value ?? defaultValue,
+    );
+
+    useEffect(() => {
+      if (value !== undefined) {
+        setInternalValue(value);
+      }
+    }, [value]);
+
+    // Mantine's own internal amPm state starts `null` whenever there's no initial hour to derive it
+    // from (see convertTimeTo12HourFormat in @mantine/dates), and it stays null — meaning Mantine
+    // never reports a valid onChange, no matter what's typed — until something interacts with the
+    // (CSS-hidden) native AM/PM <select>. Simulating that interaction once on mount, defaulting to
+    // AM, breaks the deadlock: a freshly-typed time now resolves and reports immediately, and our
+    // own BareDropdown (which drives the same native select the same way, see handleMeridiemChange)
+    // correctly displays and changes it from there. Skipped whenever a real initial value/defaultValue
+    // is already present — Mantine already derives the correct AM/PM from that on its own. See
+    // TIMEPICKER_IMPLEMENTATION_NOTES.md.
+    const amPmRef = useRef<HTMLSelectElement>(null);
+    useEffect(() => {
+      if (getHour(value ?? defaultValue) === undefined && amPmRef.current) {
+        setNativeSelectValue(amPmRef.current, "AM");
+      }
+      // Intentionally mount-only — this seeds Mantine's internal state once; after that it's driven
+      // by real interaction (typing, or our own BareDropdown).
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+
+    const emitChange = (next: string) => {
+      setInternalValue(next);
+      onChange?.(next);
+    };
+
+    const hour = getHour(internalValue);
+    const isPM = hour !== undefined && hour >= 12;
+
+    const handleFieldChange = (next: string) => {
+      emitChange(next);
+    };
+
+    const handleMeridiemChange = (next: string | null) => {
+      if (hour === undefined || !internalValue || !next) return;
+      const wantsPM = next === "PM";
+      if (wantsPM === isPM) return;
+      const nextHour = wantsPM ? hour + 12 : hour - 12;
+      emitChange(withHour(internalValue, nextHour));
+    };
+
+    const wrapperClass = className
+      ? `${styles.layoutOverride} ${className}`
+      : styles.layoutOverride;
+
+    return (
+      <WithReadOnlyWrapper
+        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}
+        withAsterisk={withAsterisk}
+        id={id}
+        readOnly={readOnly}
+        readOnlyComponent={readOnlyComponent}
+        emptyValueComponent={emptyValueComponent}
+        readOnlyType="text"
+        readOnlyValue={formatReadOnlyTime(
+          value !== undefined ? value : defaultValue,
+        )}
+        readOnlyNativeProps={props}
+        activeComponent={
+          /* Naked field execution safely decoupled from Mantine's macro Input.Wrapper DOM hooks.
+             format="12h" is always on — this is the only way this component operates, not a user
+             choice (see TIMEPICKER_IMPLEMENTATION_NOTES.md). Mantine's own native AM/PM <select>
+             (bundled unconditionally with format="12h") is CSS-hidden; our own BareDropdown next to
+             it is the only AM/PM control the user interacts with. */
+          <div
+            className={styles.root}
+            data-disabled={disabled ? "true" : undefined}
+            data-error={error ? "true" : undefined}
+          >
+            <MantineTimePicker
+              ref={ref}
+              classNames={{
+                wrapper: styles.timeWrapper,
+                input: styles.timeInput,
+                fieldsGroup: styles.fieldsGroup,
+                field: styles.timeField,
+              }}
+              disabled={disabled}
+              value={internalValue}
+              onChange={handleFieldChange}
+              format="12h"
+              withSeconds={withSeconds}
+              min={minTime}
+              max={maxTime}
+              withDropdown={false}
+              // Internal-only — not part of the public API (see the Omit list above) — used solely
+              // to seed the mount-time AM default onto Mantine's own hidden native select. See
+              // TIMEPICKER_IMPLEMENTATION_NOTES.md.
+              amPmRef={amPmRef}
+              {...(sanitizedProps as unknown as MantineTimePickerProps)}
+            />
+            <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, keeping every other Recursica style (border, colors, padding) intact.
+              // A plain `style` prop won't do this: Mantine's Select/InputBase internals
+              // (useInputProps) route a top-level `style` prop to the *label* InputWrapper, not
+              // the bordered input box itself — `styles={{ wrapper: ... }}` is the styles-api hook
+              // that actually targets that box. See TIMEPICKER_IMPLEMENTATION_NOTES.md.
+              styles={{ wrapper: { width: "fit-content" } }}
+              data={AM_PM_DATA}
+              value={hour === undefined ? null : isPM ? "PM" : "AM"}
+              onChange={handleMeridiemChange}
+              disabled={disabled}
+              error={!!error}
+              aria-label="AM or PM"
+            />
+          </div>
+        }
+      />
+    );
+  },
+);
+
+TimePicker.displayName = "TimePicker";

package/src/components/TimePicker/USAGE.md

@@ -19,10 +19,25 @@ import React from "react";
 import { TimePicker } from "@recursica/mantine-adapter";
 
 export default function Demo() {
-  return <TimePicker label="Select Time" placeholder="Pick a time" />;
+  return <TimePicker label="Select Time" />;
 }
 ```
 
+> [!IMPORTANT] > **Recursica-specific behavior:** `TimePicker` always renders in **12-hour format with a dedicated AM/PM `Dropdown`-style selector** next to the hour/minute input — this deviates from the underlying Mantine library's own default (24-hour, no AM/PM control) and is **not configurable**. There is no prop to switch to a plain 24-hour input; this is the only way the component operates.
+
+Pass `withSeconds` to add a seconds segment, and `minTime`/`maxTime` (`"HH:mm"` or `"HH:mm:ss"` with `withSeconds`) to bound the allowed range — these always describe 24-hour boundaries.
+
+```tsx
+<TimePicker
+  label="Precise Time"
+  withSeconds
+  minTime="09:00:00"
+  maxTime="17:00:00"
+/>
+```
+
+The AM/PM control visually matches Recursica's `Dropdown` component exactly, rather than a native `<select>`.
+
 ---
 
 ## 3. Design System Integration
@@ -31,6 +46,12 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 > [!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.
+
+---
+
+## 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/Timeline/USAGE.md

@@ -44,14 +44,6 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 ## 4. Key Integration Features & Constraints
 
-## Architecture
+`Timeline.Item` accepts a `timestamp` prop that renders below the item's content, and a `bulletVariant` prop (`"default" | "avatar" | "icon" | "icon-alternative"`) to control the bullet's appearance. The `lineWidth` and `bulletSize` props are not configurable, since geometry is controlled by the design system tokens.
 
-The `Timeline` component is a strict structural wrapper around Mantine's `<Timeline>` and `<Timeline.Item>` components.
-
-- `Timeline.tsx` intercepts overarching properties like `lineWidth` and `bulletSize` to strip them out via `overStyled`, strictly adhering to the CSS token mapping in `.item` rules instead.
-- `TimelineItem.tsx` implements a custom `timestamp` React node rendering slot to match the design system, positioning the text directly below the item's `children`.
-- `TimelineItem.tsx` supports a custom `bulletVariant` prop (`"default" | "avatar" | "icon" | "icon-alternative"`) mapped onto `data-variant` to handle CSS variations dynamically.
-
-## Limitations & Missing Tokens
-
-- **Avatar Bullet Size**: There is no specific pixel variable provided for the Avatar bullet size in the UI kit tokens (`avatar-size` evaluates to `"default"`). To maintain exact mathematical centering with Mantine's connector line `calc()` equations, the CSS falls back to inheriting the `default` bullet size (`20px`) for avatar nodes natively. If users supply a custom sized `img` tag, it must adhere to inline structural constraints or flex mappings.
+A known limitation: when using `bulletVariant="avatar"`, the avatar bullet always renders at the default bullet size rather than a custom size.

package/src/components/Toast/USAGE.md

@@ -23,7 +23,7 @@ export default function Demo() {
     <Toast
       title="Success"
       message="Your action completed successfully"
-      state="success"
+      variant="success"
     />
   );
 }
@@ -45,36 +45,6 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 ## 4. Key Integration Features & Constraints
 
-## 1. Standalone Visual Wrapper
+`Toast` can be used directly for a static or inline message, or wired up to `@mantine/notifications` for dynamic popups. The `variant` prop (`"default" | "error" | "success"`) controls the toast's color treatment.
 
-**Decision:** We wrap `@mantine/core`'s standalone `Notification` component instead of wrapping the `@mantine/notifications` provider.
-
-**Implementation:** The UI Kit provides variables for the `Toast` component itself (e.g., `--recursica_ui-kit_components_toast_*`). We use these variables to style the standard Mantine `Notification` element. This allows developers to use `<Toast>` manually if they want a static or inline message.
-
-If dynamic popups are required, developers can configure `@mantine/notifications` to utilize this component or use its classes.
-
----
-
-## 2. Variant Mapping via `data-variant`
-
-**Decision:** `variant` props (`"default" | "error" | "success"`) are mapped directly to `data-variant` on the Mantine root `Box`.
-
-**Implementation:** Mantine's `Notification` doesn't inherently support our custom variants out of the box in the way we want them styled. By passing `data-variant` directly to the `Box`, we can explicitly target the root element in our `Toast.module.css` (e.g., `.root[data-variant="success"]`) and pipe in the corresponding UI Kit layer colors.
-
----
-
-## 3. Minimal CSS Override Philosophy
-
-**Decision:** The CSS module only overrides visual design tokens (colors, typography, padding, borders, shadows).
-
-**Implementation:** We defer layout structure, icon rendering, loader transitions, and close button mechanics to Mantine. The `border-style: none;` is hardcoded to reset any underlying styles from Mantine's defaults, ensuring a clean mapping of elevation and shadows.
-
----
-
-## 4. Unsupported `loading` State
-
-**Decision:** The native `loading` state is explicitly stripped and bypassed from the `<Toast />` component wrapper.
-
-**Implementation:** Mantine's `Notification` inherently supports a `loading={true}` state that natively spins up a loader instead of an icon. However, Recursica's UI Kit strictly does not define structural tokens for loader states inside toasts.
-Instead of attempting to tightly couple the internal `Loader` abstraction or mapping variables incorrectly, the `loading` property is explicitly omitted and `false`-enforced from the public API.
-If consumers explicitly require a loading toast, they must manually inject a `<Loader />` component into the `icon` slot.
+The `loading` state is not supported. If a loading toast is needed, pass a `<Loader />` component into the `icon` slot instead.

package/src/components/Tooltip/USAGE.md

@@ -53,63 +53,21 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 ---
 
-## 2. Token Namespace: `tooltip`
+## 2. Behavior Notes
 
-**Decision:** The CSS module exclusively uses variables from the `--recursica_ui-kit_components_tooltip_*` namespace.
-
-**Implementation:** The Recursica token system defines the `tooltip` namespace covering:
-
-- Geometry: border-radius, border-size, min-width, min-height, max-width, padding
-- Typography: text_font-\* (family, size, style, weight, letter-spacing, line-height, text-decoration, text-transform)
-- Colors (layer-aware): background, border-color, text
-- Elevation: box-shadow
-- Beak: beak-size (16px), beak-inset (8px)
-
-No tokens from other component namespaces are referenced.
-
----
-
-## 3. Hardcoded Values
-
-### `border-style: solid` (CSS module)
-
-Mantine renders the tooltip using its `Box` component, which does not set `border-style` natively. Without this hardcoded value, the border-width and border-color tokens would have no visible effect. Same pattern as Menu and HoverCard dropdowns.
-
-### `arrowSize` defaulted to `16` (Tooltip.tsx)
-
-Mantine's `arrowSize` prop is a JavaScript number used for inline style calculations: it sets `width`, `height`, and a positioning offset (`-arrowSize/2`) directly on the arrow `<div>` element. These inline styles cannot be overridden via CSS without `!important`, and the positioning offset has no CSS equivalent. The beak size cannot be fully CSS-driven.
-
-The default value `16` matches the Recursica `beak-size` token (`--recursica_ui-kit_components_tooltip_properties_beak-size: 16px`). Developers can override `arrowSize` if needed. This is documented as an open issue in `docs/COMPONENT_ISSUES.md`.
-
-**Note:** Mantine calls this the "arrow"; Recursica calls it the "beak". The Recursica prop `withBeak` (defaulting to `true`) maps to Mantine's `withArrow`. Both are accepted; `withBeak` takes precedence.
-
-### `multiline={true}` (Tooltip.tsx)
-
-Mantine's `multiline` prop controls whether tooltip text wraps (`white-space: nowrap` when false). Recursica always enables multiline because the design system defines a `max-width` token (300px) — text should wrap naturally within that constraint rather than overflowing. The `multiline` prop is not exposed to developers.
-
-### Flexbox centering (CSS module)
-
-`display: flex; align-items: center; justify-content: center;` is applied to the `.tooltip` class. This ensures text is vertically and horizontally centered within the `min-height: 48px` container defined by the design token. Without this, text sits at the top of the tooltip.
+Tooltip text always wraps to fit within the token-defined max width, rather than staying on a single line or overflowing. The `multiline` prop is not exposed, since this behavior is always on.
 
 ---
 
-## 4. Recursica `withBeak` Prop
+## 3. Recursica `withBeak` Prop
 
 **Decision:** `withBeak` is the official Recursica prop for controlling beak visibility, defaulting to `true`.
 
-**Implementation:** Both `withBeak` and Mantine's `withArrow` are accepted. Resolution order: `withBeak ?? withArrow`. When both are provided, `withBeak` takes precedence. The default of `true` means tooltips show the beak by default, matching the Recursica design intent.
+**Implementation:** Both `withBeak` and Mantine's `withArrow` are accepted. When both are provided, `withBeak` takes precedence. The beak's size can be adjusted via the `arrowSize` prop (default `16`).
 
 ---
 
-## 5. ClassNames Binding
-
-**Decision:** CSS module classes are bound via the `classNames` prop on Mantine's Tooltip root.
-
-**Implementation:** The stylesNames for Tooltip are `tooltip` (the container) and `arrow` (the beak). Both are mapped to their respective CSS module classes: `{ tooltip: styles.tooltip, arrow: styles.arrow }`. Consumer-provided `classNames` are merged additively when `overStyled` is true.
-
----
-
-## 6. Tooltip.Floating and Tooltip.Group
+## 4. Tooltip.Floating and Tooltip.Group
 
 **Decision:** These static sub-components are direct pass-throughs to Mantine with no Recursica styling.
 
@@ -117,8 +75,6 @@ Mantine's `multiline` prop controls whether tooltip text wraps (`white-space: no
 
 ---
 
-## 7. Default Position Override
-
-**Decision:** Recursica defaults `position` to `"top"`. Mantine defaults to `"bottom"`.
+## 5. Default Position
 
-**Implementation:** The `position="top"` default is set on the Mantine root element before the prop spread, so developer-provided `position` values still take precedence. This aligns with Recursica's design intent for overlay components to appear above their trigger by default.
+Recursica defaults `position` to `"top"` instead of Mantine's default of `"bottom"`. Pass your own `position` value to override it.

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.