@recursica/mui-adapter 0.17.0 → 0.18.0

package/dist/src/components/Grid/Grid.d.ts

@@ -0,0 +1,12 @@
+import { GridProps as MuiGridProps } from '@mui/material';
+import { OmitSx, WithRecursicaSpacing } from '../../utils/filterStylingProps';
+import { RecursicaGridProps, RecursicaGridColProps } from '@recursica/adapter-common';
+export type GridProps = WithRecursicaSpacing<OmitSx<Omit<MuiGridProps, "container" | "size" | "offset">> & RecursicaGridProps>;
+declare const GridBase: import('react').ForwardRefExoticComponent<Omit<GridProps, "ref"> & import('react').RefAttributes<HTMLDivElement>>;
+export type GridColProps = WithRecursicaSpacing<OmitSx<Omit<MuiGridProps, "container" | "size" | "offset">> & RecursicaGridColProps>;
+export declare const GridCol: import('react').ForwardRefExoticComponent<Omit<GridColProps, "ref"> & import('react').RefAttributes<HTMLDivElement>>;
+type GridComponent = typeof GridBase & {
+    Col: typeof GridCol;
+};
+export declare const Grid: GridComponent;
+export {};

package/dist/src/components/Grid/index.d.ts

@@ -0,0 +1 @@
+export * from './Grid';

package/dist/src/components/index.d.ts

@@ -17,6 +17,7 @@ export * from './FileUpload';
 export * from './Flex';
 export * from './FormControlLayout';
 export * from './FormControlWrapper';
+export * from './Grid';
 export * from './Group';
 export * from './HoverCard';
 export * from './Label';

package/dist/src/index.d.ts

@@ -4,6 +4,10 @@ export declare const Box: <C extends React.ElementType = "div">(props: rawCompon
     ref?: React.ForwardedRef<any>;
 }) => React.ReactElement | null;
 export declare const Flex: import('react').ForwardRefExoticComponent<Omit<rawComponents.FlexProps, "ref"> & import('react').RefAttributes<HTMLDivElement>>;
+export declare const Grid: import('react').ForwardRefExoticComponent<Omit<rawComponents.GridProps, "ref"> & import('react').RefAttributes<HTMLDivElement>> & {
+    Col: typeof rawComponents.GridCol;
+};
+export declare const GridCol: import('react').ForwardRefExoticComponent<Omit<rawComponents.GridColProps, "ref"> & import('react').RefAttributes<HTMLDivElement>>;
 export declare const Group: import('react').ForwardRefExoticComponent<Omit<rawComponents.GroupProps, "ref"> & import('react').RefAttributes<HTMLDivElement>>;
 export declare const Stack: import('react').ForwardRefExoticComponent<Omit<rawComponents.StackProps, "ref"> & import('react').RefAttributes<HTMLDivElement>>;
 export declare const Container: import('react').ForwardRefExoticComponent<Omit<rawComponents.ContainerProps, "ref"> & import('react').RefAttributes<HTMLDivElement>>;

package/llms.txt

@@ -40,6 +40,7 @@ Each component has its own `USAGE.md` documenting its props, adapter-specific be
 - [Flex](src/components/Flex/USAGE.md)
 - [FormControlLayout](src/components/FormControlLayout/USAGE.md)
 - [FormControlWrapper](src/components/FormControlWrapper/USAGE.md)
+- [Grid](src/components/Grid/USAGE.md)
 - [Group](src/components/Group/USAGE.md)
 - [HoverCard](src/components/HoverCard/USAGE.md)
 - [Label](src/components/Label/USAGE.md)

package/package.json

@@ -13,7 +13,7 @@
     "url": "git+https://github.com/borderux/recursica.git",
     "directory": "packages/mui-adapter"
   },
-  "version": "0.17.0",
+  "version": "0.18.0",
   "publishConfig": {
     "access": "public"
   },

package/src/components/Grid/Grid.module.css

@@ -0,0 +1,72 @@
+/*
+ * HARDCODED VALUES:
+ * - Breakpoint pixel thresholds below (600/900/1200/1536) match MUI's own default
+ *   theme.breakpoints (xs/sm/md/lg/xl). They drive `visibleFrom`/`hiddenFrom`, which
+ *   have no native MUI Grid equivalent to hook into. If the consuming app customizes
+ *   its MUI theme breakpoints, these thresholds will not follow that change —
+ *   structural layout mechanics, not a design token.
+ */
+
+.root {
+}
+
+.col {
+}
+
+.hiddenFromXs {
+  display: none;
+}
+
+@media (min-width: 600px) {
+  .hiddenFromSm {
+    display: none;
+  }
+}
+
+@media (min-width: 900px) {
+  .hiddenFromMd {
+    display: none;
+  }
+}
+
+@media (min-width: 1200px) {
+  .hiddenFromLg {
+    display: none;
+  }
+}
+
+@media (min-width: 1536px) {
+  .hiddenFromXl {
+    display: none;
+  }
+}
+
+@media (max-width: 599.98px) {
+  .visibleFromSm,
+  .visibleFromMd,
+  .visibleFromLg,
+  .visibleFromXl {
+    display: none;
+  }
+}
+
+@media (max-width: 899.98px) {
+  .visibleFromMd,
+  .visibleFromLg,
+  .visibleFromXl {
+    display: none;
+  }
+}
+
+@media (max-width: 1199.98px) {
+  .visibleFromLg,
+  .visibleFromXl {
+    display: none;
+  }
+}
+
+@media (max-width: 1535.98px) {
+  .visibleFromXl {
+    display: none;
+  }
+}

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

