@recursica/adapter-mantine-v8 1.2.1 → 1.3.0

package/src/components/LayoutGrid/USAGE.md

@@ -0,0 +1,76 @@
+# LayoutGrid - Usage Guide
+
+This document describes how to integrate and use the `LayoutGrid` component in your projects using `@recursica/adapter-mantine-v8`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { LayoutGrid } from "@recursica/adapter-mantine-v8";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { LayoutGrid } from "@recursica/adapter-mantine-v8";
+
+export default function Demo() {
+  return (
+    // No layout props needed: columns, column-gutter, row-gutter and margin come from the design
+    // system's layout-grids tokens and change per breakpoint.
+    <LayoutGrid>
+      <LayoutGrid.Col span={3}>Half width at 6 columns</LayoutGrid.Col>
+      <LayoutGrid.Col span={{ xs: 6, sm: 3, md: 2 }}>
+        Responsive width
+      </LayoutGrid.Col>
+    </LayoutGrid>
+  );
+}
+```
+
+---
+
+## 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]
+>
+> - **Variables and Theming**: LayoutGrid follows the design system's own `layout-grids` tokens — columns, column-gutter, row-gutter and margin — applied automatically. Forge can define these per breakpoint, and the grid follows. None of them are configurable via props.
+
+> [!NOTE] > **Recommended: build your Mantine theme's breakpoints from the Forge manifest with `breakpointsFromRecManifest`.** Responsive keys such as `{ base, sm, md }` on `LayoutGrid.Col` (and on Flex, Stack, Group) come from `theme.breakpoints`, while Forge's layout grids switch via plain CSS `@media`. If the two differ, tokens flip at Forge's width and props at the theme's. `breakpointsFromRecManifest(manifest)` (exported from `@recursica/adapter-mantine-v8`) gives you a `theme.breakpoints` object that matches Forge, so both switch at the same widths (Mantine keeps its default `xs`–`xl` keys alongside Forge's names, so use Forge's names in responsive props). See [SETUP.md](../../../SETUP.md):
+>
+> ```tsx
+> import { createTheme } from "@mantine/core";
+> import { breakpointsFromRecManifest } from "@recursica/adapter-mantine-v8";
+> import manifest from "./recursica_manifest.json";
+>
+> const theme = createTheme({
+>   breakpoints: breakpointsFromRecManifest(manifest),
+> });
+> ```
+
+---
+
+## 4. Key Integration Features & Constraints
+
+`LayoutGrid.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 `RecursicaLayoutGridColProps` contract in
+`adapter-common` is scaffolded but not filled in yet (TODO, tracked in
+`LAYOUT_GRID_IMPLEMENTATION_NOTES.md`).
+
+`LayoutGrid` does not accept Mantine's `gutter` or `columns` props — column count, column-gutter,
+row-gutter, and margin are design-system-managed (Forge-controlled, breakpoint-aware, applied via
+CSS variables). For a fixed N-column grid unrelated to page layout, use Mantine's `Grid` directly.
+
+`span` and `offset` (numeric, or a breakpoint map like `{ base: 12, md: 6 }`) are relative to
+Forge's current column count, and `span` is clamped to it (span 6 fills the row at 3 columns).
+Breakpoint maps switch at the app's Mantine theme breakpoints. `"auto"` and `"content"` don't
+depend on the column count.
+
+`grow`, `justify`, `align` are unchanged, matching Mantine's own naming.

package/src/components/Pagination/IMPLEMENTATION_NOTES.md

@@ -1,16 +1,37 @@
 # Pagination Implementation Notes
 
-## Architecture Decision: CSS Inheritance vs. Composition
+## Architecture: Recursica Buttons driven by the manifest
 
-The Figma design tokens for the `Pagination` component dictate that pagination pages perfectly mimic `Button` variants (e.g. `active-pages_style: "solid"`, `inactive-pages_style: "outline"`, `navigation-controls_style: "text"`).
+Forge's `ui-kit.components.pagination` defines its page and navigation controls as `Button`
+variants (`active-pages`, `inactive-pages`, `navigation-controls`, each with a `selected-variants`
+style and size). Pagination therefore renders Recursica `Button`s with those props and does no
+button styling of its own: radius, padding, colors, hover and disabled all come from `Button`.
 
-As of the `1.2.0` scoped CSS update, the Figma exporter automatically handles these variants. It flattens and aliases the referenced Button properties directly into the `Pagination` component's variable namespace.
+- `Pagination` reads the selected `style` and `size` per role from the manifest with
+  `useRecursicaManifest()` (`adapter-common`), provided by `RecursicaThemeProvider`'s `manifest`
+  prop. It throws if there is no manifest or if a role has no `selected-variants`. The values are
+  passed to `Button` as is, with no validation and no fallbacks.
+- `content` (`label`, `icon-label`, `icon-only`) is not read: `Button` derives it from its own
+  children and icon, so page numbers are `label` and the navigation buttons are `icon-only`
+  (`icon-label` with `withLabels`).
 
