@recursica/mui-adapter 0.34.1 → 0.34.3

package/src/components/Grid/Grid.tsx

@@ -1,22 +1,30 @@
 /**
  * Grid layout wrapper.
  *
- * NOTE: MUI merges "container" and "item" into a single Grid component (no separate
- * Grid.Col in the underlying library, and no native `order`, `justifyContent`,
- * `alignItems`, or breakpoint-visibility support). To preserve API parity with the
- * mantine-adapter (Grid + Grid.Col dot notation, matching Mantine's own Grid/Grid.Col),
- * this file splits MUI's single component back into two wrappers: Grid always renders
- * MUI's `<Grid container>`, GridCol always renders MUI's `<Grid>` in item mode.
+ * MUI merges "container" and "item" into a single `Grid` component (no separate Grid.Col,
+ * unlike Mantine). To preserve the Grid/Grid.Col dot-notation shape across adapters, this
+ * file splits MUI's single component back into two thin wrappers: Grid always renders MUI's
+ * `<Grid container>`, GridCol always renders a plain MUI `<Grid>` (item mode).
+ *
+ * Per the layout-components rule, both wrappers simply pass through MUI's own Grid props
+ * (`size`, `offset`, `spacing`, `columns`, `direction`, `wrap`) with no Recursica renaming.
+ * MUI has no per-item "grow to fill remaining space" container flag like Mantine's `grow`;
+ * use MUI's own `size="grow"` on individual columns instead. `visibleFrom`/`hiddenFrom`
+ * don't exist in MUI at all, so — per the rule that a missing kit feature is built following
+ * Mantine's own shape — they're added here via CSS classes, keyed on MUI's own breakpoint
+ * scale (`xs`/`sm`/`md`/`lg`/`xl`).
+ *
+ * `justifyContent`/`alignItems` (container) and `order` (item) are typed on `MuiGridProps`
+ * (inherited generically from `SystemProps`) but MUI's Grid style generator — verified by
+ * reading `@mui/system`'s `gridGenerator.js`/`createGrid.js` — only wires up `size`, `offset`,
+ * `columns`, `spacing`/`rowSpacing`/`columnSpacing`, `direction`, and `wrap`; passing these
+ * three straight through would silently no-op. They're pulled out and applied via inline
+ * `style` instead, still using MUI's own native names.
  *
  * Like Flex, Stack, Group, and Container, this is a primitive layout component and
  * does not use the `RecursicaOverStyled` gatekeeper — only the `sx` prop is stripped.
  */
