@recursica/mui-adapter 0.34.0 → 0.34.3

package/package.json

@@ -13,7 +13,7 @@
     "url": "git+https://github.com/borderux/recursica.git",
     "directory": "packages/mui-adapter"
   },
-  "version": "0.34.0",
+  "version": "0.34.3",
   "publishConfig": {
     "access": "public"
   },
@@ -59,14 +59,19 @@
     "lint": "eslint .",
     "storybook": "storybook dev -p 6012",
     "analyze-tokens": "analyze-tokens --css @recursica/official-release/recursica_variables_scoped.css --dir src/components --output token-analysis.json",
-    "prebuild": "npm run analyze-tokens"
+    "prebuild": "npm run analyze-tokens",
+    "adapter-tester": "adapter-tester --serve",
+    "adapter-tester:automated": "adapter-tester",
+    "test": "vitest run --project unit",
+    "test:dom": "vitest run --project dom"
   },
   "devDependencies": {
-    "@chromatic-com/storybook": "^5.1.1",
     "@eslint/js": "^9.25.0",
     "@mui/lab": "^7.0.1-beta.25",
     "@mui/x-date-pickers": "^9.11.0",
     "@mui/x-tree-view": "^9.11.0",
+    "@playwright/test": "^1.53.0",
+    "@recursica/adapter-tester": "*",
     "@recursica/recursica-postcss-vars": "*",
     "@recursica/storybook-template": "*",
     "@recursica/token-analyzer": "*",
@@ -102,7 +107,7 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@recursica/adapter-common": "^0.25.0",
+    "@recursica/adapter-common": "^0.25.1",
     "@recursica/official-release": "^2.8.0",
     "dayjs": "^1.11.21"
   },

package/src/OverStyling.tsx

