@recursica/adapter-mantine-v8 1.0.0

package/src/components/FormControlWrapper/FormControlWrapper.test.tsx

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

package/src/components/FormControlWrapper/FormControlWrapper.tsx

@@ -0,0 +1,151 @@
+import React, { forwardRef, useId } from "react";
+import { type InputWrapperProps } from "@mantine/core";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import { Label } from "../Label/Label";
+import { FormControlLayout } from "../FormControlLayout/FormControlLayout";
+import { AssistiveElement } from "../AssistiveElement/AssistiveElement";
+import styles from "./FormControlWrapper.module.css";
+
+import { type RecursicaFormControlWrapperProps } from "@recursica/adapter-common";
+export type { RecursicaFormControlWrapperProps };
+
+export type FormControlWrapperProps = RecursicaOverStyled<
+  Omit<InputWrapperProps, "labelProps" | "inputWrapperOrder"> &
+    RecursicaFormControlWrapperProps
+>;
+
+export const FormControlWrapper = forwardRef<
+  HTMLDivElement,
+  FormControlWrapperProps
+>(function FormControlWrapper(
+  {
+    formLayout,
+    labelSize,
+    labelAlignment,
+    labelOptionalText,
+    labelWithEditIcon,
+    labelActionArea,
+    onLabelEditClick,
+
+    label,
+    description,
+    assistiveText,
+    assistiveWithIcon = true,
+    controlMaxWidth,
+    controlMinWidth,
+    error,
+    required,
+    withAsterisk,
+    id: userProvidedId,
+    children,
+    className,
+    overStyled = false,
+    labelElement, // Extracted safely preventing bleeding into HTML domains
+    ...rest
+  },
+  ref,
+) {
+  // Generate a reliable ID to map the Label's HTML context down to the component array natively.
+  const generatedId = useId();
+  const id = userProvidedId || `recursica-fc-${generatedId}`;
+  const labelId = `${id}-label`;
+
+  // Evaluate explicit assistive fallbacks ensuring assistiveText correctly prioritizes natively over underlying Mantine configurations!
+  const resolvedAssistive = assistiveText || description;
+  const assistiveId = resolvedAssistive ? `${id}-assistive` : undefined;
+  const errorId = error ? `${id}-error` : undefined;
+
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const restRecord = sanitizedProps as Record<string, unknown>;
+
+  const classNameProp =
+    className || (restRecord.className as string | undefined);
+  const rootClass = styles.root;
+  const finalClass = classNameProp
+    ? `${rootClass} ${classNameProp}`
+    : rootClass;
+
+  // Clone ARIA identifiers directly back down into the nested children wrapper so screen-readers natively hook the external strings.
+  // `id` is cloned down here too — the label's `htmlFor` below only resolves to the field's
+  // native `label.control` when the field itself actually carries this id.
+  const content = React.isValidElement(children)
+    ? React.cloneElement(
+        children as React.ReactElement<Record<string, unknown>>,
+        {
+          ...(!(children.props as Record<string, unknown>)["id"] ? { id } : {}),
+          "aria-labelledby": labelId,
+          ...(resolvedAssistive &&
+          !(children.props as Record<string, unknown>)["aria-describedby"]
+            ? { "aria-describedby": assistiveId }
+            : {}),
+          ...(error &&
+          !(children.props as Record<string, unknown>)["aria-errormessage"]
+            ? { "aria-errormessage": errorId }
+            : {}),
+        },
+      )
+    : children;
+
+  const labelNode = label ? (
+    <Label
+      id={labelId}
+      htmlFor={id} // Native label/control association — must not also be set on the label's own id
+      labelAlignment={labelAlignment}
+      labelOptionalText={labelOptionalText}
+      labelWithEditIcon={labelWithEditIcon}
+      labelActionArea={labelActionArea}
+      onLabelEditClick={onLabelEditClick}
+      required={withAsterisk ?? required}
+      // Manually propagate relevant structural logic if underlying groups dictate Label to act as generic wrapper
+      {...(labelElement === "div" ? { as: "div" } : {})}
+    >
+      {label}
+    </Label>
+  ) : undefined;
+
+  return (
+    <FormControlLayout
+      ref={ref}
+      className={finalClass}
+      formLayout={formLayout}
+      labelSize={labelSize}
+      controlMaxWidth={controlMaxWidth}
+      controlMinWidth={controlMinWidth}
+      leftSection={labelNode}
+      {...restRecord}
+    >
+      {/*
+        The Core Input Wrapper & Controls
+        Nakedly inject the actual field elements alongside natively bridged Assistive components mapped dynamically.
+      */}
+      <div className={styles.inputSection}>
+        {content}
+
+        {error && (
+          <AssistiveElement
+            id={errorId}
+            assistiveVariant="error"
+            assistiveWithIcon={assistiveWithIcon}
+          >
+            {error}
+          </AssistiveElement>
+        )}
+
+        {!error && resolvedAssistive && (
+          <AssistiveElement
+            id={assistiveId}
+            assistiveVariant="help"
+            assistiveWithIcon={assistiveWithIcon}
+          >
+            {resolvedAssistive}
+          </AssistiveElement>
+        )}
+      </div>
+    </FormControlLayout>
+  );
+});
+
+FormControlWrapper.displayName = "FormControlWrapper";

