@recursica/mui-adapter 0.2.0 → 0.3.0

package/src/components/Button/Button.tsx

@@ -1,7 +1,118 @@
-import React from "react";
+import React, { forwardRef } from "react";
+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;
+}
 
-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,
+      ...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.
+
+    return (
+      <MuiButton
+        ref={ref}
+        disableRipple
+        disableElevation
+        className={finalClass}
+        startIcon={
+          icon != null ? (
+            <span className={styles.iconWrapper} aria-hidden>
+              {icon}
+            </span>
+          ) : undefined
+        }
+        data-variant={variant}
+        data-size={size}
+        {...(isIconOnly ? { "data-icon-only": "" } : {})}
+        {...sanitizedProps}
+      >
+        <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;

package/src/components/Flex/Flex.tsx

@@ -1,7 +1,79 @@
-import React from "react";
+/**
+ * Flex layout wrapper.
+ *
+ * NOTE: MUI does not have a native `<Flex>` component (it relies on `<Box display="flex">`
+ * or `<Stack>`). To maintain API parity with the mantine-adapter and provide a consistent
+ * developer experience, this component wraps MUI's Box and forces `display="flex"`.
+ *
+ * Like Stack and Group, this is a primitive layout component. It strictly filters out the
+ * `sx` prop using `OmitSx` and `filterSxProp` to enforce the use of standard layout scales.
+ */
+import React, { forwardRef } from "react";
+import { Box as MUIBox, type BoxProps as MUIBoxProps } from "@mui/material";
+import {
+  type RecursicaSpacing,
+  SPACING_MAP,
+  type OmitSx,
+  filterSxProp,
+} from "../../utils/filterStylingProps";
 
-export type FlexProps = React.HTMLAttributes<HTMLDivElement>;
+export interface RecursicaFlexProps {
+  /**
+   * Content to render inside the flex container.
+   */
+  children?: React.ReactNode;
 
-export const Flex: React.FC<FlexProps> = (props) => {
-  return <div {...props}>Flex</div>;
-};
+  /**
+   * The gap between flex items. Accepts standard MUI spacing or Recursica gap tokens
+   * (e.g. "rec-md").
+   */
+  gap?: string | number | RecursicaSpacing;
+
+  /**
+   * The vertical gap between flex items when wrapping. Accepts standard MUI spacing
+   * or Recursica gap tokens.
+   */
+  rowGap?: string | number | RecursicaSpacing;
+
+  /**
+   * The horizontal gap between flex items when wrapping. Accepts standard MUI spacing
+   * or Recursica gap tokens.
+   */
+  columnGap?: string | number | RecursicaSpacing;
+}
+
+export type FlexProps = OmitSx<MUIBoxProps & RecursicaFlexProps>;
+
+export const Flex = forwardRef<HTMLDivElement, FlexProps>(function Flex(
+  { children, gap = "rec-default", rowGap, columnGap, ...rest },
+  ref,
+) {
+  const safeProps = filterSxProp(rest as Record<string, unknown>);
+  const resolvedGap =
+    typeof gap === "string" && gap in SPACING_MAP
+      ? SPACING_MAP[gap as keyof typeof SPACING_MAP]
+      : gap;
+  const resolvedRowGap =
+    typeof rowGap === "string" && rowGap in SPACING_MAP
+      ? SPACING_MAP[rowGap as keyof typeof SPACING_MAP]
+      : rowGap;
+  const resolvedColumnGap =
+    typeof columnGap === "string" && columnGap in SPACING_MAP
+      ? SPACING_MAP[columnGap as keyof typeof SPACING_MAP]
+      : columnGap;
+
+  return (
+    <MUIBox
+      ref={ref}
+      display="flex"
+      {...safeProps}
+      gap={resolvedGap}
+      rowGap={resolvedRowGap}
+      columnGap={resolvedColumnGap}
+    >
+      {children}
+    </MUIBox>
+  );
+});
+
+Flex.displayName = "Flex";

package/src/components/FormControlLayout/FormControlLayout.stories.tsx

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

package/src/components/FormControlWrapper/FormControlWrapper.stories.tsx

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