@recursica/mui-adapter 0.4.0 → 0.6.0

package/src/components/Modal/Modal.module.css

@@ -0,0 +1,172 @@
+/* EXEMPTIONS:
+   - 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} />,
 };

package/src/components/Modal/Modal.tsx

@@ -1,7 +1,220 @@
 import React from "react";
+import {
+  Modal as MuiModal,
+  type ModalProps as MuiModalProps,
+} from "@mui/material";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Modal.module.css";
 
-export type ModalProps = React.HTMLAttributes<HTMLDivElement>;
+/**
+ * Properties for the strictly-tokenized Modal component.
+ * Native Mui abstract properties like `size`, `radius`, and `shadow` have been stripped out
+ * because they directly conflict with the non-negotiable pixel boundaries defined in the Recursica UI Kit.
+ */
+export type ModalProps = RecursicaOverStyled<
+  Omit<MuiModalProps, "size" | "radius" | "shadow">
+>;
 
-export const Modal: React.FC<ModalProps> = (props) => {
-  return <div {...props}>Modal</div>;
+/**
+ * The `Modal` component displays a window overlaid on the primary viewport.
+ *
+ * **Recursica Abstract:**
+ * This component acts as a strict structural wrapper around Mui's `<Modal>`.
+ * It automatically enforces Figma UI Kit geometries (`max-width: 960px`, `min-width: 304px`)
+ * and handles internal body scrolling explicitly via CSS module overrides.
+ *
+ * @example
+ * ```tsx
+ * <Modal opened={opened} onClose={close} title="Hello World">
+ *   Modal Content
+ * </Modal>
+ * ```
+ */
+const ModalInner = React.forwardRef<HTMLDivElement, ModalProps>(function Modal(
+  {
+    overStyled = false,
+    children,
+    title,
+    withCloseButton = true,
+    overlayProps,
+    withOverlay = true,
+    closeButtonProps,
+    ...rest
+  },
+  ref,
+) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+
+  const mergedClassNames: Partial<Record<string, string>> = {
+    root: styles.root,
+    inner: styles.inner,
+    content: styles.content,
+    header: styles.header,
+    title: styles.title,
+    close: styles.close,
+  };
+
+  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 (
+    <div
+      ref={ref}
+      classes={mergedClassNames}
+      {...(sanitizedProps as unknown as Omit<
+        MuiModalProps,
+        "size" | "radius" | "shadow"
+      >)}
+    >
+      {withOverlay && <div {...overlayProps} />}
+      <div>
+        {(title || withCloseButton) && (
+          <div>
+            {title && <div>{title}</div>}
+            {withCloseButton && <div {...closeButtonProps} />}
+          </div>
+        )}
+        <ModalBody>{children}</ModalBody>
+      </div>
+    </div>
+  );
+});
+
+ModalInner.displayName = "Modal";
+
+/**
+ * The `Modal.Footer` provides a perfectly padded container for modal actions.
+ *
+ * **Recursica Abstract:**
+ * By default, this container aligns its children to the right (`justify-content: flex-end`)
+ * and applies the standard Figma button-gap spacing.
+ *
+ * > [!IMPORTANT]
+ * > **Button Hierarchy:** Recursica design language explicitly requires that the
+ * > primary action button MUST be the right-most element, with the secondary
+ * > (outline variant) action placed immediately to the left of it.
+ */
+const ModalFooter = React.forwardRef<
+  HTMLDivElement,
+  React.ComponentPropsWithoutRef<"div">
+>(function ModalFooter({ className, ...rest }, ref) {
+  return (
+    <div
+      ref={ref}
+      className={`${styles.footer} ${className || ""}`}
+      {...rest}
+    />
+  );
+});
+ModalFooter.displayName = "Modal.Footer";
+
+const ModalBody = React.forwardRef<
+  HTMLDivElement,
+  React.ComponentPropsWithoutRef<typeof MuiModal.Body>
+>(function ModalBody({ className, onScroll, children, ...rest }, ref) {
+  const internalRef = React.useRef<HTMLDivElement>(null);
+  const [scrolledTop, setScrolledTop] = React.useState(false);
+  const [scrolledBottom, setScrolledBottom] = React.useState(false);
+
+  const checkScroll = React.useCallback(() => {
+    if (internalRef.current) {
+      const { scrollTop, scrollHeight, clientHeight } = internalRef.current;
+      setScrolledTop(scrollTop > 0);
+      setScrolledBottom(Math.ceil(scrollTop + clientHeight) < scrollHeight);
+    }
+  }, []);
+
+  // Re-check scroll on mount and window resize
+  React.useEffect(() => {
+    checkScroll();
+    window.addEventListener("resize", checkScroll);
+    return () => window.removeEventListener("resize", checkScroll);
+  }, [checkScroll, children]);
+
+  const handleScroll = (e: React.UIEvent<HTMLDivElement>) => {
+    checkScroll();
+    onScroll?.(e);
+  };
+
+  // Intercept children to pull Modal.Footer out of the scrolling container
+  let footer: React.ReactNode = null;
+  const bodyChildren: React.ReactNode[] = [];
+
+  React.Children.forEach(children, (child) => {
+    if (
+      React.isValidElement(child) &&
+      (child.type === ModalFooter ||
+        (child.type as React.ComponentType)?.displayName === "Modal.Footer")
+    ) {
+      footer = child;
+    } else {
+      bodyChildren.push(child);
+    }
+  });
+
+  return (
+    <div
+      {...rest}
+      ref={(node) => {
+        if (typeof ref === "function") ref(node);
+        else if (ref)
+          (ref as React.MutableRefObject<HTMLDivElement | null>).current = node;
+      }}
+      className={`${styles.bodyWrapper} ${className || ""}`}
+    >
+      <div
+        ref={internalRef}
+        onScroll={handleScroll}
+        data-scrolled-top={scrolledTop || undefined}
+        data-scrolled-bottom={scrolledBottom || undefined}
+        className={styles.scrollArea}
+      >
+        {bodyChildren}
+      </div>
+      {footer}
+    </div>
+  );
+});
+ModalBody.displayName = "Modal.Body";
+
+interface ModalComponent
+  extends React.ForwardRefExoticComponent<
+    ModalProps & React.RefAttributes<HTMLDivElement>
+  > {
+  Root: typeof MuiModal.Root;
+  Overlay: typeof MuiModal.Overlay;
+  Content: typeof MuiModal.Content;
+  Header: typeof MuiModal.Header;
+  Title: typeof MuiModal.Title;
+  CloseButton: typeof MuiModal.CloseButton;
+  Body: typeof ModalBody;
+  Footer: typeof ModalFooter;
+}
+
+export const Modal = ModalInner as ModalComponent & {
+  Footer: typeof ModalFooter;
 };
+Modal.Root = MuiModal.Root;
+Modal.Overlay = MuiModal.Overlay;
+Modal.Content = MuiModal.Content;
+Modal.Header = MuiModal.Header;
+Modal.Title = MuiModal.Title;
+Modal.CloseButton = MuiModal.CloseButton;
+Modal.Body = ModalBody;
+Modal.Footer = ModalFooter;