@recursica/mui-adapter 0.33.0 → 0.34.0

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.0",
   "publishConfig": {
     "access": "public"
   },
@@ -102,7 +102,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/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.