package/src/components/FormControlWrapper/USAGE.md

@@ -0,0 +1,47 @@
+# FormControlWrapper - Usage Guide
+
+This document describes how to integrate and use the `FormControlWrapper` component in your projects using `@recursica/adapter-mantine-v8`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { FormControlWrapper } from "@recursica/adapter-mantine-v8";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { FormControlWrapper } from "@recursica/adapter-mantine-v8";
+
+export default function Demo() {
+  return (
+    <FormControlWrapper label="Email Address" required error="Invalid email">
+      <input type="email" />
+    </FormControlWrapper>
+  );
+}
+```
+
+---
+
+## 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**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **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**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.
+
+---
+
+## 4. Notes
+
+- `FormControlWrapper` renders the label, error, and help text around the child input; screen-reader associations between the input and its assistive text are handled automatically.
+- The wrapper stretches to fill its container by default. If the wrapped input has its own maximum width, pass a matching `--form-control-max-width` CSS variable via the `style` prop so the label and assistive text align to the same width as the input.

package/src/components/Grid/GRID_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,18 @@
+# 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.
+
+Per the layout-components rule (no formal Recursica common props definition — these simply pass through the underlying kit's own props), `Grid` and `Grid.Col` are typed directly off Mantine's own `GridProps`/`GridColProps` with no Recursica-specific prop renaming. The public prop for spacing between columns is Mantine's own `gutter` (previously renamed to `gap` for cross-component consistency — that rename has been reverted since it wasn't a real Mantine prop). `gutter` still accepts `rec-*` spacing tokens, resolved via `mapLayoutProps`, the same utility used elsewhere.
+
+`Grid.Col`'s `span`, `offset`, `order`, `visibleFrom`, and `hiddenFrom` props are passed straight through to Mantine's `Grid.Col` unchanged, using Mantine's own breakpoint scale (`xs`/`sm`/`md`/`lg`/`xl` — there is no `base` breakpoint in Mantine; `xs` is the smallest).
+
+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`.
+
+## Added `ResponsiveSizes` story (2026-08-30, source-of-truth audit)
+
+mui-adapter has a `ui-kit-grid--responsive-sizes` story with no counterpart here — its `story
+parity with source of truth` check would otherwise fail for mui-adapter. Added an equivalent
+`ResponsiveSizes` story using Mantine's own `span` prop (Mantine's `Grid.Col` has no `size` prop
+— see the naming-divergence note above and mui-adapter's own `IMPLEMENTATION_NOTES.md`). This is
+functionally identical to the existing `ResponsiveSpans` story above; it exists purely so
+mui-adapter's differently-named story id has a source-of-truth golden to diff against.

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,206 @@
+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: {
+    gutter: "rec-default",
+    columns: 12,
+    grow: false,
+  },
+  argTypes: {
+    gutter: {
+      control: "select",
+      options: [
+        "rec-none",
+        "rec-sm",
+        "rec-default",
+        "rec-md",
+        "rec-lg",
+        "rec-xl",
+        "rec-2xl",
+      ],
+      description: "Gutter 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={{ xs: 12, sm: 6, md: 3 }}>
+        <Swatch>xs 12 / sm 6 / md 3</Swatch>
+      </Grid.Col>
+      <Grid.Col span={{ xs: 12, sm: 6, md: 3 }}>
+        <Swatch>xs 12 / sm 6 / md 3</Swatch>
+      </Grid.Col>
+      <Grid.Col span={{ xs: 12, sm: 6, md: 3 }}>
+        <Swatch>xs 12 / sm 6 / md 3</Swatch>
+      </Grid.Col>
+      <Grid.Col span={{ xs: 12, sm: 6, md: 3 }}>
+        <Swatch>xs 12 / sm 6 / md 3</Swatch>
+      </Grid.Col>
+    </Grid>
+  ),
+};
+
+// Mirrors mui-adapter's `ResponsiveSizes` story (same breakpoints/content) under mantine's own
+// prop name — Mantine's Grid.Col has no `size` prop, only `span`, which is what `ResponsiveSpans`
+// above already exercises. This one exists purely so mui-adapter's `responsive-sizes` story id
+// has a source-of-truth counterpart to diff against (see Grid's IMPLEMENTATION_NOTES.md).
+export const ResponsiveSizes: 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={{ xs: 12, sm: 6, md: 3 }}>
+        <Swatch>xs 12 / sm 6 / md 3</Swatch>
+      </Grid.Col>
+      <Grid.Col span={{ xs: 12, sm: 6, md: 3 }}>
+        <Swatch>xs 12 / sm 6 / md 3</Swatch>
+      </Grid.Col>
+      <Grid.Col span={{ xs: 12, sm: 6, md: 3 }}>
+        <Swatch>xs 12 / sm 6 / md 3</Swatch>
+      </Grid.Col>
+      <Grid.Col span={{ xs: 12, sm: 6, md: 3 }}>
+        <Swatch>xs 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.test.tsx

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

