@recursica/adapter-mui-v7 1.0.0

package/src/components/Tree/Tree.tsx

@@ -0,0 +1,298 @@
+import React, { forwardRef } from "react";
+import { RichTreeView } from "@mui/x-tree-view/RichTreeView";
+import {
+  useTreeItem,
+  type UseTreeItemParameters,
+} from "@mui/x-tree-view/useTreeItem";
+import { useTreeItemModel, useTreeItemUtils } 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 { Button } from "../Button/Button";
+import styles from "./Tree.module.css";
+
+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;
+}
+
+/** 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={
+        rotated ? `${styles.chevron} ${styles.chevronExpanded}` : 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>
+  );
+}
+
+/** 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.
+ * `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 on the chevron from
+ * focusing this button) — without this, clicking the chevron leaves the (aria-hidden) button
+ * focused, which browsers now flag as an accessibility violation ("focus must not be hidden from
+ * assistive technology"). */
+function ExpandToggleButton({
+  rotated,
+  hidden,
+}: {
+  rotated?: boolean;
+  hidden?: boolean;
+}) {
+  return (
+    <Button
+      overStyled
+      variant="text"
+      size="small"
+      icon={<ChevronGlyph rotated={rotated} />}
+      aria-label="Toggle subtree"
+      aria-hidden="true"
+      tabIndex={-1}
+      onMouseDown={(event) => event.preventDefault()}
+      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. */
+function EndGlyph() {
+  return <ExpandToggleButton hidden />;
+}
+
+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 });
+
+    // 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
+            {...getContentProps({ className: styles.row })}
+            status={status}
+          >
+            <TreeItemIconContainer
+              {...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>
+            <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.
+ *
+ * **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 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}
+      {...(sanitizedProps as unknown as Record<string, unknown>)}
+      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}
+      // 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);
+      }}
+      onSelectedItemsChange={(_event, itemIds) => {
+        onSelectedChange?.(
+          Array.isArray(itemIds) ? itemIds : itemIds ? [itemIds] : [],
+        );
+      }}
+      slots={{
+        expandIcon: ExpandGlyph,
+        collapseIcon: CollapseGlyph,
+        endIcon: EndGlyph,
+        item: CustomTreeItem,
+      }}
+      classes={{ root: rootClass }}
+    />
+  );
+});
+
+Tree.displayName = "Tree";

package/src/components/Tree/USAGE.md

