@recursica/adapter-mantine-v8 1.0.0

package/src/components/Modal/Modal.tsx

@@ -0,0 +1,368 @@
+import React from "react";
+import {
+  Modal as MantineModal,
+  type ModalProps as MantineModalProps,
+  type ModalRootProps as MantineModalRootProps,
+  type ModalOverlayProps as MantineModalOverlayProps,
+  type ModalContentProps as MantineModalContentProps,
+  type ModalHeaderProps as MantineModalHeaderProps,
+  type ModalTitleProps as MantineModalTitleProps,
+  type ModalCloseButtonProps as MantineModalCloseButtonProps,
+  type ModalBodyProps as MantineModalBodyProps,
+} from "@mantine/core";
+import {
+  filterStylingProps,
+  omitUnsupportedProps,
+  mergeClassNames,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Modal.module.css";
+
+import { type RecursicaModalProps } from "@recursica/adapter-common";
+
+/**
+ * Properties for the strictly-tokenized Modal component.
+ * Native Mantine 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<MantineModalProps, "size" | "radius" | "shadow"> & RecursicaModalProps
+>;
+
+/**
+ * The `Modal` component displays a window overlaid on the primary viewport.
+ *
+ * **Recursica Abstract:**
+ * This component acts as a strict structural wrapper around Mantine'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,
+) {
+  // 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 = [
+    "size", // Modal width/height are enforced via CSS module tokens (min/max-width, min/max-height), not Mantine's `size` scale.
+    "radius", // Modal corner radius is token-driven via `.content` in Modal.module.css, not Mantine's `radius` prop.
+  ] as const satisfies readonly (keyof MantineModalProps)[];
+
+  const sanitizedProps = omitUnsupportedProps(
+    filterStylingProps(rest, overStyled) as Record<string, unknown>,
+    UNSUPPORTED_PROPS,
+  ) as Partial<typeof rest>;
+
+  const mergedClassNames = mergeClassNames(
+    {
+      root: styles.root,
+      inner: styles.inner,
+      content: styles.content,
+      header: styles.header,
+      title: styles.title,
+      close: styles.close,
+    },
+    (sanitizedProps as Record<string, unknown>).classNames as
+      | Partial<Record<string, string>>
+      | undefined,
+  );
+
+  return (
+    <MantineModal.Root
+      ref={ref}
+      {...(sanitizedProps as unknown as Omit<
+        MantineModalProps,
+        "size" | "radius" | "shadow"
+      >)}
+      classNames={mergedClassNames}
+    >
+      {withOverlay && <MantineModal.Overlay {...overlayProps} />}
+      <MantineModal.Content>
+        {(title || withCloseButton) && (
+          <MantineModal.Header>
+            {title && <MantineModal.Title>{title}</MantineModal.Title>}
+            {withCloseButton && (
+              <MantineModal.CloseButton {...closeButtonProps} />
+            )}
+          </MantineModal.Header>
+        )}
+        <ModalBody>{children}</ModalBody>
+      </MantineModal.Content>
+    </MantineModal.Root>
+  );
+});
+
+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.
+ */
+export type ModalFooterProps = RecursicaOverStyled<
+  React.ComponentPropsWithoutRef<"div">
+>;
+
+const ModalFooter = React.forwardRef<HTMLDivElement, ModalFooterProps>(
+  function ModalFooter({ overStyled = false, className, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    return (
+      <div
+        ref={ref}
+        {...sanitizedProps}
+        className={`${styles.footer} ${className || ""}`}
+      />
+    );
+  },
+);
+ModalFooter.displayName = "Modal.Footer";
+
+export type ModalBodyProps = RecursicaOverStyled<MantineModalBodyProps>;
+
+const ModalBody = React.forwardRef<HTMLDivElement, ModalBodyProps>(
+  function ModalBody(
+    { overStyled = false, className, onScroll, children, ...rest },
+    ref,
+  ) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    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 (
+      <MantineModal.Body
+        {...sanitizedProps}
+        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}
+      </MantineModal.Body>
+    );
+  },
+);
+ModalBody.displayName = "Modal.Body";
+
+// ============================================================
+// MODAL SUB-COMPONENTS (wrapped so overStyled/filterStylingProps applies)
+// ============================================================
+
+export type ModalRootProps = RecursicaOverStyled<MantineModalRootProps>;
+
+// 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. `Modal.Root` is used directly for
+// advanced composition, so it doesn't benefit from the top-level `Modal`'s `Omit<>` protection.
+const MODAL_ROOT_UNSUPPORTED_PROPS = [
+  "size", // Modal width/height are enforced via CSS module tokens, not Mantine's `size` scale.
+  "radius", // Modal corner radius is token-driven via `.content` in Modal.module.css, not Mantine's `radius` prop.
+] as const satisfies readonly (keyof MantineModalRootProps)[];
+
+const ModalRoot = React.forwardRef<HTMLDivElement, ModalRootProps>(
+  function ModalRoot({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = omitUnsupportedProps(
+      filterStylingProps(rest, overStyled) as Record<string, unknown>,
+      MODAL_ROOT_UNSUPPORTED_PROPS,
+    ) as Partial<typeof rest>;
+    return (
+      <MantineModal.Root
+        ref={ref}
+        {...(sanitizedProps as unknown as MantineModalRootProps)}
+      />
+    );
+  },
+);
+ModalRoot.displayName = "Modal.Root";
+
+export type ModalOverlayProps = RecursicaOverStyled<MantineModalOverlayProps>;
+
+const ModalOverlay = React.forwardRef<HTMLDivElement, ModalOverlayProps>(
+  function ModalOverlay({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    return (
+      <MantineModal.Overlay
+        ref={ref}
+        {...(sanitizedProps as unknown as MantineModalOverlayProps)}
+      />
+    );
+  },
+);
+ModalOverlay.displayName = "Modal.Overlay";
+
+export type ModalContentProps = RecursicaOverStyled<MantineModalContentProps>;
+
+// Modal corner radius is token-driven via `.content` in Modal.module.css, not Mantine's
+// native `radius` prop — deleted at runtime so it can't leak through via plain JavaScript.
+const MODAL_CONTENT_UNSUPPORTED_PROPS = [
+  "radius",
+] as const satisfies readonly (keyof MantineModalContentProps)[];
+
+const ModalContent = React.forwardRef<HTMLDivElement, ModalContentProps>(
+  function ModalContent({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = omitUnsupportedProps(
+      filterStylingProps(rest, overStyled) as Record<string, unknown>,
+      MODAL_CONTENT_UNSUPPORTED_PROPS,
+    ) as Partial<typeof rest>;
+    return (
+      <MantineModal.Content
+        ref={ref}
+        {...(sanitizedProps as unknown as MantineModalContentProps)}
+      />
+    );
+  },
+);
+ModalContent.displayName = "Modal.Content";
+
+export type ModalHeaderProps = RecursicaOverStyled<MantineModalHeaderProps>;
+
+const ModalHeader = React.forwardRef<HTMLElement, ModalHeaderProps>(
+  function ModalHeader({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    return (
+      <MantineModal.Header
+        ref={ref}
+        {...(sanitizedProps as unknown as MantineModalHeaderProps)}
+      />
+    );
+  },
+);
+ModalHeader.displayName = "Modal.Header";
+
+export type ModalTitleProps = RecursicaOverStyled<MantineModalTitleProps>;
+
+const ModalTitle = React.forwardRef<HTMLHeadingElement, ModalTitleProps>(
+  function ModalTitle({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    return (
+      <MantineModal.Title
+        ref={ref}
+        {...(sanitizedProps as unknown as MantineModalTitleProps)}
+      />
+    );
+  },
+);
+ModalTitle.displayName = "Modal.Title";
+
+export type ModalCloseButtonProps =
+  RecursicaOverStyled<MantineModalCloseButtonProps>;
+
+// The close button's dimensions and corner radius are enforced by Modal.module.css's `.close`
+// (standard icon-button tokens), not Mantine's native `size`/`radius` scales.
+const MODAL_CLOSE_BUTTON_UNSUPPORTED_PROPS = [
+  "size",
+  "radius",
+] as const satisfies readonly (keyof MantineModalCloseButtonProps)[];
+
+const ModalCloseButton = React.forwardRef<
+  HTMLButtonElement,
+  ModalCloseButtonProps
+>(function ModalCloseButton({ overStyled = false, ...rest }, ref) {
+  const sanitizedProps = omitUnsupportedProps(
+    filterStylingProps(rest, overStyled) as Record<string, unknown>,
+    MODAL_CLOSE_BUTTON_UNSUPPORTED_PROPS,
+  ) as Partial<typeof rest>;
+  return (
+    <MantineModal.CloseButton
+      ref={ref}
+      {...(sanitizedProps as unknown as MantineModalCloseButtonProps)}
+    />
+  );
+});
+ModalCloseButton.displayName = "Modal.CloseButton";
+
+interface ModalComponent
+  extends React.ForwardRefExoticComponent<
+    ModalProps & React.RefAttributes<HTMLDivElement>
+  > {
+  Root: typeof ModalRoot;
+  Overlay: typeof ModalOverlay;
+  Content: typeof ModalContent;
+  Header: typeof ModalHeader;
+  Title: typeof ModalTitle;
+  CloseButton: typeof ModalCloseButton;
+  Body: typeof ModalBody;
+  Footer: typeof ModalFooter;
+}
+
+export const Modal = ModalInner as ModalComponent & {
+  Footer: typeof ModalFooter;
+};
+Modal.Root = ModalRoot;
+Modal.Overlay = ModalOverlay;
+Modal.Content = ModalContent;
+Modal.Header = ModalHeader;
+Modal.Title = ModalTitle;
+Modal.CloseButton = ModalCloseButton;
+Modal.Body = ModalBody;
+Modal.Footer = ModalFooter;

package/src/components/Modal/USAGE.md

@@ -0,0 +1,58 @@
+# Modal - Usage Guide
+
+This document describes how to integrate and use the `Modal` component in your projects using `@recursica/adapter-mantine-v8`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Modal } from "@recursica/adapter-mantine-v8";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Modal } from "@recursica/adapter-mantine-v8";
+
+export default function Demo() {
+  return (
+    <Modal opened={isOpen} onClose={close} title="Modal Title">
+      <Text>This is a styled Modal wrapping the native primitive.</Text>
+    </Modal>
+  );
+}
+```
+
+---
+
+## 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. Key Integration Features & Constraints
+
+## Architecture
+
+`Modal` wraps Mantine's `<Modal>` component. Native Mantine styling props (`size`, `radius`, `shadow`) are not used — appearance and sizing are fully controlled by the design system tokens instead.
+
+## 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
+
+When the modal's content overflows and becomes scrollable, a divider line automatically appears, styled using the design system's scroll-divider color and thickness tokens.

package/src/components/Modal/index.ts

@@ -0,0 +1 @@
+export * from "./Modal";

package/src/components/NumberInput/NUMBER_INPUT_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,24 @@
+# NumberInput Implementation Notes
+
+This document contains specific design decisions, architectural constraints, and hacks required to bridge the Recursica design system with Mantine's underlying `NumberInput` primitive.
+
+## 1. Native Macro Wrapper Bypass
+
+**Decision:** The `<NumberInput>` component explicitly bypasses Mantine's native `Input.Wrapper` DOM injections.
+**Implementation:** We pass `label={undefined}`, `description={undefined}`, and `error={undefined}` directly into the primitive `<MantineNumberInput>`. All visual form control geometry is delegated exclusively to our unified `<FormControlWrapper>`, ensuring 100% token adherence for label spacing and assistive text styling without duplicate DOM rendering.
+
+## 2. Right Section & Controls Override
+
+**Decision:** Passing a `rightSection` element will natively remove the increment/decrement arrow controls.
+**Implementation:** Mantine inherently renders its stepper controls inside the `rightSection` DOM slot. Providing a custom right-aligned icon or text element intentionally overwrites this slot. If a layout strictly requires both a custom right-aligned element and the stepper controls simultaneously, the integrator must manually rebuild the arrows using Mantine's `handlersRef` within a custom right-section wrapper.
+
+## 3. Controls Styling
+
+**Decision:** The increment/decrement control arrows rely partially on native Mantine CSS inheritance.
+**Implementation:** The current Recursica design system tokens do not provide explicit UI styling parameters (`background`, `border`, `hover` states) for the inner number-input arrows. We have explicitly removed Mantine's default borders to cleanly nest them inside the unified input box, and mapped the icon colors to the generic `trailing-icon` token variable, but further visual configurations currently fall back to Mantine defaults.
+
+## 4. Section Text Color (non-svg content)
+
+**Bug:** `leftSection`/`rightSection` content that isn't an `<svg>` (e.g. a plain `<span>$</span>` currency stand-in, as used in the story) rendered in Mantine's own gray (`--mantine-color-dimmed`, via `--input-section-color`) instead of the Recursica leading/trailing-icon token. Only the `.section :global(svg)` rule was token-colored; anything else fell through to Mantine's `Input.Section` default.
+**Fix:** `.section` now sets `--input-section-color` — the exact variable Mantine's own `Input.Section` rule reads — to the Recursica leading-icon/trailing-icon token per position. This colors any section content (svg or plain text) with the real token instead of leaving a Mantine-library gray leaking through. The `:global(svg)` color rule is left in place (redundant but harmless).
+**Note:** the on-screen color didn't change — Recursica's token already resolves near-black; this fixed the _source_ it comes from, not the value.