@recursica/mui-adapter 0.2.0 → 0.4.0

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

@@ -1,16 +1,192 @@
+import React from "react";
 import type { Meta, StoryObj } from "@storybook/react";
 import { Button } from "./Button";
-import { ComingSoon } from "@recursica/storybook-template";
+import { Layer } from "@recursica/adapter-common";
 
-const meta: Meta<typeof Button> = {
-  title: "UI-Kit/🚧 Button",
+type ButtonStoryProps = React.ComponentProps<typeof Button>;
+
+const meta: Meta<ButtonStoryProps> = {
+  title: "UI-Kit/Button",
   component: Button,
   tags: ["autodocs"],
+  argTypes: {
+    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,
+  },
+  parameters: {
+    controls: {
+      include: [
+        "layer",
+        "withLayer",
+        "variant",
+        "size",
+        "children",
+        "component",
+        "icon",
+        "disabled",
+        "href",
+        "onClick",
+        "onChange",
+        "value",
+        "checked",
+        "loading",
+        "useRecursicaLoader",
+        "loaderVariant",
+        "loaderSize",
+      ],
+    },
+  },
 };
 
 export default meta;
-type Story = StoryObj<typeof Button>;
+
+type Story = StoryObj<ButtonStoryProps>;
 
 export const Default: Story = {
-  render: () => <ComingSoon componentName="Button" />,
+  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 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.tsx

@@ -1,7 +1,143 @@
-import React from "react";
+import React, { forwardRef } from "react";
+import { Loader } from "../Loader/Loader";
+import type { RecursicaLoaderProps } from "../Loader/Loader";
+import {
+  Button as MuiButton,
+  type ButtonProps as MuiButtonProps,
+} from "@mui/material";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Button.module.css";
 
-export type ButtonProps = React.HTMLAttributes<HTMLDivElement>;
+export interface RecursicaButtonProps {
+  variant?: "solid" | "outline" | "text";
+  size?: "default" | "small";
+  icon?: React.ReactNode;
+  /**
+   * For polymorphic support (e.g., `component="a"`), native to MUI.
+   */
+  component?: React.ElementType;
+  /** Which Recursica Loader variant to use */
+  loaderVariant?: RecursicaLoaderProps["variant"];
+  /** The size variant for the loader */
+  loaderSize?: RecursicaLoaderProps["size"];
+  /** Whether to use the Recursica loader or fallback to the Mantine loader */
+  useRecursicaLoader?: boolean;
+}
 
-export const Button: React.FC<ButtonProps> = (props) => {
-  return <div {...props}>Button</div>;
-};
+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,
+  ) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    // Explicitly delete blocked semantic expansion dimension props that MUI uses natively
+    delete restRecord["fullWidth"];
+    delete restRecord["color"]; // Recursica handles colors internally via tokens
+
+    const hasStartIcon = !!icon || !!restRecord["startIcon"];
+    const hasEndIcon = !!restRecord["endIcon"];
+    const isIconOnly =
+      (hasStartIcon || hasEndIcon) && !hasVisibleChildren(children);
+
+    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 =
+      loaderSize ?? (size === "small" ? "small" : "default");
+
+    let loadingIndicator = restRecord.loadingIndicator as React.ReactNode;
+    if (useRecursicaLoader) {
+      loadingIndicator = (
+        <Loader variant={loaderVariant} size={resolvedLoaderSize} />
+      );
+    }
+
+    return (
+      <MuiButton
+        ref={ref}
+        disableRipple
+        disableElevation
+        className={finalClass}
+        loading={!!restRecord.loading}
+        loadingIndicator={loadingIndicator}
+        startIcon={
+          icon != null ? (
+            <span className={styles.iconWrapper} aria-hidden>
+              {icon}
+            </span>
+          ) : undefined
+        }
+        data-variant={variant}
+        data-size={size}
+        {...(isIconOnly ? { "data-icon-only": "" } : {})}
+        {...(restRecord.loading ? { "data-loading": "true" } : {})}
+        {...sanitizedProps}
+        disabled={!!restRecord.disabled || !!restRecord.loading}
+      >
+        <span className={styles.labelText}>{children}</span>
+      </MuiButton>
+    );
+  },
+);
+
+Button.displayName = "Button";

