@recursica/mui-adapter 0.2.0 → 0.3.0

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,17 @@
+# 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.

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

@@ -0,0 +1,300 @@
+/* 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 > * {
+  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;
+}
+
+/* ==== 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
+  );
+}

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

@@ -1,16 +1,147 @@
+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",
+    },
+  },
+  parameters: {
+    controls: {
+      include: [
+        "layer",
+        "withLayer",
+        "variant",
+        "size",
+        "children",
+        "component",
+        "icon",
+        "disabled",
+        "href",
+        "onClick",
+        "onChange",
+        "value",
+        "checked",
+      ],
+    },
+  },
 };
 
 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>
+  ),
 };