@recursica/mui-adapter 0.2.0 → 0.4.0

package/src/Version.tsx

@@ -1,43 +1,36 @@
 import ReactMarkdown from "react-markdown";
-import {
-  Container,
-  Paper,
-  Title,
-  TypographyStylesProvider,
-  Group,
-  Anchor,
-  Divider,
-} from "@mantine/core";
+import { Paper, Divider } from "@mui/material";
+import { Container, Title, Group, Link, Box } from "./components";
 import pkg from "../package.json";
 import changelog from "../CHANGELOG.md?raw";
 
 export const VersionInfo = () => {
   return (
-    <Container size="md" py="xl">
-      <Paper withBorder p="xl" radius="md">
-        <Title order={1} mb="xs">
-          Mantine Adapter v{pkg.version}
+    <Container size="md" style={{ padding: "32px 0" }}>
+      <Paper variant="outlined" sx={{ p: 4, borderRadius: 2 }}>
+        <Title order={1} mb={1}>
+          MUI Adapter v{pkg.version}
         </Title>
-        <Group mb="xl" gap="md">
-          <Anchor
+        <Group mb={4} gap="rec-md">
+          <Link
             href="https://github.com/borderux/recursica"
             target="_blank"
             rel="noopener noreferrer"
           >
             GitHub Repository
-          </Anchor>
-          <Anchor
+          </Link>
+          <Link
             href="https://recursica.com"
             target="_blank"
             rel="noopener noreferrer"
           >
             Documentation & Website
-          </Anchor>
+          </Link>
         </Group>
-        <Divider mb="xl" />
-        <TypographyStylesProvider>
+        <Divider sx={{ mb: 4 }} />
+        <Box className="markdown-body">
           <ReactMarkdown>{changelog}</ReactMarkdown>
-        </TypographyStylesProvider>
+        </Box>
       </Paper>
     </Container>
   );

package/src/components/Accordion/Accordion.stories.tsx

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

package/src/components/AssistiveElement/AssistiveElement.stories.tsx

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

package/src/components/Avatar/Avatar.stories.tsx

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

package/src/components/Badge/Badge.stories.tsx

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

package/src/components/Box/Box.stories.tsx

@@ -12,6 +12,23 @@ const meta: Meta<typeof Box> = {
           "The `Box` component is the foundational layout primitive. It accepts all standard MUI layout properties (like `m`, `mt`, `p`, `px`, etc.), but natively intercepts **Recursica Spacing Tokens** (e.g., `rec-none`, `rec-sm`, `rec-default`, `rec-md`, `rec-lg`, `rec-xl`, `rec-2xl`). This allows developers to use Recursica's strict design tokens seamlessly alongside standard MUI spacing.",
       },
     },
+    controls: {
+      include: [
+        "layer",
+        "withLayer",
+        "children",
+        "component",
+        "variant",
+        "size",
+        "icon",
+        "disabled",
+        "href",
+        "onClick",
+        "onChange",
+        "value",
+        "checked",
+      ],
+    },
   },
 };
 
@@ -24,11 +41,7 @@ export const Default: Story = {
     m: "20px",
   },
   render: (args) => (
-    <Box
-      {...args}
-      style={{ border: "1px solid gray", padding: "10px" }}
-      overStyled={true}
-    />
+    <Box {...args} style={{ border: "1px solid gray", padding: "10px" }} />
   ),
 };
 
@@ -40,11 +53,7 @@ export const WithRecursicaTokens: Story = {
   },
   render: (args) => (
     <div style={{ border: "1px dashed #ccc", display: "inline-block" }}>
-      <Box
-        {...args}
-        style={{ backgroundColor: "rgba(0,0,0,0.1)" }}
-        overStyled={true}
-      />
+      <Box {...args} style={{ backgroundColor: "rgba(0,0,0,0.1)" }} />
     </div>
   ),
 };

package/src/components/Box/Box.tsx

@@ -1,26 +1,23 @@
+/**
+ * Box layout wrapper.
+ *
+ * NOTE: Box is the lowest-level primitive layout component. It explicitly ALLOWS
+ * the `sx` prop as an escape hatch. It does not use the strict RecursicaOverStyled gatekeeper
+ * or any style stripping utilities.
+ */
 import React, { forwardRef } from "react";
 import { Box as MUIBox, type BoxProps as MUIBoxProps } from "@mui/material";
-import {
-  filterStylingProps,
-  type RecursicaOverStyled,
-} from "../../utils/filterStylingProps";
 
