@recursica/mui-adapter 0.19.0 → 0.21.0

package/src/components/Tree/Tree.tsx

@@ -4,7 +4,7 @@ import {
   useTreeItem,
   type UseTreeItemParameters,
 } from "@mui/x-tree-view/useTreeItem";
-import { useTreeItemModel } from "@mui/x-tree-view/hooks";
+import { useTreeItemModel, useTreeItemUtils } from "@mui/x-tree-view/hooks";
 import { TreeItemProvider } from "@mui/x-tree-view/TreeItemProvider";
 import {
   TreeItemRoot,
@@ -22,6 +22,7 @@ import {
   type RecursicaTreeProps,
   type RecursicaTreeNode,
 } from "@recursica/adapter-common";
+import { Button } from "../Button/Button";
 import styles from "./Tree.module.css";
 
 export type TreeProps = RecursicaOverStyled<
@@ -40,13 +41,16 @@ function collectAllValues(nodes: RecursicaTreeNode[]): string[] {
   return values;
 }
 
-/** 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() {
+/** Chevron glyph; rendered inside a `Button` below. MUI renders a different component for
+ * expanded vs collapsed rather than one rotating icon (unlike Mantine's `[data-expanded]`
+ * approach), so `rotated` picks the CSS class that applies the rotation. Uses `currentColor` so
+ * it matches Button's own tokened icon color for the "text" variant. */
+function ChevronGlyph({ rotated }: { rotated?: boolean }) {
   return (
     <svg
-      className={styles.chevron}
+      className={
+        rotated ? `${styles.chevron} ${styles.chevronExpanded}` : styles.chevron
+      }
       viewBox="0 0 16 16"
       width="1em"
       height="1em"
@@ -61,29 +65,47 @@ function ExpandGlyph() {
     </svg>
   );
 }
-function CollapseGlyph() {
+
+/** Never independently focusable/tab-stoppable (tabIndex={-1}, aria-hidden) — expand/collapse is
+ * driven by the surrounding `TreeItemIconContainer`'s own click handling (see `CustomTreeItem`),
+ * not by this Button itself, so the row stays the only focusable element and the button never
+ * shows its own focus state. Rendered for every row, including leaf items, so row alignment
+ * stays consistent; `hidden` (visibility, not display) is used for leaf rows instead of omitting
+ * the button, so the layout space is reserved without duplicating Button's own size tokens. */
+function ExpandToggleButton({
+  rotated,
+  hidden,
+}: {
+  rotated?: boolean;
+  hidden?: boolean;
+}) {
   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"
+    <Button
+      overStyled
+      variant="text"
+      size="small"
+      icon={<ChevronGlyph rotated={rotated} />}
+      aria-label="Toggle subtree"
       aria-hidden="true"
-    >
-      <path d="M5 3l5 5-5 5" />
-    </svg>
+      tabIndex={-1}
+      className={
+        hidden
+          ? `${styles.expandButton} ${styles.expandButtonHidden}`
+          : styles.expandButton
+      }
+    />
   );
 }
+function ExpandGlyph() {
+  return <ExpandToggleButton />;
+}
+function CollapseGlyph() {
+  return <ExpandToggleButton rotated />;
+}
 /** 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. */
+ * consistent whether or not a row has an expand chevron. */
 function EndGlyph() {
-  return <span aria-hidden="true" />;
+  return <ExpandToggleButton hidden />;
 }
 
 interface CustomTreeItemProps extends UseTreeItemParameters {
@@ -111,14 +133,43 @@ const CustomTreeItem = forwardRef<HTMLLIElement, CustomTreeItemProps>(
       status,
     } = useTreeItem({ id, itemId, children, label, disabled, rootRef: ref });
 
+    // Exposes the same select/expand actions `useTreeItem`'s internal keyboard-navigation plugin
+    // uses, so we can override just the `Enter` key below without reimplementing selection.
+    const { interactions } = useTreeItemUtils({ itemId, children });
+
     const item = useTreeItemModel<RecursicaTreeNode>(itemId);
 
+    const iconContainerProps = getIconContainerProps({
+      className: styles.iconContainer,
+    });
+
+    // `Enter` selects the focused node, full stop — never expands it, unlike
+    // `@mui/x-tree-view`'s own default (which expands an expandable node on `Enter` and only
+    // falls back to selecting leaf nodes). Setting `defaultMuiPrevented` is the documented
+    // extension point `createRootHandleKeyDown` checks before running its own handling, so this
+    // fully replaces rather than races the built-in behavior. `Space` already selects-only by
+    // default, so it needs no override.
+    const handleRootKeyDown = (
+      event: React.KeyboardEvent<HTMLLIElement> & {
+        defaultMuiPrevented?: boolean;
+      },
+    ) => {
+      if (event.key !== "Enter") return;
+      event.preventDefault();
+      event.defaultMuiPrevented = true;
+      // `handleSelection` only reads modifier keys (shiftKey/ctrlKey/metaKey) off the event and
+      // forwards it on for focus bookkeeping — its `React.MouseEvent` type is narrower than
+      // necessary for what it actually uses, so a KeyboardEvent works fine at runtime here.
+      interactions.handleSelection(event as unknown as React.MouseEvent);
+    };
+
     return (
       <TreeItemProvider {...getContextProviderProps()}>
         <TreeItemRoot
           {...getRootProps({
             ...rest,
             className: `${styles.node} ${className ?? ""}`,
+            onKeyDown: handleRootKeyDown,
           })}
         >
           <TreeItemContent
@@ -126,7 +177,15 @@ const CustomTreeItem = forwardRef<HTMLLIElement, CustomTreeItemProps>(
             status={status}
           >
             <TreeItemIconContainer
-              {...getIconContainerProps({ className: styles.iconContainer })}
+              {...iconContainerProps}
+              // Stops the click from also reaching `TreeItemContent`'s own click handler, which
+              // otherwise selects on *any* click inside it (including the icon container) once
+              // `expansionTrigger` is `"iconContainer"` — the button must expand/collapse
+              // without ever selecting.
+              onClick={(event) => {
+                event.stopPropagation();
+                iconContainerProps.onClick(event);
+              }}
             >
               <TreeItemIcon status={status} />
             </TreeItemIconContainer>
@@ -152,6 +211,11 @@ const CustomTreeItem = forwardRef<HTMLLIElement, CustomTreeItemProps>(
  * 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.
+ *
+ * **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(
   {
@@ -160,8 +224,7 @@ export const Tree = forwardRef<HTMLUListElement, TreeProps>(function Tree(
     initialExpandedValues,
     initialSelectedValues,
     multiple = false,
-    expandOnClick = true,
-    selectOnClick = true,
+    disabled = false,
     onNodeExpand,
     onNodeCollapse,
     onSelectedChange,
@@ -195,12 +258,16 @@ export const Tree = forwardRef<HTMLUListElement, TreeProps>(function Tree(
         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}
+      // Whole-tree `disabled` reuses `@mui/x-tree-view`'s own per-item `isItemDisabled` — marking
+      // every item disabled at once — rather than a bespoke mechanism, since MUI already handles
+      // blocking click/keyboard select/expand and dimming (`.row[data-disabled]` in
+      // Tree.module.css) for disabled items internally.
+      isItemDisabled={disabled ? () => true : undefined}
+      // Fixed, not prop-driven: only the icon container (the chevron button) expands/collapses
+      // on click; clicking anywhere else on the row selects instead. `CustomTreeItem` additionally
+      // stops the icon container's click from also bubbling into the content's own selection
+      // handler — see IMPLEMENTATION_NOTES.md.
+      expansionTrigger="iconContainer"
       onItemExpansionToggle={(_event, itemId, isExpanded) => {
         if (isExpanded) onNodeExpand?.(itemId);
         else onNodeCollapse?.(itemId);

package/src/components/Tree/USAGE.md

@@ -60,7 +60,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` (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.
+
+### 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).
 
 ---
 
@@ -78,6 +95,5 @@ All Recursica components in the `@recursica/mui-adapter` package adhere strictly
 
 ## 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.

package/src/index.ts

@@ -183,5 +183,6 @@ export type {
   RecursicaSliderProps,
   RecursicaTextAreaProps,
   RecursicaTextFieldProps,
+  RecursicaTimePickerProps,
   RecursicaToastProps,
 } from "./components";