@@ -0,0 +1,185 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Grid } from "./Grid";
+import { Card } from "../Card/Card";
+import { Text } from "../Text/Text";
+
+type GridStoryProps = React.ComponentProps<typeof Grid>;
+
+const meta: Meta<GridStoryProps> = {
+  title: "UI-Kit/Grid",
+  component: Grid,
+  tags: ["autodocs"],
+  parameters: {
+    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.",
+      },
+    },
+    controls: {
+      include: ["children", "gap", "columns", "grow", "justify", "align"],
+    },
+  },
+  args: {
+    gap: "rec-default",
+    columns: 12,
+    grow: false,
+  },
+  argTypes: {
+    gap: {
+      control: "select",
+      options: [
+        "rec-none",
+        "rec-sm",
+        "rec-default",
+        "rec-md",
+        "rec-lg",
+        "rec-xl",
+        "rec-2xl",
+      ],
+      description: "Gap 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",
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<GridStoryProps>;
+
+const Swatch = ({ children }: { children: React.ReactNode }) => (
+  <Card>
+    <Card.Content>
+      <Text>{children}</Text>
+    </Card.Content>
+  </Card>
+);
+
+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>
+      <Grid.Col span={4}>
+        <Swatch>span 4</Swatch>
+      </Grid.Col>
+      <Grid.Col span={4}>
+        <Swatch>span 4</Swatch>
+      </Grid.Col>
+    </Grid>
+  ),
+};
+
+export const ResponsiveSpans: 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>
+      <Grid.Col span={{ base: 12, sm: 6, md: 3 }}>
+        <Swatch>base 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>
+      <Grid.Col span={{ base: 12, sm: 6, md: 3 }}>
+        <Swatch>base 12 / sm 6 / md 3</Swatch>
+      </Grid.Col>
+    </Grid>
+  ),
+};
+
+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>
+      <Grid.Col span={4}>
+        <Swatch>span 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>
+      <Grid.Col span={3}>
+        <Swatch>span 3</Swatch>
+      </Grid.Col>
+      <Grid.Col span={3}>
+        <Swatch>span 3 (grows to fill row)</Swatch>
+      </Grid.Col>
+    </Grid>
+  ),
+};
+
+export const CustomColumnCount: Story = {
+  args: {
+    columns: 6,
+  },
+  // 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>
+      <Grid.Col span={2}>
+        <Swatch>span 2 of 6</Swatch>
+      </Grid.Col>
+      <Grid.Col span={2}>
+        <Swatch>span 2 of 6</Swatch>
+      </Grid.Col>
+    </Grid>
+  ),
+};
+
+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">
+        <Swatch>hidden from sm and up</Swatch>
+      </Grid.Col>
+      <Grid.Col span={6} visibleFrom="sm">
+        <Swatch>visible from sm and up</Swatch>
+      </Grid.Col>
+    </Grid>
+  ),
+};

package/src/components/Grid/Grid.tsx