-export type BoxProps<C extends React.ElementType = "div"> = RecursicaOverStyled<
-  MUIBoxProps<C, { component?: C }>
+export type BoxProps<C extends React.ElementType = "div"> = MUIBoxProps<
+  C,
+  { component?: C }
 >;
 
 export const Box = forwardRef(function Box<C extends React.ElementType = "div">(
   props: BoxProps<C>,
   ref: React.Ref<Element>,
 ) {
-  const { overStyled = false, ...rest } = props;
-
-  const sanitizedProps = filterStylingProps(
-    rest as Record<string, unknown>,
-    overStyled,
-  );
-
-  return <MUIBox ref={ref} {...sanitizedProps} />;
+  return <MUIBox ref={ref} {...props} />;
 }) as <C extends React.ElementType = "div">(
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   props: BoxProps<C> & { ref?: React.ForwardedRef<any> },

package/src/components/Box/IMPLEMENTATION_NOTES.md

@@ -0,0 +1,5 @@
+# Box Implementation Notes
+
+## `sx` Prop Exemption
+
+By design, the `Box` component is the most permissive primitive in the UI kit. It explicitly allows the `sx` prop to pass through to the underlying MUI `Box`. It does not use any strict styling gatekeepers (`RecursicaOverStyled`, `filterSxProp`). It is intended to be used as a final escape hatch when the standard layout primitives or design system tokens cannot fulfill a unique layout requirement.

package/src/components/Breadcrumb/Breadcrumb.stories.tsx

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

package/src/components/Button/BUTTON_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,33 @@
+# Button Component Implementation Notes
+
+**Implementation Philosophy:**
+The Button component serves as a foundational building block in Recursica. This implementation wraps the `@mui/material/Button` component but **disables its native visual heuristics entirely.**
+
+We explicitly pass `disableRipple` and `disableElevation` to block MUI's dynamic behaviors. Furthermore, we intentionally **do not** map our `variant` or `size` properties to MUI's native `variant` or `size` props because doing so would trigger MUI's internal CSS engines to inject styles that clash with our strict design tokens.
+
+**Styling Strategy:**
+
+- We utilize `filterStylingProps` to prevent rogue injections of `sx`, `style`, or `className` properties that would violate the design system.
+- All styling is controlled directly via CSS Modules, mapping DOM attributes like `data-variant` and `data-size` to pure CSS selectors.
+- Hover states are managed with a standard `::after` pseudo-element overlay hack rather than relying on native hover psuedo-selectors modifying background-color directly. This allows a clean `opacity` overlay based on the provided design tokens, which guarantees identical visual feedback behavior across all underlying themes without overriding background hues manually.
+- The polymorphic `component` prop natively supported by MUI is safely forwarded to allow correct semantics (e.g. rendering as an `<a>` tag or using a router `Link`).
+
+**Accessibility:**
+
+- We inject a development-time warning explicitly requiring `aria-label` when the component detects an icon-only configuration.
+
+---
+
+## Loader color contrast
+
+**Decision:** When a Button is in a loading state, the `Recursica Loader` component is injected via the `loadingIndicator` prop. The `Loader` component strictly defines its own colors and styles per variant, meaning it does not automatically inherit the text color (`currentColor`) from the Button.
+
+**Constraint:** This can lead to contrast issues (e.g., a blue dots loader inside a solid blue button). Design has explicitly decided not to address this at the moment. As such, developers using the `loading` prop must be aware that the loader's color is fixed by its internal tokens, not by the button's context.
+
+---
+
+## Loading state enforces disabled state
+
+**Decision:** When `loading={true}` is passed to the Button, the component explicitly forces `disabled={true}` natively on the underlying element.
+
+**Implementation:** This ensures that loading buttons automatically inherit the brand theme disabled opacities (via the `:disabled` CSS pseudo-class) rather than relying solely on MUI's internal loading opacity adjustments.

package/src/components/Button/Button.module.css

@@ -0,0 +1,343 @@
+/* Baseline and Reset */
+.root {
+  box-sizing: border-box;
+  margin: 0;
+  border-style: solid;
+  overflow: hidden; /* Truncation bounding box */
+  position: relative;
+  transition: all 0.2s ease;
+  width: fit-content; /* Prevent stretching in flex columns */
+
+  /* Shared Defaults */
+  font-family: var(
+    --recursica_ui-kit_components_button_variants_sizes_default_properties_text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_button_variants_sizes_default_properties_text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_button_variants_sizes_default_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_button_variants_sizes_default_properties_text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_button_variants_sizes_default_properties_text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_button_variants_sizes_default_properties_text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_button_variants_sizes_default_properties_text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_button_variants_sizes_default_properties_text_text-transform
+  );
+}
+
+/* Reset MUI native properties */
+.root {
+  text-transform: none;
+  min-width: 0;
+  color: inherit;
+  background-color: transparent;
+}
+
+/* Internal layout logic for Truncation */
+.root > *:not(:global(.MuiButton-loadingIndicator)) {
+  min-width: 0;
+  position: relative;
+  z-index: 1;
+}
+
+.label {
+  display: flex;
+  align-items: center;
+  min-width: 0;
+  flex: 1 1 0;
+}
+
+.labelText {
+  display: block;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: inherit;
+  line-height: inherit;
+}
+.root[data-loading="true"] .labelText {
+  visibility: hidden;
+}
+
+/* 
+ * Keep the loader fully opaque, but make the background transparent 
+ * to create contrast for solid variants without changing the loader color. 
+ */
+.root[data-loading="true"] {
+  opacity: 1 !important;
+}
+
+.root[data-size="default"][data-variant="solid"][data-loading="true"] {
+  background-color: color-mix(
+    in srgb,
+    var(
+        --recursica_ui-kit_components_button_variants_styles_solid_properties_colors_background
+      )
+      calc(
+        var(
+            --recursica_ui-kit_components_button_variants_sizes_default_properties_disabled-opacity
+          ) *
+          100%
+      ),
+    transparent
+  ) !important;
+}
+
+.root[data-size="small"][data-variant="solid"][data-loading="true"] {
+  background-color: color-mix(
+    in srgb,
+    var(
+        --recursica_ui-kit_components_button_variants_styles_solid_properties_colors_background
+      )
+      calc(
+        var(
+            --recursica_ui-kit_components_button_variants_sizes_small_properties_disabled-opacity
+          ) *
+          100%
+      ),
+    transparent
+  ) !important;
+}
+
+/* ==== SIZES ==== */
+.root[data-size="default"] {
+  border-radius: var(
+    --recursica_ui-kit_components_button_variants_sizes_default_properties_border-radius
+  );
+  height: var(
+    --recursica_ui-kit_components_button_variants_sizes_default_properties_height
+  );
+  min-width: var(
+    --recursica_ui-kit_components_button_variants_sizes_default_properties_min-width
+  );
+  padding: 0
+    var(
+      --recursica_ui-kit_components_button_variants_sizes_default_properties_horizontal-padding
+    );
+}
+.root[data-size="default"] .labelText {
+  max-width: var(
+    --recursica_ui-kit_components_button_variants_sizes_default_properties_max-label-width
+  );
+}
+.root[data-size="small"] {
+  border-radius: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_border-radius
+  );
+  height: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_height
+  );
+  min-width: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_min-width
+  );
+  padding: 0
+    var(
+      --recursica_ui-kit_components_button_variants_sizes_small_properties_horizontal-padding
+    );
+
+  /* Override specific typography for small */
+  font-family: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_text_font-family,
+    var(
+      --recursica_ui-kit_components_button_variants_sizes_default_properties_text_font-family
+    )
+  );
+  font-size: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_text_font-size,
+    var(
+      --recursica_ui-kit_components_button_variants_sizes_default_properties_text_font-size
+    )
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_text_font-weight,
+    var(
+      --recursica_ui-kit_components_button_variants_sizes_default_properties_text_font-weight
+    )
+  );
+}
+.root[data-size="small"] .labelText {
+  max-width: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_max-label-width
+  );
+}
+
+/* Icon Resets */
+.iconWrapper {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+}
+.iconWrapper > * {
+  width: 100%;
+  height: 100%;
+  object-fit: contain;
+}
+.root[data-size="default"] .iconWrapper {
+  width: var(
+    --recursica_ui-kit_components_button_variants_sizes_default_properties_icon
+  );
+  height: var(
+    --recursica_ui-kit_components_button_variants_sizes_default_properties_icon
+  );
+}
+.root[data-size="small"] .iconWrapper {
+  width: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_icon
+  );
+  height: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_icon
+  );
+}
+
+/* MUI uses .MuiButton-startIcon and .MuiButton-endIcon */
+.root[data-size="default"] .MuiButton-startIcon,
+.root[data-size="default"] .MuiButton-endIcon {
+  margin-left: 0;
+  margin-right: var(
+    --recursica_ui-kit_components_button_variants_sizes_default_properties_icon-text-gap
+  );
+}
+.root[data-size="small"] .MuiButton-startIcon,
+.root[data-size="small"] .MuiButton-endIcon {
+  margin-left: 0;
+  margin-right: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_icon-text-gap
+  );
+}
+
+/* Icon-only logic overrides */
+.root[data-icon-only] .MuiButton-startIcon,
+.root[data-icon-only] .MuiButton-endIcon {
+  margin-right: 0;
+  margin-left: 0;
+}
+
+/* Disabled */
+.root[data-size="default"]:disabled,
+.root[data-size="default"]:global(.Mui-disabled) {
+  opacity: var(
+    --recursica_ui-kit_components_button_variants_sizes_default_properties_disabled-opacity
+  );
+  cursor: not-allowed;
+}
+.root[data-size="small"]:disabled,
+.root[data-size="small"]:global(.Mui-disabled) {
+  opacity: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_disabled-opacity
+  );
+  cursor: not-allowed;
+}
+
+/* Global Hover Hack Overlay */
+.root::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+  z-index: 0;
+  pointer-events: none;
+  transition: opacity 150ms ease;
+  opacity: 0;
+}
+.root[data-size="default"]::after {
+  background-color: var(
+    --recursica_ui-kit_components_button_variants_sizes_default_properties_hover-color
+  );
+}
+.root[data-size="small"]::after {
+  background-color: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_hover-color
+  );
+}
+.root:hover:not(:disabled):not(:global(.Mui-disabled))::after {
+  opacity: var(
+    --recursica_ui-kit_components_button_variants_sizes_default_properties_hover-opacity,
+    0.1
+  );
+}
+
+/* ==== VARIANTS ==== */
+
+/* SOLID */
+.root[data-variant="solid"] {
+  border-width: var(
+    --recursica_ui-kit_components_button_variants_styles_solid_properties_border-size
+  );
+  box-shadow: var(
+    --recursica_ui-kit_components_button_variants_styles_solid_properties_elevation
+  );
+  background-color: var(
+    --recursica_ui-kit_components_button_variants_styles_solid_properties_colors_background
+  );
+  border-color: var(
+    --recursica_ui-kit_components_button_variants_styles_solid_properties_colors_border-color
+  );
+  color: var(
+    --recursica_ui-kit_components_button_variants_styles_solid_properties_colors_text
+  );
+}
+.root[data-variant="solid"]:hover:not(:disabled):not(:global(.Mui-disabled)) {
+  color: var(
+    --recursica_ui-kit_components_button_variants_styles_solid_properties_colors_text-hover
+  );
+}
+
+/* OUTLINE */
+.root[data-variant="outline"] {
+  border-width: var(
+    --recursica_ui-kit_components_button_variants_styles_outline_properties_border-size
+  );
+  box-shadow: var(
+    --recursica_ui-kit_components_button_variants_styles_outline_properties_elevation
+  );
+  background-color: var(
+    --recursica_ui-kit_components_button_variants_styles_outline_properties_colors_background
+  );
+  border-color: var(
+    --recursica_ui-kit_components_button_variants_styles_outline_properties_colors_border-color
+  );
+  color: var(
+    --recursica_ui-kit_components_button_variants_styles_outline_properties_colors_text
+  );
+}
+.root[data-variant="outline"]:hover:not(:disabled):not(:global(.Mui-disabled)) {
+  color: var(
+    --recursica_ui-kit_components_button_variants_styles_outline_properties_colors_text-hover
+  );
+}
+
+/* TEXT */
+.root[data-variant="text"] {
+  border-width: var(
+    --recursica_ui-kit_components_button_variants_styles_text_properties_border-size
+  );
+  box-shadow: var(
+    --recursica_ui-kit_components_button_variants_styles_text_properties_elevation
+  );
+  background-color: var(
+    --recursica_ui-kit_components_button_variants_styles_text_properties_colors_background
+  );
+  border-color: var(
+    --recursica_ui-kit_components_button_variants_styles_text_properties_colors_border-color
+  );
+  color: var(
+    --recursica_ui-kit_components_button_variants_styles_text_properties_colors_text
+  );
+}
+.root[data-variant="text"]:hover:not(:disabled):not(:global(.Mui-disabled)) {
+  color: var(
+    --recursica_ui-kit_components_button_variants_styles_text_properties_colors_text-hover
+  );
+}