package/src/components/Grid/Grid.tsx

@@ -0,0 +1,140 @@
+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";
+
+/**
+ * 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.
+ *
+ * No formal Recursica prop contract here: this simply passes through Mantine's own
+ * `GridProps` (gutter/grow/columns/justify/align are all native to Mantine), layered only
+ * with rec- spacing token support via `WithRecursicaSpacing`.
+ */
+export type GridProps = WithRecursicaSpacing<MantineGridProps>;
+
+const _Grid = forwardRef<HTMLDivElement, GridProps>(function Grid(
+  { children, gutter = "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 { gutter: mappedGutter, ...mappedRest } = mapLayoutProps({
+    gutter,
+    ...rest,
+  } as Record<string, unknown>);
+
+  return (
+    <MantineGrid
+      ref={ref}
+      gutter={mappedGutter 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>;
+
+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/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 (
+    <Grid gutter="rec-default">
+      <Grid.Col span={6}>Half width</Grid.Col>
+      <Grid.Col span={{ xs: 12, sm: 6, md: 3 }}>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**: 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` with no Recursica-specific prop renaming — `gutter`, `columns`, `grow`, `justify`, `align` on `Grid`, and `span`, `offset`, `order`, `visibleFrom`, `hiddenFrom` on `Grid.Col` all match Mantine's own naming and accept the same shapes, including per-breakpoint objects (`{ xs, sm, md, lg, xl }`). `gutter` additionally accepts `rec-*` spacing tokens.

package/src/components/Group/GROUP_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,4 @@
+# Group Implementation Notes
+
+The `Group` component is a generic flex layout wrapper mapped directly to Mantine's `Group`.
+It currently does not require any custom logical layouts or CSS workarounds since it serves only to organize layout structure, and doesn't enforce any strict design-system token styling itself. All gap, align, wrap, and justify properties pass safely through via the `filterStylingProps` layout-property allowance.

package/src/components/Group/Group.module.css

@@ -0,0 +1,7 @@
+/* HARDCODED VALUES:
+ * None. This is a generic flex layout wrapper.
+ */
+
+.root {
+  /* Mantine handles flex, gap, align, justify. No intrinsic design-system styles required for pure layout wrappers. */
+}