@@ -35,7 +35,7 @@ export const OverStylingInfo = () => {
           Try It Yourself
         </Title>
 
-        <Stack direction="row" alignItems="center" gap="rec-sm" mb="rec-md">
+        <Stack direction="row" alignItems="center" spacing="rec-sm" mb="rec-md">
           <Switch
             label="Highlight Over-Styled Components"
             checked={isHighlightActive}
@@ -50,7 +50,7 @@ export const OverStylingInfo = () => {
           styling generics to punch right through the sandbox layout.
         </Text>
 
-        <Stack direction="row" gap="rec-default">
+        <Stack direction="row" spacing="rec-default">
           <Box>
             <Text
               variant="caption"

package/src/components/Accordion/Accordion.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Accordion component tests. Add tests here if/when needed.

package/src/components/AssistiveElement/AssistiveElement.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future AssistiveElement component tests. Add tests here if/when needed.

package/src/components/Autocomplete/Autocomplete.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Autocomplete component tests. Add tests here if/when needed.

package/src/components/Avatar/Avatar.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Avatar component tests. Add tests here if/when needed.

package/src/components/Badge/Badge.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Badge component tests. Add tests here if/when needed.

package/src/components/Box/Box.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Box component tests. Add tests here if/when needed.

package/src/components/Breadcrumb/Breadcrumb.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Breadcrumb component tests. Add tests here if/when needed.

package/src/components/Button/BUTTON_IMPLEMENTATION_NOTES.md

@@ -65,3 +65,13 @@ We explicitly pass `disableRipple` and `disableElevation` to block MUI's dynamic
 **Real discrepancy found:** `.root`'s "Shared Defaults" set `line-height` once, unconditionally, from the _default_-size token, and `.labelText` merely did `line-height: inherit` — so the small-size line-height token was never actually referenced (it was `recursica-ignore`d as "redundant"). Mantine's `Button.module.css`, by contrast, sets `line-height` directly on `.labelText` per size, from each size's own token. They currently resolve to the same literal value, so this wasn't visually observable, but it's a latent divergence from the source of truth — a future token change to the small-size line-height would silently not apply in mui-adapter.
 
 **Fix:** moved `line-height` off `.root` and onto `.labelText` (default token), added `.root[data-size="small"] .labelText { line-height: ... }` (small token), and removed the now-inaccurate `recursica-ignore` for that token — matching Mantine's structure exactly.
+
+---
+
+## Button doesn't shrink inside a constraining container (Genesis, 2026-08-27)
+
+**Bug:** in the `TruncatedLabel` story (`<div style={{ maxWidth: 250 }}><Button>...long label.../Button></div>`), the button ignored the 250px wrapper entirely and rendered at its full 534px intrinsic width, overflowing the wrapper instead of shrinking and showing the ellipsis.
+
+**Root cause:** `.root` has `width: fit-content` (to hug its own content instead of stretching in flex columns) but no `max-width`. Verified via Playwright: the wrapper measured exactly 250px, but `fit-content` on `.root` still resolved to its 534px `max-content` size — it doesn't reliably clamp against a narrower containing block on its own. Same root cause and identical fix in mantine-adapter.
+
+**Fix:** added `max-width: 100%` to `.root`. It's a no-op when the parent is wide enough (confirmed no change to `Default`/`IconOnly`/`TextWithIcon` story widths), and clamps the button to the parent's resolved width when the parent is narrower — at which point the existing `overflow: hidden` (`.root`) + `text-overflow: ellipsis`/`white-space: nowrap` (`.labelText`) take over, exactly as already documented above.

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

@@ -17,6 +17,7 @@
   position: relative;
   transition: all 0.2s ease;
   width: fit-content; /* Prevent stretching in flex columns */
+  max-width: 100%; /* Let a constraining parent (e.g. max-width container) actually shrink the button; fit-content alone ignores it */
 
   /* Shared Defaults */
   font-family: var(

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/Card/Card.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Card component tests. Add tests here if/when needed.

package/src/components/Checkbox/Checkbox.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Checkbox component tests. Add tests here if/when needed.

package/src/components/Chip/Chip.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Chip component tests. Add tests here if/when needed.

package/src/components/Container/Container.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Container component tests. Add tests here if/when needed.

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

@@ -120,6 +120,31 @@ export const ErrorState: Story = {
   },
 };
 
+export const OpenedCalendar: Story = {
+  args: {
+    label: "Meeting Date",
+    assistiveText: "Calendar rendered open by default for styling review.",
+    // MUI X's DatePicker supports a controlled `open` prop directly; pairing it with a
+    // no-op `onClose` keeps the calendar open with no click interaction needed — same
+    // intent as the mantine-adapter's `OpenedCalendar` story.
+    open: true,
+    onClose: () => {},
+    // Fixed (not computed) so the selected-day fill is visible on load, alongside the
+    // today marker, for styling review. Local-component constructor, not an ISO date
+    // string — `new Date("2026-08-26")` parses as UTC midnight, which renders as the
+    // 25th in any timezone behind UTC.
+    defaultValue: new Date(2026, 7, 26),
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "The calendar dropdown renders open by default so its styling can be reviewed without a click interaction.",
+      },
+    },
+  },
+};
+
 export const StaticReadOnly: Story = {
   args: {
     label: "Static ReadOnly Review",

package/src/components/DatePicker/DatePicker.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future DatePicker component tests. Add tests here if/when needed.

package/src/components/Dropdown/Dropdown.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Dropdown component tests. Add tests here if/when needed.

package/src/components/FileInput/FileInput.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future FileInput component tests. Add tests here if/when needed.

package/src/components/FileUpload/FileUpload.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future FileUpload component tests. Add tests here if/when needed.

package/src/components/Flex/Flex.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Flex component tests. Add tests here if/when needed.

package/src/components/Flex/Flex.tsx

@@ -2,8 +2,10 @@
  * 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"`.
+ * or `<Stack>`). Per the layout-components rule, when a UI kit lacks an equivalent component
+ * it's built following a prop definition similar to Mantine's own `Flex` (gap/rowGap/columnGap/
+ * direction/align/justify/wrap) — this shape is owned locally here, not shared as a formal
+ * cross-adapter Recursica contract.
  *
  * 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.
@@ -17,10 +19,25 @@ import {
   type WithRecursicaSpacing,
 } from "../../utils/filterStylingProps";
 
-import { type RecursicaFlexProps } from "@recursica/adapter-common";
+interface FlexOwnProps {
+  /** Global gap spacing key or CSS value */
+  gap?: string | number;
+  /** Horizontal row spacing */
+  rowGap?: string | number;
+  /** Vertical column spacing */
+  columnGap?: string | number;
+  /** Flex direction */
+  direction?: React.CSSProperties["flexDirection"];
+  /** Align items */
+  align?: React.CSSProperties["alignItems"];
+  /** Justify content */
+  justify?: React.CSSProperties["justifyContent"];
+  /** Flex wrap */
+  wrap?: React.CSSProperties["flexWrap"];
+}
 
 export type FlexProps = WithRecursicaSpacing<
-  OmitSx<MUIBoxProps & RecursicaFlexProps>
+  OmitSx<MUIBoxProps & FlexOwnProps>
 >;
 
 export const Flex = forwardRef<HTMLDivElement, FlexProps>(function Flex(

package/src/components/FormControlLayout/FormControlLayout.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future FormControlLayout component tests. Add tests here if/when needed.

package/src/components/FormControlWrapper/FormControlWrapper.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future FormControlWrapper component tests. Add tests here if/when needed.

package/src/components/Grid/Grid.stories.tsx

@@ -14,20 +14,19 @@ const meta: Meta<GridStoryProps> = {
     docs: {
       description: {
         component:
-          "Grid is a 12-column (by default) responsive grid layout hand-composed from MUI's Grid, providing column spans, offsets, ordering, and breakpoint-based visibility with the same API as the mantine-adapter's Grid/Grid.Col.",
+          "Grid is a 12-column (by default) responsive grid layout hand-composed from MUI's own Grid, providing column sizing, offsets, ordering, and breakpoint-based visibility using MUI's native prop names.",
       },
     },
     controls: {
-      include: ["children", "gap", "columns", "grow", "justify", "align"],
+      include: ["children", "spacing", "columns", "direction", "wrap"],
     },
   },
   args: {
-    gap: "rec-default",
+    spacing: "rec-default",
     columns: 12,
-    grow: false,
   },
   argTypes: {
-    gap: {
+    spacing: {
       control: "select",
       options: [
         "rec-none",
@@ -38,32 +37,12 @@ const meta: Meta<GridStoryProps> = {
         "rec-xl",
         "rec-2xl",
       ],
-      description: "Gap between columns",
+      description: "Space between columns",
     },
     columns: {
       control: "number",
       description: "Number of columns in each row",
     },
-    grow: {
-      control: "boolean",
-      description: "Columns in the last row expand to fill available space",
-    },
-    justify: {
-      control: "select",
-      options: [
-        "flex-start",
-        "center",
-        "flex-end",
-        "space-between",
-        "space-around",
-      ],
-      description: "Justify-content property",
-    },
-    align: {
-      control: "select",
-      options: ["flex-start", "center", "flex-end", "stretch"],
-      description: "Align-items property",
-    },
   },
 };
 
@@ -83,34 +62,34 @@ export const Default: Story = {
   // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
   render: ({ withLayer, layer, ...args }: any) => (
     <Grid {...args}>
-      <Grid.Col span={4}>
-        <Swatch>span 4</Swatch>
+      <Grid.Col size={4}>
+        <Swatch>size 4</Swatch>
       </Grid.Col>
-      <Grid.Col span={4}>
-        <Swatch>span 4</Swatch>
+      <Grid.Col size={4}>
+        <Swatch>size 4</Swatch>
       </Grid.Col>
-      <Grid.Col span={4}>
-        <Swatch>span 4</Swatch>
+      <Grid.Col size={4}>
+        <Swatch>size 4</Swatch>
       </Grid.Col>
     </Grid>
   ),
 };
 
-export const ResponsiveSpans: Story = {
+export const ResponsiveSizes: Story = {
   // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
   render: ({ withLayer, layer, ...args }: any) => (
     <Grid {...args}>
-      <Grid.Col span={{ base: 12, sm: 6, md: 3 }}>
-        <Swatch>base 12 / sm 6 / md 3</Swatch>
+      <Grid.Col size={{ xs: 12, sm: 6, md: 3 }}>
+        <Swatch>xs 12 / sm 6 / md 3</Swatch>
       </Grid.Col>
-      <Grid.Col span={{ base: 12, sm: 6, md: 3 }}>
-        <Swatch>base 12 / sm 6 / md 3</Swatch>
+      <Grid.Col size={{ xs: 12, sm: 6, md: 3 }}>
+        <Swatch>xs 12 / sm 6 / md 3</Swatch>
       </Grid.Col>
-      <Grid.Col span={{ base: 12, sm: 6, md: 3 }}>
-        <Swatch>base 12 / sm 6 / md 3</Swatch>
+      <Grid.Col size={{ xs: 12, sm: 6, md: 3 }}>
+        <Swatch>xs 12 / sm 6 / md 3</Swatch>
       </Grid.Col>
-      <Grid.Col span={{ base: 12, sm: 6, md: 3 }}>
-        <Swatch>base 12 / sm 6 / md 3</Swatch>
+      <Grid.Col size={{ xs: 12, sm: 6, md: 3 }}>
+        <Swatch>xs 12 / sm 6 / md 3</Swatch>
       </Grid.Col>
     </Grid>
   ),
@@ -120,31 +99,28 @@ export const Offset: Story = {
   // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
   render: ({ withLayer, layer, ...args }: any) => (
     <Grid {...args}>
-      <Grid.Col span={4} offset={4}>
-        <Swatch>span 4, offset 4</Swatch>
+      <Grid.Col size={4} offset={4}>
+        <Swatch>size 4, offset 4</Swatch>
       </Grid.Col>
-      <Grid.Col span={4}>
-        <Swatch>span 4</Swatch>
+      <Grid.Col size={4}>
+        <Swatch>size 4</Swatch>
       </Grid.Col>
     </Grid>
   ),
 };
 
 export const Grow: Story = {
-  args: {
-    grow: true,
-  },
   // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
   render: ({ withLayer, layer, ...args }: any) => (
     <Grid {...args}>
-      <Grid.Col span={3}>
-        <Swatch>span 3</Swatch>
+      <Grid.Col size={3}>
+        <Swatch>size 3</Swatch>
       </Grid.Col>
-      <Grid.Col span={3}>
-        <Swatch>span 3</Swatch>
+      <Grid.Col size={3}>
+        <Swatch>size 3</Swatch>
       </Grid.Col>
-      <Grid.Col span={3}>
-        <Swatch>span 3 (grows to fill row)</Swatch>
+      <Grid.Col size="grow">
+        <Swatch>size &quot;grow&quot; (fills remaining space)</Swatch>
       </Grid.Col>
     </Grid>
   ),
@@ -157,14 +133,14 @@ export const CustomColumnCount: Story = {
   // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
   render: ({ withLayer, layer, ...args }: any) => (
     <Grid {...args}>
-      <Grid.Col span={2}>
-        <Swatch>span 2 of 6</Swatch>
+      <Grid.Col size={2}>
+        <Swatch>size 2 of 6</Swatch>
       </Grid.Col>
-      <Grid.Col span={2}>
-        <Swatch>span 2 of 6</Swatch>
+      <Grid.Col size={2}>
+        <Swatch>size 2 of 6</Swatch>
       </Grid.Col>
-      <Grid.Col span={2}>
-        <Swatch>span 2 of 6</Swatch>
+      <Grid.Col size={2}>
+        <Swatch>size 2 of 6</Swatch>
       </Grid.Col>
     </Grid>
   ),
@@ -174,10 +150,10 @@ export const VisibleHiddenFrom: Story = {
   // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
   render: ({ withLayer, layer, ...args }: any) => (
     <Grid {...args}>
-      <Grid.Col span={6} hiddenFrom="sm">
+      <Grid.Col size={6} hiddenFrom="sm">
         <Swatch>hidden from sm and up</Swatch>
       </Grid.Col>
-      <Grid.Col span={6} visibleFrom="sm">
+      <Grid.Col size={6} visibleFrom="sm">
         <Swatch>visible from sm and up</Swatch>
       </Grid.Col>
     </Grid>

package/src/components/Grid/Grid.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Grid component tests. Add tests here if/when needed.