@recursica/adapter-mantine-v8 1.2.1 → 1.3.0

package/src/components/Pagination/Pagination.tsx

@@ -1,247 +1,381 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import React, { forwardRef } from "react";
+import React, { createContext, forwardRef, useContext } from "react";
+import { usePagination } from "@mantine/hooks";
 import {
-  Pagination as MantinePagination,
-  type PaginationProps as MantinePaginationProps,
-  type PaginationRootProps as MantinePaginationRootProps,
-  type PaginationControlProps as MantinePaginationControlProps,
-  type PaginationDotsProps as MantinePaginationDotsProps,
-} from "@mantine/core";
+  useRecursicaManifest,
+  type RecursicaPaginationProps,
+} from "@recursica/adapter-common";
 import {
   filterStylingProps,
-  withCallerOverride,
-  mergeClassNames,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
+import { Button, type ButtonProps } from "../Button/Button";
 import styles from "./Pagination.module.css";
-import {
-  NextWithLabel,
-  PrevWithLabel,
-  FirstWithLabel,
-  LastWithLabel,
-  PaginationIcon,
-} from "./Pagination.icons";
-
-import { type RecursicaPaginationProps } from "@recursica/adapter-common";
+import { PaginationIcon } from "./Pagination.icons";
 
-export type PaginationProps = RecursicaOverStyled<
-  MantinePaginationProps & RecursicaPaginationProps
->;
+type PaginationRole = "active-pages" | "inactive-pages" | "navigation-controls";
+type NavControl = "first" | "previous" | "next" | "last";
 
-export type PaginationRootProps =
-  RecursicaOverStyled<MantinePaginationRootProps>;
+interface RoleVariant {
+  variant: NonNullable<ButtonProps["variant"]>;
+  size: NonNullable<ButtonProps["size"]>;
+}
 
-export type PaginationEdgeProps<T extends React.ElementType> =
-  RecursicaOverStyled<
-    React.ComponentProps<T> & {
-      /** If set to true, displays text labels alongside the icon. */
-      withLabel?: boolean;
-      icon?: any;
+/** Reads which Button style and size the manifest selects for a Pagination role. */
+function usePaginationRole(role: PaginationRole): RoleVariant {
+  const manifest = useRecursicaManifest();
+  const selected = (
+    manifest as {
+      "ui-kit"?: {
+        components?: {
+          pagination?: {
+            properties?: Record<
+              string,
+              {
+                $extensions?: {
+                  "recursica.component"?: {
+                    "selected-variants"?: Record<string, unknown>;
+                  };
+                };
+              }
+            >;
+          };
+        };
+      };
     }
-  >;
+  )["ui-kit"]?.components?.pagination?.properties?.[role]?.$extensions?.[
+    "recursica.component"
+  ]?.["selected-variants"];
+  if (!selected) {
+    throw new Error(
+      `Pagination: manifest has no ui-kit.components.pagination.properties.${role} selected-variants`,
+    );
+  }
+  return {
+    variant: selected.style as RoleVariant["variant"],
+    size: selected.size as RoleVariant["size"],
+  };
+}
 
-function usePaginationClassNames(restRecord: Record<string, unknown>): {
-  className: string;
-  classNames: Partial<Record<string, string>>;
-} {
-  const mergedClassNames = mergeClassNames(
-    {
-      root: styles.root,
-      control: styles.control,
-      dots: styles.dots,
-    },
-    restRecord.classNames as Partial<Record<string, string>> | undefined,
-  );
+interface PaginationContextValue {
+  total: number;
+  active: number;
+  range: (number | "dots")[];
+  disabled?: boolean;
+  setPage: (page: number) => void;
+  first: () => void;
+  previous: () => void;
+  next: () => void;
+  last: () => void;
+  getItemProps?: (page: number) => Record<string, unknown>;
+  getControlProps?: (control: NavControl) => Record<string, unknown>;
+  dotsIcon?: React.ReactNode;
+}
+
+const PaginationContext = createContext<PaginationContextValue | null>(null);
 
-  const classNameProp = restRecord.className as string | undefined;
-  const finalClass = classNameProp
-    ? `${styles.root} ${classNameProp}`
-    : styles.root;
+function usePaginationContext(): PaginationContextValue {
+  const ctx = useContext(PaginationContext);
+  if (!ctx) {
+    throw new Error("Pagination parts must be rendered inside Pagination.Root");
+  }
+  return ctx;
+}
 
-  return { className: finalClass, classNames: mergedClassNames };
+interface PaginationBaseProps {
+  /** Total number of pages */
+  total: number;
+  /** Active page (controlled) */
+  value?: number;
+  /** Initial active page (uncontrolled) */
+  defaultValue?: number;
+  /** Called when the active page changes */
+  onChange?: (page: number) => void;
+  /** Pages shown on each side of the active page */
+  siblings?: number;
+  /** Pages always shown at the start and end */
+  boundaries?: number;
+  disabled?: boolean;
+  /** Extra props for each page button */
+  getItemProps?: (page: number) => Record<string, unknown>;
+  /** Extra props for each first/previous/next/last button */
+  getControlProps?: (control: NavControl) => Record<string, unknown>;
+  /** Replaces the dots between page ranges */
+  dotsIcon?: React.ReactNode;
 }
 
-const _PaginationRoot = forwardRef<HTMLDivElement, PaginationRootProps>(
-  function PaginationRoot({ overStyled = false, ...rest }, ref) {
+export type PaginationRootProps = RecursicaOverStyled<
+  PaginationBaseProps &
+    Omit<React.ComponentPropsWithoutRef<"nav">, "onChange" | "children"> & {
+      children?: React.ReactNode;
+    }
+>;
+
+const _PaginationRoot = forwardRef<HTMLElement, PaginationRootProps>(
+  function PaginationRoot(
+    {
+      overStyled = false,
+      total,
+      value,
+      defaultValue,
+      onChange,
+      siblings,
+      boundaries,
+      disabled,
+      getItemProps,
+      getControlProps,
+      dotsIcon,
+      children,
+      ...rest
+    },
+    ref,
+  ) {
+    const pagination = usePagination({
+      total,
+      page: value,
+      initialPage: defaultValue,
+      onChange,
+      siblings,
+      boundaries,
+    });
     const sanitizedProps = filterStylingProps(rest, overStyled);
-    const stylingParams = usePaginationClassNames(
-      sanitizedProps as Record<string, unknown>,
-    );
+    const classNameProp = (sanitizedProps as { className?: string }).className;
 
     return (
-      <MantinePagination.Root
-        ref={ref}
-        {...(sanitizedProps as MantinePaginationRootProps)}
-        className={stylingParams.className}
-        classNames={stylingParams.classNames}
-      />
+      <PaginationContext.Provider
+        value={{
+          total,
+          active: pagination.active,
+          range: pagination.range,
+          disabled,
+          setPage: pagination.setPage,
+          first: pagination.first,
+          previous: pagination.previous,
+          next: pagination.next,
+          last: pagination.last,
+          getItemProps,
+          getControlProps,
+          dotsIcon,
+        }}
+      >
+        <nav
+          ref={ref}
+          aria-label="Pagination"
+          {...sanitizedProps}
+          className={
+            classNameProp ? `${styles.root} ${classNameProp}` : styles.root
+          }
+        >
+          {children}
+        </nav>
+      </PaginationContext.Provider>
     );
   },
 );
 _PaginationRoot.displayName = "Pagination.Root";
 
-const _PaginationNext = forwardRef<
-  HTMLButtonElement,
-  PaginationEdgeProps<typeof MantinePagination.Next>
->(function PaginationNext(
-  { overStyled = false, withLabel, icon, ...rest },
-  ref,
-) {
-  const sanitizedProps = filterStylingProps(rest, overStyled);
-  const computedIcon = withLabel ? NextWithLabel : undefined;
-  return (
-    <MantinePagination.Next
-      ref={ref}
-      {...sanitizedProps}
-      data-variant="text"
-      icon={withCallerOverride(computedIcon, icon) as any}
-    />
-  );
-});
-_PaginationNext.displayName = "Pagination.Next";
-
-const _PaginationPrevious = forwardRef<
-  HTMLButtonElement,
-  PaginationEdgeProps<typeof MantinePagination.Previous>
->(function PaginationPrevious(
-  { overStyled = false, withLabel, icon, ...rest },
-  ref,
-) {
-  const sanitizedProps = filterStylingProps(rest, overStyled);
-  const computedIcon = withLabel ? PrevWithLabel : undefined;
-  return (
-    <MantinePagination.Previous
-      ref={ref}
-      {...sanitizedProps}
-      data-variant="text"
-      icon={withCallerOverride(computedIcon, icon) as any}
-    />
-  );
-});
-_PaginationPrevious.displayName = "Pagination.Previous";
+type ButtonElementProps = Omit<
+  React.ComponentPropsWithoutRef<"button">,
+  "style" | "className"
+> &
+  Pick<ButtonProps, "overStyled">;
 
-const _PaginationFirst = forwardRef<
-  HTMLButtonElement,
-  PaginationEdgeProps<typeof MantinePagination.First>
->(function PaginationFirst(
-  { overStyled = false, withLabel, icon, ...rest },
-  ref,
-) {
-  const sanitizedProps = filterStylingProps(rest, overStyled);
-  const computedIcon = withLabel ? FirstWithLabel : undefined;
-  return (
-    <MantinePagination.First
-      ref={ref}
-      {...sanitizedProps}
-      data-variant="text"
-      icon={withCallerOverride(computedIcon, icon) as any}
-    />
-  );
-});
-_PaginationFirst.displayName = "Pagination.First";
+export type PaginationControlProps = RecursicaOverStyled<
+  ButtonElementProps & {
+    /** Whether this is the active page: uses the manifest's `active-pages` Button variant. */
+    active?: boolean;
+  }
+>;
 
-const _PaginationLast = forwardRef<
+const _PaginationControl = forwardRef<
   HTMLButtonElement,
-  PaginationEdgeProps<typeof MantinePagination.Last>
->(function PaginationLast(
-  { overStyled = false, withLabel, icon, ...rest },
-  ref,
-) {
-  const sanitizedProps = filterStylingProps(rest, overStyled);
-  const computedIcon = withLabel ? LastWithLabel : undefined;
+  PaginationControlProps
+>(function PaginationControl({ active = false, disabled, ...rest }, ref) {
+  const ctx = usePaginationContext();
+  const activeRole = usePaginationRole("active-pages");
+  const inactiveRole = usePaginationRole("inactive-pages");
+  const role = active ? activeRole : inactiveRole;
   return (
-    <MantinePagination.Last
+    <Button
       ref={ref}
-      {...sanitizedProps}
-      data-variant="text"
-      icon={withCallerOverride(computedIcon, icon) as any}
+      variant={role.variant}
+      size={role.size}
+      disabled={disabled || ctx.disabled}
+      aria-current={active ? "page" : undefined}
+      {...(rest as ButtonProps)}
     />
   );
 });
-_PaginationLast.displayName = "Pagination.Last";
-
-const _Pagination = forwardRef<HTMLDivElement, PaginationProps>(
-  function Pagination(
-    { overStyled = false, getControlProps, withLabels, ...rest },
-    ref,
-  ) {
-    const sanitizedProps = filterStylingProps(rest, overStyled);
-    const stylingParams = usePaginationClassNames(
-      sanitizedProps as Record<string, unknown>,
-    );
-
-    const mergedGetControlProps = (
-      control: "first" | "previous" | "last" | "next",
-    ) => {
-      const baseProps = { "data-variant": "text" };
-      if (getControlProps) {
-        return { ...baseProps, ...getControlProps(control) };
-      }
-      return baseProps;
-    };
+_PaginationControl.displayName = "Pagination.Control";
 
-    const labelsIcons = withLabels
-      ? {
-          nextIcon: NextWithLabel,
-          previousIcon: PrevWithLabel,
-          firstIcon: FirstWithLabel,
-          lastIcon: LastWithLabel,
-        }
-      : {};
+export type PaginationDotsProps = React.ComponentPropsWithoutRef<"div"> & {
+  icon?: React.ReactNode;
+};
 
+const _PaginationDots = forwardRef<HTMLDivElement, PaginationDotsProps>(
+  function PaginationDots({ icon, ...rest }, ref) {
+    const { size } = usePaginationRole("inactive-pages");
     return (
-      <MantinePagination
-        ref={ref}
-        {...labelsIcons}
-        {...(sanitizedProps as MantinePaginationProps)}
-        className={stylingParams.className}
-        classNames={stylingParams.classNames}
-        getControlProps={mergedGetControlProps}
-      />
+      <div ref={ref} className={styles.dots} data-size={size} {...rest}>
+        {icon ?? "…"}
+      </div>
     );
   },
 );
-_Pagination.displayName = "Pagination";
-
-export type PaginationControlProps =
-  RecursicaOverStyled<MantinePaginationControlProps>;
+_PaginationDots.displayName = "Pagination.Dots";
 
-const _PaginationControl = forwardRef<
-  HTMLButtonElement,
-  PaginationControlProps
->(function PaginationControl({ overStyled = false, ...rest }, ref) {
-  const sanitizedProps = filterStylingProps(rest, overStyled);
+function PaginationItems() {
+  const ctx = usePaginationContext();
   return (
-    <MantinePagination.Control
-      ref={ref}
-      {...(sanitizedProps as unknown as MantinePaginationControlProps)}
-    />
+    <>
+      {ctx.range.map((page, index) =>
+        page === "dots" ? (
+          <_PaginationDots key={index} icon={ctx.dotsIcon} />
+        ) : (
+          <_PaginationControl
+            key={index}
+            active={page === ctx.active}
+            aria-label={`Page ${page}`}
+            onClick={() => ctx.setPage(page)}
+            {...ctx.getItemProps?.(page)}
+          >
+            {(ctx.getItemProps?.(page)?.children as React.ReactNode) ?? page}
+          </_PaginationControl>
+        ),
+      )}
+    </>
   );
-});
-_PaginationControl.displayName = "Pagination.Control";
+}
+PaginationItems.displayName = "Pagination.Items";
 
-export type PaginationDotsProps =
-  RecursicaOverStyled<MantinePaginationDotsProps>;
+export type PaginationEdgeProps = RecursicaOverStyled<
+  Omit<ButtonElementProps, "children" | "rightSection"> & {
+    /** If set to true, displays text labels alongside the icon. */
+    withLabel?: boolean;
+    icon?: React.ReactNode;
+  }
+>;
 
-const _PaginationDots = forwardRef<HTMLDivElement, PaginationDotsProps>(
-  function PaginationDots({ overStyled = false, ...rest }, ref) {
-    const sanitizedProps = filterStylingProps(rest, overStyled);
+const NAV_ARIA_LABEL: Record<NavControl, string> = {
+  first: "First page",
+  previous: "Previous page",
+  next: "Next page",
+  last: "Last page",
+};
+
+const NAV_LABEL: Record<NavControl, string> = {
+  first: "First",
+  previous: "Prev",
+  next: "Next",
+  last: "Last",
+};
+
+function createNavControl(
+  control: NavControl,
+  iconType: "first" | "prev" | "next" | "last",
+  iconAfterLabel: boolean,
+  displayName: string,
+) {
+  const Component = forwardRef<HTMLButtonElement, PaginationEdgeProps>(
+    function PaginationNav({ withLabel, icon, disabled, ...rest }, ref) {
+      const ctx = usePaginationContext();
+      const role = usePaginationRole("navigation-controls");
+      const atStart = ctx.active === 1;
+      const atEnd = ctx.active === ctx.total;
+      const isDisabled =
+        disabled ||
+        ctx.disabled ||
+        ((control === "first" || control === "previous") && atStart) ||
+        ((control === "next" || control === "last") && atEnd);
+      const iconElement = icon ?? <PaginationIcon type={iconType} />;
+      const sections = withLabel
+        ? iconAfterLabel
+          ? {
+              rightSection: (
+                <span className={styles.rightIcon}>{iconElement}</span>
+              ),
+            }
+          : { icon: iconElement }
+        : { icon: iconElement };
+      return (
+        <Button
+          ref={ref}
+          variant={role.variant}
+          size={role.size}
+          aria-label={NAV_ARIA_LABEL[control]}
+          disabled={isDisabled}
+          onClick={ctx[control]}
+          {...({
+            ...sections,
+            ...ctx.getControlProps?.(control),
+            ...rest,
+          } as ButtonProps)}
+        >
+          {withLabel ? NAV_LABEL[control] : undefined}
+        </Button>
+      );
+    },
+  );
+  Component.displayName = displayName;
+  return Component;
+}
+
+const _PaginationFirst = createNavControl(
+  "first",
+  "first",
+  false,
+  "Pagination.First",
+);
+const _PaginationPrevious = createNavControl(
+  "previous",
+  "prev",
+  false,
+  "Pagination.Previous",
+);
+const _PaginationNext = createNavControl(
+  "next",
+  "next",
+  true,
+  "Pagination.Next",
+);
+const _PaginationLast = createNavControl(
+  "last",
+  "last",
+  true,
+  "Pagination.Last",
+);
+
+export type PaginationProps = RecursicaOverStyled<
+  RecursicaPaginationProps &
+    PaginationBaseProps &
+    Omit<React.ComponentPropsWithoutRef<"nav">, "onChange" | "children">
+>;
+
+const _Pagination = forwardRef<HTMLElement, PaginationProps>(
+  function Pagination(
+    { withEdges, withControls = true, withLabels, ...rest },
+    ref,
+  ) {
     return (
-      <MantinePagination.Dots
-        ref={ref}
-        {...(sanitizedProps as unknown as MantinePaginationDotsProps)}
-      />
+      <_PaginationRoot ref={ref} {...(rest as PaginationRootProps)}>
+        {withEdges && <_PaginationFirst withLabel={withLabels} />}
+        {withControls && <_PaginationPrevious withLabel={withLabels} />}
+        <PaginationItems />
+        {withControls && <_PaginationNext withLabel={withLabels} />}
+        {withEdges && <_PaginationLast withLabel={withLabels} />}
+      </_PaginationRoot>
     );
   },
 );
-_PaginationDots.displayName = "Pagination.Dots";
+_Pagination.displayName = "Pagination";
 
 /**
- * Recursica Pagination component wrapping Mantine's Pagination.
+ * Recursica Pagination. Its page and navigation buttons are Recursica `Button`s whose style and
+ * size come from the manifest's `ui-kit.components.pagination` selected variants. Requires the
+ * `manifest` prop on `RecursicaThemeProvider`.
  */
 export const Pagination = _Pagination as typeof _Pagination & {
   Root: typeof _PaginationRoot;
-  Items: typeof MantinePagination.Items;
+  Items: typeof PaginationItems;
   Control: typeof _PaginationControl;
   Dots: typeof _PaginationDots;
   Next: typeof _PaginationNext;
@@ -252,10 +386,7 @@ export const Pagination = _Pagination as typeof _Pagination & {
 };
 
 Pagination.Root = _PaginationRoot;
-// Pagination.Items has no styling props of its own (just a `dotsIcon` prop, no
-// `style`/`className`/BoxProps), so re-exporting Mantine's implementation
-// directly is not a styling-gate gap.
-Pagination.Items = MantinePagination.Items;
+Pagination.Items = PaginationItems;
 Pagination.Control = _PaginationControl;
 Pagination.Dots = _PaginationDots;
 Pagination.Next = _PaginationNext;

package/src/components/Pagination/USAGE.md

@@ -31,6 +31,7 @@ All Recursica components in the `@recursica/adapter-mantine-v8` package adhere s
 
 > [!IMPORTANT]
 >
+> - **Requires the manifest**: Pagination reads which Button `style` and `size` to use for its pages and navigation controls from the Forge manifest, so `RecursicaThemeProvider` must be given `manifest={manifest}` (the parsed `recursica_manifest.json`). It throws without it. See [SETUP.md](../../../SETUP.md).
 > - **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.

package/src/components/Stack/USAGE.md

@@ -36,10 +36,11 @@ All Recursica components in the `@recursica/adapter-mantine-v8` package adhere s
 
 > [!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.
 
+> [!NOTE] > **Responsive props use your Mantine theme's breakpoints, not Forge's.** Keys such as `{ base, sm, md }` come from `theme.breakpoints`; Forge's layout grids switch via plain CSS `@media` and never edit the Mantine theme. Build your theme with `breakpointsFromRecManifest` so the two agree (see [LayoutGrid](../LayoutGrid/USAGE.md)).
+
 ---
 
 ## 4. Key Integration Features & Constraints

package/src/components/index.ts

@@ -23,7 +23,7 @@ export * from "./FileUpload/FileUpload";
 export type { RecursicaFileUploadProps } from "./FileUpload/FileUpload";
 export * from "./Flex/Flex";
 export * from "./FormControlLayout/FormControlLayout";
-export * from "./Grid/Grid";
+export * from "./LayoutGrid/LayoutGrid";
 export * from "./Group/Group";
 export * from "./Heading/Heading";
 export * from "./HoverCard/HoverCard";

package/src/index.ts

@@ -1,3 +1,4 @@
 import "@recursica/adapter-common/style.css";
 
 export * from "./components";
+export * from "./utils/breakpointsFromRecManifest";

package/src/utils/breakpointsFromRecManifest.test.ts

@@ -0,0 +1,40 @@
+import { describe, it, expect } from "vitest";
+import { breakpointsFromRecManifest } from "./breakpointsFromRecManifest";
+
+const grid = (width: Record<string, number>) =>
+  Object.fromEntries(Object.entries(width).map(([k, v]) => [k, { $value: v }]));
+
+describe("breakpointsFromRecManifest", () => {
+  it("starts each grid at its min-width and places default after the widest max-width", () => {
+    const manifest = {
+      brand: {
+        "layout-grids": {
+          default: {},
+          mobile: grid({ "max-width": 480 }),
+          tablet: grid({ "min-width": 481, "max-width": 780 }),
+        },
+      },
+    };
+    expect(breakpointsFromRecManifest(manifest)).toEqual({
+      mobile: "0px",
+      tablet: "481px",
+      default: "781px",
+    });
+  });
+
+  it("returns an empty object when default is the only grid", () => {
+    expect(
+      breakpointsFromRecManifest({
+        brand: { "layout-grids": { default: {} } },
+      }),
+    ).toEqual({});
+  });
+
+  it("throws for a non-default grid with no width", () => {
+    expect(() =>
+      breakpointsFromRecManifest({
+        brand: { "layout-grids": { default: {}, odd: {} } },
+      }),
+    ).toThrow(/neither min-width nor max-width/);
+  });
+});