@recursica/mui-adapter 0.5.0 → 0.6.0

package/src/components/Menu/Menu.tsx

@@ -1,8 +1,321 @@
-import React from "react";
-import "./Menu.module.css";
+import { forwardRef } from "react";
+import { Menu as MuiMenu, type MenuProps as MuiMenuProps } from "@mui/material";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Menu.module.css";
 
-export type MenuProps = React.HTMLAttributes<HTMLDivElement>;
+// ============================================================
+// MENU ROOT
+// ============================================================
 
-export const Menu: React.FC<MenuProps> = (props) => {
-  return <div {...props}>Menu</div>;
+/**
+ * Recursica Menu component wrapping Mui'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<MuiMenuProps>;
+
+const MenuBase = function Menu({ overStyled = false, ...rest }: MenuProps) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+
+  // Bind CSS module classes to Mui's internal classNames API
+  const mergedClassNames: Partial<Record<string, string>> = {
+    dropdown: styles.dropdown,
+    item: styles.item,
+    itemLabel: styles.itemLabel,
+    itemSection: styles.itemSection,
+    divider: styles.divider,
+    label: styles.label,
+    chevron: styles.chevron,
+  };
+
+  const classNamesProp = (sanitizedProps as Record<string, unknown>).classNames;
+  if (
+    classNamesProp &&
+    typeof classNamesProp === "object" &&
+    !Array.isArray(classNamesProp)
+  ) {
+    const o = classNamesProp as Record<string, string>;
+    Object.keys(o).forEach((key) => {
+      if (mergedClassNames[key]) {
+        mergedClassNames[key] = `${mergedClassNames[key]} ${o[key]}`;
+      } else {
+        mergedClassNames[key] = o[key];
+      }
+    });
+  }
+
+  return (
+    <MuiMenu
+      classes={mergedClassNames}
+      {...(sanitizedProps as unknown as MuiMenuProps)}
+    />
+  );
+};
+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 = any;
+
+const MenuTarget = function MenuTarget(props: MenuTargetProps) {
+  return <div {...props} />;
 };
+MenuTarget.displayName = "MenuTarget";
+
+// ============================================================
+// MENU DROPDOWN
+// ============================================================
+
+/** The dropdown panel containing menu items, dividers, and labels. */
+export type MenuDropdownProps = RecursicaOverStyled<any>;
+
+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 (
+      <div
+        ref={ref}
+        className={classNameProp}
+        {...(sanitizedProps as unknown as any)}
+      />
+    );
+  },
+);
+MenuDropdown.displayName = "MenuDropdown";
+
+// ============================================================
+// MENU ITEM
+// ============================================================
+
+/**
+ * An individual actionable item within the menu dropdown.
+ *
+ * **Note:** Mui'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<any, "color">>;
+
+const _MenuItem = forwardRef<HTMLButtonElement, MenuItemProps>(
+  function MenuItem({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    // Strip Mui's `color` prop to enforce token-driven styling
+    if (!overStyled) {
+      delete restRecord["color"];
+    }
+
+    const classNameProp = restRecord.className as string | undefined;
+
+    return (
+      <div
+        ref={ref}
+        className={classNameProp}
+        {...(sanitizedProps as unknown as any)}
+      />
+    );
+  },
+);
+_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 = _MenuItem as any;
+
+// ============================================================
+// MENU DIVIDER
+// ============================================================
+
+/** A visual separator between groups of menu items. */
+export type MenuDividerProps = RecursicaOverStyled<any>;
+
+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 (
+      <hr
+        ref={ref}
+        className={classNameProp}
+        {...(sanitizedProps as unknown as any)}
+      />
+    );
+  },
+);
+MenuDivider.displayName = "MenuDivider";
+
+// ============================================================
+// MENU LABEL
+// ============================================================
+
+/** A non-interactive section label used to categorize groups of menu items. */
+export type MenuLabelProps = RecursicaOverStyled<any>;
+
+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 (
+    <div
+      ref={ref}
+      className={classNameProp}
+      {...(sanitizedProps as unknown as any)}
+    />
+  );
+});
+MenuLabel.displayName = "MenuLabel";
+
+// ============================================================
+// MENU SUB (SUBMENU CONTAINER)
+// ============================================================
+
+/** Container for a submenu, wrapping Menu.Sub.Target and Menu.Sub.Dropdown. */
+export type MenuSubProps = any;
+
+const MenuSubBase = function MenuSub(props: MenuSubProps) {
+  return <div {...props} />;
+};
+MenuSubBase.displayName = "MenuSub";
+
+// ============================================================
+// MENU SUB TARGET
+// ============================================================
+
+/** Wrapper for the element that triggers the submenu. */
+export type MenuSubTargetProps = any;
+
+const MenuSubTarget = function MenuSubTarget(props: MenuSubTargetProps) {
+  return <div {...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<any, "color">>;
+
+const _MenuSubItem = forwardRef<HTMLButtonElement, MenuSubItemProps>(
+  function MenuSubItem({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    if (!overStyled) {
+      delete restRecord["color"];
+    }
+
+    const classNameProp = restRecord.className as string | undefined;
+
+    return (
+      <div
+        ref={ref}
+        className={classNameProp}
+        {...(sanitizedProps as unknown as any)}
+      />
+    );
+  },
+);
+_MenuSubItem.displayName = "MenuSubItem";
+
+/**
+ * A menu item that acts as a submenu trigger.
+ *
+ * Supports polymorphism via the `component` prop.
+ */
+const MenuSubItem = _MenuSubItem as any;
+
+// ============================================================
+// MENU SUB DROPDOWN
+// ============================================================
+
+/** The dropdown panel for a submenu. */
+export type MenuSubDropdownProps = RecursicaOverStyled<any>;
+
+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 (
+      <div
+        ref={ref}
+        className={classNameProp}
+        {...(sanitizedProps as unknown as any)}
+      />
+    );
+  },
+);
+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/Modal/Modal.module.css

@@ -1,36 +1,172 @@
 /* EXEMPTIONS:
-   This component is a placeholder stub. Once fully implemented, its specific
-   tokens will be fully wired up to direct styles. */
-
-/* recursica-ignore: --recursica_ui-kit_components_modal_properties_border-radius */
-/* recursica-ignore: --recursica_ui-kit_components_modal_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_modal_properties_button-gap */
-/* recursica-ignore: --recursica_ui-kit_components_modal_properties_colors_background */
-/* recursica-ignore: --recursica_ui-kit_components_modal_properties_colors_border-color */
-/* recursica-ignore: --recursica_ui-kit_components_modal_properties_colors_content */
-/* recursica-ignore: --recursica_ui-kit_components_modal_properties_colors_scroll-divider */
-/* recursica-ignore: --recursica_ui-kit_components_modal_properties_colors_title */
-/* recursica-ignore: --recursica_ui-kit_components_modal_properties_content-style_fontFamily */
-/* recursica-ignore: --recursica_ui-kit_components_modal_properties_content-style_fontSize */
-/* recursica-ignore: --recursica_ui-kit_components_modal_properties_content-style_fontStyle */
-/* recursica-ignore: --recursica_ui-kit_components_modal_properties_content-style_fontWeight */
-/* recursica-ignore: --recursica_ui-kit_components_modal_properties_content-style_letterSpacing */
-/* recursica-ignore: --recursica_ui-kit_components_modal_properties_content-style_lineHeight */
-/* recursica-ignore: --recursica_ui-kit_components_modal_properties_content-style_textCase */
-/* recursica-ignore: --recursica_ui-kit_components_modal_properties_content-style_textDecoration */
-/* recursica-ignore: --recursica_ui-kit_components_modal_properties_elevation */
-/* recursica-ignore: --recursica_ui-kit_components_modal_properties_header-style_fontFamily */
-/* recursica-ignore: --recursica_ui-kit_components_modal_properties_header-style_fontSize */
-/* recursica-ignore: --recursica_ui-kit_components_modal_properties_header-style_fontStyle */
-/* recursica-ignore: --recursica_ui-kit_components_modal_properties_header-style_fontWeight */
-/* recursica-ignore: --recursica_ui-kit_components_modal_properties_header-style_letterSpacing */
-/* recursica-ignore: --recursica_ui-kit_components_modal_properties_header-style_lineHeight */
-/* recursica-ignore: --recursica_ui-kit_components_modal_properties_header-style_textCase */
-/* recursica-ignore: --recursica_ui-kit_components_modal_properties_header-style_textDecoration */
-/* recursica-ignore: --recursica_ui-kit_components_modal_properties_horizontal-padding */
-/* recursica-ignore: --recursica_ui-kit_components_modal_properties_max-height */
-/* recursica-ignore: --recursica_ui-kit_components_modal_properties_max-width */
-/* recursica-ignore: --recursica_ui-kit_components_modal_properties_min-height */
-/* recursica-ignore: --recursica_ui-kit_components_modal_properties_min-width */
-/* recursica-ignore: --recursica_ui-kit_components_modal_properties_scroll-divider-thickness */
-/* recursica-ignore: --recursica_ui-kit_components_modal_properties_vertical-padding */
+   - content-style and header-style parent variables represent raw JSON styling objects rather than 
+     direct CSS variables and cannot be applied directly in standard CSS files.
+     Sub-properties are fully and individually mapped to elements natively. */
+/* recursica-ignore: --recursica_ui-kit_components_modal_properties_content-style */
+/* recursica-ignore: --recursica_ui-kit_components_modal_properties_header-style */
+
+.root {
+}
+
+.inner {
+  /* Mantine applies padding to inner to keep modal away from edges. We rely on content constraints. */
+}
+
+.content {
+  /* Geometric Bounds */
+  min-width: var(--recursica_ui-kit_components_modal_properties_min-width);
+  max-width: var(--recursica_ui-kit_components_modal_properties_max-width);
+  min-height: var(--recursica_ui-kit_components_modal_properties_min-height);
+
+  /* Restrict max-height to either the UI Kit max or the viewport bounds to force internal scrolling */
+  max-height: min(
+    var(--recursica_ui-kit_components_modal_properties_max-height),
+    calc(100vh - 4rem)
+  );
+  overflow: hidden;
+
+  /* Box model */
+  border-radius: var(
+    --recursica_ui-kit_components_modal_properties_border-radius
+  );
+  border-width: var(--recursica_ui-kit_components_modal_properties_border-size);
+  border-color: var(
+    --recursica_ui-kit_components_modal_properties_colors_border-color
+  );
+  border-style: solid;
+
+  /* Appearance */
+  background-color: var(
+    --recursica_ui-kit_components_modal_properties_colors_background
+  );
+  box-shadow: var(--recursica_ui-kit_components_modal_properties_elevation);
+
+  /* Internal Flex container to trap header and let body scroll */
+  display: flex;
+  flex-direction: column;
+}
+
+.header {
+  padding: var(--recursica_ui-kit_components_modal_properties_vertical-padding)
+    var(--recursica_ui-kit_components_modal_properties_horizontal-padding);
+  background-color: transparent; /* Inherit from content */
+}
+
+.title {
+  color: var(--recursica_ui-kit_components_modal_properties_colors_title);
+
+  /* Direct Figma Typography Mapping */
+  font-family: var(
+    --recursica_ui-kit_components_modal_properties_header-style_fontFamily
+  );
+  font-size: var(
+    --recursica_ui-kit_components_modal_properties_header-style_fontSize
+  );
+  font-style: var(
+    --recursica_ui-kit_components_modal_properties_header-style_fontStyle
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_modal_properties_header-style_fontWeight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_modal_properties_header-style_letterSpacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_modal_properties_header-style_lineHeight
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_modal_properties_header-style_textCase
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_modal_properties_header-style_textDecoration
+  );
+}
+
+.bodyWrapper {
+  /* This is the container that overrides Mantine's native Body. It strips padding and acts as a flex column. */
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  flex: 1 1 auto;
+  overflow: hidden;
+  min-height: 0; /* Critical for flex child scrolling constraint */
+}
+
+.scrollArea {
+  padding: var(--recursica_ui-kit_components_modal_properties_vertical-padding)
+    var(--recursica_ui-kit_components_modal_properties_horizontal-padding);
+
+  /* Internal scrolling */
+  flex: 1 1 auto;
+  overflow-y: auto;
+  min-height: 0; /* Critical for flex child scrolling constraint */
+
+  color: var(--recursica_ui-kit_components_modal_properties_colors_content);
+
+  /* Direct Figma Typography Mapping */
+  font-family: var(
+    --recursica_ui-kit_components_modal_properties_content-style_fontFamily
+  );
+  font-size: var(
+    --recursica_ui-kit_components_modal_properties_content-style_fontSize
+  );
+  font-style: var(
+    --recursica_ui-kit_components_modal_properties_content-style_fontStyle
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_modal_properties_content-style_fontWeight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_modal_properties_content-style_letterSpacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_modal_properties_content-style_lineHeight
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_modal_properties_content-style_textCase
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_modal_properties_content-style_textDecoration
+  );
+
+  /* Ensure button gap token is easily usable if developers use standard spacing */
+  --modal-button-gap: var(
+    --recursica_ui-kit_components_modal_properties_button-gap
+  );
+
+  /* Smooth divider transitions */
+  transition: border-color 0.15s ease;
+  border-top: var(
+      --recursica_ui-kit_components_modal_properties_scroll-divider-thickness
+    )
+    solid transparent;
+  border-bottom: var(
+      --recursica_ui-kit_components_modal_properties_scroll-divider-thickness
+    )
+    solid transparent;
+}
+
+.scrollArea[data-scrolled-top] {
+  border-top-color: var(
+    --recursica_ui-kit_components_modal_properties_colors_scroll-divider
+  );
+}
+
+.scrollArea[data-scrolled-bottom] {
+  border-bottom-color: var(
+    --recursica_ui-kit_components_modal_properties_colors_scroll-divider
+  );
+}
+
+.footer {
+  padding: var(--recursica_ui-kit_components_modal_properties_vertical-padding)
+    var(--recursica_ui-kit_components_modal_properties_horizontal-padding);
+  background-color: transparent;
+  display: flex;
+  justify-content: flex-end;
+  gap: var(--recursica_ui-kit_components_modal_properties_button-gap);
+}
+
+.close {
+  /* Inherits standard icon button tokens natively, but we can override if required */
+}

package/src/components/Modal/Modal.stories.tsx

@@ -1,35 +1,79 @@
+import { useState } from "react";
 import type { Meta, StoryObj } from "@storybook/react";
-import { Modal } from "./Modal";
-import { ComingSoon } from "@recursica/storybook-template";
+import { Modal, type ModalProps } from "./Modal";
+import { Button } from "../Button";
 
 const meta: Meta<typeof Modal> = {
-  title: "UI-Kit/🚧 Modal",
+  title: "UI-Kit/Modal",
   component: Modal,
   tags: ["autodocs"],
-  parameters: {
-    controls: {
-      include: [
-        "layer",
-        "withLayer",
-        "children",
-        "component",
-        "variant",
-        "size",
-        "icon",
-        "disabled",
-        "href",
-        "onClick",
-        "onChange",
-        "value",
-        "checked",
-      ],
-    },
+  argTypes: {
+    opened: { table: { disable: true } },
+    onClose: { table: { disable: true } },
+    defaultChecked: { table: { disable: true } },
   },
 };
 
 export default meta;
+
 type Story = StoryObj<typeof Modal>;
 
+const DefaultWrapper = (args: ModalProps) => {
+  const [opened, setOpened] = useState(false);
+  return (
+    <>
+      <Modal {...args} opened={opened} onClose={() => setOpened(false)}>
+        Please log in to continue accessing this feature.
+        <Modal.Footer>
+          <Button variant="outline" onClick={() => setOpened(false)}>
+            Cancel
+          </Button>
+          <Button onClick={() => setOpened(false)}>Confirm</Button>
+        </Modal.Footer>
+      </Modal>
+      <Button onClick={() => setOpened(true)}>Open Modal</Button>
+    </>
+  );
+};
+
 export const Default: Story = {
-  render: () => <ComingSoon componentName="Modal" />,
+  args: {
+    title: "Authentication Required",
+  },
+  render: (args) => <DefaultWrapper {...args} />,
+};
+
+const ScrollingWrapper = (args: ModalProps) => {
+  const [opened, setOpened] = useState(false);
+  return (
+    <>
+      <Modal {...args} opened={opened} onClose={() => setOpened(false)}>
+        <p>
+          This modal demonstrates the dynamically injected scroll dividers. When
+          this body content overflows, the borders between the Header and Footer
+          automatically appear to define the scrolling boundary.
+        </p>
+        {Array(20)
+          .fill(0)
+          .map((_, i) => (
+            <p key={i}>Scrolling content block {i + 1}...</p>
+          ))}
+        {/* The new Footer abstraction */}
+        <Modal.Footer>
+          <Button variant="outline" onClick={() => setOpened(false)}>
+            Decline
+          </Button>
+          <Button onClick={() => setOpened(false)}>Accept Terms</Button>
+        </Modal.Footer>
+      </Modal>
+      <Button onClick={() => setOpened(true)}>Open Scrolling Modal</Button>
+    </>
+  );
+};
+
+export const ScrollingContent: Story = {
+  args: {
+    title: "Terms and Conditions",
+  },
+  render: (args) => <ScrollingWrapper {...args} />,
 };