@@ -0,0 +1,240 @@
+/**
+ * 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.
+ *
+ * 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 { Grid as MuiGrid, type GridProps as MuiGridProps } from "@mui/material";
+import {
+  SPACING_MAP,
+  type OmitSx,
+  filterSxProp,
+  type WithRecursicaSpacing,
+} 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>> = {
+  xs: styles.hiddenFromXs,
+  sm: styles.hiddenFromSm,
+  md: styles.hiddenFromMd,
+  lg: styles.hiddenFromLg,
+  xl: styles.hiddenFromXl,
+};
+
+// "xs"/"base" intentionally absent: visible from the smallest breakpoint means never hidden.
+const VISIBLE_FROM_CLASS: Partial<Record<Breakpoint, string>> = {
+  sm: styles.visibleFromSm,
+  md: styles.visibleFromMd,
+  lg: styles.visibleFromLg,
+  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
+>;
+
+const GridBase = forwardRef<HTMLDivElement, GridProps>(function Grid(
+  {
+    children,
+    gap = "rec-default",
+    columns = 12,
+    grow = false,
+    justify,
+    align,
+    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;
+
+  return (
+    <GridContext.Provider value={{ grow }}>
+      <MuiGrid
+        ref={ref}
+        container
+        columns={columns}
+        spacing={resolvedGap}
+        className={styles.root}
+        {...(safeProps as unknown as MuiGridProps)}
+        style={{
+          justifyContent: justify,
+          alignItems: align,
+          ...(style as CSSProperties),
+        }}
+      >
+        {children}
+      </MuiGrid>
+    </GridContext.Provider>
+  );
+});
+GridBase.displayName = "Grid";
+
+// ============================================================
+// GRID.COL
+// ============================================================
+
+export type GridColProps = WithRecursicaSpacing<
+  OmitSx<Omit<MuiGridProps, "container" | "size" | "offset">> &
+    RecursicaGridColProps
+>;
+
+export const GridCol = forwardRef<HTMLDivElement, GridColProps>(
+  function GridCol(
+    {
+      children,
+      span,
+      offset,
+      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)]
+      : hiddenFrom
+        ? HIDDEN_FROM_CLASS[normalizeBreakpoint(hiddenFrom)]
+        : undefined;
+
+    const finalClassName = [styles.col, visibilityClass, className]
+      .filter(Boolean)
+      .join(" ");
+
+    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),
+        }}
+      >
+        {children}
+      </MuiGrid>
+    );
+  },
+);
+GridCol.displayName = "GridCol";
+
+// ============================================================
+// DOT NOTATION EXPORT
+// ============================================================
+
+type GridComponent = typeof GridBase & {
+  Col: typeof GridCol;
+};
+
+export const Grid = GridBase as GridComponent;
+Grid.Col = GridCol;

package/src/components/Grid/IMPLEMENTATION_NOTES.md

@@ -0,0 +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.
+
+Prop mapping details and divergences from a literal 1:1 MUI wrap:
+
+- **`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.
+
+**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.

package/src/components/Grid/USAGE.md

@@ -0,0 +1,55 @@
+# Grid - Usage Guide
+
+This document describes how to integrate and use the `Grid` component in your projects using `@recursica/mui-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Grid } from "@recursica/mui-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+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>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/mui-adapter` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: `Grid` is a primitive layout component (see [OVERSTYLING.md](../../../OVERSTYLING.md)) and is exempt from the `RecursicaOverStyled` gatekeeper — only the `sx` prop is stripped, everything else passes through freely.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Spacing is entirely determined by the `rec-*` token scale, mapped transparently to MUI's `spacing` value.
+
+---
+
+## 4. Key Integration Features & Constraints
+
+`Grid` and `Grid.Col` expose the same public API as the mantine-adapter's `Grid`/`Grid.Col` (same prop names and shapes), so code written against one adapter ports to the other without changes. Internally, MUI has no native `AppShell`-style Grid/Col split — MUI merges "container" and "item" into a single `Grid` component — so this adapter hand-composes `Grid` (always `container`) and `Grid.Col` (always item mode) from that single underlying component.
+
+Notable mapping details:
+
+- `gap` maps to MUI's own `spacing` prop (same concept as `gutter` on the mantine side).
+- `span`'s `"auto"`/`"content"` keywords are the inverse of MUI's own `"grow"`/`"auto"` keywords — this adapter translates between them internally, so the public `span` values match Mantine's semantics exactly regardless of adapter.
+- `offset` maps directly to MUI's own `offset` prop (same name, same shape).
+- `order` is applied directly for a fixed number. A responsive object (`{ base, sm, md, ... }`) is **not** fully supported yet — the smallest specified breakpoint's value is applied as a single static order, since MUI's Grid has no native per-breakpoint `order` mechanism. See `IMPLEMENTATION_NOTES.md`.
+- `visibleFrom`/`hiddenFrom` are implemented via a small CSS module using MUI's own default breakpoint pixel values (600/900/1200/1536), since MUI's Grid has no built-in breakpoint-visibility mechanism.

package/src/components/Grid/index.ts

@@ -0,0 +1 @@
+export * from "./Grid";

package/src/components/index.ts

@@ -17,6 +17,7 @@ export * from "./FileUpload";
 export * from "./Flex";
 export * from "./FormControlLayout";
 export * from "./FormControlWrapper";
+export * from "./Grid";
 export * from "./Group";
 export * from "./HoverCard";
 export * from "./Label";

package/src/index.ts

@@ -7,6 +7,8 @@ export * from "@recursica/adapter-common";
 // Expose unwrapped structural layout primitives to preserve their polymorphic types
 export const Box = rawComponents.Box;
 export const Flex = rawComponents.Flex;
+export const Grid = rawComponents.Grid;
+export const GridCol = rawComponents.GridCol;
 export const Group = rawComponents.Group;
 export const Stack = rawComponents.Stack;
 export const Container = rawComponents.Container;