@recursica/mantine-adapter 0.33.0 → 0.35.0

package/src/OverStyling.tsx

@@ -1,3 +1,5 @@
+import ReactMarkdown from "react-markdown";
+import { TypographyStylesProvider } from "@mantine/core";
 import {
   Container,
   Card,
@@ -13,6 +15,7 @@ import {
   toggleGlobalOverStyled,
   wrapComponent,
 } from "@recursica/adapter-common";
+import overStylingDoc from "../OVERSTYLING.md?raw";
 
 const Button = wrapComponent(RawButton);
 const Text = wrapComponent(RawText);
@@ -24,246 +27,27 @@ export const OverStylingInfo = () => {
     <Container size="md" style={{ padding: "32px 0" }}>
       <Card>
         <Card.Content>
-          <Title order={1} mb="rec-md">
-            Over Styling (<code>overStyled</code>)
-          </Title>
-          <Text mb="rec-md">
-            By default, all Recursica components are strictly sandboxed. This
-            means they are protected against arbitrary styling configurations
-            (like passing generic React <code>style</code> objects, custom{" "}
-            <code>classNames</code> injections, or using deep Mantine layout
-            hooks like <code>bg</code> and <code>c</code>). This strict
-            compile-time and run-time enforcement guarantees that your design
-            system tokens remain true across your application.
-          </Text>
-          <Text mb="rec-md">
-            However, there may be edge cases where a developer absolutely must
-            modify a component beyond what the design tokens natively allow. For
-            this, we provide the <strong>escape hatch</strong> property:{" "}
-            <code>overStyled={`{true}`}</code>.
-          </Text>
-
-          <Title order={3} mb="rec-sm">
-            The Core Philosophy
-          </Title>
-          <Text mb="rec-sm">
-            **You should not over-style components.** Using{" "}
-            <code>overStyled</code> explicitly signifies that you are breaking
-            design system rules.
-          </Text>
-          <Stack
-            component="ol"
-            style={{ paddingLeft: "24px" }}
-            mb="rec-xl"
-            gap="rec-sm"
-          >
-            <li>
-              <Text>
-                <strong>Technical Debt:</strong> If over-styling is required, it
-                should be treated as a short-term workaround. Ideally, the
-                component will be refactored once the required layouts or
-                variants are officially integrated into the core Recursica
-                component library.
-              </Text>
-            </li>
-            <li>
-              <Text>
-                <strong>Auditing & Searching:</strong> Because this pattern
-                creates technical debt, we enforce the explicit{" "}
-                <code>overStyled</code> boolean. This provides a highly
-                auditable, easily searchable string. Product managers and
-                engineers can quickly grep the codebase for{" "}
-                <code>overStyled</code> (or the <code>RecursicaOverStyled</code>{" "}
-                typings) to hunt down components that don't match standard
-                patterns.
-              </Text>
-            </li>
-            <li>
-              <Text>
-                <strong>Highly Custom Components:</strong> If your application
-                genuinely requires massive custom layouts that the UI kit cannot
-                support, <strong>do not hack the Recursica component</strong>.
-                Instead, it is highly encouraged that you import the underlying
-                primitive component directly from <code>@mantine/core</code> and
-                construct your independent feature there. While you can utilize
-                raw Recursica CSS variables on these custom components, note
-                that they are not guaranteed to be accurately maintained as
-                Recursica evolves. Keep strict components strict!
-              </Text>
-            </li>
-          </Stack>
+          <TypographyStylesProvider>
+            <ReactMarkdown>{overStylingDoc}</ReactMarkdown>
+          </TypographyStylesProvider>
 
           <Stack
             style={{ height: 1, backgroundColor: "#eaeaea" }}
-            mb="rec-xl"
+            my="rec-xl"
           />
 
-          <Title order={3} mb="rec-sm">
-            Permitted Layout Properties
-          </Title>
-          <Text mb="rec-sm">
-            Unlike deep styling bounds (colors, typography, padding,
-            dimensions), external <strong>layout spacing properties</strong>{" "}
-            like Margins (<code>m</code>, <code>mt</code>, <code>mb</code>,{" "}
-            <code>mx</code>) are safely <strong>permitted by default</strong>.
-            This allows integrators to structurally compose components alongside
-            siblings without breaching internal token boundaries.
-          </Text>
-          <Text mb="rec-xl">
-            When using layout properties, you have the flexibility to use either
-            ecosystem seamlessly:
-          </Text>
-          <Stack
-            component="ol"
-            style={{ paddingLeft: "24px" }}
-            mb="rec-md"
-            gap="rec-sm"
-          >
-            <li>
-              <Text>
-                <strong>Mantine Core Values:</strong> Passing standard Mantine
-                sizes (like <code>mt="md"</code>) passes straight through to
-                Mantine natively, allowing you to interface completely normally
-                with a parent application's existing Mantine Theme setup that
-                might fall outside Recursica's scope.
-              </Text>
-            </li>
-            <li>
-              <Text>
-                <strong>Recursica Strict Tokens:</strong> Passing our custom
-                prefixed tokens (like <code>mt="rec-md"</code>) signals our
-                internal layout interceptor to securely translate the value
-                directly to our native <code>recursica_brand_dimensions</code>{" "}
-                CSS variables. This ensures strict design token measurements
-                while sharing the exact same prop interface!
-              </Text>
-            </li>
-          </Stack>
-          <Text mb="rec-sm" overStyled fw={500}>
-            Available Recursica Layout Tokens:
-          </Text>
-          <Stack
-            component="ul"
-            style={{ paddingLeft: "24px" }}
-            mb="rec-xl"
-            gap="rec-none"
-          >
-            <li>
-              <Text>
-                <code>rec-none</code> (0px limit)
-              </Text>
-            </li>
-            <li>
-              <Text>
-                <code>rec-sm</code> (0.5x scaling)
-              </Text>
-            </li>
-            <li>
-              <Text>
-                <code>rec-default</code> (1.0x scaling)
-              </Text>
-            </li>
-            <li>
-              <Text>
-                <code>rec-md</code> (1.5x scaling)
-              </Text>
-            </li>
-            <li>
-              <Text>
-                <code>rec-lg</code> (2.0x scaling)
-              </Text>
-            </li>
-            <li>
-              <Text>
-                <code>rec-xl</code> (3.0x scaling)
-              </Text>
-            </li>
-            <li>
-              <Text>
-                <code>rec-2xl</code> (4.0x scaling)
-              </Text>
-            </li>
-          </Stack>
-
-          <Stack
-            style={{ height: 1, backgroundColor: "#eaeaea" }}
-            mb="rec-xl"
-          />
-
-          <Title order={3} mb="rec-sm">
-            Primitive Layout Components Exemption
+          <Title order={3} mb="rec-md">
+            Try It Yourself
           </Title>
-          <Text mb="rec-sm">
-            Unlike complex UI components (Buttons, Tabs, Inputs) which are
-            strictly protected, <strong>Primitive Layout Components</strong> (
-            <code>Flex</code>, <code>Stack</code>, <code>Group</code>,{" "}
-            <code>Container</code>) are entirely exempt from the{" "}
-            <code>RecursicaOverStyled</code> gatekeeper.
-          </Text>
-          <Text mb="rec-xl">
-            Because the entire functional purpose of these components is
-            structural layout composition, developers are free to pass any
-            standard Mantine width, height, padding, margin, gap, and alignment
-            property directly to them without needing to flag{" "}
-            <code>overStyled={`{true}`}</code>. The internal custom token mapper
-            (such as converting <code>gap="rec-md"</code>) is still active
-            natively on these wrappers.
-          </Text>
-
-          <Stack
-            style={{ height: 1, backgroundColor: "#eaeaea" }}
-            mb="rec-xl"
-          />
 
-          <Title order={3} mb="rec-sm">
-            Visual Auditing & Highlights (Development Only)
-          </Title>
-          <Text mb="rec-sm">
-            To make it easy to spot technical debt and design system violations,
-            Recursica automatically tracks any component that uses the{" "}
-            <code>overStyled={`{true}`}</code> prop.
-          </Text>
-          <Text mb="rec-sm">
-            In <strong>development builds</strong>, you can highlight all
-            over-styled components on the page. Open your browser's developer
-            console and run:
-          </Text>
-          <Stack
-            style={{
-              padding: 12,
-              backgroundColor: "#f5f5f5",
-              borderRadius: 6,
-              fontSize: 13,
-              marginTop: 8,
-              marginBottom: 16,
-            }}
-          >
-            <code>recursica.toggleOverStyled()</code>
-          </Stack>
-          <Group mb="rec-md">
+          <Group mb="rec-xl">
             <Switch
               label="Highlight Over-Styled Components"
               checked={isHighlightActive}
               onChange={() => toggleGlobalOverStyled()}
             />
           </Group>
-          <Text mb="rec-xl">
-            This toggles a <strong>cyan 2px box shadow</strong> outline around
-            the children of all over-styled components. The wrapping elements
-            use <code>display: contents</code> under the hood to ensure they
-            occupy zero DOM space and do not affect flex, grid, or absolute
-            positioning flow. In production builds, this debugging helper is
-            completely disabled and stripped with zero performance overhead.
-          </Text>
 
-          <Stack
-            style={{ height: 1, backgroundColor: "#eaeaea" }}
-            mb="rec-xl"
-          />
-
-          <Title order={3} mb="rec-md">
-            Live Example
-          </Title>
           <Text mb="rec-xl">
             Below is a side-by-side comparison. The first is a standard
             Recursica Button protected by the design tokens mapping. The second

package/src/components/Grid/GRID_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,9 @@
+# Grid Implementation Notes
+
+The `Grid` component is a generic 12-column (by default) layout wrapper mapped directly to Mantine's `Grid`/`Grid.Col`. It requires no custom logical layouts or CSS workarounds — Mantine handles column geometry, breakpoints, and wrapping natively.
+
+The one deliberate divergence from Mantine's native API: the public `gap` prop replaces Mantine's `gutter`, for naming consistency with the other primitive layout components (`Flex`, `Stack`, `Group`). `gap` is translated to Mantine's `gutter` prop internally via `mapLayoutProps`, the same utility used to resolve `rec-*` spacing tokens elsewhere.
+
+`Grid.Col`'s `span`, `offset`, `order`, `visibleFrom`, and `hiddenFrom` props are passed straight through to Mantine's `Grid.Col` unchanged — Mantine already uses generic, portable naming for these.
+
+Like the other primitive layout components, `Grid` and `Grid.Col` use `WithRecursicaSpacing<T>` rather than `RecursicaOverStyled<T>` and are listed in the "Primitive Layout Components Exemption" section of `OVERSTYLING.md`.

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

@@ -0,0 +1,11 @@
+/* HARDCODED VALUES:
+ * None. This is a generic grid layout wrapper.
+ */
+
+.root {
+  /* Mantine handles the grid geometry (columns, gutter, spans) natively. No intrinsic design-system styles required for pure layout wrappers. */
+}
+
+.col {
+  /* Mantine handles column sizing (span, offset, order, visibleFrom/hiddenFrom) natively. */
+}

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

@@ -0,0 +1,182 @@
+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 that maps directly to Mantine's Grid/Grid.Col, providing column spans, offsets, ordering, and breakpoint-based visibility.",
+      },
+    },
+  },
+  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,145 @@
+import { forwardRef } from "react";
+import {
+  Grid as MantineGrid,
+  type GridProps as MantineGridProps,
+  type GridColProps as MantineGridColProps,
+  createPolymorphicComponent,
+} from "@mantine/core";
+import {
+  mapLayoutProps,
+  type WithRecursicaSpacing,
+} from "../../utils/filterStylingProps";
+import styles from "./Grid.module.css";
+
+import {
+  type RecursicaGridProps,
+  type RecursicaGridColProps,
+} from "@recursica/adapter-common";
+
+/**
+ * Grid layout wrapper.
+ *
+ * Note: Unlike complex UI components, primitive layout components (Flex, Stack, Group, Container, Grid)
+ * DO NOT use the `RecursicaOverStyled` gatekeeper. Developers must be able to freely pass
+ * width, height, padding, margins, and flexbox alignment props to construct structural layouts.
+ */
+export type GridProps = WithRecursicaSpacing<
+  Omit<MantineGridProps, "gutter"> & RecursicaGridProps
+>;
+
+const _Grid = forwardRef<HTMLDivElement, GridProps>(function Grid(
+  { children, gap = "rec-default", ...rest },
+  ref,
+) {
+  const mergedClassNames: Partial<Record<string, string>> = {
+    root: styles.root,
+  };
+
+  const classNamesProp = rest.classNames;
+  if (
+    classNamesProp &&
+    typeof classNamesProp === "object" &&
+    !Array.isArray(classNamesProp)
+  ) {
+    const o = classNamesProp as Partial<Record<string, string>>;
+    mergedClassNames.root = o.root ? `${styles.root} ${o.root}` : styles.root;
+  }
+
+  const classNameProp = rest.className as string | undefined;
+  const finalClass = classNameProp
+    ? `${styles.root} ${classNameProp}`
+    : styles.root;
+
+  const { gap: gutter, ...mappedRest } = mapLayoutProps({
+    gap,
+    ...rest,
+  } as Record<string, unknown>);
+
+  return (
+    <MantineGrid
+      ref={ref}
+      gutter={gutter as MantineGridProps["gutter"]}
+      className={finalClass}
+      classNames={mergedClassNames}
+      {...(mappedRest as unknown as Omit<MantineGridProps, "gutter">)}
+    >
+      {children}
+    </MantineGrid>
+  );
+});
+_Grid.displayName = "Grid";
+
+/**
+ * Recursica Grid layout wrapper.
+ *
+ * Supports polymorphism via the `component` prop for custom element rendering.
+ * @example
+ * ```tsx
+ * <Grid gap="rec-default">
+ *   <Grid.Col span={6}>Half width</Grid.Col>
+ *   <Grid.Col span={6}>Half width</Grid.Col>
+ * </Grid>
+ * ```
+ */
+const GridBase = createPolymorphicComponent<"div", GridProps>(_Grid);
+
+// ============================================================
+// GRID.COL
+// ============================================================
+
+export type GridColProps = WithRecursicaSpacing<
+  MantineGridColProps & RecursicaGridColProps
+>;
+
+const _GridCol = forwardRef<HTMLDivElement, GridColProps>(function GridCol(
+  { children, ...rest },
+  ref,
+) {
+  const mergedClassNames: Partial<Record<string, string>> = {
+    col: styles.col,
+  };
+
+  const classNamesProp = rest.classNames;
+  if (
+    classNamesProp &&
+    typeof classNamesProp === "object" &&
+    !Array.isArray(classNamesProp)
+  ) {
+    const o = classNamesProp as Partial<Record<string, string>>;
+    mergedClassNames.col = o.col ? `${styles.col} ${o.col}` : styles.col;
+  }
+
+  const classNameProp = rest.className as string | undefined;
+  const finalClass = classNameProp
+    ? `${styles.col} ${classNameProp}`
+    : styles.col;
+
+  return (
+    <MantineGrid.Col
+      ref={ref}
+      className={finalClass}
+      classNames={mergedClassNames}
+      {...(mapLayoutProps(
+        rest as Record<string, unknown>,
+      ) as unknown as MantineGridColProps)}
+    >
+      {children}
+    </MantineGrid.Col>
+  );
+});
+_GridCol.displayName = "GridCol";
+
+export const GridCol = createPolymorphicComponent<"div", GridColProps>(
+  _GridCol,
+);
+
+// ============================================================
+// DOT NOTATION EXPORT
+// ============================================================
+
+type GridComponent = typeof GridBase & {
+  Col: typeof GridCol;
+};
+
+export const Grid = GridBase as GridComponent;
+Grid.Col = GridCol;

package/src/components/Grid/USAGE.md

@@ -0,0 +1,47 @@
+# Grid - Usage Guide
+
+This document describes how to integrate and use the `Grid` component in your projects using `@recursica/mantine-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Grid } from "@recursica/mantine-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Grid } from "@recursica/mantine-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/mantine-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, so standard Mantine layout props pass 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 standard Mantine gutter values.
+
+---
+
+## 4. Key Integration Features & Constraints
+
+The `Grid` component maps directly to Mantine's `Grid`/`Grid.Col`. The one deviation from Mantine's native API: the prop for spacing between columns is named `gap` (not Mantine's `gutter`), for consistency with `Flex`, `Stack`, and `Group`. Everything else — `columns`, `grow`, `justify`, `align` on `Grid`, and `span`, `offset`, `order`, `visibleFrom`, `hiddenFrom` on `Grid.Col` — matches Mantine's own naming and accepts the same shapes, including per-breakpoint objects (`{ base, xs, sm, md, lg, xl }`).