package/src/components/Card/Card.stories.tsx

@@ -6,6 +6,25 @@ const meta: Meta<typeof Card> = {
   title: "UI-Kit/🚧 Card",
   component: Card,
   tags: ["autodocs"],
+  parameters: {
+    controls: {
+      include: [
+        "layer",
+        "withLayer",
+        "children",
+        "component",
+        "variant",
+        "size",
+        "icon",
+        "disabled",
+        "href",
+        "onClick",
+        "onChange",
+        "value",
+        "checked",
+      ],
+    },
+  },
 };
 
 export default meta;

package/src/components/Checkbox/Checkbox.stories.tsx

@@ -6,6 +6,25 @@ const meta: Meta<typeof Checkbox> = {
   title: "UI-Kit/🚧 Checkbox",
   component: Checkbox,
   tags: ["autodocs"],
+  parameters: {
+    controls: {
+      include: [
+        "layer",
+        "withLayer",
+        "children",
+        "component",
+        "variant",
+        "size",
+        "icon",
+        "disabled",
+        "href",
+        "onClick",
+        "onChange",
+        "value",
+        "checked",
+      ],
+    },
+  },
 };
 
 export default meta;

package/src/components/Chip/Chip.stories.tsx

@@ -6,6 +6,25 @@ const meta: Meta<typeof Chip> = {
   title: "UI-Kit/🚧 Chip",
   component: Chip,
   tags: ["autodocs"],
+  parameters: {
+    controls: {
+      include: [
+        "layer",
+        "withLayer",
+        "children",
+        "component",
+        "variant",
+        "size",
+        "icon",
+        "disabled",
+        "href",
+        "onClick",
+        "onChange",
+        "value",
+        "checked",
+      ],
+    },
+  },
 };
 
 export default meta;

package/src/components/Container/Container.stories.tsx

@@ -6,6 +6,25 @@ const meta: Meta<typeof Container> = {
   title: "UI-Kit/🚧 Container",
   component: Container,
   tags: ["autodocs"],
+  parameters: {
+    controls: {
+      include: [
+        "layer",
+        "withLayer",
+        "children",
+        "component",
+        "variant",
+        "size",
+        "icon",
+        "disabled",
+        "href",
+        "onClick",
+        "onChange",
+        "value",
+        "checked",
+      ],
+    },
+  },
 };
 
 export default meta;

package/src/components/Container/Container.tsx

@@ -1,7 +1,58 @@
-import React from "react";
+/**
+ * Container layout wrapper.
+ *
+ * NOTE: As a foundational structural boundary, the Container component DOES NOT use
+ * the `RecursicaOverStyled` gatekeeper. Furthermore, unlike other primitive layouts
+ * (Stack, Group, Flex), Container explicitly ALLOWS the `sx` prop as an escape hatch
+ * for advanced layout positioning.
+ */
+import React, { forwardRef } from "react";
+import {
+  Container as MUIContainer,
+  type ContainerProps as MUIContainerProps,
+} from "@mui/material";
+import { type RecursicaSpacing } from "../../utils/filterStylingProps";
 
-export type ContainerProps = React.HTMLAttributes<HTMLDivElement>;
+export interface RecursicaContainerProps {
+  children?: React.ReactNode;
+  size?:
+    | "xs"
+    | "sm"
+    | "md"
+    | "lg"
+    | "xl"
+    | RecursicaSpacing
+    | (string & {})
+    | number;
+}
 
-export const Container: React.FC<ContainerProps> = (props) => {
-  return <div {...props}>Container</div>;
-};
+export type ContainerProps = Omit<MUIContainerProps, "maxWidth"> &
+  RecursicaContainerProps;
+
+export const Container = forwardRef<HTMLDivElement, ContainerProps>(
+  function Container({ children, size, ...rest }, ref) {
+    const mapSize: Record<string, "xs" | "sm" | "md" | "lg" | "xl"> = {
+      "rec-sm": "sm",
+      "rec-default": "md",
+      "rec-md": "md",
+      "rec-lg": "lg",
+      "rec-xl": "xl",
+      "rec-2xl": "xl",
+    };
+
+    const resolvedSize =
+      typeof size === "string" && mapSize[size] ? mapSize[size] : size;
+
+    return (
+      <MUIContainer
+        ref={ref}
+        maxWidth={resolvedSize as MUIContainerProps["maxWidth"]}
+        {...rest}
+      >
+        {children}
+      </MUIContainer>
+    );
+  },
+);
+
+Container.displayName = "Container";

