@recursica/mui-adapter 0.18.1 → 0.19.0

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

@@ -1,43 +1,208 @@
-/* recursica-ignore: --recursica_ui-kit_components_tree_properties_border-radius */
-/* recursica-ignore: --recursica_ui-kit_components_tree_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_tree_properties_button-node-gap */
-/* recursica-ignore: --recursica_ui-kit_components_tree_properties_horizontal-padding */
-/* recursica-ignore: --recursica_ui-kit_components_tree_properties_indent */
-/* recursica-ignore: --recursica_ui-kit_components_tree_properties_item-gap */
-/* recursica-ignore: --recursica_ui-kit_components_tree_properties_max-width */
-/* recursica-ignore: --recursica_ui-kit_components_tree_properties_selected-text_font-family */
-/* recursica-ignore: --recursica_ui-kit_components_tree_properties_selected-text_font-size */
-/* recursica-ignore: --recursica_ui-kit_components_tree_properties_selected-text_font-style */
-/* recursica-ignore: --recursica_ui-kit_components_tree_properties_selected-text_font-weight */
-/* recursica-ignore: --recursica_ui-kit_components_tree_properties_selected-text_letter-spacing */
-/* recursica-ignore: --recursica_ui-kit_components_tree_properties_selected-text_line-height */
-/* recursica-ignore: --recursica_ui-kit_components_tree_properties_selected-text_text-decoration */
-/* recursica-ignore: --recursica_ui-kit_components_tree_properties_selected-text_text-transform */
-/* recursica-ignore: --recursica_ui-kit_components_tree_properties_unselected-text_font-family */
-/* recursica-ignore: --recursica_ui-kit_components_tree_properties_unselected-text_font-size */
-/* recursica-ignore: --recursica_ui-kit_components_tree_properties_unselected-text_font-style */
-/* recursica-ignore: --recursica_ui-kit_components_tree_properties_unselected-text_font-weight */
-/* recursica-ignore: --recursica_ui-kit_components_tree_properties_unselected-text_letter-spacing */
-/* recursica-ignore: --recursica_ui-kit_components_tree_properties_unselected-text_line-height */
-/* recursica-ignore: --recursica_ui-kit_components_tree_properties_unselected-text_text-decoration */
-/* recursica-ignore: --recursica_ui-kit_components_tree_properties_unselected-text_text-transform */
-/* recursica-ignore: --recursica_ui-kit_components_tree_properties_vertical-padding */
-/* recursica-ignore: --recursica_ui-kit_components_tree_properties_colors_hover-background */
-/* recursica-ignore: --recursica_ui-kit_components_tree_properties_colors_hover-border-color */
-/* recursica-ignore: --recursica_ui-kit_components_tree_properties_colors_hover-text */
-/* recursica-ignore: --recursica_ui-kit_components_tree_properties_colors_selected-background */
-/* recursica-ignore: --recursica_ui-kit_components_tree_properties_colors_selected-border-color */
-/* recursica-ignore: --recursica_ui-kit_components_tree_properties_colors_selected-text */
-/* recursica-ignore: --recursica_ui-kit_components_tree_properties_colors_unselected-text */
+/* HARDCODED VALUES:
+ * - list-style/margin/padding resets on .root/.subtree/.node: layout resets, no corresponding
+ *   design tokens (structural, not visual design values).
+ * - .chevron size (1em) and rotation: no dedicated icon-size/icon-color token exists for Tree;
+ *   the glyph is drawn with `currentColor` so it always tracks the row's already-tokened text
+ *   color, and sized relative to the row's own font-size.
+ * - Hover overlay uses the generic --recursica_brand_states_hover_* tokens (same technique as
+ *   Menu/Accordion/Button): Tree has no component-specific hover tokens of its own.
+ * - .row's padding-left keeps MUI's own depth-based indentation formula (base + indent * depth)
+ *   but substitutes our own horizontal-padding token as the base instead of MUI's theme spacing.
+ */
 
 .root {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  outline: 0;
+  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);
+
+  /* MUI sets this as an inline style on the root <ul> (see useTreeViewRootProps in
+     @mui/x-tree-view). Override with !important to reliably beat it regardless of stylesheet
+     injection order (same category of override as mantine-adapter's --level-offset, itself
+     modeled on Timeline's --mantine-spacing-xl / --tl-line-width). */
+  --TreeView-itemChildrenIndentation: var(
+    --recursica_ui-kit_components_tree_properties_indent
+  ) !important;
+}
+
+.subtree {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  display: flex;
+  flex-direction: column;
+  gap: var(--recursica_ui-kit_components_tree_properties_item-gap);
+}
+
+.node {
+  list-style: none;
+}
+
+.row {
+  position: relative;
   box-sizing: border-box;
-  font-family: sans-serif;
-  padding: 24px;
-  border: 1px dashed #ccc;
-  border-radius: 8px;
-  color: #666;
-  text-align: center;
-  font-weight: 500;
-  background-color: #fafafa;
+  display: flex;
+  align-items: center;
+  width: 100%;
+  cursor: pointer;
+  gap: var(--recursica_ui-kit_components_tree_properties_button-node-gap);
+
+  padding-top: var(
+    --recursica_ui-kit_components_tree_properties_vertical-padding
+  );
+  padding-bottom: var(
+    --recursica_ui-kit_components_tree_properties_vertical-padding
+  );
+  padding-right: var(
+    --recursica_ui-kit_components_tree_properties_horizontal-padding
+  );
+  padding-left: calc(
+    var(--recursica_ui-kit_components_tree_properties_horizontal-padding) +
+      var(--TreeView-itemChildrenIndentation, 0px) *
+      var(--TreeView-itemDepth, 0)
+  );
+
+  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
+  );
+}
+
+/* Neutralize MUI's own hover/focused background-color changes (see TreeItemContent's defaults
+   in @mui/x-tree-view) so only the Recursica hover overlay below controls the hover look. */
+.row:hover,
+.row[data-focused] {
+  background-color: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_unselected_properties_colors_background-color
+  );
+}
+
+/* Hover overlay via ::after pseudo-element (same technique as Menu/Accordion) */
+.row::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+  z-index: 0;
+  pointer-events: none;
+  background-color: var(--recursica_brand_states_hover_color);
+  opacity: 0;
+  transition: opacity 150ms ease;
+}
+.row:hover::after {
+  opacity: var(--recursica_brand_states_hover_opacity);
+}
+
+/* Selected row state — written after the hover/focus resets above so it wins the equal-
+   specificity tie via source order, including when hovered/focused while selected. */
+.row[data-selected],
+.row[data-selected]:hover,
+.row[data-selected][data-focused] {
+  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
+  );
+}
+
+.row[data-disabled] {
+  opacity: var(--recursica_brand_states_disabled);
+  cursor: auto;
+}
+
+.iconContainer {
+  position: relative;
+  z-index: 1;
+  width: 1em;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  color: inherit;
+}
+
+.chevron {
+  transition: transform 150ms ease;
+}
+.chevronExpanded {
+  transform: rotate(90deg);
+}
+
+.label {
+  position: relative;
+  z-index: 1;
+  color: inherit;
+  font: inherit;
+  letter-spacing: inherit;
+  text-decoration: inherit;
+  text-transform: inherit;
 }

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

