@recursica/mantine-adapter 0.11.0 → 0.12.0

package/dist/src/components/Menu/Menu.d.ts

@@ -1,3 +1,85 @@
-import { default as React } from 'react';
-export type MenuProps = React.HTMLAttributes<HTMLDivElement>;
-export declare const Menu: React.FC<MenuProps>;
+import { MenuProps as MantineMenuProps, MenuTargetProps as MantineMenuTargetProps, MenuDropdownProps as MantineMenuDropdownProps, MenuItemProps as MantineMenuItemProps, MenuDividerProps as MantineMenuDividerProps, MenuLabelProps as MantineMenuLabelProps, MenuSubProps as MantineMenuSubProps, MenuSubTargetProps as MantineMenuSubTargetProps, MenuSubDropdownProps as MantineMenuSubDropdownProps } from '@mantine/core';
+import { RecursicaOverStyled } from '../../utils/filterStylingProps';
+/**
+ * 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>;
+declare const MenuBase: {
+    ({ overStyled, ...rest }: MenuProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+/**
+ * Wrapper for the element that triggers the menu.
+ * Requires a single child element that supports ref forwarding.
+ */
+export type MenuTargetProps = MantineMenuTargetProps;
+declare const MenuTarget: {
+    (props: MenuTargetProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+/** The dropdown panel containing menu items, dividers, and labels. */
+export type MenuDropdownProps = RecursicaOverStyled<MantineMenuDropdownProps>;
+declare const MenuDropdown: import('react').ForwardRefExoticComponent<MenuDropdownProps & import('react').RefAttributes<HTMLDivElement>>;
+/**
+ * An individual actionable item within the menu dropdown.
+ *
+ * **Note:** Mantine's `color` prop is stripped in strict mode to enforce
+ * design token adherence. Use `overStyled={true}` if you need to bypass.
+ */
+export type MenuItemProps = RecursicaOverStyled<Omit<MantineMenuItemProps, "color">>;
+declare const MenuItem: import('react').ForwardRefExoticComponent<MenuItemProps & import('react').RefAttributes<HTMLButtonElement>>;
+/** A visual separator between groups of menu items. */
+export type MenuDividerProps = RecursicaOverStyled<MantineMenuDividerProps>;
+declare const MenuDivider: import('react').ForwardRefExoticComponent<MenuDividerProps & import('react').RefAttributes<HTMLHRElement>>;
+/** A non-interactive section label used to categorize groups of menu items. */
+export type MenuLabelProps = RecursicaOverStyled<MantineMenuLabelProps>;
+declare const MenuLabel: import('react').ForwardRefExoticComponent<MenuLabelProps & import('react').RefAttributes<HTMLDivElement>>;
+/** Container for a submenu, wrapping Menu.Sub.Target and Menu.Sub.Dropdown. */
+export type MenuSubProps = MantineMenuSubProps;
+declare const MenuSubBase: {
+    (props: MenuSubProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+/** Wrapper for the element that triggers the submenu. */
+export type MenuSubTargetProps = MantineMenuSubTargetProps;
+declare const MenuSubTarget: {
+    (props: MenuSubTargetProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+/**
+ * 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">>;
+declare const MenuSubItem: import('react').ForwardRefExoticComponent<MenuSubItemProps & import('react').RefAttributes<HTMLButtonElement>>;
+/** The dropdown panel for a submenu. */
+export type MenuSubDropdownProps = RecursicaOverStyled<MantineMenuSubDropdownProps>;
+declare const MenuSubDropdown: import('react').ForwardRefExoticComponent<MenuSubDropdownProps & import('react').RefAttributes<HTMLDivElement>>;
+type MenuSubComponent = typeof MenuSubBase & {
+    Target: typeof MenuSubTarget;
+    Item: typeof MenuSubItem;
+    Dropdown: typeof MenuSubDropdown;
+};
+type MenuComponent = typeof MenuBase & {
+    Target: typeof MenuTarget;
+    Dropdown: typeof MenuDropdown;
+    Item: typeof MenuItem;
+    Divider: typeof MenuDivider;
+    Label: typeof MenuLabel;
+    Sub: MenuSubComponent;
+};
+export declare const Menu: MenuComponent;
+export {};

package/package.json

@@ -11,7 +11,7 @@
     "type": "git",
     "url": "git+https://github.com/borderux/recursica.git"
   },
-  "version": "0.11.0",
+  "version": "0.12.0",
   "type": "module",
   "main": "./dist/mantine-adapter.cjs",
   "module": "./dist/mantine-adapter.js",

package/src/components/Menu/MENU_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,78 @@
+# Menu – Implementation Notes
+
+Decisions and design tweaks strictly tailored for the UI Kit's Menu wrapped against `@mantine/core`. This is a living document that tracks _why_ specific logic decisions exist.
+
+---
+
+## 1. Composable API Preservation (1:1 Mapping)
+
+**Decision:** We maintain the exact library composition API structure (`<Menu>`, `<Menu.Target>`, `<Menu.Dropdown>`, `<Menu.Item>`, `<Menu.Divider>`, `<Menu.Label>`, `<Menu.Sub>`, `<Menu.Sub.Target>`, `<Menu.Sub.Item>`, `<Menu.Sub.Dropdown>`) as a 1:1 React component mapping.
+
+**Implementation:** Mantine's Menu internally manages WAI-ARIA role assignments (`role="menu"`, `role="menuitem"`, `aria-haspopup`, `aria-expanded`, `aria-controls`), keyboard navigation (arrow keys, Enter, Escape), and focus trapping natively across its composable hierarchy. By preserving the exact sub-component tree, Recursica safely adopts all of these accessibility behaviors without reimplementation.
+
+---
+
+## 2. Hover State Overlay Technique
+
+**Decision:** We nullify Mantine's native hover background on `Menu.Item` and exclusively utilize Recursica's hover structure via a `::after` pseudo-element overlay.
+
+**Implementation:** The `.item::after` pseudo-object dynamically pulls `hover-color` & `hover-opacity` bindings from the Recursica token system. Mantine natively changes `background-color` on item hover which would override our token-driven colors. We enforce `background-color` to remain the unselected-item background on hover, then layer our pseudo-overlay on top. This is the same technique used in the Accordion component.
+
+---
+
+## 3. Selected vs Unselected Item States
+
+**Decision:** Menu items map to Recursica's `selected-item` and `unselected-item` color token groups.
+
+**Implementation:** The CSS module defaults all items to `unselected-item_*` tokens (background, text, opacity). Items with `[data-selected]` switch to `selected-item_*` tokens. This mapping is natively driven by Mantine's internal state tracking without React state hooks.
+
+---
+
+## 4. `color` Prop Stripping
+
+**Decision:** Mantine's `color` prop on `Menu.Item` (used for semantics like "danger/red") is explicitly stripped in strict mode.
+
+**Implementation:** The `color` prop is deleted from the sanitized props when `overStyled` is `false`. This enforces strict design token adherence — all item colors come from the CSS module referencing Recursica variables. Developers requiring custom color semantics must either:
+
+1. Use `overStyled={true}` as an explicit escape hatch
+2. Contribute a proper Recursica variant to the token system
+
+**Rationale:** The Recursica token set does not currently include danger-specific or semantic-color variants for menu items. Allowing arbitrary `color` values would break design system consistency.
+
+---
+
+## 5. Menu.Target Pass-Through
+
+**Decision:** `Menu.Target` is a transparent pass-through with no styling applied.
+
+**Implementation:** The target wrapper exists solely to manage Mantine's ref forwarding and event binding for the trigger element. No `filterStylingProps` or CSS module classes are applied — the trigger's appearance is entirely controlled by whatever component the integrator places inside it (e.g., `<Button>`).
+
+---
+
+## 6. Sub-Menu Support
+
+**Decision:** We wrap the full Mantine sub-menu hierarchy (`Menu.Sub`, `Menu.Sub.Target`, `Menu.Sub.Item`, `Menu.Sub.Dropdown`).
+
+**Implementation:** Sub-menu components inherit the same CSS module classes as their top-level counterparts since the Recursica token set does not distinguish sub-menu-specific styling. `Menu.Sub.Item` also strips the `color` prop in strict mode, consistent with `Menu.Item`. The sub-menu dropdown portal inherits the same `classNames` from the root Menu's `classNames` mapping.
+
+---
+
+## 7. Dropdown Container Padding
+
+**Decision:** The dropdown container uses `divider-item-gap` as its internal padding.
+
+**Implementation:** This ensures consistent spacing between the dropdown border and its content items. The gap token (`4px` by default) creates a subtle inset that visually separates items from the container edge, matching the Figma design specifications.
+
+---
+
+## 8. Minimal CSS Override Philosophy
+
+**Decision:** The CSS module only overrides visual design tokens (colors, typography, spacing, borders, shadows). All structural layout properties (flex, cursor, pointer-events, box-sizing, etc.) are deferred to Mantine's native behavior.
+
+**Implementation:** Unlike form-field components (e.g., Dropdown/TextField) which require deep structural overrides to strip Mantine's macro wrappers, the Menu is an overlay component where Mantine's native layout is already correct. We avoid setting:
+
+- `overflow` on the dropdown (Mantine renders sub-menu dropdowns inside the parent DOM tree using Floating UI absolute positioning — setting overflow clips them)
+- `display`, `align-items`, `width`, `cursor` on items (Mantine's button-based items already handle this)
+- `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.

package/src/components/Menu/Menu.module.css

@@ -0,0 +1,244 @@
+/* HARDCODED VALUES:
+   - border-style: solid. Structural rendering rule for the dropdown border (Mantine uses Paper which may not set border natively).
+   - opacity: 0.5 on disabled items. Recursica has no dedicated disabled-opacity token for menu items.
+   - NOTE: overflow is intentionally NOT set on .dropdown. Mantine renders sub-menu dropdowns
+     inside the parent dropdown DOM tree using Floating UI absolute positioning. Setting
+     overflow: hidden clips sub-menus; overflow-y: auto causes unwanted scrollbars.
+   - All structural layout (flex, cursor, pointer-events on disabled) is deferred to Mantine's
+     native behavior. We only override visual design tokens (colors, typography, spacing, borders).
+*/
+
+/* ======================================
+   DROPDOWN CONTAINER
+   ====================================== */
+
+.dropdown {
+  background-color: var(
+    --recursica_ui-kit_components_menu_properties_colors_background
+  );
+  border-style: solid; /* HARDCODE: Mantine Paper does not set border-style natively */
+  border-width: var(--recursica_ui-kit_components_menu_properties_border-size);
+  border-color: var(
+    --recursica_ui-kit_components_menu_properties_colors_border-color
+  );
+  border-radius: var(
+    --recursica_ui-kit_components_menu_properties_border-radius
+  );
+  box-shadow: var(--recursica_ui-kit_components_menu_properties_elevation);
+
+  min-width: var(--recursica_ui-kit_components_menu_properties_min-width);
+  max-width: var(--recursica_ui-kit_components_menu_properties_max-width);
+
+  padding: var(
+    --recursica_ui-kit_components_menu-item_properties_divider-item-gap
+  );
+}
+
+/* ======================================
+   MENU ITEM
+   ====================================== */
+
+.item {
+  position: relative;
+
+  /* Geometry */
+  padding: var(
+      --recursica_ui-kit_components_menu-item_properties_vertical-padding
+    )
+    var(--recursica_ui-kit_components_menu-item_properties_horizontal-padding);
+  border-radius: var(
+    --recursica_ui-kit_components_menu-item_properties_border-radius
+  );
+
+  /* Typography */
+  font-family: var(
+    --recursica_ui-kit_components_menu-item_properties_text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_menu-item_properties_text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_menu-item_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_menu-item_properties_text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_menu-item_properties_text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_menu-item_properties_text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_menu-item_properties_text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_menu-item_properties_text_text-transform
+  );
+
+  /* Default State: Unselected */
+  background-color: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_unselected-item_background
+  );
+  color: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_unselected-item_text
+  );
+  opacity: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_unselected-item_opacity
+  );
+}
+
+/* Override Mantine's native hover background to use our overlay technique */
+.item:hover {
+  background-color: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_unselected-item_background
+  );
+}
+
+/* Hover overlay using ::after pseudo-element (same technique as Accordion) */
+.item::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+  z-index: 0;
+  pointer-events: none;
+  background-color: var(
+    --recursica_ui-kit_components_menu-item_properties_hover-color
+  );
+  opacity: 0;
+  transition: opacity 150ms ease;
+}
+
+.item:hover:not([data-disabled])::after {
+  opacity: var(
+    --recursica_ui-kit_components_menu-item_properties_hover-opacity,
+    0.1
+  );
+}
+
+/* Selected item state */
+.item[data-selected] {
+  background-color: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_selected-item_background
+  );
+  color: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_selected-item_text
+  );
+  opacity: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_selected-item_opacity
+  );
+}
+
+/* Hovered item state (keyboard navigation) */
+.item[data-hovered] {
+  background-color: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_unselected-item_background
+  );
+}
+.item[data-hovered]::after {
+  opacity: var(
+    --recursica_ui-kit_components_menu-item_properties_hover-opacity,
+    0.1
+  );
+}
+
+/* Disabled item */
+.item[data-disabled] {
+  /* HARDCODE: 0.5 opacity fallback; no dedicated disabled-opacity token for menu items */
+  opacity: 0.5;
+}
+
+/* ======================================
+   ITEM LABEL
+   ====================================== */
+
+.itemLabel {
+  position: relative;
+  z-index: 1;
+  color: inherit;
+}
+
+/* ======================================
+   ITEM SECTION (LEFT / RIGHT ICONS)
+   ====================================== */
+
+.itemSection {
+  position: relative;
+  z-index: 1;
+  color: inherit;
+}
+
+/* ======================================
+   DIVIDER
+   ====================================== */
+
+.divider {
+  height: var(
+    --recursica_ui-kit_components_menu-item_properties_divider-height
+  );
+  background-color: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_divider-color
+  );
+  opacity: var(
+    --recursica_ui-kit_components_menu-item_properties_divider-opacity
+  );
+  margin: var(
+      --recursica_ui-kit_components_menu-item_properties_divider-item-gap
+    )
+    0;
+}
+
+/* ======================================
+   SECTION LABEL
+   ====================================== */
+
+.label {
+  padding: var(
+      --recursica_ui-kit_components_menu-item_properties_vertical-padding
+    )
+    var(--recursica_ui-kit_components_menu-item_properties_horizontal-padding);
+
+  /* Supporting Text Typography */
+  font-family: var(
+    --recursica_ui-kit_components_menu-item_properties_supporting-text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_menu-item_properties_supporting-text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_menu-item_properties_supporting-text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_menu-item_properties_supporting-text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_menu-item_properties_supporting-text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_menu-item_properties_supporting-text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_menu-item_properties_supporting-text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_menu-item_properties_supporting-text_text-transform
+  );
+
+  color: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_unselected-item_supporting-text-color
+  );
+  opacity: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_unselected-item_supporting-text-opacity
+  );
+}
+
+/* ======================================
+   SUB-MENU CHEVRON
+   ====================================== */
+
+.chevron {
+  position: relative;
+  z-index: 1;
+  color: inherit;
+}