@recursica/mantine-adapter 0.34.0 → 0.35.1

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 }`).

package/src/components/Layer/USAGE.md

@@ -0,0 +1,54 @@
+# Layer - Usage Guide
+
+This document describes how to integrate and use the `Layer` component in your projects using `@recursica/mantine-adapter`.
+
+> [!NOTE] > `Layer` is defined once in `@recursica/adapter-common` and re-exported here so it shares the exact same behavior across every Recursica adapter.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Layer } from "@recursica/mantine-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+`Layer` sets `data-recursica-layer` on its root element, which is what makes the theme+layer scoped CSS variables (surface color, border, elevation, padding) in `recursica_variables_scoped.css` actually apply. [`RecursicaThemeProvider`](../RecursicaThemeProvider/USAGE.md) automatically wraps your app in a `layer={0}` `Layer` by default (via its `initLayer0` prop), so you don't need to add one yourself for the base page. You still add `Layer`s manually for anything visually elevated above the page background:
+
+```tsx
+import {
+  RecursicaThemeProvider,
+  Layer,
+  Card,
+} from "@recursica/mantine-adapter";
+
+function App() {
+  return (
+    <RecursicaThemeProvider theme="light">
+      {/* Page background/surface already uses layer 0, applied automatically */}
+      <Layer layer={1}>
+        <Card>Elevated content sits on layer 1</Card>
+      </Layer>
+    </RecursicaThemeProvider>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+> [!IMPORTANT]
+>
+> - **Layer 0 is automatic**: `RecursicaThemeProvider` applies it for you by default. Only opt out (`initLayer0={false}`) if you need to control exactly where layer 0 starts in the tree, or need `contentsOnly` on the base layer — see [RecursicaThemeProvider usage](../RecursicaThemeProvider/USAGE.md).
+> - **Layers 1–3 are manual**: Wrap any content that's visually elevated above the page background (a Card, Modal, Popover, etc.) in its own `<Layer layer={1|2|3}>`. Nesting `Layer`s is how Recursica communicates elevation to descendant components — do **not** pass a `layer` prop directly to other components; wrap them in a `Layer` instead (every other component's `USAGE.md` repeats this rule).
+> - **`contentsOnly`**: When `true`, `Layer` renders with `display: contents` and omits `data-recursica-layer` entirely — use this when you need a layer boundary in your component tree without adding an extra DOM box or applying layer styling (e.g. a purely structural wrapper).
+
+---
+
+## 4. Key Integration Features & Constraints
+
+`Layer` has no visual variants of its own — its entire purpose is to bind a subtree to a numbered layer's design tokens. It does not accept `overStyled`; instead, if you find yourself needing to override a layer's surface styling, that's a signal you may want a different layer number rather than an escape hatch.

package/src/components/RecursicaThemeProvider/USAGE.md

@@ -0,0 +1,60 @@
+# RecursicaThemeProvider - Usage Guide
+
+This document describes how to integrate and use `RecursicaThemeProvider` in your projects using `@recursica/mantine-adapter`.
+
+> [!NOTE] > `RecursicaThemeProvider` is defined once in `@recursica/adapter-common` and re-exported here so it shares the exact same behavior across every Recursica adapter.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { RecursicaThemeProvider } from "@recursica/mantine-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import { MantineProvider } from "@mantine/core";
+import { RecursicaThemeProvider } from "@recursica/mantine-adapter";
+
+function App() {
+  return (
+    <MantineProvider>
+      <RecursicaThemeProvider theme="light">
+        {/* Your App Components */}
+      </RecursicaThemeProvider>
+    </MantineProvider>
+  );
+}
+```
+
+By default, `RecursicaThemeProvider` also wraps `children` in a base [`Layer`](../Layer/USAGE.md) (`layer={0}`), so surface/border/elevation variables resolve immediately — no separate `Layer` needed for the page background.
+
+If you want to place the base layer yourself (e.g. to use `contentsOnly`, or to control exactly where layer 0 starts in the tree), opt out with `initLayer0={false}`:
+
+```tsx
+import { RecursicaThemeProvider, Layer } from "@recursica/mantine-adapter";
+
+<RecursicaThemeProvider theme="light" initLayer0={false}>
+  <Layer layer={0}>{/* Your App Components */}</Layer>
+</RecursicaThemeProvider>;
+```
+
+---
+
+## 3. Design System Integration
+
+> [!IMPORTANT]
+>
+> - **Required for setup**: `RecursicaThemeProvider` must wrap your entire application, once, near the root. See [SETUP.md](../../../SETUP.md) for the full setup sequence.
+> - **`initLayer0` (default `true`)**: Automatically wraps `children` in a layer-0 [`Layer`](../Layer/USAGE.md). `RecursicaThemeProvider` itself only sets `data-recursica-theme` (`"light"` or `"dark"`, defaults to `"light"`) on `document.documentElement` — without a `Layer` in the tree (either the automatic one or one you add yourself with `initLayer0={false}`), none of Recursica's surface CSS variables resolve.
+> - **Runtime theme switching**: Changing the `theme` prop re-runs the effect and updates `data-recursica-theme` immediately, so you can drive light/dark switching from application state.
+
+---
+
+## 4. Key Integration Features & Constraints
+
+`RecursicaThemeProvider` also wires up the `overStyled` development-mode visual auditing helper (see [OVERSTYLING.md](../../../OVERSTYLING.md)) — `recursica.toggleOverStyled()` in the browser console only works once this provider has mounted.

package/src/components/index.ts

@@ -1,4 +1,5 @@
 export * from "./Accordion";
+export * from "./AssistiveElement/AssistiveElement";
 export * from "./AutoComplete/AutoComplete";
 export * from "./Avatar";
 export * from "./Badge/Badge";
@@ -15,6 +16,7 @@ export * from "./FileInput/FileInput";
 export * from "./FileUpload/FileUpload";
 export * from "./Flex/Flex";
 export * from "./FormControlLayout/FormControlLayout";
+export * from "./Grid/Grid";
 export * from "./Group/Group";
 export * from "./HoverCard/HoverCard";
 export * from "./Link/Link";

package/src/index.ts

@@ -6,6 +6,8 @@ export * from "@recursica/adapter-common";
 
 // Expose unwrapped structural layout primitives to preserve their polymorphic types
 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;
@@ -25,6 +27,9 @@ export const AccordionControl = wrapComponent(
 export const AccordionPanel = wrapComponent(
   rawComponents.AccordionPanel,
 ) as typeof rawComponents.AccordionPanel;
+export const AssistiveElement = wrapComponent(
+  rawComponents.AssistiveElement,
+) as typeof rawComponents.AssistiveElement;
 export const AutoComplete = wrapComponent(
   rawComponents.AutoComplete,
 ) as typeof rawComponents.AutoComplete;