@recursica/adapter-mui-v7 1.0.0

package/src/components/Link/Link.tsx

@@ -0,0 +1,45 @@
+import { forwardRef } from "react";
+import { Link as MUILink, type LinkProps as MUILinkProps } from "@mui/material";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Link.module.css";
+
+import { type RecursicaLinkProps } from "@recursica/adapter-common";
+
+export type LinkProps = RecursicaOverStyled<
+  Omit<MUILinkProps, "underline"> & RecursicaLinkProps
+>;
+
+export const Link = forwardRef<HTMLAnchorElement, LinkProps>(function Link(
+  { icon, children, overStyled = false, ...rest },
+  ref,
+) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const restRecord = sanitizedProps as Record<string, unknown>;
+
+  const classNameProp = restRecord.className as string | undefined;
+  const finalClass = classNameProp
+    ? `${styles.root} ${classNameProp}`
+    : styles.root;
+
+  return (
+    <MUILink
+      ref={ref}
+      className={finalClass}
+      underline="none"
+      {...(icon ? { "data-has-icon": "" } : {})}
+      {...sanitizedProps}
+    >
+      {icon && (
+        <span className={styles.iconWrapper} aria-hidden>
+          {icon}
+        </span>
+      )}
+      <span className={styles.labelText}>{children}</span>
+    </MUILink>
+  );
+});
+
+Link.displayName = "Link";

package/src/components/Link/USAGE.md

