@recursica/mantine-adapter 0.35.1 → 0.36.0

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

@@ -1,43 +1,177 @@
-/* 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: layout resets, no corresponding
+ *   design tokens (structural, not visual design values).
+ * - .expandIcon size (1em) and rotation transition: 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.
+ */
 
 .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;
+}
+
+.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 row-level visual styling
+     (box model, colors, typography) lives on .row instead, not here. */
+  position: relative;
+}
+
+.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;
+  cursor: pointer;
+  margin-left: var(--label-offset, 0px);
+  gap: var(--recursica_ui-kit_components_tree_properties_button-node-gap);
+  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) */
+.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,
+.row[data-hovered]::after {
+  opacity: var(--recursica_brand_states_hover_opacity);
+}
+
+.row[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
+  );
+}
+
+.expandIcon {
+  position: relative;
+  z-index: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: 1em;
+  height: 1em;
+  color: inherit;
+}
+
+.row[data-has-children] .expandIcon {
+  transition: transform 150ms ease;
+}
+.row[data-expanded] .expandIcon {
+  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 \`@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;
-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,126 @@
-import React, { forwardRef } from "react";
-import { type RecursicaOverStyled } from "../../utils/filterStylingProps";
+import React, { forwardRef, useEffect } from "react";
+import {
+  Tree as MantineTree,
+  useTree,
+  getTreeExpandedState,
+  type RenderTreeNodePayload,
+} from "@mantine/core";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import { type RecursicaTreeProps } 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">
+>;
+
+/** Simple chevron glyph; rotates via `[data-expanded]` in CSS. Uses `currentColor` so it
+ * always matches the row's tokened text color — Tree has no dedicated icon-color token. */
+function ExpandGlyph() {
+  return (
+    <svg
+      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 renderTreeNode({
+  node,
+  hasChildren,
+  expanded,
+  elementProps,
+}: RenderTreeNodePayload) {
+  return (
+    <div
+      {...elementProps}
+      className={styles.row}
+      data-has-children={hasChildren || undefined}
+      data-expanded={hasChildren && expanded ? true : undefined}
+    >
+      <span className={styles.expandIcon} aria-hidden="true">
+        {hasChildren && <ExpandGlyph />}
+      </span>
+      <span className={styles.label}>{node.label}</span>
+    </div>
+  );
 }
 
 /**
- * Placeholder component for Tree (Coming Soon).
+ * 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.
  */
-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;
-    return (
-      <div ref={ref} className={finalClass} {...rest}>
-        Tree (Coming Soon)
-      </div>
-    );
+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 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]);
+
+  const classNameProp = (sanitizedProps as Record<string, unknown>)
+    .className as string | undefined;
+  const rootClass = classNameProp
+    ? `${styles.root} ${classNameProp}`
+    : styles.root;
+
+  return (
+    <MantineTree
+      ref={ref}
+      data={data}
+      tree={tree}
+      expandOnClick={expandOnClick}
+      selectOnClick={selectOnClick}
+      renderNode={renderTreeNode}
+      classNames={{
+        root: rootClass,
+        node: styles.node,
+        subtree: styles.subtree,
+      }}
+      {...(sanitizedProps as unknown as Record<string, unknown>)}
+    />
+  );
+});
 
 Tree.displayName = "Tree";

package/src/components/Tree/USAGE.md

@@ -25,22 +25,55 @@ 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` / `selectOnClick` (both default `true`) control whether clicking a row toggles its expansion and/or selection.
+
 ---
 
-## 3. Design System Integration
+## 4. Design System Integration
 
 All Recursica components in the `@recursica/mantine-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
+
+- 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.