-We opted to use Mantine's native `PaginationControl` components to ensure all DOM structure, focus management, and accessibility attributes are preserved natively without us needing to carefully rebuild `Pagination.Items` mappings.
+## Why not Mantine's `Pagination.Control`
 
-To honor the Figma design intents while using Mantine's raw `<button>` elements:
+Mantine's `Pagination.Control` is not polymorphic, so it can't render our `Button`. The component is
+built on `usePagination` from `@mantine/hooks` instead (page state, ranges, siblings/boundaries),
+with its own context shared by `Pagination.Root`, `Items`, `Control`, `Dots`, `Next`, `Previous`,
+`First` and `Last`. Page buttons set `aria-current="page"` on the active page, and the navigation
+buttons have fixed `aria-label`s.
 
-1. We inherit and map all natively scoped `Pagination` variant styles (small typography, outline/solid/text colors, and hover overlays) directly into `.control` and `.control[data-active]` within `Pagination.module.css`. We do not need to manually reference `Button` variables cross-component.
-2. We inject `data-variant="text"` via `getControlProps` onto the navigation buttons so that they inherit the explicitly aliased text style variables (`navigation-controls`) defined by the UI Kit for pagination.
+## Labels
 
-This achieves exact optical alignment with the tokens while maintaining Mantine's robust internal event handling for pagination.
+`withLabels` adds a text label to each navigation button. `Previous`/`First` put the icon first
+(`Button`'s `icon`); `Next`/`Last` put it after the label (`rightSection`, sized to the Button's
+icon token via `[data-size]` in `Pagination.module.css`).
+
+## Styling
+
+`Pagination.module.css` only lays out the row (`item-gap`) and styles the dots (`dots-color`).
+
+- The root is a `<nav aria-label="Pagination">` landmark, and each page button has `aria-label="Page N"`
+  (`Previous page`, `Next page`, etc. for the navigation buttons). Both can be overridden by props.

package/src/components/Pagination/Pagination.icons.tsx

@@ -32,35 +32,3 @@ export const PaginationIcon = ({
     <path d={paths[type as PaginationIconType]} fill="currentColor" />
   </svg>
 );
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export const NextWithLabel = (props: any) => (
-  <div className={styles.iconWithLabel}>
-    <span>Next</span>
-    <PaginationIcon type="next" {...props} />
-  </div>
-);
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export const PrevWithLabel = (props: any) => (
-  <div className={styles.iconWithLabel}>
-    <PaginationIcon type="prev" {...props} />
-    <span>Prev</span>
-  </div>
-);
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export const FirstWithLabel = (props: any) => (
-  <div className={styles.iconWithLabel}>
-    <PaginationIcon type="first" {...props} />
-    <span>First</span>
-  </div>
-);
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export const LastWithLabel = (props: any) => (
-  <div className={styles.iconWithLabel}>
-    <span>Last</span>
-    <PaginationIcon type="last" {...props} />
-  </div>
-);

package/src/components/Pagination/Pagination.manifest.dom.test.tsx

@@ -0,0 +1,108 @@
+import React from "react";
+import { describe, it, expect } from "vitest";
+import { createRoot } from "react-dom/client";
+import { flushSync } from "react-dom";
+import { MantineProvider } from "@mantine/core";
+import { RecursicaManifestContext } from "@recursica/adapter-common";
+import { Pagination } from "./Pagination";
+
+const role = (style: string, size: string) => ({
+  $extensions: {
+    "recursica.component": { "selected-variants": { style, size } },
+  },
+});
+const manifest = (props: Record<string, unknown>) => ({
+  "ui-kit": { components: { pagination: { properties: props } } },
+});
+const full = manifest({
+  "active-pages": role("solid", "small"),
+  "inactive-pages": role("outline", "small"),
+  "navigation-controls": role("text", "small"),
+});
+
+class Catch extends React.Component<
+  { children: React.ReactNode },
+  { error?: Error }
+> {
+  state: { error?: Error } = {};
+  static getDerivedStateFromError(error: Error) {
+    return { error };
+  }
+  render() {
+    return this.state.error ? (
+      <span data-error>{this.state.error.message}</span>
+    ) : (
+      this.props.children
+    );
+  }
+}
+
+function mount(m: Record<string, unknown> | undefined) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const root = createRoot(container);
+  flushSync(() =>
+    root.render(
+      <MantineProvider>
+        <Catch>
+          <RecursicaManifestContext.Provider value={m}>
+            <Pagination total={5} defaultValue={2} />
+          </RecursicaManifestContext.Provider>
+        </Catch>
+      </MantineProvider>,
+    ),
+  );
+  return {
+    container,
+    error: container.querySelector("[data-error]")?.textContent,
+    done: () => {
+      root.unmount();
+      container.remove();
+    },
+  };
+}
+
+describe("Pagination manifest variants", () => {
+  it("renders Buttons with the style and size the manifest selects per role", () => {
+    const { container, error, done } = mount(full);
+    expect(error).toBeUndefined();
+    const active = container.querySelector('[aria-current="page"]');
+    expect(active?.getAttribute("data-variant")).toBe("solid");
+    expect(active?.getAttribute("data-size")).toBe("small");
+    const inactive = [...container.querySelectorAll("button")].find(
+      (b) => b.textContent === "3",
+    );
+    expect(inactive?.getAttribute("data-variant")).toBe("outline");
+    const next = container.querySelector('[aria-label="Next page"]');
+    expect(next?.getAttribute("data-variant")).toBe("text");
+    expect(next?.getAttribute("data-content")).toBe("icon-only");
+    done();
+  });
+
+  it("renders a labelled nav with a labelled button per page", () => {
+    const { container, error, done } = mount(full);
+    expect(error).toBeUndefined();
+    expect(container.querySelector("nav")?.getAttribute("aria-label")).toBe(
+      "Pagination",
+    );
+    const three = [...container.querySelectorAll("button")].find(
+      (b) => b.textContent === "3",
+    );
+    expect(three?.getAttribute("aria-label")).toBe("Page 3");
+    done();
+  });
+
+  it("throws without a manifest", () => {
+    const { error, done } = mount(undefined);
+    expect(error).toMatch(/Recursica manifest/);
+    done();
+  });
+
+  it("throws when a role has no selected variants", () => {
+    const { error, done } = mount(
+      manifest({ "active-pages": role("solid", "small") }),
+    );
+    expect(error).toMatch(/navigation-controls selected-variants/);
+    done();
+  });
+});

