@recursica/adapter-mui-v7 1.0.0

package/src/components/Menu/Menu.tsx

@@ -0,0 +1,103 @@
+import { forwardRef, type CSSProperties } from "react";
+import {
+  Menu as MuiMenu,
+  type MenuProps as MuiMenuProps,
+  MenuItem as MuiMenuItem,
+  type MenuItemProps as MuiMenuItemProps,
+  Divider as MuiDivider,
+  type DividerProps as MuiDividerProps,
+} from "@mui/material";
+import {
+  filterStylingProps,
+  mergeClassNames,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Menu.module.css";
+
+import { type RecursicaMenuProps } from "@recursica/adapter-common";
+
+export type MenuProps = RecursicaOverStyled<MuiMenuProps & RecursicaMenuProps>;
+
+export const Menu = forwardRef<HTMLDivElement, MenuProps>(function Menu(
+  { overStyled = false, className, maxHeight, ...rest },
+  ref,
+) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const restRecord = sanitizedProps as Record<string, unknown>;
+
+  const mergedClassNames = mergeClassNames(
+    {
+      paper: styles.dropdown,
+      list: styles.dropdown,
+    },
+    restRecord.classes as Partial<Record<string, string>> | undefined,
+  );
+
+  // `maxHeight` is a caller-supplied override of the token-driven dropdown max-height, applied
+  // to the Paper slot's inline style — an explicit per-instance escape hatch, not a design token.
+  const callerSlotProps = restRecord.slotProps as
+    | { paper?: Record<string, unknown> }
+    | undefined;
+  const mergedSlotProps = maxHeight
+    ? {
+        ...callerSlotProps,
+        paper: {
+          ...callerSlotProps?.paper,
+          style: {
+            ...(callerSlotProps?.paper?.style as CSSProperties | undefined),
+            maxHeight,
+          },
+        },
+      }
+    : callerSlotProps;
+
+  return (
+    <MuiMenu
+      ref={ref}
+      {...(sanitizedProps as MuiMenuProps)}
+      className={className}
+      classes={mergedClassNames}
+      {...(mergedSlotProps
+        ? { slotProps: mergedSlotProps as MuiMenuProps["slotProps"] }
+        : {})}
+    />
+  );
+});
+
+Menu.displayName = "Menu";
+
+export type MenuItemProps = RecursicaOverStyled<MuiMenuItemProps>;
+
+export const MenuItem = forwardRef<HTMLLIElement, MenuItemProps>(
+  function MenuItem({ overStyled = false, className, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+
+    return (
+      <MuiMenuItem
+        ref={ref}
+        {...(sanitizedProps as MuiMenuItemProps)}
+        className={`${styles.item} ${className || ""}`}
+      />
+    );
+  },
+);
+
+MenuItem.displayName = "MenuItem";
+
+export type MenuDividerProps = RecursicaOverStyled<MuiDividerProps>;
+
+export const MenuDivider = forwardRef<HTMLHRElement, MenuDividerProps>(
+  function MenuDivider({ overStyled = false, className, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+
+    return (
+      <MuiDivider
+        ref={ref}
+        {...(sanitizedProps as MuiDividerProps)}
+        className={`${styles.divider} ${className || ""}`}
+      />
+    );
+  },
+);
+
+MenuDivider.displayName = "MenuDivider";

package/src/components/Menu/USAGE.md

@@ -0,0 +1,53 @@
+# Menu - Usage Guide
+
+This document describes how to integrate and use the `Menu` component in your projects using `@recursica/adapter-mui-v7`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Menu } from "@recursica/adapter-mui-v7";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Menu } from "@recursica/adapter-mui-v7";
+
+export default function Demo() {
+  return (
+    <Menu>
+      <Menu.Target>
+        <Button>Toggle Menu</Button>
+      </Menu.Target>
+      <Menu.Dropdown>
+        <Menu.Item>Profile</Menu.Item>
+        <Menu.Item>Settings</Menu.Item>
+        <Menu.Item color="red">Logout</Menu.Item>
+      </Menu.Dropdown>
+    </Menu>
+  );
+}
+```
+
+---
+
+## 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.
+
+---
+
+## 4. Notes
+
+- `maxHeight` on `<Menu>` overrides the dropdown's token-driven max-height with an explicit pixel (or other CSS length) value, e.g. `<Menu maxHeight={320}>`. It's a per-instance escape hatch, not a design token — leave it unset to use the token default.

package/src/components/Menu/index.ts

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

package/src/components/Modal/MODAL_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,31 @@
+# Modal Implementation Notes
+
+## `.title` descender clipping (Matt Massey, 2026-08-28)
+
+`.title` truncates with an ellipsis (`white-space: nowrap; text-overflow: ellipsis`) rather than
+wrapping, needing `flex: 1 1 auto; min-width: 0;` since it's a flex child of `.header` alongside
+the close button. It used plain `overflow: hidden` to make the ellipsis work, which also clips
+descenders (e.g. the "g" in a long title) whenever `text_line-height` is tighter than the font's
+natural ascent+descent. Switched to `overflow: clip; overflow-clip-margin: 0.35em;` — same
+truncation, but ink can bleed slightly past the line box before it's actually clipped.
+Project-wide fix; see Chip's `CHIP_IMPLEMENTATION_NOTES.md` for the original discovery. Matches
+mantine-adapter's equivalent `.title` rule (see its own `MODAL_IMPLEMENTATION_NOTES.md`).
+
+## Vertical anchor position (source-of-truth audit, 2026-08-30)
+
+**Decision:** Anchor the modal near the top of the viewport instead of MUI's own default
+vertical centering, matching mantine's `Modal`, which has no `centered` override and so uses
+its own library default (near-top, via `.mantine-Modal-inner`'s `align-items: flex-start` +
+`padding: 30px 40px` — unstyled by any Recursica token).
+
+**Implementation:** MUI's `Dialog` centers its paper both axes by default via
+`.MuiDialog-container`. `.root :global(.MuiDialog-container)` overrides that to
+`align-items: flex-start; padding: 30px 40px;`, matching mantine's numbers exactly since
+neither side is token-driven — this is purely "reproduce the source of truth's own default
+library shape" (see Grid's `IMPLEMENTATION_NOTES.md` for the same rule applied to Grid).
+`.inner` (the paper) also gets `margin: 0` — MUI's paper ships its own default 32px margin on
+top of the container padding, which would double the offset otherwise.
+
+Residual: still a small width/horizontal-offset gap against mantine's golden after this fix
+(diffPixels dropped from ~172k to ~25k, still over the 2500 threshold) — not yet root-caused,
+see `OPEN_QUESTIONS.txt`.

package/src/components/Modal/Modal.module.css

@@ -0,0 +1,302 @@
+/* Brand-layer exemptions (recursica-allow-brand) — see recursica-token-analyzer README.md.
+ * Close button is styled to match the Button component's text/icon-only variant, so it reuses
+ * the same global hover/focus state tokens Button.module.css exempts.
+ *   recursica-allow-brand: --recursica_brand_states_focus_blur
+ *   recursica-allow-brand: --recursica_brand_states_focus_border-size
+ *   recursica-allow-brand: --recursica_brand_states_focus_color
+ *   recursica-allow-brand: --recursica_brand_states_focus_margin
+ *   recursica-allow-brand: --recursica_brand_states_hover_color
+ *   recursica-allow-brand: --recursica_brand_states_hover_opacity
+ */
+
+.root {
+}
+
+/* MUI's Dialog container centers its paper vertically by default. Mantine's Modal has no such
+   behavior — it anchors near the top (its own `.mantine-Modal-inner` default: align-items:
+   flex-start, padding: 30px 40px, unstyled by any Recursica token). Reproducing that shape here
+   since nothing here is Recursica-token-driven; it's purely "match the source of truth's own
+   default library behavior" per the layout-components rule (see Grid's IMPLEMENTATION_NOTES.md). */
+.root :global(.MuiDialog-container) {
+  align-items: flex-start;
+  padding: 30px 40px;
+}
+
+.inner {
+  /* Mantine applies padding to inner to keep modal away from edges. We rely on content constraints. */
+  /* MUI's paper also ships its own default 32px margin on top of that — zero it out so the
+     container's padding (below) is the only source of edge spacing, matching Mantine's shape. */
+  margin: 0;
+
+  /* Unlike Mantine, where `.content` (Modal.Content) wraps header/body/footer as one element,
+     MUI's Dialog renders header/body(.content)/footer as separate siblings inside this Paper
+     (mapped via `classes.paper`) — so the border-radius belongs here, on the Paper that is the
+     whole visible modal, not on the body's DialogContent below. `overflow: hidden` clips the
+     header/footer's square corners to match. No box-shadow — Mantine's static default story
+     renders with none. */
+  border-radius: var(
+    --recursica_ui-kit_components_modal_properties_border-radius
+  );
+  overflow: hidden;
+}
+
+.content {
+  /* Geometric Bounds */
+  min-width: var(--recursica_ui-kit_components_modal_properties_min-width);
+  max-width: var(--recursica_ui-kit_components_modal_properties_max-width);
+  min-height: var(--recursica_ui-kit_components_modal_properties_min-height);
+
+  /* Restrict max-height to either the UI Kit max or the viewport bounds to force internal scrolling */
+  max-height: min(
+    var(--recursica_ui-kit_components_modal_properties_max-height),
+    calc(100vh - 4rem)
+  );
+  overflow: hidden;
+
+  /* Box model */
+  border-width: var(--recursica_ui-kit_components_modal_properties_border-size);
+  border-color: var(
+    --recursica_ui-kit_components_modal_properties_colors_border-color
+  );
+  border-style: solid;
+
+  /* Appearance */
+  background-color: var(
+    --recursica_ui-kit_components_modal_properties_colors_content-background-color
+  );
+
+  /* Internal Flex container to trap header and let body scroll */
+  display: flex;
+  flex-direction: column;
+}
+
+.header {
+  display: flex; /* HARDCODE: puts the title and close button side-by-side so the title has a bounded width to truncate against */
+  align-items: center;
+  justify-content: space-between;
+  padding: var(
+      --recursica_ui-kit_components_modal_properties_header-footer-vertical-padding
+    )
+    var(
+      --recursica_ui-kit_components_modal_properties_header-footer-horizontal-padding
+    );
+  background-color: transparent; /* Inherit from content */
+}
+
+.title {
+  flex: 1 1 auto; /* HARDCODE: let the title claim the space between the header edge and the close button */
+  min-width: 0; /* HARDCODE: required for text-overflow ellipsis to take effect on a flex child */
+  overflow: clip; /* HARDCODE: `hidden` clips descenders (e.g. "g") when text_line-height is
+    tighter than the font's natural ascent+descent; overflow-clip-margin gives ink a small bleed
+    allowance while still clipping genuinely overflowing text (see Chip's IMPLEMENTATION_NOTES.md). */
+  overflow-clip-margin: 0.35em;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+
+  color: var(--recursica_ui-kit_components_modal_properties_colors_title);
+
+  /* Direct Figma Typography Mapping */
+  font-family: var(
+    --recursica_ui-kit_components_modal_properties_header-style_fontFamily
+  );
+  font-size: var(
+    --recursica_ui-kit_components_modal_properties_header-style_fontSize
+  );
+  font-style: var(
+    --recursica_ui-kit_components_modal_properties_header-style_fontStyle
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_modal_properties_header-style_fontWeight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_modal_properties_header-style_letterSpacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_modal_properties_header-style_lineHeight
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_modal_properties_header-style_textCase
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_modal_properties_header-style_textDecoration
+  );
+}
+
+.bodyWrapper {
+  /* This is the container that overrides Mantine's native Body. It strips padding and acts as a flex column. */
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  flex: 1 1 auto;
+  overflow: hidden;
+  min-height: 0; /* Critical for flex child scrolling constraint */
+}
+
+.scrollArea {
+  padding: var(
+      --recursica_ui-kit_components_modal_properties_content-vertical-padding
+    )
+    var(
+      --recursica_ui-kit_components_modal_properties_content-horizontal-padding
+    );
+
+  /* Internal scrolling */
+  flex: 1 1 auto;
+  overflow-y: auto;
+  min-height: 0; /* Critical for flex child scrolling constraint */
+
+  color: var(--recursica_ui-kit_components_modal_properties_colors_content);
+
+  /* Direct Figma Typography Mapping */
+  font-family: var(
+    --recursica_ui-kit_components_modal_properties_content-style_fontFamily
+  );
+  font-size: var(
+    --recursica_ui-kit_components_modal_properties_content-style_fontSize
+  );
+  font-style: var(
+    --recursica_ui-kit_components_modal_properties_content-style_fontStyle
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_modal_properties_content-style_fontWeight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_modal_properties_content-style_letterSpacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_modal_properties_content-style_lineHeight
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_modal_properties_content-style_textCase
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_modal_properties_content-style_textDecoration
+  );
+
+  /* Ensure button gap token is easily usable if developers use standard spacing */
+  --modal-button-gap: var(
+    --recursica_ui-kit_components_modal_properties_button-gap
+  );
+
+  /* Smooth divider transitions */
+  transition: border-color 0.15s ease;
+  border-top: var(
+      --recursica_ui-kit_components_modal_properties_scroll-divider-size
+    )
+    solid transparent;
+  border-bottom: var(
+      --recursica_ui-kit_components_modal_properties_scroll-divider-size
+    )
+    solid transparent;
+}
+
+.scrollArea[data-scrolled-top] {
+  border-top-color: var(
+    --recursica_ui-kit_components_modal_properties_colors_scroll-divider
+  );
+}
+
+.scrollArea[data-scrolled-bottom] {
+  border-bottom-color: var(
+    --recursica_ui-kit_components_modal_properties_colors_scroll-divider
+  );
+}
+
+.footer {
+  padding: var(
+      --recursica_ui-kit_components_modal_properties_header-footer-vertical-padding
+    )
+    var(
+      --recursica_ui-kit_components_modal_properties_header-footer-horizontal-padding
+    );
+  background-color: transparent;
+  display: flex;
+  justify-content: flex-end;
+  gap: var(--recursica_ui-kit_components_modal_properties_button-gap);
+}
+
+.close {
+  /* Matches the Button component's text-variant, icon-only, small-size visual treatment
+     (see Button.module.css) so the modal close control looks like a Recursica Button
+     rather than MUI's native IconButton. */
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  position: relative;
+  overflow: hidden;
+  transition: all 0.2s ease;
+
+  height: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_height
+  );
+  min-width: var(
+    --recursica_ui-kit_components_button_variants_content_icon-only_variants_sizes_small_properties_min-width
+  );
+  padding: 0
+    var(
+      --recursica_ui-kit_components_button_variants_content_icon-only_variants_sizes_small_properties_horizontal-padding
+    );
+  border-radius: var(
+    --recursica_ui-kit_components_button_variants_content_icon-only_variants_sizes_small_properties_border-radius
+  );
+
+  border-style: solid;
+  border-width: var(
+    --recursica_ui-kit_components_button_variants_styles_text_properties_border-size
+  );
+  border-color: var(
+    --recursica_ui-kit_components_button_variants_styles_text_properties_colors_border-color
+  );
+  background-color: var(
+    --recursica_ui-kit_components_button_variants_styles_text_properties_colors_background-color
+  );
+  color: var(
+    --recursica_ui-kit_components_button_variants_styles_text_properties_colors_icon-color
+  );
+}
+
+.close svg {
+  position: relative;
+  z-index: 1;
+  width: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_icon
+  );
+  height: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_icon
+  );
+}
+
+.close::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+  z-index: 0;
+  pointer-events: none;
+  transition: opacity 150ms ease;
+  opacity: 0;
+  background-color: var(--recursica_brand_states_hover_color);
+}
+.close:hover:not(:disabled)::after {
+  opacity: var(--recursica_brand_states_hover_opacity);
+}
+
+/* MuiIconButton injects its own `:hover` background via emotion at render time, which lands in
+   the DOM after this stylesheet and wins the tie at equal specificity — same class of conflict
+   documented in DatePicker.module.css's error/disabled state overrides. `!important` keeps the
+   button's own background transparent so only the `::after` overlay above renders the hover
+   feedback, matching Button's single-overlay hover treatment exactly. */
+.close:hover {
+  background-color: transparent !important;
+}
+
+.close:focus-visible {
+  outline: none;
+  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);
+}

package/src/components/Modal/Modal.stories.tsx

@@ -0,0 +1,105 @@
+import { useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Modal, type ModalProps } from "./Modal";
+import { Button } from "../Button";
+
+const meta: Meta<typeof Modal> = {
+  title: "UI-Kit/Modal",
+  component: Modal,
+  tags: ["autodocs"],
+  argTypes: {
+    opened: { table: { disable: true } },
+    onClose: { table: { disable: true } },
+    defaultChecked: { table: { disable: true } },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Modal>;
+
+const DefaultWrapper = (args: ModalProps) => {
+  // Starts opened so the modal is visible without pressing a button first.
+  const [opened, setOpened] = useState(true);
+  return (
+    <>
+      <Modal {...args} opened={opened} onClose={() => setOpened(false)}>
+        Please log in to continue accessing this feature.
+        <Modal.Footer>
+          <Button variant="outline" onClick={() => setOpened(false)}>
+            Cancel
+          </Button>
+          <Button onClick={() => setOpened(false)}>Confirm</Button>
+        </Modal.Footer>
+      </Modal>
+      <Button onClick={() => setOpened(true)}>Open Modal</Button>
+    </>
+  );
+};
+
+export const Default: Story = {
+  args: {
+    title: "Authentication Required",
+  },
+  render: (args) => <DefaultWrapper {...args} />,
+};
+
+const LongTitleWrapper = (args: ModalProps) => {
+  const [opened, setOpened] = useState(true);
+  return (
+    <>
+      <Modal {...args} opened={opened} onClose={() => setOpened(false)}>
+        The title above is longer than the header can display, so it truncates
+        with an ellipsis instead of wrapping onto a second line.
+        <Modal.Footer>
+          <Button onClick={() => setOpened(false)}>Got it</Button>
+        </Modal.Footer>
+      </Modal>
+      <Button onClick={() => setOpened(true)}>Open Modal</Button>
+    </>
+  );
+};
+
+export const LongTitle: Story = {
+  args: {
+    title:
+      "This Modal Title Is Deliberately Long Enough To Exceed The Available Header Width",
+  },
+  render: (args) => <LongTitleWrapper {...args} />,
+};
+
+const ScrollingWrapper = (args: ModalProps) => {
+  // Starts opened so the modal is visible without pressing a button first.
+  const [opened, setOpened] = useState(true);
+  return (
+    <>
+      <Modal {...args} opened={opened} onClose={() => setOpened(false)}>
+        <p>
+          This modal demonstrates the dynamically injected scroll dividers. When
+          this body content overflows, the borders between the Header and Footer
+          automatically appear to define the scrolling boundary.
+        </p>
+        {Array(20)
+          .fill(0)
+          .map((_, i) => (
+            <p key={i}>Scrolling content block {i + 1}...</p>
+          ))}
+        {/* The new Footer abstraction */}
+        <Modal.Footer>
+          <Button variant="outline" onClick={() => setOpened(false)}>
+            Decline
+          </Button>
+          <Button onClick={() => setOpened(false)}>Accept Terms</Button>
+        </Modal.Footer>
+      </Modal>
+      <Button onClick={() => setOpened(true)}>Open Scrolling Modal</Button>
+    </>
+  );
+};
+
+export const ScrollingContent: Story = {
+  args: {
+    title: "Terms and Conditions",
+  },
+  render: (args) => <ScrollingWrapper {...args} />,
+};

package/src/components/Modal/Modal.test.tsx

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