@recursica/adapter-mantine-v8 1.2.2 → 1.3.1

package/src/components/Grid/Grid.tsx

@@ -1,179 +0,0 @@
-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 {
-  type RecursicaGridColProps,
-  type RecursicaGridProps,
-} from "@recursica/adapter-common";
-import styles from "./Grid.module.css";
-
-/**
- * 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.
- *
- * Recursica's `layout-grids` tokens (column-gutter, row-gutter, margin) are design-system-managed
- * values, not integrator-facing settings — Grid applies them itself via CSS variables. Mantine's
- * own `gutter` prop is not accepted; only `columns` (from `RecursicaGridProps` in
- * `adapter-common`) is exposed as an override, matching how `Container.size` overrides its own
- * token-backed default. See `GRID_IMPLEMENTATION_NOTES.md`.
- */
-export type GridProps = WithRecursicaSpacing<
-  Omit<MantineGridProps, "gutter" | "columns"> & RecursicaGridProps
->;
-
-const _Grid = forwardRef<HTMLDivElement, GridProps>(function Grid(
-  { children, columns, ...rest },
-  ref,
-) {
-  const mergedClassNames: Partial<Record<string, string>> = {
-    root: styles.root,
-    inner: styles.inner,
-    col: styles.col,
-  };
-
-  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;
-    mergedClassNames.inner = o.inner
-      ? `${styles.inner} ${o.inner}`
-      : styles.inner;
-    mergedClassNames.col = o.col ? `${styles.col} ${o.col}` : styles.col;
-  }
-
-  const classNameProp = rest.className as string | undefined;
-  const finalClass = classNameProp
-    ? `${styles.root} ${classNameProp}`
-    : styles.root;
-
-  // `gutter` is no longer a supported prop — column-gutter is design-system-managed (see below),
-  // dropped defensively here so a caller still passing the old prop name at runtime can't shadow
-  // the token-driven value passed to Mantine below via the `{...mappedRest}` spread.
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  const { gutter: _legacyGutter, ...restWithoutGutter } = rest as Record<
-    string,
-    unknown
-  >;
-
-  const mappedRest = mapLayoutProps(
-    restWithoutGutter as Record<string, unknown>,
-  );
-
-  // `columns` has no CSS-variable equivalent in Mantine — it computes each column's flex-basis
-  // from a plain number, so the design system default is baked in here as a JS default rather
-  // than wired live through CSS. Sourced from --recursica_brand_layout-grids_default_columns.
-  const resolvedColumns = columns ?? 6;
-
-  return (
-    <MantineGrid
-      ref={ref}
-      columns={resolvedColumns}
-      gutter="var(--recursica_brand_layout-grids_default_column-gutter)"
-      className={finalClass}
-      classNames={mergedClassNames}
-      {...(mappedRest as unknown as Omit<
-        MantineGridProps,
-        "gutter" | "columns"
-      >)}
-    >
-      {children}
-    </MantineGrid>
-  );
-});
-_Grid.displayName = "Grid";
-
-/**
- * Recursica Grid layout wrapper.
- *
- * Supports polymorphism via the `component` prop for custom element rendering.
- * @example
- * ```tsx
- * <Grid>
- *   <Grid.Col span={3}>Quarter width (defaults to 6 columns)</Grid.Col>
- *   <Grid.Col span={3}>Quarter width</Grid.Col>
- * </Grid>
- * ```
- */
-const GridBase = createPolymorphicComponent<"div", GridProps>(_Grid);
-
-// ============================================================
-// GRID.COL
-// ============================================================
-
-// TODO(grid-col-contract): `RecursicaGridColProps` currently only contributes `children` here —
-// `span`, `order`, `visibleFrom`, and `hiddenFrom` are all drafted in that type (adapter-common)
-// but commented out for now (2026-09-22, Matt — paused to get Grid merged). Until they're
-// restored there, this stays a plain pass-through of Mantine's own `GridColProps`; no Omit needed
-// since nothing here is contract-backed yet. Re-add the intersection/Omit once
-// `RecursicaGridColProps` picks these back up. See `GRID_IMPLEMENTATION_NOTES.md`.
-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

@@ -1,61 +0,0 @@
-# Grid - Usage Guide
-
-This document describes how to integrate and use the `Grid` component in your projects using `@recursica/adapter-mantine-v8`.
-
----
-
-## 1. Import Reference
-
-```tsx
-import { Grid } from "@recursica/adapter-mantine-v8";
-```
-
----
-
-## 2. Basic Example
-
-```tsx
-import React from "react";
-import { Grid } from "@recursica/adapter-mantine-v8";
-
-export default function Demo() {
-  return (
-    // No props needed for the design system default: 6 columns, with the design system's own
-    // column-gutter/row-gutter/margin values.
-    <Grid>
-      <Grid.Col span={3}>Half width (of 6)</Grid.Col>
-      <Grid.Col span={{ xs: 6, sm: 3, md: 2 }}>Responsive width</Grid.Col>
-    </Grid>
-  );
-}
-```
-
----
-
-## 3. Design System Integration
-
-All Recursica components in the `@recursica/adapter-mantine-v8` 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)), so standard Mantine layout props pass through freely without needing `overStyled`.
-> - **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**: Grid follows the design system's own `layout-grids` tokens — 6 columns, with column-gutter/row-gutter/margin applied automatically. Only `columns` is an integrator-facing override; the gutter/margin values are design-system-managed and not configurable via props.
-
----
-
-## 4. Key Integration Features & Constraints
-
-`Grid.Col`'s `span`, `offset`, `order`, `visibleFrom`, `hiddenFrom` match Mantine's own naming and
-accept the same shapes, including per-breakpoint objects (`{ xs, sm, md, lg, xl }`) — all still a
-straight Mantine pass-through for now. A formal `RecursicaGridColProps` contract in
-`adapter-common` is scaffolded but not filled in yet (TODO, tracked in
-`GRID_IMPLEMENTATION_NOTES.md`).
-
-`Grid` no longer accepts Mantine's own `gutter` prop — column-gutter, row-gutter, and margin are
-design-system-managed (Forge-controlled, applied via CSS variables) rather than integrator
-settings:
-
-- `columns?: number` — the only design-token-backed override on Grid; defaults to 6.
-
-`grow`, `justify`, `align` are unchanged, matching Mantine's own naming.