package/src/components/Pagination/Pagination.module.css

@@ -1,9 +1,5 @@
-/* Brand-layer exemptions (recursica-allow-brand) — see recursica-token-analyzer README.md.
- * Global hover/focus/disabled state tokens (recursica_variables_scoped.css header, 'Hover & Focus states' / 'Disabled state' — implicit rule for every interactive element; components must not define their own per-component treatment).
- *   recursica-allow-brand: --recursica_brand_states_disabled
- *   recursica-allow-brand: --recursica_brand_states_hover_color
- *   recursica-allow-brand: --recursica_brand_states_hover_opacity
- */
+/* The page and navigation buttons are Recursica Buttons (see Pagination.tsx), so this file only
+ * lays out the row and styles the dots and the labelled-icon wrapper. */
 
 .root {
   display: flex;
@@ -11,178 +7,52 @@
   gap: var(--recursica_ui-kit_components_pagination_properties_item-gap);
 }
 
-.control {
-  box-sizing: border-box;
-  margin: 0;
-  border-style: solid;
-  position: relative;
-  transition: all 0.2s ease;
-  overflow: hidden;
+/* Dots: sized like the page buttons around them (the inactive-pages size from the manifest). */
+.dots {
   display: inline-flex;
   align-items: center;
   justify-content: center;
-
-  /* Typography */
-  font-family: var(
-    --recursica_ui-kit_components_button_variants_sizes_default_properties_text_font-family
-  );
-  font-size: var(
-    --recursica_ui-kit_components_button_variants_sizes_default_properties_text_font-size
-  );
-  font-style: var(
-    --recursica_ui-kit_components_button_variants_sizes_default_properties_text_font-style
-  );
-  font-weight: var(
-    --recursica_ui-kit_components_button_variants_sizes_default_properties_text_font-weight
-  );
-  letter-spacing: var(
-    --recursica_ui-kit_components_button_variants_sizes_default_properties_text_letter-spacing
-  );
-  line-height: var(
-    --recursica_ui-kit_components_button_variants_sizes_default_properties_text_line-height
-  );
-  text-decoration: var(
-    --recursica_ui-kit_components_button_variants_sizes_default_properties_text_text-decoration
-  );
-  text-transform: var(
-    --recursica_ui-kit_components_button_variants_sizes_default_properties_text_text-transform
-  );
-
-  /* Dimensions */
-  border-radius: var(
-    --recursica_ui-kit_components_button_variants_content_icon-only_variants_sizes_default_properties_border-radius
-  );
   height: var(
     --recursica_ui-kit_components_button_variants_sizes_default_properties_height
   );
   min-width: var(
     --recursica_ui-kit_components_button_variants_sizes_default_properties_min-width
   );
-  padding: 0
-    var(
-      --recursica_ui-kit_components_button_variants_sizes_default_properties_horizontal-padding
-    );
-
-  /* Base Inactive Style: Outline */
-  border-width: var(
-    --recursica_ui-kit_components_button_variants_styles_outline_properties_border-size
-  );
-  box-shadow: var(
-    --recursica_ui-kit_components_button_variants_styles_outline_properties_elevation
-  );
-  background-color: var(
-    --recursica_ui-kit_components_button_variants_styles_outline_properties_colors_background-color
-  );
-  border-color: var(
-    --recursica_ui-kit_components_button_variants_styles_outline_properties_colors_border-color
-  );
-  color: var(
-    --recursica_ui-kit_components_button_variants_styles_outline_properties_colors_text-color
-  );
-}
-
-.control:disabled {
-  opacity: var(--recursica_brand_states_disabled);
-  cursor: not-allowed;
-}
-
-/* Hover Overlay: no per-variant hover-color/hover-opacity tokens exist anymore; use the
-   generic overlay tokens shared across components (same as Button). */
-.control::after {
-  content: "";
-  position: absolute;
-  inset: 0;
-  border-radius: inherit;
-  z-index: 0;
-  pointer-events: none;
-  transition: opacity 150ms ease;
-  opacity: 0;
-  background-color: var(--recursica_brand_states_hover_color);
-}
-
-.control:hover:not(:disabled)::after {
-  opacity: var(--recursica_brand_states_hover_opacity);
-}
-
-/* Active Style: Solid */
-.control[data-active] {
-  border-width: var(
-    --recursica_ui-kit_components_button_variants_styles_solid_properties_border-size
-  );
-  box-shadow: var(
-    --recursica_ui-kit_components_button_variants_styles_solid_properties_elevation
-  );
-  background-color: var(
-    --recursica_ui-kit_components_button_variants_styles_solid_properties_colors_background-color
-  );
-  border-color: var(
-    --recursica_ui-kit_components_button_variants_styles_solid_properties_colors_border-color
-  );
   color: var(
-    --recursica_ui-kit_components_button_variants_styles_solid_properties_colors_text-color
+    --recursica_ui-kit_components_pagination_properties_colors_dots-color
   );
 }
 
-/* Navigation Style: Text */
-.control[data-variant="text"] {
-  border-width: var(
-    --recursica_ui-kit_components_button_variants_styles_text_properties_border-size
-  );
-  box-shadow: var(
-    --recursica_ui-kit_components_button_variants_styles_text_properties_elevation
-  );
-  background-color: var(
-    --recursica_ui-kit_components_button_variants_styles_text_properties_colors_background-color
-  );
-  border-color: var(
-    --recursica_ui-kit_components_button_variants_styles_text_properties_colors_border-color
-  );
-  color: var(
-    --recursica_ui-kit_components_button_variants_styles_text_properties_colors_text-color
-  );
-
-  /* Also explicitly inherit navigation sizes incase they differ from pages */
-  border-radius: var(
-    --recursica_ui-kit_components_button_variants_content_icon-only_variants_sizes_default_properties_border-radius
-  );
+.dots[data-size="small"] {
   height: var(
-    --recursica_ui-kit_components_button_variants_sizes_default_properties_height
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_height
   );
   min-width: var(
-    --recursica_ui-kit_components_button_variants_sizes_default_properties_min-width
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_min-width
   );
-  padding: 0
-    var(
-      --recursica_ui-kit_components_button_variants_sizes_default_properties_horizontal-padding
-    );
 }
 
-/* Dots */
-.dots {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  height: var(
-    --recursica_ui-kit_components_button_variants_sizes_default_properties_height
-  );
-  min-width: var(
-    --recursica_ui-kit_components_button_variants_sizes_default_properties_min-width
-  );
-  color: var(
-    --recursica_ui-kit_components_pagination_properties_colors_dots-color
-  );
+/* Icons: sized by the Button's own icon wrapper (left icons) or by its size (right icons). */
+.baseIcon {
+  width: 100%;
+  height: 100%;
 }
 
-/* Icon Styles */
-.iconWithLabel {
+.rightIcon {
   display: flex;
-  align-items: center;
-  gap: var(
-    --recursica_ui-kit_components_button_variants_sizes_default_properties_icon-text-gap
+  width: var(
+    --recursica_ui-kit_components_button_variants_sizes_default_properties_icon
+  );
+  height: var(
+    --recursica_ui-kit_components_button_variants_sizes_default_properties_icon
   );
 }
 
-.baseIcon {
-  width: calc(var(--pagination-control-size) / 1.8);
-  height: calc(var(--pagination-control-size) / 1.8);
+[data-size="small"] .rightIcon {
+  width: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_icon
+  );
+  height: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_icon
+  );
 }