@recursica/adapter-mantine-v8 1.0.0

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

@@ -0,0 +1,232 @@
+/* Brand-layer exemptions (recursica-allow-brand) — see recursica-token-analyzer README.md.
+ * Global hover/focus/disabled state tokens (recursica_variables_scoped.css header, 'Hover & Focus states' / 'Disabled state' — implicit rule for every interactive element; components must not define their own per-component treatment).
+ *   recursica-allow-brand: --recursica_brand_states_disabled
+ *   recursica-allow-brand: --recursica_brand_states_focus_blur
+ *   recursica-allow-brand: --recursica_brand_states_focus_border-size
+ *   recursica-allow-brand: --recursica_brand_states_focus_color
+ *   recursica-allow-brand: --recursica_brand_states_focus_margin
+ *   recursica-allow-brand: --recursica_brand_states_hover_color
+ *   recursica-allow-brand: --recursica_brand_states_hover_opacity
+ */
+
+/* HARDCODED VALUES:
+ * - list-style/margin/padding resets on .root/.subtree: layout resets, no corresponding
+ *   design tokens (structural, not visual design values).
+ * - .expandGlyph's rotation transition (150ms ease): no dedicated timing token exists for Tree;
+ *   the glyph itself is sized/colored entirely by Button's own "text"/"small" tokens now, not a
+ *   hand-drawn size/color like the previous plain-SVG implementation.
+ * - Hover overlay uses the generic --recursica_brand_states_hover_* tokens (same technique as
+ *   Menu/Accordion/Button): Tree has no component-specific hover tokens of its own.
+ *
+ * NOTE: the row's box model (padding/border/font/color/background) lives entirely on `.label`,
+ * not `.row` — the highlighted "chip" (hover/selected/focus) covers only the label, never the
+ * expand button. `.row` itself is a plain flex layout container (indentation + button-node-gap).
+ */
+
+.root {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  max-width: var(--recursica_ui-kit_components_tree_properties_max-width);
+  display: flex;
+  flex-direction: column;
+  gap: var(--recursica_ui-kit_components_tree_properties_item-gap);
+
+  /* Mantine computes each node's --label-offset (per-level indent) from --level-offset via its
+     own internal vars resolver (same category of override as Timeline's --mantine-spacing-xl /
+     --tl-line-width). Use !important to reliably beat Mantine's own generated rule. */
+  --level-offset: var(
+    --recursica_ui-kit_components_tree_properties_indent
+  ) !important;
+}
+
+/* Whole-tree `disabled` (no per-node concept — see RecursicaTreeProps.ts). `pointer-events: none`
+   blocks every mouse interaction tree-wide in one rule (row clicks, chevron clicks); keyboard is
+   separately blocked in Tree.tsx, since pointer-events has no effect on Tab/Enter/Space/arrows.
+   Uses the generic disabled opacity token, same convention as every other disabled component in
+   the design system (no tree-specific disabled token exists). */
+.root[data-disabled] {
+  opacity: var(--recursica_brand_states_disabled);
+  pointer-events: none;
+}
+
+.subtree {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  display: flex;
+  flex-direction: column;
+  gap: var(--recursica_ui-kit_components_tree_properties_item-gap);
+}
+
+.node {
+  /* Mantine's own base class already resets margin/padding/list-style and sets cursor:pointer
+     on this <li>; it also holds the subtree as a second child, so all node-level visual styling
+     (box model, colors, typography) lives on .label instead, not here. */
+  position: relative;
+}
+
+/* Mantine's roving-tabindex keyboard navigation (arrow up/down moves focus between rows, left/
+   right expand/collapse, matching the WAI-ARIA treeitem pattern) already works out of the box —
+   but with no visible indicator, it looked broken. DOM focus lands on this <li> (.node), not the
+   visible row box, so the ring is drawn on .label instead — the "node" content area, deliberately
+   excluding the expand Button, which never shows a focus state of its own (it's not independently
+   focusable at all: tabIndex={-1}). */
+.node:focus-visible {
+  outline: none;
+}
+/* `> .row` (child combinator), not a plain descendant selector: a node's own `.row` is always a
+   direct child of its `.node` <li>, while every descendant node's `.row` (inside the nested
+   `.subtree` <ul>) is not — without the `>`, focusing a parent node drew the ring on every
+   expanded descendant's label too, since they're all still descendants of the focused `.node`. */
+.node:focus-visible > .row .label {
+  box-shadow:
+    0 0 0 var(--recursica_brand_states_focus_border-size)
+      var(--recursica_brand_states_focus_color),
+    0 0 var(--recursica_brand_states_focus_blur)
+      var(--recursica_brand_states_focus_margin)
+      var(--recursica_brand_states_focus_color);
+}
+
+.row {
+  position: relative;
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  cursor: pointer;
+  margin-left: var(--label-offset, 0px);
+  gap: var(--recursica_ui-kit_components_tree_properties_button-node-gap);
+}
+
+/* The expand Button is always rendered (even for leaf nodes, which have nothing to toggle) so
+   every row reserves identical layout space — hidden via visibility (not display) on leaf rows so
+   the label stays aligned across the whole tree without duplicating Button's own size tokens. */
+.expandButton {
+  position: relative;
+  z-index: 1;
+  flex-shrink: 0;
+}
+.row:not([data-has-children]) .expandButton {
+  visibility: hidden;
+}
+
+.expandGlyph {
+  color: inherit;
+}
+.row[data-has-children] .expandGlyph {
+  transition: transform 150ms ease;
+}
+.row[data-expanded] .expandGlyph {
+  transform: rotate(90deg);
+}
+
+.label {
+  position: relative;
+  z-index: 1;
+  /* Sized to its own content, not stretched to fill the row's remaining width — the
+     hover/selected/focus "chip" should cover just the label, not the full row width. */
+  flex: 0 1 auto;
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  padding: var(--recursica_ui-kit_components_tree_properties_vertical-padding)
+    var(--recursica_ui-kit_components_tree_properties_horizontal-padding);
+  border-style: solid; /* HARDCODE: structural border rule; thickness/color are tokened */
+  border-width: var(--recursica_ui-kit_components_tree_properties_border-size);
+  border-radius: var(
+    --recursica_ui-kit_components_tree_properties_border-radius
+  );
+
+  font-family: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_unselected_properties_text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_unselected_properties_text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_unselected_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_unselected_properties_text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_unselected_properties_text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_unselected_properties_text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_unselected_properties_text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_unselected_properties_text_text-transform
+  );
+
+  color: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_unselected_properties_colors_text-color
+  );
+  background-color: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_unselected_properties_colors_background-color
+  );
+  border-color: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_unselected_properties_colors_border-color
+  );
+}
+
+/* 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: -1;
+  pointer-events: none;
+  background-color: var(--recursica_brand_states_hover_color);
+  opacity: 0;
+  transition: opacity 150ms ease;
+}
+.row:hover .label::after,
+.row[data-hovered] .label::after {
+  opacity: var(--recursica_brand_states_hover_opacity);
+}
+
+.label[data-selected] {
+  font-family: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_selected_properties_text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_selected_properties_text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_selected_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_selected_properties_text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_selected_properties_text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_selected_properties_text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_selected_properties_text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_selected_properties_text_text-transform
+  );
+
+  color: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_selected_properties_colors_text-color
+  );
+  background-color: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_selected_properties_colors_background-color
+  );
+  border-color: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_selected_properties_colors_border-color
+  );
+}

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

@@ -0,0 +1,104 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Tree } from "./Tree";
+import { Layer, type RecursicaTreeNode } from "@recursica/adapter-common";
+
+const sampleData: RecursicaTreeNode[] = [
+  {
+    value: "documents",
+    label: "Documents",
+    children: [
+      { value: "documents/resume.pdf", label: "resume.pdf" },
+      { value: "documents/cover-letter.docx", label: "cover-letter.docx" },
+      {
+        value: "documents/taxes",
+        label: "Taxes",
+        children: [
+          { value: "documents/taxes/2023.pdf", label: "2023.pdf" },
+          { value: "documents/taxes/2024.pdf", label: "2024.pdf" },
+        ],
+      },
+    ],
+  },
+  {
+    value: "photos",
+    label: "Photos",
+    children: [
+      { value: "photos/vacation.jpg", label: "vacation.jpg" },
+      { value: "photos/family.jpg", label: "family.jpg" },
+    ],
+  },
+  { value: "readme.md", label: "readme.md" },
+];
+
+const meta: Meta<typeof Tree> = {
+  title: "UI-Kit/Tree",
+  component: Tree,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The \`Tree\` component renders hierarchical \`data\` as an expandable/selectable tree, wrapping \`@mantine/core\`'s \`Tree\` with a fully custom node renderer so every visual property (row box model, selected/unselected colors and typography, indent, item spacing) comes from Recursica's \`tree\` design tokens.
+
+Each node needs a unique \`value\` and a \`label\`; a \`children\` array (even empty) makes a node expandable.
+        `,
+      },
+    },
+  },
+};
+
+export default meta;
+
+export const Default: StoryObj<typeof Tree> = {
+  render: () => (
+    <Tree data={sampleData} initialExpandedValues={["documents"]} />
+  ),
+};
+
+export const AllExpanded: StoryObj<typeof Tree> = {
+  render: () => <Tree data={sampleData} initialExpandedValues="*" />,
+};
+
+export const PreSelected: StoryObj<typeof Tree> = {
+  render: () => (
+    <Tree
+      data={sampleData}
+      initialExpandedValues={["documents"]}
+      initialSelectedValues={["documents/resume.pdf"]}
+    />
+  ),
+};
+
+export const MultipleSelection: StoryObj<typeof Tree> = {
+  render: () => (
+    <Tree
+      data={sampleData}
+      initialExpandedValues="*"
+      initialSelectedValues={["documents/resume.pdf", "photos/vacation.jpg"]}
+      multiple
+    />
+  ),
+};
+
+/** 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> = {
+  render: () => (
+    <Layer layer={1} style={{ padding: "24px" }}>
+      <Tree data={sampleData} initialExpandedValues={["documents"]} />
+    </Layer>
+  ),
+};

package/src/components/Tree/Tree.test.tsx

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

package/src/components/Tree/Tree.tsx

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

package/src/components/Tree/USAGE.md

@@ -0,0 +1,96 @@
+# Tree - Usage Guide
+
+This document describes how to integrate and use the `Tree` component in your projects using `@recursica/adapter-mantine-v8`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Tree } from "@recursica/adapter-mantine-v8";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Tree } from "@recursica/adapter-mantine-v8";
+
+export default function Demo() {
+  return (
+    <Tree
+      data={[
+        {
+          value: "1",
+          label: "Root",
+          children: [
+            { value: "1.1", label: "Child A" },
+            { value: "1.2", label: "Child B" },
+          ],
+        },
+        { value: "2", label: "Sibling" },
+      ]}
+    />
+  );
+}
+```
+
+Each node needs a unique `value` and a `label`. Any node with a `children` array (even an empty one) renders an expand/collapse chevron.
+
+---
+
+## 3. Controlled Selection / Expansion
+
+```tsx
+<Tree
+  data={data}
+  initialExpandedValues={["1"]}
+  initialSelectedValues={["1.1"]}
+  multiple
+  onSelectedChange={(values) => console.log("selected:", values)}
+  onNodeExpand={(value) => console.log("expanded:", value)}
+  onNodeCollapse={(value) => console.log("collapsed:", value)}
+/>
+```
+
+- `initialExpandedValues` accepts an array of node values, or `"*"` to start with every node expanded.
+- `multiple` allows more than one node to be selected at once (default: single-select).
+
+### Interaction pattern
+
+Expanding/collapsing and selecting are independent, fixed interactions (not prop-configurable):
+
+- Clicking the expand/collapse chevron toggles that node's subtree only — it never selects.
+- Clicking anywhere else on a row selects it — it never toggles expansion.
+- `Enter`/`Space` on a focused node selects it, even if the node has children.
+- `ArrowLeft`/`ArrowRight` expand/collapse the focused node only, without changing selection.
+- `ArrowUp`/`ArrowDown` move focus between rows.
+
+### Disabled
+
+```tsx
+<Tree data={data} initialSelectedValues={["1.1"]} disabled />
+```
+
+`disabled` disables the whole tree — no expand/collapse or select via click or keyboard, dimmed to the standard disabled opacity. A pre-selected node stays visibly selected, just dimmed along with the rest. There's no per-node disabled state (see **Known Constraints** below).
+
+---
+
+## 4. 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.
+
+---
+
+## 5. Known Constraints
+
+- No checkbox/multi-check styling is exposed — the underlying Mantine `Tree` supports a `checked` node state, but Recursica's `tree` design tokens don't yet define a checked visual state, so it isn't part of the Recursica API.
+- No per-node `disabled` state — the Figma UI Kit tokens don't define one, and Mantine's `Tree` data shape has no built-in `disabled` field either.

package/src/components/Tree/index.ts

@@ -0,0 +1 @@
+export * from "./Tree";