@recursica/mantine-adapter 0.49.0 → 0.50.1

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.1",
   "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/DatePicker/DATEPICKER_IMPLEMENTATION_NOTES.md

@@ -27,3 +27,4 @@ The `DatePicker` component is a wrapper around the `@mantine/dates` `DatePickerI
 - **Default leading icon**: `leftSection={<CalendarIcon />}` (new `DatePicker.icons.tsx`, following the existing local-inline-SVG convention used by `Pagination.icons.tsx` — no icon library is a dependency of either adapter) is set the same way, overridable via `leftSection`.
 - **Default placeholder**: `placeholder="MM / DD / YY"`, set the same way (before `sanitizedProps`, so consumers can override).
 - **Single-line enforcement (bug fix)**: `DatePickerInput` renders its value/placeholder as a `<button>`'s text content, not a native `<input>` — it wraps like any other block text by default. A long placeholder (e.g. the original story's `"Select a deadline..."`) wrapped to two lines, inflating the field's height well past its `min-height` token and making the field visually look narrower than its actual `width` token value even though the box itself was always the right size. Fixed with `white-space: nowrap`/`text-overflow: ellipsis`/`overflow-x: clip`/`overflow-y: visible` on `.input`, the same convention `FileInput.module.css`'s `.value` uses.
+- **Day focus ring (bug fix)**: Mantine's `Day` ships no built-in `:focus-visible` style of its own (unlike `.calendarHeaderControl`/`.calendarHeaderLevel`, which are styled as `Button` and inherited a focus ring from that treatment), so a focused day — e.g. the auto-focused selected/today day when the calendar opens — fell through to the browser's native blue outline instead of a Recursica token. Fixed by adding `.day:focus-visible` with the same generic `--recursica_brand_states_focus_*` box-shadow ring already used by `.input` and `.calendarHeaderControl`/`.calendarHeaderLevel`. mui-adapter's `.MuiPickerDay-root.Mui-focusVisible` already had this — only the mantine-adapter side was missing it.

package/src/components/DatePicker/DatePicker.module.css

@@ -544,3 +544,16 @@
   );
   opacity: 1;
 }
+
+/* Focus ring, same convention as calendarHeaderControl/input's own :focus-visible treatment.
+   Mantine's Day ships no explicit focus style of its own, so without this it fell through to
+   the browser's native (blue) :focus-visible outline instead of a Recursica token. */
+.day: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/DatePicker/DatePicker.stories.tsx

@@ -115,6 +115,31 @@ export const ErrorState: Story = {
   },
 };
 
+export const OpenedCalendar: Story = {
+  args: {
+    label: "Meeting Date",
+    assistiveText: "Calendar rendered open by default for styling review.",
+    // `popoverProps.opened` overrides Mantine's own internal disclosure state (see
+    // PickerInputBase's `opened: dropdownOpened, ...popoverProps` spread order), so the
+    // dropdown stays open with no click interaction needed — same convention as Menu's
+    // `opened: true` stories.
+    popoverProps: { opened: true },
+    // 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/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.