@recursica/mantine-adapter 0.36.1 → 0.38.0

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

@@ -1,11 +1,15 @@
 /* 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.
+ * - .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 {
@@ -25,6 +29,16 @@
   ) !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;
@@ -36,11 +50,33 @@
 
 .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. */
+     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;
@@ -49,6 +85,39 @@
   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 */
@@ -93,24 +162,28 @@
   );
 }
 
-/* Hover overlay via ::after pseudo-element (same technique as Menu/Accordion) */
-.row::after {
+/* 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: 0;
+  z-index: -1;
   pointer-events: none;
   background-color: var(--recursica_brand_states_hover_color);
   opacity: 0;
   transition: opacity 150ms ease;
 }
-.row:hover::after,
-.row[data-hovered]::after {
+.row:hover .label::after,
+.row[data-hovered] .label::after {
   opacity: var(--recursica_brand_states_hover_opacity);
 }
 
-.row[data-selected] {
+.label[data-selected] {
   font-family: var(
     --recursica_ui-kit_components_tree_variants_selection-states_selected_properties_text_font-family
   );
@@ -146,32 +219,3 @@
     --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

@@ -80,6 +80,19 @@ export const MultipleSelection: StoryObj<typeof Tree> = {
   ),
 };
 
+/** 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> = {

package/src/components/Tree/Tree.tsx

@@ -5,22 +5,27 @@ import {
   getTreeExpandedState,
   type RenderTreeNodePayload,
 } from "@mantine/core";
+import { useMergedRef } from "@mantine/hooks";
 import {
   filterStylingProps,
   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 `[data-expanded]` in CSS. Uses `currentColor` so it
- * always matches the row's tokened text color — Tree has no dedicated icon-color token. */
+/** 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"
@@ -36,25 +41,56 @@ function ExpandGlyph() {
   );
 }
 
-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>
-  );
+/** 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. 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}
+          onClick={(event) => {
+            event.stopPropagation();
+            if (disabled) return;
+            tree.toggleExpanded(node.value);
+          }}
+        />
+        <span className={styles.label} data-selected={selected || undefined}>
+          {node.label}
+        </span>
+      </div>
+    );
+  };
 }
 
 /**
@@ -64,6 +100,11 @@ function renderTreeNode({
  * 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(
   {
@@ -72,8 +113,7 @@ export const Tree = forwardRef<HTMLUListElement, TreeProps>(function Tree(
     initialExpandedValues,
     initialSelectedValues,
     multiple = false,
-    expandOnClick = true,
-    selectOnClick = true,
+    disabled = false,
     onNodeExpand,
     onNodeCollapse,
     onSelectedChange,
@@ -99,6 +139,53 @@ export const Tree = forwardRef<HTMLUListElement, TreeProps>(function Tree(
     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 classNameProp = (sanitizedProps as Record<string, unknown>)
     .className as string | undefined;
   const rootClass = classNameProp
@@ -107,12 +194,14 @@ export const Tree = forwardRef<HTMLUListElement, TreeProps>(function Tree(
 
   return (
     <MantineTree
-      ref={ref}
+      ref={mergedRef}
       data={data}
       tree={tree}
-      expandOnClick={expandOnClick}
-      selectOnClick={selectOnClick}
-      renderNode={renderTreeNode}
+      expandOnClick={false}
+      selectOnClick={!disabled}
+      expandOnSpace={false}
+      renderNode={createRenderTreeNode(disabled)}
+      data-disabled={disabled || undefined}
       classNames={{
         root: rootClass,
         node: styles.node,

package/src/components/Tree/USAGE.md

@@ -57,7 +57,24 @@ Each node needs a unique `value` and a `label`. Any node with a `children` array
 
 - `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.
+
+### 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).
 
 ---
 

package/src/index.ts

@@ -175,4 +175,5 @@ export type {
   RecursicaSwitchGroupProps,
   RecursicaTextAreaProps,
   RecursicaTextFieldProps,
+  RecursicaTimePickerProps,
 } from "./components";