@@ -0,0 +1,99 @@
+# Tree - Usage Guide
+
+This document describes how to integrate and use the `Tree` component in your projects using `@recursica/adapter-mui-v7`.
+
+> [!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
+
+```tsx
+import { Tree } from "@recursica/adapter-mui-v7";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Tree } from "@recursica/adapter-mui-v7";
+
+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-mui-v7` 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 — `@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/components/Tree/index.ts

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

package/src/components/Typography/TYPOGRAPHY_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,17 @@
+# Typography – Implementation Notes
+
+`Typography` is the shared rendering base for both `Text` and `Heading` in adapter-mui-v7 — anything
+applied here reaches both components.
+
+## `.root` `text-wrap: balance` (Matt Massey, 2026-08-28)
+
+**Decision:** Added `text-wrap: balance` via a new `Typography.module.css` `.root` class, merged
+onto the typography class alongside the caller's own `className`. Since both `Text` and `Heading`
+render through this component, it covers all `order` heading levels (h1–h6) and paragraph text in
+one place.
+
+**Implementation:** UX asked for more evenly balanced multi-line wrapping instead of a ragged last
+line. Not a design token — it's a layout algorithm choice, so it's hardcoded rather than pulled
+from `recursica_variables_scoped.css`. Most effective on short text (headings); Chromium/Firefox
+only balance up to ~6 lines, so long paragraphs silently fall back to normal wrapping past that
+point. No fallback needed — browsers that don't support the value just ignore the declaration.

package/src/components/Typography/Typography.module.css

@@ -0,0 +1,13 @@
+/*
+ * HARDCODED VALUES
+ * - `.root` `text-wrap: balance` — not a design token; a layout algorithm choice requested by
+ *   UX (Matt Massey, 2026-08-28) to even out wrapped line lengths. See TEXT_IMPLEMENTATION_NOTES.md.
+ */
+
+.root {
+  /* HARDCODE: balances wrapped line lengths instead of leaving a ragged short last line. Most
+     effective on short text; browsers cap balancing at ~6 lines, so long paragraphs silently
+     fall back to normal wrapping past that point — no fallback needed, unsupported browsers
+     just ignore the declaration. */
+  text-wrap: balance;
+}

package/src/components/Typography/Typography.test.tsx

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

package/src/components/Typography/Typography.tsx

@@ -0,0 +1,43 @@
+import React, { forwardRef } from "react";
+import {
+  Typography as MuiTypography,
+  type TypographyProps as MuiTypographyProps,
+} from "@mui/material";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Typography.module.css";
+
+export type TypographyProps = RecursicaOverStyled<
+  Omit<MuiTypographyProps, "variant"> & {
+    /**
+     * Internal typography class mapping
+     */
+    typographyClass: string;
+    component?: React.ElementType;
+  }
+>;
+
+export const Typography = forwardRef<HTMLElement, TypographyProps>(
+  function Typography({ typographyClass, overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    const classNameProp = restRecord.className as string | undefined;
+    const finalClass = [typographyClass, styles.root, classNameProp]
+      .filter(Boolean)
+      .join(" ");
+
+    return (
+      <MuiTypography
+        ref={ref}
+        className={finalClass}
+        variant="inherit"
+        {...sanitizedProps}
+      />
+    );
+  },
+);
+
+Typography.displayName = "Typography";

package/src/components/Typography/USAGE.md

@@ -0,0 +1,40 @@
+# Typography - Usage Guide
+
+This document describes how to integrate and use the `Typography` component in your projects using `@recursica/adapter-mui-v7`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Typography } from "@recursica/adapter-mui-v7";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Typography } from "@recursica/adapter-mui-v7";
+
+export default function Demo() {
+  return (
+    <Typography variant="body1">
+      Typography is used for presenting textual content cleanly.
+    </Typography>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/adapter-mui-v7` 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.
+> - **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.

package/src/components/Typography/index.ts

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

package/src/components/index.ts

@@ -0,0 +1,50 @@
+export * from "./Accordion";
+export * from "./AssistiveElement";
+export * from "./AutoComplete";
+export * from "./Avatar";
+export * from "./Badge";
+export * from "./Breadcrumb";
+export * from "./Button";
+export * from "./Card";
+export * from "./Checkbox";
+export * from "./Chip";
+export * from "./Container";
+export * from "./DatePicker";
+export * from "./Dropdown";
+export * from "./FileInput";
+export * from "./FileUpload";
+export * from "./Flex";
+export * from "./FormControlLayout";
+export * from "./FormControlWrapper";
+export * from "./Grid";
+export * from "./Group";
+export * from "./Heading";
+export * from "./HoverCard";
+export * from "./Label";
+export * from "./Link";
+export * from "./Loader";
+export * from "./Menu";
+export * from "./Modal";
+export * from "./NumberInput";
+export * from "./Pagination";
+export * from "./Panel";
+export * from "./Popover";
+export * from "./Radio";
+export * from "./ReadOnlyField";
+export * from "./SegmentedControl";
+export * from "./Slider";
+export * from "./Stack";
+export * from "./Stepper";
+export * from "./Switch";
+export * from "./Table";
+export * from "./Tabs";
+export * from "./Text";
+export * from "./TextArea";
+export * from "./TextField";
+export * from "./TimePicker";
+export * from "./Timeline";
+export * from "./Toast";
+export * from "./Tooltip";
+export * from "./TransferList";
+export * from "./Typography";
+export * from "./Tree";

package/src/env.d.ts

@@ -0,0 +1,7 @@
+/// <reference types="vite/client" />
+/// <reference types="vite-plugin-svgr/client" />
+
+declare module "*.module.css" {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}