@recursica/adapter-mantine-v8 1.0.0

package/src/components/Menu/Menu.tsx

@@ -0,0 +1,373 @@
+import { forwardRef, type CSSProperties } from "react";
+import {
+  Menu as MantineMenu,
+  type MenuProps as MantineMenuProps,
+  type MenuTargetProps as MantineMenuTargetProps,
+  type MenuDropdownProps as MantineMenuDropdownProps,
+  type MenuItemProps as MantineMenuItemProps,
+  type MenuDividerProps as MantineMenuDividerProps,
+  type MenuLabelProps as MantineMenuLabelProps,
+  type MenuSubProps as MantineMenuSubProps,
+  type MenuSubTargetProps as MantineMenuSubTargetProps,
+  type MenuSubDropdownProps as MantineMenuSubDropdownProps,
+  createPolymorphicComponent,
+} from "@mantine/core";
+import {
+  filterStylingProps,
+  omitUnsupportedProps,
+  mergeClassNames,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Menu.module.css";
+
+import { type RecursicaMenuProps } from "@recursica/adapter-common";
+
+// ============================================================
+// MENU ROOT
+// ============================================================
+
+/**
+ * Recursica Menu component wrapping Mantine's composable Menu.
+ *
+ * Usage follows the composable dot-notation pattern:
+ * ```tsx
+ * <Menu>
+ *   <Menu.Target><Button>Open</Button></Menu.Target>
+ *   <Menu.Dropdown>
+ *     <Menu.Label>Section</Menu.Label>
+ *     <Menu.Item>Action</Menu.Item>
+ *     <Menu.Divider />
+ *     <Menu.Item>Another action</Menu.Item>
+ *   </Menu.Dropdown>
+ * </Menu>
+ * ```
+ */
+export type MenuProps = RecursicaOverStyled<
+  MantineMenuProps & RecursicaMenuProps
+>;
+
+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(
+    {
+      dropdown: styles.dropdown,
+      item: styles.item,
+      itemLabel: styles.itemLabel,
+      itemSection: styles.itemSection,
+      divider: styles.divider,
+      label: styles.label,
+      chevron: styles.chevron,
+    },
+    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
+      {...(menuRestRecord as unknown as MantineMenuProps)}
+      classNames={mergedClassNames}
+      {...(mergedStyles ? { styles: mergedStyles } : {})}
+    />
+  );
+};
+MenuBase.displayName = "Menu";
+
+// ============================================================
+// MENU TARGET
+// ============================================================
+
+/**
+ * Wrapper for the element that triggers the menu.
+ * Requires a single child element that supports ref forwarding.
+ */
+export type MenuTargetProps = RecursicaOverStyled<MantineMenuTargetProps>;
+
+const MenuTarget = function MenuTarget({
+  overStyled = false,
+  ...rest
+}: MenuTargetProps) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+
+  return (
+    <MantineMenu.Target
+      {...(sanitizedProps as unknown as MantineMenuTargetProps)}
+    />
+  );
+};
+MenuTarget.displayName = "MenuTarget";
+
+// ============================================================
+// MENU DROPDOWN
+// ============================================================
+
+/** The dropdown panel containing menu items, dividers, and labels. */
+export type MenuDropdownProps = RecursicaOverStyled<MantineMenuDropdownProps>;
+
+const MenuDropdown = forwardRef<HTMLDivElement, MenuDropdownProps>(
+  function MenuDropdown({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const classNameProp = (sanitizedProps as Record<string, unknown>)
+      .className as string | undefined;
+
+    return (
+      <MantineMenu.Dropdown
+        {...(sanitizedProps as unknown as MantineMenuDropdownProps)}
+        ref={ref}
+        className={classNameProp}
+      />
+    );
+  },
+);
+MenuDropdown.displayName = "MenuDropdown";
+
+// ============================================================
+// MENU ITEM
+// ============================================================
+
+/**
+ * An individual actionable item within the menu dropdown.
+ *
+ * **Note:** Mantine's `color` prop is stripped to enforce design token adherence.
+ */
+export type MenuItemProps = RecursicaOverStyled<
+  Omit<MantineMenuItemProps, "color">
+>;
+
+const _MenuItem = forwardRef<HTMLButtonElement, MenuItemProps>(
+  function MenuItem({ overStyled = false, ...rest }, ref) {
+    // Props this component intentionally doesn't support — deleted at runtime so they can't leak
+    // through even if a caller forces them via plain JavaScript, bypassing the `Omit<>` above.
+    const UNSUPPORTED_PROPS = [
+      "color", // Colors are token-driven; the library's native palette isn't exposed.
+    ] as const satisfies readonly (keyof MantineMenuItemProps)[];
+
+    const sanitizedProps = omitUnsupportedProps(
+      filterStylingProps(rest, overStyled) as Record<string, unknown>,
+      UNSUPPORTED_PROPS,
+    );
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    const classNameProp = restRecord.className as string | undefined;
+
+    return (
+      <MantineMenu.Item
+        {...(sanitizedProps as unknown as MantineMenuItemProps)}
+        ref={ref}
+        className={classNameProp}
+      />
+    );
+  },
+);
+_MenuItem.displayName = "MenuItem";
+
+/**
+ * An individual actionable item within the menu dropdown.
+ *
+ * Supports polymorphism via the `component` prop for link-style items.
+ * @example
+ * ```tsx
+ * <Menu.Item component="a" href="/settings">Settings</Menu.Item>
+ * ```
+ */
+const MenuItem = createPolymorphicComponent<"button", MenuItemProps>(_MenuItem);
+
+// ============================================================
+// MENU DIVIDER
+// ============================================================
+
+/** A visual separator between groups of menu items. */
+export type MenuDividerProps = RecursicaOverStyled<MantineMenuDividerProps>;
+
+const MenuDivider = forwardRef<HTMLHRElement, MenuDividerProps>(
+  function MenuDivider({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const classNameProp = (sanitizedProps as Record<string, unknown>)
+      .className as string | undefined;
+
+    return (
+      <MantineMenu.Divider
+        {...(sanitizedProps as unknown as MantineMenuDividerProps)}
+        ref={ref}
+        className={classNameProp}
+      />
+    );
+  },
+);
+MenuDivider.displayName = "MenuDivider";
+
+// ============================================================
+// MENU LABEL
+// ============================================================
+
+/** A non-interactive section label used to categorize groups of menu items. */
+export type MenuLabelProps = RecursicaOverStyled<MantineMenuLabelProps>;
+
+const MenuLabel = forwardRef<HTMLDivElement, MenuLabelProps>(function MenuLabel(
+  { overStyled = false, ...rest },
+  ref,
+) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const classNameProp = (sanitizedProps as Record<string, unknown>)
+    .className as string | undefined;
+
+  return (
+    <MantineMenu.Label
+      {...(sanitizedProps as unknown as MantineMenuLabelProps)}
+      ref={ref}
+      className={classNameProp}
+    />
+  );
+});
+MenuLabel.displayName = "MenuLabel";
+
+// ============================================================
+// MENU SUB (SUBMENU CONTAINER)
+// ============================================================
+
+/** Container for a submenu, wrapping Menu.Sub.Target and Menu.Sub.Dropdown. */
+export type MenuSubProps = MantineMenuSubProps;
+
+const MenuSubBase = function MenuSub(props: MenuSubProps) {
+  return <MantineMenu.Sub {...props} />;
+};
+MenuSubBase.displayName = "MenuSub";
+
+// ============================================================
+// MENU SUB TARGET
+// ============================================================
+
+/** Wrapper for the element that triggers the submenu. */
+export type MenuSubTargetProps = MantineMenuSubTargetProps;
+
+const MenuSubTarget = function MenuSubTarget(props: MenuSubTargetProps) {
+  return <MantineMenu.Sub.Target {...props} />;
+};
+MenuSubTarget.displayName = "MenuSubTarget";
+
+// ============================================================
+// MENU SUB ITEM (triggers submenu)
+// ============================================================
+
+/**
+ * A menu item that acts as a submenu trigger.
+ * Renders within Menu.Sub.Target and displays a chevron indicator.
+ */
+export type MenuSubItemProps = RecursicaOverStyled<
+  Omit<MantineMenuItemProps, "color">
+>;
+
+const _MenuSubItem = forwardRef<HTMLButtonElement, MenuSubItemProps>(
+  function MenuSubItem({ overStyled = false, ...rest }, ref) {
+    // Props this component intentionally doesn't support — deleted at runtime so they can't leak
+    // through even if a caller forces them via plain JavaScript, bypassing the `Omit<>` above.
+    const UNSUPPORTED_PROPS = [
+      "color", // Colors are token-driven; the library's native palette isn't exposed.
+    ] as const satisfies readonly (keyof MantineMenuItemProps)[];
+
+    const sanitizedProps = omitUnsupportedProps(
+      filterStylingProps(rest, overStyled) as Record<string, unknown>,
+      UNSUPPORTED_PROPS,
+    );
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    const classNameProp = restRecord.className as string | undefined;
+
+    return (
+      <MantineMenu.Sub.Item
+        {...(sanitizedProps as unknown as MantineMenuItemProps)}
+        ref={ref}
+        className={classNameProp}
+      />
+    );
+  },
+);
+_MenuSubItem.displayName = "MenuSubItem";
+
+/**
+ * A menu item that acts as a submenu trigger.
+ *
+ * Supports polymorphism via the `component` prop.
+ */
+const MenuSubItem = createPolymorphicComponent<"button", MenuSubItemProps>(
+  _MenuSubItem,
+);
+
+// ============================================================
+// MENU SUB DROPDOWN
+// ============================================================
+
+/** The dropdown panel for a submenu. */
+export type MenuSubDropdownProps =
+  RecursicaOverStyled<MantineMenuSubDropdownProps>;
+
+const MenuSubDropdown = forwardRef<HTMLDivElement, MenuSubDropdownProps>(
+  function MenuSubDropdown({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const classNameProp = (sanitizedProps as Record<string, unknown>)
+      .className as string | undefined;
+
+    return (
+      <MantineMenu.Sub.Dropdown
+        {...(sanitizedProps as unknown as MantineMenuSubDropdownProps)}
+        ref={ref}
+        className={classNameProp}
+      />
+    );
+  },
+);
+MenuSubDropdown.displayName = "MenuSubDropdown";
+
+// ============================================================
+// DOT NOTATION EXPORT
+// ============================================================
+
+type MenuSubComponent = typeof MenuSubBase & {
+  Target: typeof MenuSubTarget;
+  Item: typeof MenuSubItem;
+  Dropdown: typeof MenuSubDropdown;
+};
+
+const MenuSub = MenuSubBase as MenuSubComponent;
+MenuSub.Target = MenuSubTarget;
+MenuSub.Item = MenuSubItem;
+MenuSub.Dropdown = MenuSubDropdown;
+
+type MenuComponent = typeof MenuBase & {
+  Target: typeof MenuTarget;
+  Dropdown: typeof MenuDropdown;
+  Item: typeof MenuItem;
+  Divider: typeof MenuDivider;
+  Label: typeof MenuLabel;
+  Sub: MenuSubComponent;
+};
+
+export const Menu = MenuBase as MenuComponent;
+Menu.Target = MenuTarget;
+Menu.Dropdown = MenuDropdown;
+Menu.Item = MenuItem;
+Menu.Divider = MenuDivider;
+Menu.Label = MenuLabel;
+Menu.Sub = MenuSub;

package/src/components/Menu/USAGE.md

@@ -0,0 +1,55 @@
+# Menu - Usage Guide
+
+This document describes how to integrate and use the `Menu` component in your projects using `@recursica/adapter-mantine-v8`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Menu } from "@recursica/adapter-mantine-v8";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Menu } from "@recursica/adapter-mantine-v8";
+
+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-mantine-v8` 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
+
+- 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.

package/src/components/Modal/MODAL_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,32 @@
+# Modal Implementation Notes
+
+## Architecture
+
+The `Modal` component strictly wraps Mantine's `<Modal>` primitive. We strip Mantine's abstract native styling props (`size`, `radius`, `shadow`) via the `overStyled` interface and strictly inject CSS variable definitions onto the internal node abstractions (`.content`, `.header`, `.body`, `.title`).
+
+## Limitations & Structural Decisions
+
+### 1. Stripped `size` Prop
+
+Mantine natively exposes an abstract `size` prop (`"sm" | "md" | "lg" | "xl"`) that scales the Modal geometry. The Recursica UI Kit explicitly dictates strict geometric bounding boxes: `max-width: 960px` and `min-width: 304px`. To enforce absolute parity with the design system, the `size` prop has been intentionally omitted from the component's interface. The width of the Modal will scale fluidly strictly between these Figma-driven pixel limits.
+
+### 2. Scroll Dividers behavior
+
+Mantine internally handles scroll state natively, dynamically showing/hiding a divider line when content overflows in `.body`. This logic is tightly coupled to React DOM measurements internally. Our component inherits this dynamic behavior rather than statically rendering a permanent divider, matching Mantine's robust overflow UX. However, we aggressively override the generated `border-bottom` via CSS modules to ensure that when it _does_ appear, it correctly utilizes the `--recursica_ui-kit_components_modal_colors_scroll-divider` variable and `--recursica_ui-kit_components_modal_properties_scroll-divider-thickness` token.
+
+### 3. Title truncation
+
+`.title` truncates with an ellipsis (`overflow: clip; overflow-clip-margin: 0.35em`, `white-space: nowrap`, `text-overflow: ellipsis`) rather than wrapping. It also needs `flex: 1 1 auto; min-width: 0;` since it's a flex child of `.header` alongside the close button — without `min-width: 0`, a flex item won't shrink below its content's intrinsic width, so ellipsis never engages. `.header`'s `display: flex` is likewise explicit rather than relied upon from Mantine's own header class, so the mui-adapter's plain-`<div>` header gets identical layout.
+
+`.title` used plain `overflow: hidden` until 2026-08-28 (Matt Massey) — it clipped descenders
+(e.g. "g" in a long title) whenever `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, same project-wide fix as Chip's `CHIP_IMPLEMENTATION_NOTES.md`.
+
+### 4. Width was pinned to Mantine's `md` size, not content-driven
+
+Despite §1 above, `.content` never actually scaled fluidly: Mantine's own CSS sets `flex: 0 0 var(--modal-size)` (defaulting to 440px) on the Content element, and our module only added `min-width`/`max-width` without touching `flex`. A fixed flex-basis with `flex-shrink: 0` pins the box at exactly 440px regardless of those bounds, so they were unreachable dead code — e.g. "Authentication Required" (the `Default` story's title) didn't fit at 440px and silently wrapped to two lines. Overriding to `flex: 0 1 auto` makes the width shrink-to-fit the content within `min-width`/`max-width`, which is what makes title truncation (§3) only kick in once a title would exceed `max-width` rather than truncating titles that would otherwise fit. `.content[data-full-screen]` restores Mantine's own `flex: 0 0 100%` since the shrink-to-fit override would otherwise stop `fullScreen` from filling the viewport.
+
+### 5. Close button restyled to match Button
+
+`.close` reuses Button's text-variant/icon-only/small tokens (radius, padding, background/icon color, hover overlay, focus ring) instead of Mantine's native CloseButton look. Two overrides need `!important`/an explicit reset to win: Mantine's `CloseIcon` sizes itself via an inline `style` (`--cb-icon-size`, default `70%`), which beats any plain class rule — same category as Tree's `--level-offset` override; and Mantine's own subtle-variant `:hover` background (from `CloseButton.css`) is pinned back to the Button background token so only our `::after` overlay renders hover feedback.