-import {
-  createContext,
-  forwardRef,
-  useContext,
-  type CSSProperties,
-} from "react";
+import { forwardRef, type CSSProperties } from "react";
 import { Grid as MuiGrid, type GridProps as MuiGridProps } from "@mui/material";
 import {
   SPACING_MAP,
@@ -26,81 +34,9 @@ import {
 } from "../../utils/filterStylingProps";
 import styles from "./Grid.module.css";
 
-import {
-  type RecursicaGridProps,
-  type RecursicaGridColProps,
-} from "@recursica/adapter-common";
-
 type Breakpoint = "xs" | "sm" | "md" | "lg" | "xl";
-type RecursicaBreakpoint = "base" | Breakpoint;
-
-const GridContext = createContext<{ grow: boolean }>({ grow: false });
-
-/** Remaps the Recursica-only "base" breakpoint key to MUI's "xs" (its smallest breakpoint). */
-function remapBase<T>(
-  value: T | Partial<Record<RecursicaBreakpoint, T>> | undefined,
-): T | Partial<Record<Breakpoint, T>> | undefined {
-  if (value === undefined || typeof value !== "object") {
-    return value as T | undefined;
-  }
-  const { base, ...rest } = value as Partial<Record<RecursicaBreakpoint, T>>;
-  return base !== undefined
-    ? ({ xs: base, ...rest } as Partial<Record<Breakpoint, T>>)
-    : (rest as Partial<Record<Breakpoint, T>>);
-}
-
-/**
- * Recursica's "auto" (grow to fill remaining space) and "content" (size to content)
- * are the inverse of MUI's own "auto" (size to content) and "grow" (fill remaining
- * space) keywords.
- */
-function mapSpanValue(
-  value: number | "auto" | "content" | undefined,
-): number | "auto" | "grow" | undefined {
-  if (value === "auto") return "grow";
-  if (value === "content") return "auto";
-  return value;
-}
-
-function mapSpan(span: RecursicaGridColProps["span"]): MuiGridProps["size"] {
-  const remapped = remapBase(span);
-  if (remapped === undefined || typeof remapped !== "object") {
-    return mapSpanValue(remapped as number | "auto" | "content" | undefined);
-  }
-  const mapped: Partial<Record<Breakpoint, number | "auto" | "grow">> = {};
-  (
-    Object.entries(remapped) as [Breakpoint, number | "auto" | "content"][]
-  ).forEach(([key, value]) => {
-    mapped[key] = mapSpanValue(value);
-  });
-  return mapped as MuiGridProps["size"];
-}
-
-function mapOffset(
-  offset: RecursicaGridColProps["offset"],
-): MuiGridProps["offset"] {
-  return remapBase(offset) as MuiGridProps["offset"];
-}
-
-/**
- * `order` has no native MUI Grid equivalent. A fixed number is applied directly.
- * A responsive object is NOT fully supported in this v1 — the smallest specified
- * breakpoint's value is applied as a single static order (documented in
- * IMPLEMENTATION_NOTES.md), rather than building bespoke per-breakpoint CSS for it.
- */
-function resolveOrder(
-  order: RecursicaGridColProps["order"],
-): number | undefined {
-  if (order === undefined || typeof order === "number") {
-    return order;
-  }
-  const remapped = remapBase(order) as Partial<Record<Breakpoint, number>>;
-  return (
-    remapped.xs ?? remapped.sm ?? remapped.md ?? remapped.lg ?? remapped.xl
-  );
-}
 
-const HIDDEN_FROM_CLASS: Partial<Record<Breakpoint, string>> = {
+const HIDDEN_FROM_CLASS: Record<Breakpoint, string> = {
   xs: styles.hiddenFromXs,
   sm: styles.hiddenFromSm,
   md: styles.hiddenFromMd,
@@ -108,7 +44,7 @@ const HIDDEN_FROM_CLASS: Partial<Record<Breakpoint, string>> = {
   xl: styles.hiddenFromXl,
 };
 
-// "xs"/"base" intentionally absent: visible from the smallest breakpoint means never hidden.
+// "xs" intentionally absent: visible from the smallest breakpoint means never hidden.
 const VISIBLE_FROM_CLASS: Partial<Record<Breakpoint, string>> = {
   sm: styles.visibleFromSm,
   md: styles.visibleFromMd,
@@ -116,56 +52,47 @@ const VISIBLE_FROM_CLASS: Partial<Record<Breakpoint, string>> = {
   xl: styles.visibleFromXl,
 };
 
-function normalizeBreakpoint(bp: RecursicaBreakpoint): Breakpoint {
-  return bp === "base" ? "xs" : bp;
-}
-
 // ============================================================
 // GRID
 // ============================================================
 
 export type GridProps = WithRecursicaSpacing<
-  OmitSx<Omit<MuiGridProps, "container" | "size" | "offset">> &
-    RecursicaGridProps
->;
+  OmitSx<Omit<MuiGridProps, "container" | "justifyContent" | "alignItems">>
+> & {
+  /** Sets `justify-content` on the container. Applied via inline style — see notes above. */
+  justifyContent?: CSSProperties["justifyContent"];
+  /** Sets `align-items` on the container. Applied via inline style — see notes above. */
+  alignItems?: CSSProperties["alignItems"];
+};
 
 const GridBase = forwardRef<HTMLDivElement, GridProps>(function Grid(
   {
     children,
-    gap = "rec-default",
-    columns = 12,
-    grow = false,
-    justify,
-    align,
+    spacing = "rec-default",
+    justifyContent,
+    alignItems,
     style,
     ...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 resolvedSpacing =
+    typeof spacing === "string" && spacing in SPACING_MAP
+      ? SPACING_MAP[spacing as keyof typeof SPACING_MAP]
+      : spacing;
 
   return (
-    <GridContext.Provider value={{ grow }}>
-      <MuiGrid
-        ref={ref}
-        {...(safeProps as unknown as MuiGridProps)}
-        container
-        columns={columns}
-        spacing={resolvedGap}
-        className={styles.root}
-        style={{
-          justifyContent: justify,
-          alignItems: align,
-          ...(style as CSSProperties),
-        }}
-      >
-        {children}
-      </MuiGrid>
-    </GridContext.Provider>
+    <MuiGrid
+      ref={ref}
+      {...(safeProps as unknown as MuiGridProps)}
+      container
+      spacing={resolvedSpacing}
+      className={styles.root}
+      style={{ justifyContent, alignItems, ...(style as CSSProperties) }}
+    >
+      {children}
+    </MuiGrid>
   );
 });
 GridBase.displayName = "Grid";
@@ -175,33 +102,27 @@ GridBase.displayName = "Grid";
 // ============================================================
 
 export type GridColProps = WithRecursicaSpacing<
-  OmitSx<Omit<MuiGridProps, "container" | "size" | "offset">> &
-    RecursicaGridColProps
->;
+  OmitSx<Omit<MuiGridProps, "container" | "order">>
+> & {
+  /** Sets the CSS `order` property. Applied via inline style — see notes above. */
+  order?: number;
+  /** Hides the column below the given breakpoint. MUI has no native equivalent. */
+  visibleFrom?: Breakpoint;
+  /** Hides the column above the given breakpoint. MUI has no native equivalent. */
+  hiddenFrom?: Breakpoint;
+};
 
 export const GridCol = forwardRef<HTMLDivElement, GridColProps>(
   function GridCol(
-    {
-      children,
-      span,
-      offset,
-      order,
-      visibleFrom,
-      hiddenFrom,
-      style,
-      className,
-      ...rest
-    },
+    { children, order, visibleFrom, hiddenFrom, style, className, ...rest },
     ref,
   ) {
-    const { grow } = useContext(GridContext);
     const safeProps = filterSxProp(rest as Record<string, unknown>);
-    const resolvedOrder = resolveOrder(order);
 
     const visibilityClass = visibleFrom
-      ? VISIBLE_FROM_CLASS[normalizeBreakpoint(visibleFrom)]
+      ? VISIBLE_FROM_CLASS[visibleFrom]
       : hiddenFrom
-        ? HIDDEN_FROM_CLASS[normalizeBreakpoint(hiddenFrom)]
+        ? HIDDEN_FROM_CLASS[hiddenFrom]
         : undefined;
 
     const finalClassName = [styles.col, visibilityClass, className]
@@ -211,15 +132,9 @@ export const GridCol = forwardRef<HTMLDivElement, GridColProps>(
     return (
       <MuiGrid
         ref={ref}
-        size={mapSpan(span)}
-        offset={mapOffset(offset)}
         className={finalClassName}
         {...(safeProps as unknown as MuiGridProps)}
-        style={{
-          order: resolvedOrder,
-          ...(grow ? { flexGrow: 1 } : {}),
-          ...(style as CSSProperties),
-        }}
+        style={{ order, ...(style as CSSProperties) }}
       >
         {children}
       </MuiGrid>

package/src/components/Grid/IMPLEMENTATION_NOTES.md

@@ -1,16 +1,16 @@
 # Grid Implementation Notes
 
-MUI has no native Grid/Grid.Col split — MUI's own `Grid` component merges "container" and "item" behavior into one component (toggled by the `container` boolean and a `size` prop). To keep the exact same public API as the mantine-adapter (`Grid` + `Grid.Col` dot notation, matching Mantine's own `Grid`/`Grid.Col`), this file hand-composes two wrappers around that single underlying component: `Grid` always renders `<MuiGrid container>`, `Grid.Col` always renders `<MuiGrid>` in item mode. A `GridContext` (internal, not exported) carries the parent's `grow` flag down to `Grid.Col`, since MUI has no equivalent React context of its own for this and siblings can't share props directly.
+MUI has no native Grid/Grid.Col split — MUI's own `Grid` component merges "container" and "item" behavior into one component (toggled by the `container` boolean and a `size` prop). To keep the same `Grid` + `Grid.Col` dot-notation shape as the mantine-adapter, this file hand-composes two thin wrappers around that single underlying component: `Grid` always renders `<MuiGrid container>`, `Grid.Col` always renders `<MuiGrid>` in item mode. This is a structural convenience only — the props on each wrapper are MUI's own, not a Recursica-defined contract.
 
-Prop mapping details and divergences from a literal 1:1 MUI wrap:
+Per the layout-components rule (no formal Recursica common props definition — layout components simply pass through the underlying kit's own props), this Grid does **not** attempt prop-name parity with the mantine-adapter's Grid. Its public API is MUI's own vocabulary:
 
-- **`gap` → `spacing`**: MUI's own container-spacing prop is `spacing` (not `gutter`, which is Mantine's term). Resolved through the same `rec-*` → `SPACING_MAP` lookup used elsewhere in this adapter.
-- **`span` keyword inversion**: Recursica's `"auto"` (fill remaining space) and `"content"` (size to content) are the _inverse_ of MUI's own `size` keywords — MUI's `"auto"` means size-to-content and `"grow"` means fill-remaining-space. `mapSpanValue()` translates between them so the public `span` prop matches Mantine's semantics exactly. Verified against `@mui/system`'s `generateGridSizeStyles` (`grow` → `flexGrow:1`, `auto` → `flexBasis:auto`).
-- **`offset`**: Maps directly to MUI's own `offset` prop — same name, same responsive shape and semantics. No translation needed.
-- **`"base"` breakpoint key**: Recursica's breakpoint objects (matching Mantine's `Grid.Col` shape) use `base` for the default/smallest value; MUI has no `"base"` key, only `xs` as its smallest breakpoint (`min-width: 0`). `remapBase()` renames `base` → `xs` (an explicit `xs` in the same object wins over `base` if both are present).
-- **`order`**: MUI's Grid has no `order` prop at all. A fixed number is applied via inline `style.order` (inline style always wins the cascade, so this works regardless of MUI's generated styles). A responsive object is **not** fully implemented — building full per-breakpoint CSS custom-property cascading for a rarely-used prop wasn't judged worth the added CSS surface for v1. `resolveOrder()` currently just takes the smallest specified breakpoint's value and applies it as a single static order. This is a known, documented gap, not a silent one — revisit if a real per-breakpoint ordering need comes up.
-- **`grow`**: MUI's Grid has no equivalent. Mantine's own implementation (and this one) relies on a CSS quirk: setting `flex-grow: 1` on every column in a row only visibly affects the _last, incomplete_ row — fully-filled rows have zero remaining space to grow into. Applied via inline `style.flexGrow` on `Grid.Col`, read from `GridContext`.
-- **`visibleFrom` / `hiddenFrom`**: No native MUI Grid mechanism. Implemented via `Grid.module.css` media-query classes, hardcoded to MUI's own default `theme.breakpoints` pixel values (`xs:0, sm:600, md:900, lg:1200, xl:1536`). If the consuming app customizes its MUI theme breakpoints, these thresholds won't follow — structural layout mechanics, not a design token, so this doesn't go through the token pipeline.
-- **`justifyContent` / `alignItems`**: MUI's `Grid` does not register these as recognized style-system props the way `Box` does (confirmed by reading `@mui/system`'s `gridGenerator.js` — no generator function reads them), so passing them as bare props would silently do nothing. They're applied via inline `style` instead.
+- **`spacing`** (not Mantine's `gutter`/the old Recursica `gap` alias) — MUI's own container-spacing prop. Still accepts `rec-*` tokens, resolved through the same `SPACING_MAP` lookup used elsewhere in this adapter.
+- **`size`** (not Mantine's `span`) — MUI's own item-sizing prop on `Grid.Col`: a column count, `"auto"` (size to content), `"grow"` (fill remaining space), or a responsive object keyed by MUI's own breakpoints. No inversion/translation against Mantine's `span` semantics.
+- **`offset`** — MUI's own prop, used as-is.
+- **Breakpoint objects** use MUI's own scale (`xs`/`sm`/`md`/`lg`/`xl`) directly. There is no `"base"` alias — `xs` is MUI's smallest breakpoint, same role Mantine's own smallest breakpoint plays.
+- **`grow` (container-level)**: not implemented. Mantine's container `grow` flag ("last row's columns expand to fill available space") has no MUI equivalent, but MUI's own `size="grow"` on individual `Grid.Col`s already covers the same real-world need — set it per-column instead of on the container.
+- **`order`**: MUI types `order` generically (via `SystemProps`) but its Grid style generator (`gridGenerator.js`/`createGrid.js`, read directly to confirm) never wires it up — passing it straight through silently no-ops. Applied here via inline `style.order` instead, single value only (no per-breakpoint object).
+- **`justifyContent` / `alignItems`** (container only): same issue as `order` — typed but not read by MUI's Grid generator (confirmed by reading `gridGenerator.js`: only `size`, `offset`, `columns`, spacing, `direction`, and `wrap` have generator functions). Applied via inline `style` instead, using MUI's own prop names (not Mantine's `justify`/`align`).
+- **`visibleFrom` / `hiddenFrom`**: no native MUI Grid mechanism at all, so — per the rule that a missing kit feature is built following Mantine's own shape — implemented via `Grid.module.css` media-query classes, hardcoded to MUI's own default `theme.breakpoints` pixel values (`xs:0, sm:600, md:900, lg:1200, xl:1536`). If the consuming app customizes its MUI theme breakpoints, these thresholds won't follow — structural layout mechanics, not a design token.
 
-**Cross-adapter parity caveat**: `visibleFrom`/`hiddenFrom` (and the eventual full responsive `order`) are pinned to MUI's default breakpoints here, while the mantine-adapter's equivalent behavior is driven by Mantine's own default breakpoints (576/768/992/1200/1408). The two adapters' Grid stories may show different columns at the exact same viewport width in the `adapter-tester` visual-regression suite as a result — a real, structural difference between the two underlying libraries' breakpoint scales, not a bug in either adapter.
+**Cross-adapter parity caveat**: `visibleFrom`/`hiddenFrom` are pinned to MUI's default breakpoints here, while the mantine-adapter's equivalent behavior is driven by Mantine's own default breakpoints (576/768/992/1200/1408). The two adapters' Grid stories may show different columns at the exact same viewport width in the `adapter-tester` visual-regression suite as a result — a real, structural difference between the two underlying libraries' breakpoint scales, not a bug in either adapter. The two adapters' Grid APIs are also no longer prop-name-identical (`spacing`/`size` here vs. `gutter`/`span` in mantine-adapter) — this is intentional per the layout-components rule; each adapter's Grid speaks its own kit's vocabulary.

package/src/components/Grid/USAGE.md

@@ -20,9 +20,9 @@ import { Grid } from "@recursica/mui-adapter";
 
 export default function Demo() {
   return (
-    <Grid gap="rec-default">
-      <Grid.Col span={6}>Half width</Grid.Col>
-      <Grid.Col span={{ base: 12, sm: 6, md: 3 }}>Responsive width</Grid.Col>
+    <Grid spacing="rec-default">
+      <Grid.Col size={6}>Half width</Grid.Col>
+      <Grid.Col size={{ xs: 12, sm: 6, md: 3 }}>Responsive width</Grid.Col>
     </Grid>
   );
 }
@@ -44,8 +44,10 @@ All Recursica components in the `@recursica/mui-adapter` package adhere strictly
 
 ## 4. Key Integration Features & Constraints
 
-- `gap` controls the spacing between grid items.
-- `span` accepts a column count, `"auto"`, `"content"`, or a responsive object (`{ base, sm, md, ... }`).
+This Grid uses MUI's own prop vocabulary directly (see [IMPLEMENTATION_NOTES.md](./IMPLEMENTATION_NOTES.md)) — it is not name-for-name identical to the mantine-adapter's Grid.
+
+- `spacing` controls the space between grid items (accepts `rec-*` tokens).
+- `size` accepts a column count, `"auto"`, `"grow"`, or a responsive object (`{ xs, sm, md, ... }`).
 - `offset` shifts a column by a number of columns.
-- `order` accepts a fixed number to control a column's visual order. A responsive object (`{ base, sm, md, ... }`) is **not** fully supported yet — only the smallest specified breakpoint's value is applied.
+- `order` accepts a fixed number to control a column's visual order (single value only, no responsive object).
 - `visibleFrom`/`hiddenFrom` show or hide a column at the standard breakpoints (600/900/1200/1536px).

package/src/components/Group/Group.test.tsx

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

package/src/components/Group/Group.tsx

@@ -1,3 +1,12 @@
+/**
+ * Group layout wrapper.
+ *
+ * NOTE: MUI has no native `<Group>` component. 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 `Group` (gap/rowGap/columnGap/justify/align/wrap) — this shape is owned locally here,
+ * not shared as a formal cross-adapter Recursica contract. It's implemented as a row-direction,
+ * wrapping MUI `Stack`.
+ */
 import { forwardRef } from "react";
 import {
   Stack as MUIStack,
@@ -10,10 +19,23 @@ import {
   type WithRecursicaSpacing,
 } from "../../utils/filterStylingProps";
 
-import { type RecursicaGroupProps } from "@recursica/adapter-common";
+interface GroupOwnProps {
+  /** Gap spacing */
+  gap?: string | number;
+  /** Row gap spacing */
+  rowGap?: string | number;
+  /** Column gap spacing */
+  columnGap?: string | number;
+  /** Align items justify properties */
+  justify?: React.CSSProperties["justifyContent"];
+  /** Align items vertical alignment */
+  align?: React.CSSProperties["alignItems"];
+  /** Flex-wrap settings */
+  wrap?: React.CSSProperties["flexWrap"];
+}
 
 export type GroupProps = WithRecursicaSpacing<
-  OmitSx<Omit<MUIStackProps, "spacing" | "direction"> & RecursicaGroupProps>
+  OmitSx<Omit<MUIStackProps, "spacing" | "direction"> & GroupOwnProps>
 >;
 
 export const Group = forwardRef<HTMLDivElement, GroupProps>(function Group(

package/src/components/HoverCard/HoverCard.test.tsx

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

package/src/components/Label/Label.test.tsx

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

package/src/components/Link/Link.test.tsx

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

package/src/components/Loader/Loader.test.tsx

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

package/src/components/Menu/Menu.test.tsx

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

package/src/components/Modal/Modal.test.tsx

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

package/src/components/NumberInput/NumberInput.test.tsx

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

package/src/components/Pagination/Pagination.test.tsx

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

package/src/components/Panel/Panel.test.tsx

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

package/src/components/Popover/Popover.test.tsx

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

package/src/components/Radio/Radio.test.tsx

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

package/src/components/ReadOnlyField/ReadOnlyField.test.tsx

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

package/src/components/SegmentedControl/SegmentedControl.test.tsx

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

package/src/components/Slider/Slider.test.tsx

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

package/src/components/Stack/Stack.stories.tsx

@@ -19,12 +19,12 @@ const meta: Meta<StackStoryProps> = {
     },
   },
   args: {
-    gap: "rec-default",
-    align: "stretch",
-    justify: "flex-start",
+    spacing: "rec-default",
+    alignItems: "stretch",
+    justifyContent: "flex-start",
   },
   argTypes: {
-    gap: {
+    spacing: {
       control: "select",
       options: [
         "rec-none",
@@ -40,14 +40,14 @@ const meta: Meta<StackStoryProps> = {
         "lg",
         "xl",
       ],
-      description: "Gap between elements",
+      description: "Space between elements",
     },
-    align: {
+    alignItems: {
       control: "select",
       options: ["flex-start", "center", "flex-end", "stretch"],
       description: "Align-items property",
     },
-    justify: {
+    justifyContent: {
       control: "select",
       options: [
         "flex-start",
@@ -81,7 +81,7 @@ export const Default: Story = {
 
 export const StaticGapSmall: Story = {
   args: {
-    gap: "rec-sm",
+    spacing: "rec-sm",
   },
   // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
   render: ({ withLayer, layer, ...args }: any) => (
@@ -95,7 +95,7 @@ export const StaticGapSmall: Story = {
 
 export const StaticGapLarge: Story = {
   args: {
-    gap: "rec-xl",
+    spacing: "rec-xl",
   },
   // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
   render: ({ withLayer, layer, ...args }: any) => (

package/src/components/Stack/Stack.test.tsx

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

package/src/components/Stack/Stack.tsx

@@ -1,3 +1,10 @@
+/**
+ * Stack layout wrapper.
+ *
+ * MUI has a native `Stack`, so this simply passes through its own props (`direction`,
+ * `spacing`, `alignItems`, `justifyContent`, etc.) with no Recursica renaming — only
+ * `spacing` gains `rec-*` token support via `WithRecursicaSpacing`.
+ */
 import { forwardRef } from "react";
 import {
   Stack as MUIStack,
@@ -10,29 +17,23 @@ import {
   type WithRecursicaSpacing,
 } from "../../utils/filterStylingProps";
 
-import { type RecursicaStackProps } from "@recursica/adapter-common";
-
-export type StackProps = WithRecursicaSpacing<
-  OmitSx<Omit<MUIStackProps, "spacing"> & RecursicaStackProps>
->;
+export type StackProps = WithRecursicaSpacing<OmitSx<MUIStackProps>>;
 
 export const Stack = forwardRef<HTMLDivElement, StackProps>(function Stack(
-  { children, gap = "rec-default", align, justify, ...rest },
+  { children, spacing = "rec-default", ...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 resolvedSpacing =
+    typeof spacing === "string" && spacing in SPACING_MAP
+      ? SPACING_MAP[spacing as keyof typeof SPACING_MAP]
+      : spacing;
 
   return (
     <MUIStack
       ref={ref}
-      {...safeProps}
-      spacing={resolvedGap}
-      alignItems={align}
-      justifyContent={justify}
+      {...(safeProps as unknown as MUIStackProps)}
+      spacing={resolvedSpacing}
     >
       {children}
     </MUIStack>

package/src/components/Stack/USAGE.md

@@ -20,7 +20,7 @@ import { Stack } from "@recursica/mui-adapter";
 
 export default function Demo() {
   return (
-    <Stack gap="md" align="stretch">
+    <Stack spacing="md" alignItems="stretch">
       <Text>Item 1</Text>
       <Text>Item 2</Text>
     </Stack>

package/src/components/Stepper/Stepper.test.tsx

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

package/src/components/Switch/Switch.stories.tsx

@@ -77,7 +77,7 @@ export const SideBySideLayout: Story = {
 export const StaticVariations: Story = {
   args: {},
   render: () => (
-    <Stack gap="xl">
+    <Stack spacing="xl">
       <Switch label="Default Unchecked State" />
       <Switch label="Checked State" defaultChecked />
       <Switch label="Disabled Unchecked" disabled />

package/src/components/Switch/Switch.test.tsx

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

package/src/components/Table/Table.test.tsx

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

package/src/components/Tabs/Tabs.test.tsx

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

package/src/components/Text/Text.stories.tsx

@@ -1,6 +1,5 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { Text } from "./Text";
-import { Layer } from "@recursica/adapter-common";
 
 const meta: Meta<typeof Text> = {
   title: "UI-Kit/Text",
@@ -46,25 +45,13 @@ export const Default: Story = {
     children:
       "This is standard body typography controlled by the central UI-kit boundaries exclusively.",
   },
-  render: ({ ...args }) => (
-    <Layer layer={0} style={{ padding: "48px" }}>
-      <Text {...args} />
-    </Layer>
-  ),
+  render: ({ ...args }) => <Text {...args} />,
 };
 
 export const StaticVariations: Story = {
   args: {},
   render: () => (
-    <Layer
-      layer={0}
-      style={{
-        padding: "48px",
-        display: "flex",
-        flexDirection: "column",
-        gap: "16px",
-      }}
-    >
+    <div style={{ display: "flex", flexDirection: "column", gap: "24px" }}>
       <Text variant="body">
         Body (Base paragraph and generic information flow)
       </Text>
@@ -83,6 +70,6 @@ export const StaticVariations: Story = {
       <Text variant="subtitle-small">
         Subtitle Small (Section anchors deep in hierarchy)
       </Text>
-    </Layer>
+    </div>
   ),
 };

package/src/components/Text/Text.test.tsx

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

package/src/components/TextArea/TextArea.test.tsx

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

package/src/components/TextField/TextField.test.tsx

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

package/src/components/TimePicker/TimePicker.test.tsx

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