@recursica/adapter-mantine-v8 1.0.0

package/src/components/TransferList/TransferList.stories.tsx

@@ -0,0 +1,121 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { TransferList } from "./TransferList";
+import { formControlArgTypes } from "../../../.storybook/commonArgTypes";
+
+type TransferListStoryProps = React.ComponentProps<typeof TransferList>;
+
+const SAMPLE_DATA: TransferListStoryProps["defaultData"] = [
+  [
+    { value: "alpha", label: "Alpha" },
+    { value: "bravo", label: "Bravo" },
+    { value: "charlie", label: "Charlie" },
+    { value: "delta", label: "Delta" },
+    { value: "echo", label: "Echo" },
+  ],
+  [{ value: "foxtrot", label: "Foxtrot" }],
+];
+
+const GROUPED_DATA: TransferListStoryProps["defaultData"] = [
+  [
+    { value: "apple", label: "Apple", group: "Fruit" },
+    { value: "banana", label: "Banana", group: "Fruit" },
+    { value: "carrot", label: "Carrot", group: "Vegetable" },
+    { value: "daikon", label: "Daikon", group: "Vegetable" },
+    { value: "eagle", label: "Eagle" },
+  ],
+  [],
+];
+
+const meta: Meta<TransferListStoryProps> = {
+  title: "UI-Kit/TransferList",
+  component: TransferList,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "TransferList (dual listbox) lets users move items between two lists. Composes FormControlWrapper, TextField, Checkbox, CheckboxGroup, Badge, and Button.",
+      },
+    },
+  },
+  args: {
+    label: "Assign users",
+    assistiveText: "Move users into the selected list.",
+    defaultData: SAMPLE_DATA,
+    disabled: false,
+    required: false,
+  },
+  argTypes: {
+    disabled: {
+      control: "boolean",
+    },
+    ...formControlArgTypes,
+    sourceLabel: {
+      control: "text",
+    },
+    targetLabel: {
+      control: "text",
+    },
+    searchable: {
+      control: "boolean",
+    },
+    searchPlaceholder: {
+      control: "text",
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<TransferListStoryProps>;
+
+export const Default: Story = {};
+
+export const Grouped: Story = {
+  args: {
+    label: "Assign ingredients",
+    defaultData: GROUPED_DATA,
+  },
+};
+
+export const SideBySide: Story = {
+  args: {
+    formLayout: "side-by-side",
+  },
+};
+
+export const NoSearch: Story = {
+  args: {
+    label: "Assign users (no filtering)",
+    searchable: false,
+  },
+};
+
+export const StaticError: Story = {
+  args: {
+    error: "Select at least one user.",
+    defaultData: [[], SAMPLE_DATA![0]],
+  },
+};
+
+export const StaticDisabled: Story = {
+  args: {
+    disabled: true,
+  },
+};
+
+export const Empty: Story = {
+  args: {
+    label: "Assign users",
+    defaultData: [[], []],
+  },
+};
+
+export const ReadOnly: Story = {
+  args: {
+    label: "Assigned users",
+    defaultData: [[], SAMPLE_DATA![0]],
+    readOnly: true,
+  },
+};

package/src/components/TransferList/TransferList.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future TransferList component tests. Add tests here if/when needed.

package/src/components/TransferList/TransferList.tsx

@@ -0,0 +1,419 @@
+import { forwardRef, useCallback, useId, useMemo, useState } from "react";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import { type FormControlWrapperProps } from "../FormControlWrapper/FormControlWrapper";
+import { WithReadOnlyWrapper } from "../ReadOnlyField/WithReadOnlyWrapper";
+import { Badge } from "../Badge/Badge";
+import { Button } from "../Button/Button";
+import { TextField } from "../TextField/TextField";
+import { Checkbox } from "../Checkbox/Checkbox";
+import { CheckboxGroup } from "../Checkbox/CheckboxGroup";
+import styles from "./TransferList.module.css";
+
+import {
+  type ReadOnlyControlProps,
+  type RecursicaTransferListProps as BaseRecursicaTransferListProps,
+  type RecursicaTransferListItem,
+  type RecursicaTransferListData,
+} from "@recursica/adapter-common";
+
+export type { RecursicaTransferListItem, RecursicaTransferListData };
+
+export interface RecursicaTransferListProps
+  extends Omit<
+      FormControlWrapperProps,
+      | "children"
+      | "overStyled"
+      | "controlMaxWidth"
+      | "controlMinWidth"
+      | "onChange"
+    >,
+    ReadOnlyControlProps,
+    BaseRecursicaTransferListProps {
+  /** Disables the whole control */
+  disabled?: boolean;
+}
+
+export type TransferListProps = RecursicaOverStyled<RecursicaTransferListProps>;
+
+/** Single/double chevron glyphs for the transfer buttons; flipped via CSS for the "left" direction
+ * so only one path needs to be maintained, same approach as Tree's `ExpandGlyph`. */
+function ChevronIcon({ direction }: { direction: "left" | "right" }) {
+  return (
+    <svg
+      className={styles.chevron}
+      data-direction={direction}
+      viewBox="0 0 16 16"
+      width="1em"
+      height="1em"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M6 3l5 5-5 5" />
+    </svg>
+  );
+}
+
+function ChevronsIcon({ direction }: { direction: "left" | "right" }) {
+  return (
+    <svg
+      className={styles.chevron}
+      data-direction={direction}
+      viewBox="0 0 16 16"
+      width="1em"
+      height="1em"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M3 3l5 5-5 5M9 3l5 5-5 5" />
+    </svg>
+  );
+}
+
+/** Splits items into grouped/ungrouped buckets, same shape Forge's reference groups by `group`. */
+function groupItems(items: RecursicaTransferListItem[]) {
+  const groups: Record<string, RecursicaTransferListItem[]> = {};
+  const ungrouped: RecursicaTransferListItem[] = [];
+  items.forEach((item) => {
+    if (item.group) {
+      (groups[item.group] ??= []).push(item);
+    } else {
+      ungrouped.push(item);
+    }
+  });
+  return { groups, ungrouped };
+}
+
+export const TransferList = forwardRef<HTMLDivElement, TransferListProps>(
+  function TransferList(props, ref) {
+    const {
+      overStyled = false,
+      formLayout = "stacked",
+
+      // Label & Wrapper Maps
+      labelSize,
+      labelAlignment,
+      labelOptionalText,
+      labelWithEditIcon,
+      labelActionArea,
+      onLabelEditClick,
+
+      label,
+      assistiveText,
+      description,
+      helperText,
+      assistiveWithIcon,
+      error,
+      required,
+      id: userProvidedId,
+      readOnly,
+      readOnlyComponent,
+      emptyValueComponent,
+
+      data: controlledData,
+      defaultData,
+      onChange,
+      sourceLabel = "Available",
+      targetLabel = "Selected",
+      searchable = true,
+      searchPlaceholder = "Filter items...",
+      disabled = false,
+
+      className,
+      style,
+      ...rest
+    } = props;
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+
+    const generatedId = useId();
+    const id = userProvidedId || `recursica-transfer-list-${generatedId}`;
+
+    // Manage internal state for uncontrolled mode
+    const [internalData, setInternalData] = useState<RecursicaTransferListData>(
+      () => defaultData ?? controlledData ?? [[], []],
+    );
+    const effectiveData =
+      controlledData !== undefined ? controlledData : internalData;
+
+    const handleChange = useCallback(
+      (newData: RecursicaTransferListData) => {
+        if (controlledData === undefined) {
+          setInternalData(newData);
+        }
+        onChange?.(newData);
+      },
+      [controlledData, onChange],
+    );
+
+    const [sourceSearch, setSourceSearch] = useState("");
+    const [targetSearch, setTargetSearch] = useState("");
+    const [sourceSelected, setSourceSelected] = useState<Set<string>>(
+      () => new Set(),
+    );
+    const [targetSelected, setTargetSelected] = useState<Set<string>>(
+      () => new Set(),
+    );
+
+    const filteredSource = useMemo(() => {
+      if (!sourceSearch) return effectiveData[0];
+      const query = sourceSearch.toLowerCase();
+      return effectiveData[0].filter((item) =>
+        item.label.toLowerCase().includes(query),
+      );
+    }, [effectiveData, sourceSearch]);
+
+    const filteredTarget = useMemo(() => {
+      if (!targetSearch) return effectiveData[1];
+      const query = targetSearch.toLowerCase();
+      return effectiveData[1].filter((item) =>
+        item.label.toLowerCase().includes(query),
+      );
+    }, [effectiveData, targetSearch]);
+
+    const transferToTarget = useCallback(() => {
+      if (sourceSelected.size === 0) return;
+      const newSource = effectiveData[0].filter(
+        (item) => !sourceSelected.has(item.value),
+      );
+      const moved = effectiveData[0].filter((item) =>
+        sourceSelected.has(item.value),
+      );
+      setSourceSelected(new Set());
+      handleChange([newSource, [...effectiveData[1], ...moved]]);
+    }, [effectiveData, sourceSelected, handleChange]);
+
+    const transferToSource = useCallback(() => {
+      if (targetSelected.size === 0) return;
+      const newTarget = effectiveData[1].filter(
+        (item) => !targetSelected.has(item.value),
+      );
+      const moved = effectiveData[1].filter((item) =>
+        targetSelected.has(item.value),
+      );
+      setTargetSelected(new Set());
+      handleChange([[...effectiveData[0], ...moved], newTarget]);
+    }, [effectiveData, targetSelected, handleChange]);
+
+    const transferAllToTarget = useCallback(() => {
+      if (effectiveData[0].length === 0) return;
+      setSourceSelected(new Set());
+      handleChange([[], [...effectiveData[1], ...effectiveData[0]]]);
+    }, [effectiveData, handleChange]);
+
+    const transferAllToSource = useCallback(() => {
+      if (effectiveData[1].length === 0) return;
+      setTargetSelected(new Set());
+      handleChange([[...effectiveData[0], ...effectiveData[1]], []]);
+    }, [effectiveData, handleChange]);
+
+    const toggleSourceItem = useCallback((value: string) => {
+      setSourceSelected((prev) => {
+        const next = new Set(prev);
+        if (next.has(value)) next.delete(value);
+        else next.add(value);
+        return next;
+      });
+    }, []);
+
+    const toggleTargetItem = useCallback((value: string) => {
+      setTargetSelected((prev) => {
+        const next = new Set(prev);
+        if (next.has(value)) next.delete(value);
+        else next.add(value);
+        return next;
+      });
+    }, []);
+
+    const renderPane = (
+      paneId: string,
+      paneLabel: string,
+      items: RecursicaTransferListItem[],
+      allItems: RecursicaTransferListItem[],
+      selected: Set<string>,
+      onToggle: (value: string) => void,
+      search: string,
+      onSearchChange: (value: string) => void,
+    ) => {
+      const { groups, ungrouped } = groupItems(items);
+      const groupNames = Object.keys(groups).sort();
+      const countText =
+        selected.size > 0
+          ? `${selected.size} / ${allItems.length}`
+          : `${allItems.length}`;
+
+      return (
+        <div className={styles.pane} data-pane={paneId}>
+          <div className={styles.paneHeader}>
+            <span>{paneLabel}</span>
+            <Badge>{countText}</Badge>
+          </div>
+
+          {searchable && (
+            <div className={styles.paneSearch}>
+              <TextField
+                value={search}
+                onChange={(e) => onSearchChange(e.currentTarget.value)}
+                placeholder={searchPlaceholder}
+                disabled={disabled}
+                aria-label={`Filter ${paneLabel.toLowerCase()}`}
+              />
+            </div>
+          )}
+
+          <div className={styles.paneList}>
+            {items.length === 0 && (
+              <div className={styles.emptyState}>No items</div>
+            )}
+
+            {ungrouped.length > 0 && (
+              <CheckboxGroup>
+                {ungrouped.map((item) => (
+                  <Checkbox
+                    key={item.value}
+                    id={`${id}-${paneId}-${item.value}`}
+                    label={item.label}
+                    checked={selected.has(item.value)}
+                    onChange={() => onToggle(item.value)}
+                    disabled={disabled}
+                  />
+                ))}
+              </CheckboxGroup>
+            )}
+
+            {groupNames.map((groupName) => (
+              <CheckboxGroup
+                key={groupName}
+                label={groupName}
+                labelSize="small"
+              >
+                {groups[groupName].map((item) => (
+                  <Checkbox
+                    key={item.value}
+                    id={`${id}-${paneId}-${item.value}`}
+                    label={item.label}
+                    checked={selected.has(item.value)}
+                    onChange={() => onToggle(item.value)}
+                    disabled={disabled}
+                  />
+                ))}
+              </CheckboxGroup>
+            ))}
+          </div>
+        </div>
+      );
+    };
+
+    const wrapperClass = className
+      ? `${styles.layoutOverride} ${className}`
+      : styles.layoutOverride;
+
+    return (
+      <WithReadOnlyWrapper
+        ref={ref}
+        formLayout={formLayout}
+        labelSize={labelSize}
+        labelAlignment={labelAlignment}
+        labelOptionalText={labelOptionalText}
+        labelWithEditIcon={labelWithEditIcon}
+        labelActionArea={labelActionArea}
+        onLabelEditClick={onLabelEditClick}
+        label={label}
+        assistiveText={assistiveText}
+        description={description}
+        helperText={helperText}
+        assistiveWithIcon={assistiveWithIcon}
+        error={error}
+        required={required}
+        id={id}
+        className={wrapperClass}
+        style={style}
+        overStyled={overStyled as true}
+        readOnly={readOnly}
+        readOnlyComponent={readOnlyComponent}
+        emptyValueComponent={emptyValueComponent}
+        readOnlyType="text"
+        readOnlyValue={effectiveData[1].map((item) => item.label)}
+        readOnlyNativeProps={props}
+        activeComponent={
+          <div
+            {...(sanitizedProps as Record<string, unknown>)}
+            className={styles.root}
+            data-disabled={disabled ? "true" : undefined}
+            data-error={error ? "true" : undefined}
+          >
+            <div className={styles.panes}>
+              {renderPane(
+                "source",
+                sourceLabel,
+                filteredSource,
+                effectiveData[0],
+                sourceSelected,
+                toggleSourceItem,
+                sourceSearch,
+                setSourceSearch,
+              )}
+
+              <div className={styles.transferColumn}>
+                <Button
+                  variant="outline"
+                  size="small"
+                  icon={<ChevronsIcon direction="right" />}
+                  aria-label={`Move all to ${targetLabel}`}
+                  disabled={disabled || effectiveData[0].length === 0}
+                  onClick={transferAllToTarget}
+                />
+                <Button
+                  variant="outline"
+                  size="small"
+                  icon={<ChevronIcon direction="right" />}
+                  aria-label={`Move selected to ${targetLabel}`}
+                  disabled={disabled || sourceSelected.size === 0}
+                  onClick={transferToTarget}
+                />
+                <Button
+                  variant="outline"
+                  size="small"
+                  icon={<ChevronIcon direction="left" />}
+                  aria-label={`Move selected to ${sourceLabel}`}
+                  disabled={disabled || targetSelected.size === 0}
+                  onClick={transferToSource}
+                />
+                <Button
+                  variant="outline"
+                  size="small"
+                  icon={<ChevronsIcon direction="left" />}
+                  aria-label={`Move all to ${sourceLabel}`}
+                  disabled={disabled || effectiveData[1].length === 0}
+                  onClick={transferAllToSource}
+                />
+              </div>
+
+              {renderPane(
+                "target",
+                targetLabel,
+                filteredTarget,
+                effectiveData[1],
+                targetSelected,
+                toggleTargetItem,
+                targetSearch,
+                setTargetSearch,
+              )}
+            </div>
+          </div>
+        }
+      />
+    );
+  },
+);
+
+TransferList.displayName = "TransferList";

package/src/components/TransferList/USAGE.md

@@ -0,0 +1,77 @@
+# TransferList - Usage Guide
+
+This document describes how to integrate and use the `TransferList` component in your projects
+using `@recursica/adapter-mantine-v8`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { TransferList } from "@recursica/adapter-mantine-v8";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { TransferList } from "@recursica/adapter-mantine-v8";
+
+export default function Demo() {
+  return (
+    <TransferList
+      label="Assign users"
+      sourceLabel="Available"
+      targetLabel="Selected"
+      defaultData={[
+        [
+          { value: "1", label: "Item 1" },
+          { value: "2", label: "Item 2" },
+        ],
+        [{ value: "3", label: "Item 3" }],
+      ]}
+      onChange={(data) => console.log(data)}
+    />
+  );
+}
+```
+
+Items sharing a `group` field render under a `CheckboxGroup` heading in their pane:
+
+```tsx
+<TransferList
+  label="Assign ingredients"
+  defaultData={[
+    [
+      { value: "apple", label: "Apple", group: "Fruit" },
+      { value: "carrot", label: "Carrot", group: "Vegetable" },
+      { value: "eagle", label: "Eagle" }, // ungrouped, renders above the groups
+    ],
+    [],
+  ]}
+/>
+```
+
+Pass `data` instead of `defaultData` to control the selection yourself.
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/adapter-mantine-v8` package adhere strictly to design
+system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **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.
+> - **Form control layout**: `label`, `formLayout` (`stacked`/`side-by-side`), `required`,
+>   `assistiveText`/`description`/`helperText`, and `error` all route through the shared
+>   `FormControlWrapper`, same as every other form control.

package/src/components/Tree/IMPLEMENTATION_NOTES.md

@@ -0,0 +1,48 @@
+# Tree Implementation Notes
+
+- **Fully custom `renderNode`, not Mantine's default row markup.** Mantine's `Tree` renders each node as `<li {...getStyles("node")}>{renderNode ? renderNode(payload) : <div {...elementProps}>{node.label}</div>}{subtree}</li>`. We always pass a custom `renderNode` (never rely on the fallback) so every visual property — box model, colors, typography, the expand chevron — is fully token-driven rather than inheriting Mantine's own `Tree.module.css` defaults (which include Mantine's own light/dark `[data-selected]` background using its own gray palette).
+
+- **`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.
+
+- **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.
+
+- **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 adapter-mantine-v8 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.
+
+- **Chevron `Button` could still steal DOM focus despite `tabIndex={-1}` (Matt Massey, 2026-08-24), caught via a live browser console warning.** The embedded chevron `Button`'s `tabIndex={-1}`/`aria-hidden` combination (added when the chevron became a real `Button` — see above) only removes it from the sequential tab order; it doesn't stop a native `<button>` from receiving DOM focus on a direct mouse click, which browsers still do regardless of `tabIndex`. Since the button also has `aria-hidden="true"`, a click on it left an aria-hidden element holding focus — flagged by Chrome as "Blocked aria-hidden on an element because its descendant retained focus." Fixed with `onMouseDown={(event) => event.preventDefault()}` on the same `Button`: this suppresses the browser's default click-focuses-the-target behavior without affecting the `onClick` handler (`click` still fires normally on mouseup). Same fix applied to mui-adapter's `ExpandToggleButton`.