@recursica/mui-adapter 0.33.0 → 0.34.1

package/package.json

@@ -13,7 +13,7 @@
     "url": "git+https://github.com/borderux/recursica.git",
     "directory": "packages/mui-adapter"
   },
-  "version": "0.33.0",
+  "version": "0.34.1",
   "publishConfig": {
     "access": "public"
   },
@@ -59,7 +59,9 @@
     "lint": "eslint .",
     "storybook": "storybook dev -p 6012",
     "analyze-tokens": "analyze-tokens --css @recursica/official-release/recursica_variables_scoped.css --dir src/components --output token-analysis.json",
-    "prebuild": "npm run analyze-tokens"
+    "prebuild": "npm run analyze-tokens",
+    "adapter-tester": "adapter-tester --serve",
+    "adapter-tester:automated": "adapter-tester"
   },
   "devDependencies": {
     "@chromatic-com/storybook": "^5.1.1",
@@ -67,6 +69,8 @@
     "@mui/lab": "^7.0.1-beta.25",
     "@mui/x-date-pickers": "^9.11.0",
     "@mui/x-tree-view": "^9.11.0",
+    "@playwright/test": "^1.53.0",
+    "@recursica/adapter-tester": "*",
     "@recursica/recursica-postcss-vars": "*",
     "@recursica/storybook-template": "*",
     "@recursica/token-analyzer": "*",
@@ -102,7 +106,7 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@recursica/adapter-common": "^0.24.0",
+    "@recursica/adapter-common": "^0.25.0",
     "@recursica/official-release": "^2.8.0",
     "dayjs": "^1.11.21"
   },

package/src/components/DatePicker/DatePicker.stories.tsx

@@ -120,6 +120,31 @@ export const ErrorState: Story = {
   },
 };
 
+export const OpenedCalendar: Story = {
+  args: {
+    label: "Meeting Date",
+    assistiveText: "Calendar rendered open by default for styling review.",
+    // MUI X's DatePicker supports a controlled `open` prop directly; pairing it with a
+    // no-op `onClose` keeps the calendar open with no click interaction needed — same
+    // intent as the mantine-adapter's `OpenedCalendar` story.
+    open: true,
+    onClose: () => {},
+    // Fixed (not computed) so the selected-day fill is visible on load, alongside the
+    // today marker, for styling review. Local-component constructor, not an ISO date
+    // string — `new Date("2026-08-26")` parses as UTC midnight, which renders as the
+    // 25th in any timezone behind UTC.
+    defaultValue: new Date(2026, 7, 26),
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "The calendar dropdown renders open by default so its styling can be reviewed without a click interaction.",
+      },
+    },
+  },
+};
+
 export const StaticReadOnly: Story = {
   args: {
     label: "Static ReadOnly Review",

package/src/components/Menu/IMPLEMENTATION_NOTES.md

@@ -2,3 +2,4 @@
 
 - **Compositional API Dropped:** Mantine uses `<Menu.Target>`, `<Menu.Dropdown>`, `<Menu.Item>`, etc., and manages state natively via React context within `<Menu>`. MUI's API is fully monolithic.
 - **Monolithic API Adopted:** Following architectural review, we have abandoned the fabricated context wrappers for `mui-adapter`. We now natively export `Menu`, `MenuItem`, and `MenuDivider` wrapping their `@mui/material` counterparts. Developers are expected to manage `anchorEl` state themselves, just like native MUI. Storybook tests have been updated to simulate this open state so visual regressions still cover the dropdown menu visually.
+- **`maxHeight` Override:** `<Menu maxHeight={...}>` overrides the token-driven dropdown max-height with an explicit pixel (or other CSS length) value — the one deliberate exception to "no inline design tokens in TSX" (see `COMPONENT_DEV_GUIDE.md`). Implemented by merging `maxHeight` into `slotProps.paper.style`, alongside any caller-supplied `slotProps`, rather than a CSS module change; the CSS module's token-driven `max-height` stays untouched when the prop isn't passed.

package/src/components/Menu/Menu.stories.tsx

@@ -300,6 +300,43 @@ export const WithSubmenus: Story = {
   },
 };
 
+export const WithMaxHeight: Story = {
+  render: (args) => (
+    <InteractiveMenu {...args}>
+      <MenuItem>
+        <SettingsIcon style={{ marginRight: 8 }} /> Settings
+      </MenuItem>
+      <MenuItem>
+        <MessageIcon style={{ marginRight: 8 }} /> Messages
+      </MenuItem>
+      <MenuItem>
+        <ImageIcon style={{ marginRight: 8 }} /> Gallery
+      </MenuItem>
+      <MenuItem>
+        <SearchIcon style={{ marginRight: 8 }} /> Search
+      </MenuItem>
+      <MenuItem>
+        <ArrowsIcon style={{ marginRight: 8 }} /> Transfer my data
+      </MenuItem>
+      <MenuItem>
+        <TrashIcon style={{ marginRight: 8 }} /> Delete my account
+      </MenuItem>
+    </InteractiveMenu>
+  ),
+  args: {
+    opened: true,
+    maxHeight: 160,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "`maxHeight` overrides the token-driven dropdown max-height with an explicit pixel value, scrolling the item list once it's exceeded.",
+      },
+    },
+  },
+};
+
 // mui-adapter's Menu has no native hover-trigger support (unlike Mantine's `trigger` prop),
 // so this story implements open-on-hover itself: hovering the target opens the menu, and a
 // short close delay (mirroring Mantine's `closeDelay`) keeps it open while the pointer moves

package/src/components/Menu/Menu.tsx

@@ -1,4 +1,4 @@
-import { forwardRef } from "react";
+import { forwardRef, type CSSProperties } from "react";
 import {
   Menu as MuiMenu,
   type MenuProps as MuiMenuProps,
@@ -19,27 +19,47 @@ import { type RecursicaMenuProps } from "@recursica/adapter-common";
 export type MenuProps = RecursicaOverStyled<MuiMenuProps & RecursicaMenuProps>;
 
 export const Menu = forwardRef<HTMLDivElement, MenuProps>(function Menu(
-  { overStyled = false, className, ...rest },
+  { 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,
     },
-    (sanitizedProps as Record<string, unknown>).classes as
-      | Partial<Record<string, string>>
-      | undefined,
+    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"] }
+        : {})}
     />
   );
 });

package/src/components/Menu/USAGE.md

@@ -45,3 +45,9 @@ All Recursica components in the `@recursica/mui-adapter` package adhere strictly
 > - **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/Modal/Modal.module.css

@@ -1,3 +1,14 @@
+/* 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 {
 }
 
@@ -40,6 +51,9 @@
 }
 
 .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
     )
@@ -50,6 +64,12 @@
 }
 
 .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: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+
   color: var(--recursica_ui-kit_components_modal_properties_colors_title);
 
   /* Direct Figma Typography Mapping */
@@ -173,5 +193,87 @@
 }
 
 .close {
-  /* Inherits standard icon button tokens natively, but we can override if required */
+  /* 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

@@ -19,7 +19,8 @@ export default meta;
 type Story = StoryObj<typeof Modal>;
 
 const DefaultWrapper = (args: ModalProps) => {
-  const [opened, setOpened] = useState(false);
+  // 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)}>
@@ -43,8 +44,33 @@ export const Default: Story = {
   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) => {
-  const [opened, setOpened] = useState(false);
+  // 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)}>