@@ -1,14 +1,91 @@
 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: "Components/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 \`@mui/x-tree-view\`'s \`RichTreeView\` with a fully custom item 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;
-type Story = StoryObj<typeof Tree>;
 
-export const ComingSoon: Story = {
-  args: {},
+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
+    />
+  ),
+};
+
+/** 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.tsx

@@ -1,24 +1,225 @@
 import React, { forwardRef } from "react";
-import { type RecursicaOverStyled } from "../../utils/filterStylingProps";
+import { RichTreeView } from "@mui/x-tree-view/RichTreeView";
+import {
+  useTreeItem,
+  type UseTreeItemParameters,
+} from "@mui/x-tree-view/useTreeItem";
+import { useTreeItemModel } from "@mui/x-tree-view/hooks";
+import { TreeItemProvider } from "@mui/x-tree-view/TreeItemProvider";
+import {
+  TreeItemRoot,
+  TreeItemContent,
+  TreeItemIconContainer,
+  TreeItemGroupTransition,
+  TreeItemLabel,
+} from "@mui/x-tree-view/TreeItem";
+import { TreeItemIcon } from "@mui/x-tree-view/TreeItemIcon";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import {
+  type RecursicaTreeProps,
+  type RecursicaTreeNode,
+} from "@recursica/adapter-common";
 import styles from "./Tree.module.css";
 
-export interface TreeProps extends React.ComponentPropsWithoutRef<"div"> {
-  overStyled?: boolean;
+export type TreeProps = RecursicaOverStyled<
+  RecursicaTreeProps & Omit<React.ComponentPropsWithoutRef<"ul">, "children">
+>;
+
+function collectAllValues(nodes: RecursicaTreeNode[]): string[] {
+  const values: string[] = [];
+  const walk = (list: RecursicaTreeNode[]) => {
+    list.forEach((node) => {
+      values.push(node.value);
+      if (node.children) walk(node.children);
+    });
+  };
+  walk(nodes);
+  return values;
 }
 
-/**
- * Placeholder component for Tree (Coming Soon).
- */
-export const Tree = forwardRef<HTMLDivElement, RecursicaOverStyled<TreeProps>>(
-  function Tree({ overStyled: _overStyled = false, className, ...rest }, ref) {
-    void _overStyled;
-    const finalClass = className ? `${styles.root} ${className}` : styles.root;
+/** Simple chevron glyph; MUI renders a different component for expanded vs collapsed rather
+ * than one rotating icon (unlike Mantine's `[data-expanded]` approach), so collapseIcon carries
+ * its own rotated variant. Both use `currentColor` — no dedicated icon-color token exists. */
+function ExpandGlyph() {
+  return (
+    <svg
+      className={styles.chevron}
+      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>
+  );
+}
+function CollapseGlyph() {
+  return (
+    <svg
+      className={`${styles.chevron} ${styles.chevronExpanded}`}
+      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>
+  );
+}
+/** Rendered for leaf items so the icon-container box (and therefore row alignment) stays
+ * consistent whether or not a row has an expand chevron, matching the mantine-adapter
+ * implementation's always-present `.expandIcon` span. */
+function EndGlyph() {
+  return <span aria-hidden="true" />;
+}
+
+interface CustomTreeItemProps extends UseTreeItemParameters {
+  className?: string;
+}
+
+/** Custom `slots.item` renderer. Mirrors the mantine-adapter's `renderNode`: every visual
+ * property comes from Tree.module.css rather than @mui/x-tree-view's own default TreeItem
+ * styles. `useTreeItemModel` retrieves the *original* `RecursicaTreeNode` (with its real
+ * `React.ReactNode` label) — `getItemLabel` on `RichTreeView` only ever sees a coerced string
+ * (required for its internal a11y/typeahead search), so this is the only way to render rich
+ * (non-string) labels. See IMPLEMENTATION_NOTES.md. */
+const CustomTreeItem = forwardRef<HTMLLIElement, CustomTreeItemProps>(
+  function CustomTreeItem(
+    { id, itemId, label, disabled, children, className, ...rest },
+    ref,
+  ) {
+    const {
+      getContextProviderProps,
+      getRootProps,
+      getContentProps,
+      getIconContainerProps,
+      getLabelProps,
+      getGroupTransitionProps,
+      status,
+    } = useTreeItem({ id, itemId, children, label, disabled, rootRef: ref });
+
+    const item = useTreeItemModel<RecursicaTreeNode>(itemId);
+
     return (
-      <div ref={ref} className={finalClass} {...rest}>
-        Tree (Coming Soon)
-      </div>
+      <TreeItemProvider {...getContextProviderProps()}>
+        <TreeItemRoot
+          {...getRootProps({
+            ...rest,
+            className: `${styles.node} ${className ?? ""}`,
+          })}
+        >
+          <TreeItemContent
+            {...getContentProps({ className: styles.row })}
+            status={status}
+          >
+            <TreeItemIconContainer
+              {...getIconContainerProps({ className: styles.iconContainer })}
+            >
+              <TreeItemIcon status={status} />
+            </TreeItemIconContainer>
+            <TreeItemLabel {...getLabelProps({ className: styles.label })}>
+              {item?.label ?? label}
+            </TreeItemLabel>
+          </TreeItemContent>
+          {children && (
+            <TreeItemGroupTransition
+              {...getGroupTransitionProps({ className: styles.subtree })}
+            />
+          )}
+        </TreeItemRoot>
+      </TreeItemProvider>
     );
   },
 );
 
+/**
+ * Recursively renders hierarchical `data` as an expandable/selectable tree.
+ *
+ * **Recursica Abstract:**
+ * Wraps `@mui/x-tree-view`'s `RichTreeView` with a fully custom item 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 MUI's defaults.
+ */
+export const Tree = forwardRef<HTMLUListElement, TreeProps>(function Tree(
+  {
+    overStyled = false,
+    data,
+    initialExpandedValues,
+    initialSelectedValues,
+    multiple = false,
+    expandOnClick = true,
+    selectOnClick = true,
+    onNodeExpand,
+    onNodeCollapse,
+    onSelectedChange,
+    ...rest
+  },
+  ref,
+) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+
+  const defaultExpandedItems =
+    initialExpandedValues === "*"
+      ? collectAllValues(data)
+      : initialExpandedValues;
+
+  const classNameProp = (sanitizedProps as Record<string, unknown>)
+    .className as string | undefined;
+  const rootClass = classNameProp
+    ? `${styles.root} ${classNameProp}`
+    : styles.root;
+
+  return (
+    <RichTreeView
+      ref={ref}
+      items={data}
+      getItemId={(item: RecursicaTreeNode) => item.value}
+      getItemLabel={(item: RecursicaTreeNode) =>
+        typeof item.label === "string" ? item.label : item.value
+      }
+      defaultExpandedItems={defaultExpandedItems}
+      defaultSelectedItems={
+        multiple ? (initialSelectedValues ?? []) : initialSelectedValues?.[0]
+      }
+      multiSelect={multiple}
+      // MUI has no separate expandOnClick/selectOnClick toggles; `expansionTrigger` controls
+      // whether clicking the row content (vs only the icon container) also expands/collapses.
+      // `selectOnClick={false}` has no exact MUI equivalent (selection always follows content
+      // clicks unless disabled entirely) — see IMPLEMENTATION_NOTES.md.
+      expansionTrigger={expandOnClick ? "content" : "iconContainer"}
+      disableSelection={!selectOnClick}
+      onItemExpansionToggle={(_event, itemId, isExpanded) => {
+        if (isExpanded) onNodeExpand?.(itemId);
+        else onNodeCollapse?.(itemId);
+      }}
+      onSelectedItemsChange={(_event, itemIds) => {
+        onSelectedChange?.(
+          Array.isArray(itemIds) ? itemIds : itemIds ? [itemIds] : [],
+        );
+      }}
+      slots={{
+        expandIcon: ExpandGlyph,
+        collapseIcon: CollapseGlyph,
+        endIcon: EndGlyph,
+        item: CustomTreeItem,
+      }}
+      classes={{ root: rootClass }}
+      {...(sanitizedProps as unknown as Record<string, unknown>)}
+    />
+  );
+});
+
 Tree.displayName = "Tree";

package/src/components/Tree/USAGE.md

@@ -2,6 +2,9 @@
 
 This document describes how to integrate and use the `Tree` component in your projects using `@recursica/mui-adapter`.
 
+> [!IMPORTANT]
+> This component requires `@mui/x-tree-view` (MIT-licensed, free community edition) as a peer dependency, in addition to `@mui/material`. Install it alongside your other MUI packages: `npm install @mui/x-tree-view`.
+
 ---
 
 ## 1. Import Reference
@@ -25,22 +28,56 @@ export default function Demo() {
         {
           value: "1",
           label: "Root",
-          children: [{ value: "2", label: "Child" }],
+          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).
+- `expandOnClick` (default `true`) controls whether clicking a row's content also expands/collapses it (vs. only clicking its chevron); `selectOnClick` (default `true`) controls whether selection is enabled at all. See **Known Constraints** below for how these map onto the underlying library.
+
 ---
 
-## 3. Design System Integration
+## 4. Design System Integration
 
 All Recursica components in the `@recursica/mui-adapter` package adhere strictly to design system spacing, scaling, and behavior patterns.
 
 > [!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.
+
+---
+
+## 5. Known Constraints
+
+- **`expandOnClick`/`selectOnClick` are approximated, not exact.** `@mui/x-tree-view` doesn't expose the same two independent toggles Mantine's `Tree` does. `expandOnClick` maps to MUI's `expansionTrigger` (`"content"` vs `"iconContainer"`); `selectOnClick={false}` maps to `disableSelection` (which disables selection entirely, rather than only suppressing it on a content click while leaving some other path to select). See `IMPLEMENTATION_NOTES.md`.
+- No checkbox/multi-check styling is exposed — `@mui/x-tree-view` supports checkbox selection, 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 `RecursicaTreeNode` has no `disabled` field either.