package/src/components/Container/IMPLEMENTATION_NOTES.md

@@ -0,0 +1,5 @@
+# Container Implementation Notes
+
+## `sx` Prop Exemption
+
+By design, the `Container` component explicitly allows the `sx` prop to pass through to the underlying MUI `Container`. Unlike standard UI kit components (which use the `RecursicaOverStyled` gatekeeper) or flex layout primitives (which strip `sx` via `OmitSx` and `filterSxProp`), `Container` acts as a structural boundary where advanced, one-off positioning adjustments may be required by the consuming application.

package/src/components/DatePicker/DatePicker.stories.tsx

@@ -6,6 +6,25 @@ const meta: Meta<typeof DatePicker> = {
   title: "UI-Kit/🚧 DatePicker",
   component: DatePicker,
   tags: ["autodocs"],
+  parameters: {
+    controls: {
+      include: [
+        "layer",
+        "withLayer",
+        "children",
+        "component",
+        "variant",
+        "size",
+        "icon",
+        "disabled",
+        "href",
+        "onClick",
+        "onChange",
+        "value",
+        "checked",
+      ],
+    },
+  },
 };
 
 export default meta;

package/src/components/Dropdown/Dropdown.stories.tsx

@@ -6,6 +6,25 @@ const meta: Meta<typeof Dropdown> = {
   title: "UI-Kit/🚧 Dropdown",
   component: Dropdown,
   tags: ["autodocs"],
+  parameters: {
+    controls: {
+      include: [
+        "layer",
+        "withLayer",
+        "children",
+        "component",
+        "variant",
+        "size",
+        "icon",
+        "disabled",
+        "href",
+        "onClick",
+        "onChange",
+        "value",
+        "checked",
+      ],
+    },
+  },
 };
 
 export default meta;

package/src/components/FileInput/FileInput.stories.tsx

@@ -6,6 +6,25 @@ const meta: Meta<typeof FileInput> = {
   title: "UI-Kit/🚧 FileInput",
   component: FileInput,
   tags: ["autodocs"],
+  parameters: {
+    controls: {
+      include: [
+        "layer",
+        "withLayer",
+        "children",
+        "component",
+        "variant",
+        "size",
+        "icon",
+        "disabled",
+        "href",
+        "onClick",
+        "onChange",
+        "value",
+        "checked",
+      ],
+    },
+  },
 };
 
 export default meta;

package/src/components/FileUpload/FileUpload.stories.tsx

@@ -6,6 +6,25 @@ const meta: Meta<typeof FileUpload> = {
   title: "UI-Kit/🚧 FileUpload",
   component: FileUpload,
   tags: ["autodocs"],
+  parameters: {
+    controls: {
+      include: [
+        "layer",
+        "withLayer",
+        "children",
+        "component",
+        "variant",
+        "size",
+        "icon",
+        "disabled",
+        "href",
+        "onClick",
+        "onChange",
+        "value",
+        "checked",
+      ],
+    },
+  },
 };
 
 export default meta;

package/src/components/Flex/Flex.stories.tsx

@@ -6,6 +6,25 @@ const meta: Meta<typeof Flex> = {
   title: "UI-Kit/🚧 Flex",
   component: Flex,
   tags: ["autodocs"],
+  parameters: {
+    controls: {
+      include: [
+        "layer",
+        "withLayer",
+        "children",
+        "component",
+        "variant",
+        "size",
+        "icon",
+        "disabled",
+        "href",
+        "onClick",
+        "onChange",
+        "value",
+        "checked",
+      ],
+    },
+  },
 };
 
 export default meta;