@recursica/adapter-mui-v7 1.0.0

package/src/components/Button/Button.stories.tsx

@@ -0,0 +1,196 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Button } from "./Button";
+import { Layer } from "@recursica/adapter-common";
+
+type ButtonStoryProps = React.ComponentProps<typeof Button>;
+
+const meta: Meta<ButtonStoryProps> = {
+  title: "UI-Kit/Button",
+  component: Button,
+  tags: ["autodocs"],
+  argTypes: {
+    disabled: {
+      control: "boolean",
+    },
+    variant: {
+      control: "select",
+      options: ["solid", "outline", "text"],
+      description: "The visual variant of the button",
+    },
+    size: {
+      control: "radio",
+      options: ["default", "small"],
+      description: "The size of the button",
+    },
+    loading: {
+      control: "boolean",
+      description: "Sets the button to a loading state",
+    },
+    useRecursicaLoader: {
+      control: "boolean",
+      description:
+        "Use the Recursica Loader component instead of the default Mantine loader",
+    },
+    loaderVariant: {
+      control: "select",
+      options: ["oval", "bars", "dots"],
+      description: "The visual variant of the Recursica Loader",
+    },
+    loaderSize: {
+      control: "select",
+      options: [undefined, "sm", "md", "lg", "small", "default", "large"],
+      description: "The size variant for the loader",
+    },
+  },
+  args: {
+    useRecursicaLoader: true,
+    loaderVariant: "oval",
+    loaderSize: undefined,
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<ButtonStoryProps>;
+
+export const Default: Story = {
+  args: {
+    children: "Explore Button",
+    variant: "solid",
+    size: "default",
+    disabled: false,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => {
+    return <Button {...args} />;
+  },
+};
+
+export const SolidDefault: Story = {
+  args: {
+    children: "Solid Default",
+    variant: "solid",
+    size: "default",
+  },
+};
+
+export const OutlineSmall: Story = {
+  args: {
+    children: "Outline Small",
+    variant: "outline",
+    size: "small",
+  },
+};
+
+export const TextWithIcon: Story = {
+  args: {
+    children: "Text With Icon",
+    variant: "text",
+    size: "default",
+    icon: (
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        width="24"
+        height="24"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      >
+        <circle cx="11" cy="11" r="8"></circle>
+        <line x1="21" y1="21" x2="16.65" y2="16.65"></line>
+      </svg>
+    ),
+  },
+};
+
+export const IconOnly: Story = {
+  args: {
+    variant: "solid",
+    size: "default",
+    "aria-label": "Search",
+    icon: (
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        width="24"
+        height="24"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      >
+        <circle cx="11" cy="11" r="8"></circle>
+        <line x1="21" y1="21" x2="16.65" y2="16.65"></line>
+      </svg>
+    ),
+  },
+};
+
+export const LayerOneSolid: Story = {
+  args: {
+    children: "Layer 1 Solid",
+    variant: "solid",
+    size: "default",
+  },
+  render: (args: ButtonStoryProps) => (
+    <Layer layer={1} style={{ padding: "24px" }}>
+      <Button {...args} />
+    </Layer>
+  ),
+};
+
+export const DisabledSolid: Story = {
+  args: {
+    children: "Disabled Solid",
+    variant: "solid",
+    size: "default",
+    disabled: true,
+  },
+};
+
+export const PolymorphicAsLink: Story = {
+  args: {
+    children: "Button as Link",
+    variant: "solid",
+    size: "default",
+    component: "a",
+    href: "https://example.com",
+    target: "_blank",
+  },
+};
+
+export const TruncatedLabel: Story = {
+  args: {
+    children:
+      "This is an exceptionally long button label designed to demonstrate how the component handles text overflow by applying an ellipsis rather than breaking the layout or wrapping to multiple lines.",
+    variant: "solid",
+    size: "default",
+  },
+  render: (args: ButtonStoryProps) => (
+    <div style={{ maxWidth: "250px" }}>
+      <Button {...args} />
+    </div>
+  ),
+};
+
+export const Loading: Story = {
+  args: {
+    children: "Saving Changes",
+    variant: "solid",
+    size: "default",
+    loading: true,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "When `loading={true}` is applied, the Button injects the Recursica `<Loader />` component. Per Recursica design rules, placing a Button in a loading state automatically forces the `disabled={true}` state on the underlying element. This ensures the button immediately receives the brand theme disabled opacities without relying solely on semantic logic.",
+      },
+    },
+  },
+};

package/src/components/Button/Button.styleIsolation.dom.test.tsx

@@ -0,0 +1,98 @@
+import React from "react";
+import { describe, it, expect } from "vitest";
+import { createRoot, type Root } from "react-dom/client";
+import { flushSync } from "react-dom";
+import { ThemeProvider, createTheme, Button as MuiButton } from "@mui/material";
+import { Button as RecursicaButton } from "./Button";
+
+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();
+}
+
+const theme = createTheme({ colorSchemes: { light: true, dark: true } });
+
+function withProvider(node: React.ReactElement) {
+  return <ThemeProvider theme={theme}>{node}</ThemeProvider>;
+}
+
+/**
+ * Guards against Recursica's Button CSS bleeding onto (or being bled onto by) a plain,
+ * unwrapped MUI Button rendered in the same document. The two must be visibly different
+ * (Recursica's own classes/data-attributes), but the plain kit button must render identically
+ * whether or not a Recursica Button exists alongside it.
+ */
+describe("Button style isolation from the underlying MUI kit", () => {
+  it("adds Recursica-only classes/attributes without leaking them onto a plain MUI Button", () => {
+    const recursica = mount(
+      withProvider(<RecursicaButton>Recursica</RecursicaButton>),
+    );
+    const kit = mount(withProvider(<MuiButton>Plain</MuiButton>));
+
+    try {
+      const recursicaButton = recursica.container.querySelector("button")!;
+      const kitButton = kit.container.querySelector("button")!;
+
+      const recursicaClasses = Array.from(recursicaButton.classList);
+      const kitClasses = new Set(kitButton.classList);
+      const recursicaOnlyClasses = recursicaClasses.filter(
+        (cls) => !kitClasses.has(cls),
+      );
+
+      // Recursica's Button.module.css classes must exist...
+      expect(recursicaOnlyClasses.length).toBeGreaterThan(0);
+      // ...and none of them are present on the plain kit button.
+      for (const cls of recursicaOnlyClasses) {
+        expect(kitButton.classList.contains(cls)).toBe(false);
+      }
+
+      // Recursica-only markers confirm the two are meaningfully different components.
+      expect(recursicaButton.getAttribute("data-variant")).toBe("solid");
+      expect(kitButton.getAttribute("data-variant")).toBeNull();
+    } finally {
+      unmount(recursica);
+      unmount(kit);
+    }
+  });
+
+  it("renders a plain MUI Button identically whether or not Recursica's Button is mounted alongside it", () => {
+    const recursica = mount(
+      withProvider(<RecursicaButton>Recursica</RecursicaButton>),
+    );
+    const kitAlongsideRecursica = mount(
+      withProvider(<MuiButton>Plain</MuiButton>),
+    );
+    const kitIsolated = mount(withProvider(<MuiButton>Plain</MuiButton>));
+
+    try {
+      const kitButton =
+        kitAlongsideRecursica.container.querySelector("button")!;
+      const isolatedButton = kitIsolated.container.querySelector("button")!;
+
+      expect(Array.from(kitButton.classList).sort()).toEqual(
+        Array.from(isolatedButton.classList).sort(),
+      );
+
+      const kitStyle = getComputedStyle(kitButton);
+      const isolatedStyle = getComputedStyle(isolatedButton);
+      expect(kitStyle.borderRadius).toBe(isolatedStyle.borderRadius);
+      expect(kitStyle.backgroundColor).toBe(isolatedStyle.backgroundColor);
+      expect(kitStyle.fontFamily).toBe(isolatedStyle.fontFamily);
+    } finally {
+      unmount(recursica);
+      unmount(kitAlongsideRecursica);
+      unmount(kitIsolated);
+    }
+  });
+});

