@recursica/mantine-adapter 0.49.0 → 0.50.0

package/package.json

@@ -13,7 +13,7 @@
     "url": "git+https://github.com/borderux/recursica.git",
     "directory": "packages/mantine-adapter"
   },
-  "version": "0.49.0",
+  "version": "0.50.0",
   "type": "module",
   "main": "./dist/mantine-adapter.cjs",
   "module": "./dist/mantine-adapter.js",
@@ -94,7 +94,7 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@recursica/adapter-common": "^0.24.0",
+    "@recursica/adapter-common": "^0.25.0",
     "@recursica/official-release": "^2.8.0"
   },
   "peerDependencies": {

package/src/components/Menu/MENU_IMPLEMENTATION_NOTES.md

@@ -76,3 +76,13 @@ Decisions and design tweaks strictly tailored for the UI Kit's Menu wrapped agai
 - `pointer-events` on disabled items (Mantine handles disabled natively)
 
 **Rationale:** Early iterations included aggressive structural resets (like `overflow: hidden`, `box-sizing: border-box`, `margin: 0`) cargo-culted from the Dropdown component. These caused sub-menus to render clipped inside the parent dropdown with scrollbars. The lesson: default to Mantine's native behavior and only override what the Recursica token system explicitly needs to control.
+
+---
+
+## 9. `maxHeight` Override
+
+**Decision:** `<Menu maxHeight={...}>` lets a caller override the token-driven `.dropdown` max-height with an explicit pixel (or other CSS length) value.
+
+**Implementation:** This is the one deliberate exception to "no inline design tokens in TSX" (see `COMPONENT_DEV_GUIDE.md`) — it's applied via Mantine's per-part `styles` API (`styles={{ dropdown: { maxHeight } }}`), the same mechanism already used for `classNames`, merged with any caller-supplied `styles`. It only takes effect when `maxHeight` is actually passed; otherwise the CSS module's token-driven `max-height` is untouched.
+
+**Caveat:** Because sub-menu dropdowns inherit the root Menu's `classNames`/`styles` mapping (see §6), setting `maxHeight` on the root also caps `Menu.Sub.Dropdown`'s height, not just the top-level dropdown.

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

@@ -161,6 +161,11 @@ const meta: Meta = {
       description:
         "Controlled open state. Leave undefined for uncontrolled behavior.",
     },
+    maxHeight: {
+      control: "number",
+      description:
+        "Overrides the token-driven dropdown max-height with an explicit pixel value.",
+    },
   },
   parameters: {
     docs: {
@@ -303,6 +308,43 @@ export const WithSubmenus: Story = {
   },
 };
 
+export const WithMaxHeight: Story = {
+  args: {
+    position: "bottom-start",
+    maxHeight: 160,
+    // Rendered open by default so this story is diffable against the MUI adapter
+    // without an interaction step.
+    opened: true,
+  },
+  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.",
+      },
+    },
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  render: ({ withLayer, layer, ...args }: MenuStoryArgs) => {
+    return (
+      <Menu {...args}>
+        <Menu.Target>
+          <Button variant="solid">Menu with maxHeight</Button>
+        </Menu.Target>
+
+        <Menu.Dropdown>
+          <Menu.Item leftSection={<SettingsIcon />}>Settings</Menu.Item>
+          <Menu.Item leftSection={<MessageIcon />}>Messages</Menu.Item>
+          <Menu.Item leftSection={<ImageIcon />}>Gallery</Menu.Item>
+          <Menu.Item leftSection={<SearchIcon />}>Search</Menu.Item>
+          <Menu.Item leftSection={<ArrowsIcon />}>Transfer my data</Menu.Item>
+          <Menu.Item leftSection={<TrashIcon />}>Delete my account</Menu.Item>
+        </Menu.Dropdown>
+      </Menu>
+    );
+  },
+};
+
 export const HoverTrigger: Story = {
   args: {
     trigger: "click-hover",

package/src/components/Menu/Menu.tsx

@@ -1,4 +1,4 @@
-import { forwardRef } from "react";
+import { forwardRef, type CSSProperties } from "react";
 import {
   Menu as MantineMenu,
   type MenuProps as MantineMenuProps,
@@ -49,6 +49,7 @@ export type MenuProps = RecursicaOverStyled<
 const MenuBase = function Menu({ overStyled = false, ...rest }: MenuProps) {
   const sanitizedProps = filterStylingProps(rest, overStyled);
   const restRecord = sanitizedProps as Record<string, unknown>;
+  const { maxHeight, ...menuRestRecord } = restRecord;
 
   // Bind CSS module classes to Mantine's internal classNames API
   const mergedClassNames = mergeClassNames(
@@ -64,10 +65,31 @@ const MenuBase = function Menu({ overStyled = false, ...rest }: MenuProps) {
     restRecord.classNames as Partial<Record<string, string>> | undefined,
   );
 
+  // `maxHeight` is a caller-supplied override of the token-driven dropdown max-height, applied
+  // via Mantine's per-part `styles` API (same mechanism as `classNames` above) rather than a CSS
+  // module change, since it's an explicit per-instance escape hatch, not a design token. The CSS
+  // module deliberately leaves `overflow` unset (see MENU_IMPLEMENTATION_NOTES.md §8) so it
+  // doesn't clip sub-menus at the token default height; once a caller opts into a fixed
+  // `maxHeight`, though, items need to scroll instead of spilling out past the boundary.
+  const callerStyles = menuRestRecord.styles as
+    | Partial<Record<string, CSSProperties>>
+    | undefined;
+  const mergedStyles = maxHeight
+    ? {
+        ...callerStyles,
+        dropdown: {
+          ...callerStyles?.dropdown,
+          maxHeight: maxHeight as CSSProperties["maxHeight"],
+          overflowY: "auto" as CSSProperties["overflowY"],
+        },
+      }
+    : callerStyles;
+
   return (
     <MantineMenu
-      {...(sanitizedProps as unknown as MantineMenuProps)}
+      {...(menuRestRecord as unknown as MantineMenuProps)}
       classNames={mergedClassNames}
+      {...(mergedStyles ? { styles: mergedStyles } : {})}
     />
   );
 };

package/src/components/Menu/USAGE.md

@@ -52,3 +52,4 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 - The full Mantine composition API is supported, including sub-menus: `Menu`, `Menu.Target`, `Menu.Dropdown`, `Menu.Item`, `Menu.Divider`, `Menu.Label`, `Menu.Sub`, `Menu.Sub.Target`, `Menu.Sub.Item`, and `Menu.Sub.Dropdown`.
 - The `color` prop on `Menu.Item` (and `Menu.Sub.Item`) — used by Mantine for semantics like a "danger" item — is ignored unless `overStyled={true}` is set.
+- `maxHeight` on the root `<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.