@@ -0,0 +1,40 @@
+# Link - Usage Guide
+
+This document describes how to integrate and use the `Link` component in your projects using `@recursica/adapter-mui-v7`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Link } from "@recursica/adapter-mui-v7";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Link } from "@recursica/adapter-mui-v7";
+
+export default function Demo() {
+  return (
+    <Link href="/dashboard" variant="inline">
+      Go to Dashboard
+    </Link>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/adapter-mui-v7` 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.

package/src/components/Link/index.ts

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

package/src/components/Loader/LOADER_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,25 @@
+# Loader Implementation Notes
+
+## Architecture & Integration
+
+The `Loader` component for the MUI adapter has been completely hand-coded from scratch using pure CSS and basic HTML `<span>` elements. It explicitly **does not** use MUI's native `<CircularProgress>` component.
+
+This was a deliberate architectural decision to ensure 100% feature and visual parity with the `mantine-adapter`.
+
+### Key Decisions:
+
+- **Bypassing Native Components:** MUI's native loaders (like `<CircularProgress>`) are built using complex animated SVGs and only support a circular "oval" shape. Since the Recursica design system mandates `oval`, `bars`, and `dots` variants, relying on MUI's primitives would have forced a fragmented architecture where `oval` used MUI but `bars` and `dots` were hand-coded.
+- **Parity with Mantine:** To guarantee identical animation timing, easing curves, and DOM structures across frameworks, the CSS keyframes and layout strategies used internally by Mantine's `<Loader>` were extracted and directly replicated in this adapter's `Loader.module.css`.
+
+### Token Mapping:
+
+Sizes are bound through `data-size` attributes (`sm`, `md`, `lg` parsing to target `<div data-size="small">`, etc.).
+
+- **Oval Variant:** Uses a CSS spinning `::after` pseudo-element. To avoid CSS border inheritance bugs when computing tokenized border-widths, a custom `--loader-thickness` CSS variable is used to bridge the token into the spinning element.
+- **Bars & Dots Variants:** Render three internal `<span />` elements sequentially, styled via `Loader.module.css` to handle individual keyframe delays for bouncing or fading animations.
+
+### Color Contrast Rules:
+
+Loaders are hardcoded to map to their explicitly defined design tokens (e.g., `--recursica_ui-kit_components_loader_properties_indicator-color`). By default, they do **not** inherit `currentColor`.
+
+When injected into components like the `Button` (where contrast issues may arise against solid backgrounds), it is the responsibility of the parent component (e.g., `Button.module.css`) to use contextual CSS overrides to force `--loader-color: currentColor !important` if necessary.

package/src/components/Loader/Loader.animate.dom.test.tsx

@@ -0,0 +1,72 @@
+import React from "react";
+import { describe, it, expect } from "vitest";
+import { createRoot, type Root } from "react-dom/client";
+import { flushSync } from "react-dom";
+import { Loader } from "./Loader";
+
+function mount(node: React.ReactElement): {
+  container: HTMLElement;
+  root: Root;
+} {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const root = createRoot(container);
+  flushSync(() => root.render(node));
+  return { container, root };
+}
+
+function unmount({ container, root }: { container: HTMLElement; root: Root }) {
+  root.unmount();
+  container.remove();
+}
+
+/**
+ * `animate={false}` must deterministically freeze every variant — including
+ * the bars'/dots' individually-animated child spans, which the freeze rule
+ * can only reach via a descendant selector, not the `data-variant`-scoped
+ * rules the size/thickness CSS uses.
+ */
+describe("Loader animate prop", () => {
+  it.each(["oval", "bars", "dots"] as const)(
+    "freezes every animated element for variant=%s when animate is false, and animates by default",
+    (variant) => {
+      const animated = mount(<Loader variant={variant} />);
+      const frozen = mount(<Loader variant={variant} animate={false} />);
+
+      try {
+        const animatedRoot =
+          animated.container.querySelector("[data-variant]")!;
+        const frozenRoot = frozen.container.querySelector("[data-variant]")!;
+
+        const animatedTargets = [
+          animatedRoot,
+          ...Array.from(animatedRoot.querySelectorAll("*")),
+        ];
+        const frozenTargets = [
+          frozenRoot,
+          ...Array.from(frozenRoot.querySelectorAll("*")),
+        ];
+
+        // At least one element (or the root's own ::after, for oval) actually
+        // animates by default — otherwise this test would trivially pass.
+        const hasAnimation = (el: Element, pseudo?: string) =>
+          getComputedStyle(el, pseudo).animationName !== "none";
+        const animatedHasMotion =
+          animatedTargets.some((el) => hasAnimation(el)) ||
+          hasAnimation(animatedRoot, "::after");
+        expect(animatedHasMotion).toBe(true);
+
+        // Frozen: nothing animates, root included, pseudo-element included.
+        for (const el of frozenTargets) {
+          expect(getComputedStyle(el).animationName).toBe("none");
+        }
+        expect(getComputedStyle(frozenRoot, "::after").animationName).toBe(
+          "none",
+        );
+      } finally {
+        unmount(animated);
+        unmount(frozen);
+      }
+    },
+  );
+});

package/src/components/Loader/Loader.module.css

@@ -0,0 +1,175 @@
+.root {
+  /* Default inheritance mapped from component variables if not explicitly overridden by variants */
+  --loader-color: var(
+    --recursica_ui-kit_components_loader_properties_indicator-color
+  );
+  box-sizing: border-box;
+}
+.root * {
+  box-sizing: border-box;
+}
+
+/* `animate={false}` — freezes every variant's animation (the oval's own
+ * spinning ::after, and the bars'/dots' individually-animated child spans)
+ * so the loader renders deterministically, e.g. for a visual-regression
+ * snapshot that would otherwise diff differently every run. */
+.root[data-animate="false"],
+.root[data-animate="false"] *,
+.root[data-animate="false"]::after {
+  animation: none !important;
+}
+
+/* data-size mapping */
+
+/* SMALL */
+.root[data-size="small"] {
+  --loader-size: var(
+    --recursica_ui-kit_components_loader_variants_sizes_small_properties_size
+  );
+}
+.root[data-size="small"][data-variant="oval"] {
+  --loader-thickness: var(
+    --recursica_ui-kit_components_loader_variants_sizes_small_properties_thickness-size
+  );
+}
+.root[data-size="small"]:not([data-variant="oval"]) span {
+  border-radius: var(
+    --recursica_ui-kit_components_loader_variants_sizes_small_properties_border-radius
+  );
+}
+
+/* DEFAULT */
+.root[data-size="default"] {
+  --loader-size: var(
+    --recursica_ui-kit_components_loader_variants_sizes_default_properties_size
+  );
+}
+.root[data-size="default"][data-variant="oval"] {
+  --loader-thickness: var(
+    --recursica_ui-kit_components_loader_variants_sizes_default_properties_thickness-size
+  );
+}
+.root[data-size="default"]:not([data-variant="oval"]) span {
+  border-radius: var(
+    --recursica_ui-kit_components_loader_variants_sizes_default_properties_border-radius
+  );
+}
+
+/* LARGE */
+.root[data-size="large"] {
+  --loader-size: var(
+    --recursica_ui-kit_components_loader_variants_sizes_large_properties_size
+  );
+}
+.root[data-size="large"][data-variant="oval"] {
+  --loader-thickness: var(
+    --recursica_ui-kit_components_loader_variants_sizes_large_properties_thickness-size
+  );
+}
+.root[data-size="large"]:not([data-variant="oval"]) span {
+  border-radius: var(
+    --recursica_ui-kit_components_loader_variants_sizes_large_properties_border-radius
+  );
+}
+
+/* ----- Oval loader ----- */
+@keyframes oval-spin {
+  0% {
+    transform: rotate(0deg);
+  }
+  100% {
+    transform: rotate(360deg);
+  }
+}
+
+.root[data-variant="oval"] {
+  display: inline-block;
+  width: var(--loader-size);
+  height: var(--loader-size);
+}
+.root[data-variant="oval"]::after {
+  content: "";
+  display: block;
+  width: var(--loader-size);
+  height: var(--loader-size);
+  border-radius: 10000px;
+  border-width: var(--loader-thickness);
+  border-style: solid;
+  border-color: var(--loader-color) var(--loader-color) var(--loader-color)
+    transparent;
+  animation: oval-spin 1.2s linear infinite;
+}
+
+/* ----- Bars loader ----- */
+@keyframes bars-bounce {
+  0% {
+    transform: scale(0.6);
+    opacity: 0;
+  }
+  50%,
+  100% {
+    transform: scale(1);
+    opacity: 1;
+  }
+}
+
+.root[data-variant="bars"] {
+  position: relative;
+  width: var(--loader-size);
+  height: var(--loader-size);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: calc(var(--loader-size) / 5);
+}
+
+.root[data-variant="bars"] span {
+  flex: 1;
+  height: 100%;
+  background: var(--loader-color);
+  animation: bars-bounce 1.2s cubic-bezier(0, 0.5, 0.5, 1) infinite;
+}
+
+.root[data-variant="bars"] span:nth-of-type(1) {
+  animation-delay: -240ms;
+}
+.root[data-variant="bars"] span:nth-of-type(2) {
+  animation-delay: -120ms;
+}
+.root[data-variant="bars"] span:nth-of-type(3) {
+  animation-delay: 0;
+}
+
+/* ----- Dots loader ----- */
+@keyframes dots-pulse {
+  0%,
+  100% {
+    transform: scale(1);
+    opacity: 1;
+  }
+  50% {
+    transform: scale(0.6);
+    opacity: 0.5;
+  }
+}
+
+.root[data-variant="dots"] {
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  gap: calc(var(--loader-size) / 10);
+  position: relative;
+  width: var(--loader-size);
+  height: var(--loader-size);
+}
+
+.root[data-variant="dots"] span {
+  width: calc(var(--loader-size) / 3 - var(--loader-size) / 15);
+  height: calc(var(--loader-size) / 3 - var(--loader-size) / 15);
+  background: var(--loader-color);
+  animation: dots-pulse 0.8s infinite linear;
+}
+
+.root[data-variant="dots"] span:nth-child(2) {
+  animation-delay: 0.4s;
+}

package/src/components/Loader/Loader.stories.tsx

@@ -0,0 +1,123 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Loader } from "./Loader";
+import { Layer } from "@recursica/adapter-common";
+
+type LoaderStoryArgs = React.ComponentProps<typeof Loader> & {
+  layer?: 0 | 1 | 2 | 3;
+};
+
+const meta: Meta<LoaderStoryArgs> = {
+  title: "UI-Kit/Loader",
+  component: Loader as React.ComponentType<LoaderStoryArgs>,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "The Loader bridges the Recursica UI-Kit `loader` variables to the generic primitive, rendering deterministic sizes and variants visually mapped strictly from the explicit design boundary tokens.",
+      },
+    },
+  },
+  argTypes: {
+    variant: {
+      control: "select",
+      options: ["oval", "bars", "dots"],
+      description: "The structural layout variant of the loading indicator",
+    },
+    size: {
+      control: "select",
+      options: ["sm", "md", "lg", "small", "default", "large"],
+      description:
+        "Scales the dimensional and thickness layout constrained to the explicit UI variables",
+    },
+    color: {
+      control: "color",
+      description:
+        "Optional inline dynamic color override spanning the token defaults",
+    },
+    layer: {
+      control: { type: "range", min: 0, max: 3, step: 1 },
+      description:
+        "Applies a wrapping context to observe rendering logic externally",
+    },
+    animate: {
+      control: "boolean",
+      description:
+        "Freezes the CSS animation when false — deterministic, for visual regression",
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<LoaderStoryArgs>;
+
+/**
+ * Animated — excluded from visual regression (`adapter-tester.config.json`),
+ * since a moving animation diffs differently every run. See the `Static*`
+ * stories below for the deterministic, visual-regression-covered equivalents.
+ */
+export const Default: Story = {
+  args: {
+    variant: "oval",
+    size: "default",
+    layer: 0,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <Layer layer={layer ?? 0} style={{ padding: "24px" }}>
+      <Loader {...args} />
+    </Layer>
+  ),
+};
+
+/** `animate: false` freezes the spin — deterministic for visual regression. */
+export const StaticOvalDefault: Story = {
+  args: {
+    variant: "oval",
+    size: "default",
+    animate: false,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => <Loader {...args} />,
+};
+
+/** `animate: false` freezes the bars — deterministic for visual regression. */
+export const StaticBarsLarge: Story = {
+  args: {
+    variant: "bars",
+    size: "large",
+    animate: false,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => <Loader {...args} />,
+};
+
+/** `animate: false` freezes the dots — deterministic for visual regression. */
+export const StaticDotsSmall: Story = {
+  args: {
+    variant: "dots",
+    size: "sm",
+    animate: false,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => <Loader {...args} />,
+};
+
+/**
+ * Animated — excluded from visual regression, same as `Default`; this one
+ * additionally demonstrates rendering inside a `layer={2}` context.
+ */
+export const LayerTwoOval: Story = {
+  args: {
+    variant: "oval",
+    size: "default",
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <Layer layer={2} style={{ padding: "24px" }}>
+      <Loader {...args} />
+    </Layer>
+  ),
+};

package/src/components/Loader/Loader.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Loader component tests. Add tests here if/when needed.

package/src/components/Loader/Loader.tsx

@@ -0,0 +1,72 @@
+import React, { forwardRef } from "react";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Loader.module.css";
+
+import { type RecursicaLoaderProps } from "@recursica/adapter-common";
+
+export type LoaderProps = RecursicaOverStyled<
+  React.HTMLAttributes<HTMLSpanElement> & RecursicaLoaderProps
+>;
+
+export const Loader = forwardRef<HTMLSpanElement, LoaderProps>(function Loader(
+  {
+    variant = "oval",
+    size = "default",
+    animate = true,
+    overStyled = false,
+    ...rest
+  },
+  ref,
+) {
+  const mapSize = {
+    sm: "small",
+    md: "default",
+    lg: "large",
+    small: "small",
+    default: "default",
+    large: "large",
+  } as const;
+
+  const resolvedSize = mapSize[size] || "default";
+
+  // Strip all visual override injections unless developer has specifically opted into overStyling.
+  // External layout props like margins are safely preserved.
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+
+  const classNameProp = (sanitizedProps as Record<string, unknown>)
+    .className as string | undefined;
+  const finalClass = classNameProp
+    ? `${styles.root} ${classNameProp}`
+    : styles.root;
+
+  const renderChildren = () => {
+    if (variant === "bars" || variant === "dots") {
+      return (
+        <>
+          <span />
+          <span />
+          <span />
+        </>
+      );
+    }
+    return null; // Oval is handled purely via CSS ::after
+  };
+
+  return (
+    <span
+      ref={ref}
+      data-variant={variant}
+      data-size={resolvedSize}
+      data-animate={animate}
+      {...sanitizedProps}
+      className={finalClass}
+    >
+      {renderChildren()}
+    </span>
+  );
+});
+
+Loader.displayName = "Loader";

package/src/components/Loader/USAGE.md

@@ -0,0 +1,42 @@
+# Loader - Usage Guide
+
+This document describes how to integrate and use the `Loader` component in your projects using `@recursica/adapter-mui-v7`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Loader } from "@recursica/adapter-mui-v7";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Loader } from "@recursica/adapter-mui-v7";
+
+export default function Demo() {
+  return <Loader size="md" />;
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/adapter-mui-v7` 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
+
+Loader colors are determined by their own design tokens by default and do not automatically inherit `currentColor` from a parent component, which can occasionally affect contrast when a loader is placed on a colored background.

package/src/components/Loader/index.ts

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

package/src/components/Menu/IMPLEMENTATION_NOTES.md

@@ -0,0 +1,5 @@
+# Menu Implementation Notes
+
+- **Compositional API Dropped:** Mantine uses `<Menu.Target>`, `<Menu.Dropdown>`, `<Menu.Item>`, etc., and manages state natively via React context within `<Menu>`. MUI's API is fully monolithic.
+- **Monolithic API Adopted:** Following architectural review, we have abandoned the fabricated context wrappers for `adapter-mui-v7`. We now natively export `Menu`, `MenuItem`, and `MenuDivider` wrapping their `@mui/material` counterparts. Developers are expected to manage `anchorEl` state themselves, just like native MUI. Storybook tests have been updated to simulate this open state so visual regressions still cover the dropdown menu visually.
+- **`maxHeight` Override:** `<Menu maxHeight={...}>` overrides the token-driven dropdown max-height with an explicit pixel (or other CSS length) value — the one deliberate exception to "no inline design tokens in TSX" (see `COMPONENT_DEV_GUIDE.md`). Implemented by merging `maxHeight` into `slotProps.paper.style`, alongside any caller-supplied `slotProps`, rather than a CSS module change; the CSS module's token-driven `max-height` stays untouched when the prop isn't passed.