package/src/components/Button/Button.tsx

@@ -0,0 +1,156 @@
+import React, { forwardRef } from "react";
+import { Loader } from "../Loader/Loader";
+import {
+  Button as MuiButton,
+  type ButtonProps as MuiButtonProps,
+} from "@mui/material";
+import {
+  filterStylingProps,
+  omitUnsupportedProps,
+  withCallerOverride,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Button.module.css";
+
+import { type RecursicaButtonProps } from "@recursica/adapter-common";
+
+export type ButtonProps = RecursicaOverStyled<
+  Omit<MuiButtonProps, "variant" | "size" | "color" | "fullWidth"> &
+    RecursicaButtonProps
+>;
+
+function hasVisibleChildren(children: React.ReactNode): boolean {
+  if (children == null || children === "") return false;
+  if (typeof children === "string") return children.trim() !== "";
+  return true;
+}
+
+/**
+ * Recursica Button component wrapping MUI's Button.
+ *
+ * Supports polymorphism via the `component` prop for custom element rendering.
+ * This is particularly useful when you need a button that behaves as a hyperlink (rendering an `<a>` tag)
+ * or integrates with a routing library (e.g., `react-router-dom` or Next.js), while preserving full visual styling.
+ *
+ * @example
+ * ```tsx
+ * // Renders as an <a> tag natively
+ * <Button component="a" href="/dashboard" target="_blank">Navigate</Button>
+ *
+ * // Renders using a custom router link
+ * <Button component={Link} to="/home">Home</Button>
+ * ```
+ */
+export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
+  function Button(
+    {
+      variant = "solid",
+      size = "default",
+      icon,
+      children,
+      overStyled = false,
+      loaderVariant = "oval",
+      loaderSize,
+      useRecursicaLoader = true,
+      ...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 = [
+      "color", // Recursica handles colors internally via tokens
+    ] as const satisfies readonly (keyof MuiButtonProps)[];
+
+    const sanitizedProps = omitUnsupportedProps(
+      filterStylingProps(rest, overStyled),
+      UNSUPPORTED_PROPS,
+    );
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    const hasStartIcon = !!icon || !!restRecord["startIcon"];
+    const hasEndIcon = !!restRecord["endIcon"];
+    const hasVisibleText = hasVisibleChildren(children);
+    const isIconOnly = (hasStartIcon || hasEndIcon) && !hasVisibleText;
+
+    let contentType = "label";
+    if (isIconOnly) {
+      contentType = "icon-only";
+    } else if (hasStartIcon || hasEndIcon) {
+      contentType = "icon-label";
+    }
+
+    if (
+      typeof process !== "undefined" &&
+      process.env.NODE_ENV !== "production" &&
+      isIconOnly &&
+      !restRecord["aria-label"]
+    ) {
+      console.warn(
+        '[Recursica Button] Icon-only buttons must provide an accessible name. Pass aria-label (e.g. aria-label="Submit").',
+      );
+    }
+
+    const classNameProp = restRecord.className as string | undefined;
+    const finalClass = classNameProp
+      ? `${styles.root} ${classNameProp}`
+      : styles.root;
+
+    // We don't map Recursica variant/size to MUI's because we want to completely disable MUI's native
+    // variant logic (e.g., elevation, shadows) and style everything strictly through our CSS Modules.
+    // However, Mui Button requires some string, but we can just leave it as standard or ignore since
+    // our CSS resets its properties anyway, but to be clean we just don't pass variant to MUI.
+
+    const resolvedLoaderSize = withCallerOverride(
+      size === "small" ? "small" : "default",
+      loaderSize,
+    );
+
+    let loadingIndicator = restRecord.loadingIndicator as React.ReactNode;
+    if (useRecursicaLoader) {
+      // overStyled + style unlock the "--loader-color" override below — this is a fully
+      // internal composition (no external prop threading), so it doesn't widen Loader's public
+      // contract. Matches the button's own text-color token instead of Loader's standalone
+      // indicator-color default. See IMPLEMENTATION_NOTES.md.
+      loadingIndicator = (
+        <Loader
+          variant={loaderVariant}
+          size={resolvedLoaderSize}
+          overStyled
+          style={
+            { "--loader-color": "var(--button-color)" } as React.CSSProperties
+          }
+        />
+      );
+    }
+
+    return (
+      <MuiButton
+        ref={ref}
+        {...sanitizedProps}
+        disableRipple
+        disableElevation
+        className={finalClass}
+        loading={!!restRecord.loading}
+        loadingIndicator={loadingIndicator}
+        fullWidth={!!restRecord.fullWidth}
+        startIcon={
+          icon != null ? (
+            <span className={styles.iconWrapper} aria-hidden>
+              {icon}
+            </span>
+          ) : undefined
+        }
+        data-variant={variant}
+        data-size={size}
+        data-content={contentType}
+        {...(restRecord.loading ? { "data-loading": "true" } : {})}
+        disabled={!!restRecord.disabled || !!restRecord.loading}
+      >
+        <span className={styles.labelText}>{children}</span>
+      </MuiButton>
+    );
+  },
+);
+
+Button.displayName = "Button";

package/src/components/Button/USAGE.md

@@ -0,0 +1,46 @@
+# Button - Usage Guide
+
+This document describes how to integrate and use the `Button` component in your projects using `@recursica/adapter-mui-v7`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Button } from "@recursica/adapter-mui-v7";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Button } from "@recursica/adapter-mui-v7";
+
+export default function Demo() {
+  return (
+    <Button variant="primary" onClick={() => console.log("Clicked!")}>
+      Click Me
+    </Button>
+  );
+}
+```
+
+---
+
+## 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
+
+When `loading={true}` is passed to the Button, the button is also automatically disabled, and its loading indicator's color may not always match the button's text color, which can affect contrast in some variants.

package/src/components/Button/index.ts

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

package/src/components/Card/CARD_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,15 @@
+# Card Implementation Notes
+
+## Architecture Overrides
+
+Because MUI natively constructs `Card` bounding boxes using `<Paper>` components (which lack the precise edge-to-edge layouts native to Mantine's sections), we implemented custom margins for edge-to-edge section components:
+
+- `<Card.Header>` explicitly hooks `--recursica_ui-kit_components_card_properties_header-background` and corresponding padding variables, stretching edge-to-edge via negative margin resets.
+- `<Card.Footer>` explicitly hooks `--recursica_ui-kit_components_card_properties_footer-background` and corresponding padding variables.
+
+## Layout Alignment Exceptions
+
+To allow Cards to fit cleanly inside dynamic/flex layouts (like dashboard panels, grid tracks, or sidebar layout segments), the Card wrapper implements a custom gatekeeper bypass for outer styling properties:
+
+- Exposes a safe subset of flexbox/dimensions styling properties (`flex`, `flexGrow`, `flexShrink`, `flexBasis`, `grow`, `h`, `height`) on the root `<Card>` component to allow proper sizing alongside layout siblings.
+- Sets `<Card.Content>` to `flex-grow: 1;` by default via CSS modules. Since the root `<Card>` has `display: flex; flex-direction: column;`, this makes the content area expand to fill all vertical space, pushing `<Card.Footer>` to align at the absolute bottom of the bounding box.

package/src/components/Card/Card.module.css

@@ -0,0 +1,155 @@
+/* HARDCODED VALUES:
+   - display: flex on root
+   - flex-direction: column
+   - gap: section-gap
+ */
+
+.root {
+  /* HARDCODE: Map Recursica explicitly into Mantine's variable format so internal components know the margins */
+  --card-padding: var(--recursica_ui-kit_components_card_properties_padding);
+
+  background-color: var(
+    --recursica_ui-kit_components_card_properties_colors_background-color
+  );
+  border-radius: var(
+    --recursica_ui-kit_components_card_properties_borders_border-radius
+  );
+  border: var(--recursica_ui-kit_components_card_properties_borders_border-size)
+    solid var(--recursica_ui-kit_components_card_properties_colors_border-color);
+  box-shadow: var(
+    --recursica_ui-kit_components_card_properties_elevations_elevation
+  );
+
+  padding: var(--card-padding);
+  min-width: var(--recursica_ui-kit_components_card_properties_min-width);
+  max-width: var(--recursica_ui-kit_components_card_properties_max-width);
+  color: var(--recursica_ui-kit_components_card_properties_colors_content);
+
+  display: flex;
+  flex-direction: column;
+  gap: var(--recursica_ui-kit_components_card_properties_section-gap);
+}
+
+.header {
+  background-color: var(
+    --recursica_ui-kit_components_card_properties_colors_header-background-color
+  );
+  padding: var(--recursica_ui-kit_components_card_properties_header-padding);
+  color: var(--recursica_ui-kit_components_card_properties_colors_title);
+  border-bottom: var(--recursica_ui-kit_components_card_properties_divider-size)
+    solid
+    var(--recursica_ui-kit_components_card_properties_colors_divider-color);
+
+  /* Direct Figma Typography Mapping */
+  font-family: var(
+    --recursica_ui-kit_components_card_properties_header-style_fontFamily
+  );
+  font-size: var(
+    --recursica_ui-kit_components_card_properties_header-style_fontSize
+  );
+  font-style: var(
+    --recursica_ui-kit_components_card_properties_header-style_fontStyle
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_card_properties_header-style_fontWeight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_card_properties_header-style_letterSpacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_card_properties_header-style_lineHeight
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_card_properties_header-style_textCase
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_card_properties_header-style_textDecoration
+  );
+
+  /* Edge-to-edge behavior */
+  margin-left: calc(var(--card-padding) * -1) !important;
+  margin-right: calc(var(--card-padding) * -1) !important;
+}
+
+.header:first-child {
+  margin-top: calc(var(--card-padding) * -1) !important;
+}
+
+.header:last-child {
+  margin-bottom: calc(var(--card-padding) * -1) !important;
+}
+
+.footer {
+  background-color: var(
+    --recursica_ui-kit_components_card_properties_colors_footer-background-color
+  );
+  padding: var(--recursica_ui-kit_components_card_properties_footer-padding);
+  border-top: var(--recursica_ui-kit_components_card_properties_divider-size)
+    solid
+    var(--recursica_ui-kit_components_card_properties_colors_divider-color);
+
+  /* Edge-to-edge behavior */
+  margin-left: calc(var(--card-padding) * -1) !important;
+  margin-right: calc(var(--card-padding) * -1) !important;
+}
+
+.footer:first-child {
+  margin-top: calc(var(--card-padding) * -1) !important;
+}
+
+.footer:last-child {
+  margin-bottom: calc(var(--card-padding) * -1) !important;
+}
+
+.section {
+  /* Just maps standard section spacing overrides if passed explicitly */
+  margin-top: var(
+    --recursica_ui-kit_components_card_properties_vertical-gutter
+  );
+
+  /* Edge-to-edge behavior */
+  margin-left: calc(var(--card-padding) * -1) !important;
+  margin-right: calc(var(--card-padding) * -1) !important;
+}
+
+.section:first-child {
+  margin-top: calc(var(--card-padding) * -1) !important;
+}
+
+.section:last-child {
+  margin-bottom: calc(var(--card-padding) * -1) !important;
+}
+
+.content {
+  display: flex;
+  flex-direction: column;
+  gap: var(--recursica_ui-kit_components_card_properties_vertical-gutter);
+  padding: 0;
+  flex-grow: 1;
+
+  /* Direct Figma Typography Mapping */
+  font-family: var(
+    --recursica_ui-kit_components_card_properties_content-style_fontFamily
+  );
+  font-size: var(
+    --recursica_ui-kit_components_card_properties_content-style_fontSize
+  );
+  font-style: var(
+    --recursica_ui-kit_components_card_properties_content-style_fontStyle
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_card_properties_content-style_fontWeight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_card_properties_content-style_letterSpacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_card_properties_content-style_lineHeight
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_card_properties_content-style_textCase
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_card_properties_content-style_textDecoration
+  );
+}