@recursica/adapter-mantine-v8 1.0.0

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

@@ -0,0 +1,188 @@
+/* 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
+ */
+
+.root {
+  display: flex;
+  align-items: center;
+  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;
+  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
+  );
+}
+
+/* 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
+  );
+  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
+    );
+}
+
+/* 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
+  );
+}
+
+/* Icon Styles */
+.iconWithLabel {
+  display: flex;
+  align-items: center;
+  gap: var(
+    --recursica_ui-kit_components_button_variants_sizes_default_properties_icon-text-gap
+  );
+}
+
+.baseIcon {
+  width: calc(var(--pagination-control-size) / 1.8);
+  height: calc(var(--pagination-control-size) / 1.8);
+}

package/src/components/Pagination/Pagination.stories.tsx

@@ -0,0 +1,48 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Pagination } from "./Pagination";
+
+const meta: Meta<typeof Pagination> = {
+  title: "UI-Kit/Pagination",
+  component: Pagination,
+  tags: ["autodocs"],
+  argTypes: {
+    total: { control: "number" },
+    withEdges: { control: "boolean" },
+    withControls: { control: "boolean" },
+    disabled: { control: "boolean" },
+    withLabels: {
+      control: "boolean",
+      description: "Toggle text labels alongside icons",
+    },
+    defaultChecked: { table: { disable: true } },
+  },
+  args: {
+    total: 10,
+    withEdges: false,
+    withControls: true,
+    withLabels: false,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unused-vars
+  render: ({ withLayer, layer, ...args }: any) => {
+    return <Pagination {...args} />;
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Pagination>;
+
+export const Default: Story = {};
+
+export const WithEdges: Story = {
+  args: {
+    withEdges: true,
+  },
+};
+
+export const WithTextLabels: Story = {
+  args: {
+    withEdges: true,
+    withLabels: true,
+  },
+};

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

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

package/src/components/Pagination/Pagination.tsx

@@ -0,0 +1,265 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import React, { forwardRef } from "react";
+import {
+  Pagination as MantinePagination,
+  type PaginationProps as MantinePaginationProps,
+  type PaginationRootProps as MantinePaginationRootProps,
+  type PaginationControlProps as MantinePaginationControlProps,
+  type PaginationDotsProps as MantinePaginationDotsProps,
+} from "@mantine/core";
+import {
+  filterStylingProps,
+  withCallerOverride,
+  mergeClassNames,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Pagination.module.css";
+import {
+  NextWithLabel,
+  PrevWithLabel,
+  FirstWithLabel,
+  LastWithLabel,
+  PaginationIcon,
+} from "./Pagination.icons";
+
+import { type RecursicaPaginationProps } from "@recursica/adapter-common";
+
+export type PaginationProps = RecursicaOverStyled<
+  MantinePaginationProps & RecursicaPaginationProps
+>;
+
+export type PaginationRootProps =
+  RecursicaOverStyled<MantinePaginationRootProps>;
+
+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;
+    }
+  >;
+
+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,
+  );
+
+  const classNameProp = restRecord.className as string | undefined;
+  const finalClass = classNameProp
+    ? `${styles.root} ${classNameProp}`
+    : styles.root;
+
+  return { className: finalClass, classNames: mergedClassNames };
+}
+
+const _PaginationRoot = forwardRef<HTMLDivElement, PaginationRootProps>(
+  function PaginationRoot({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const stylingParams = usePaginationClassNames(
+      sanitizedProps as Record<string, unknown>,
+    );
+
+    return (
+      <MantinePagination.Root
+        ref={ref}
+        {...(sanitizedProps as MantinePaginationRootProps)}
+        className={stylingParams.className}
+        classNames={stylingParams.classNames}
+      />
+    );
+  },
+);
+_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";
+
+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";
+
+const _PaginationLast = forwardRef<
+  HTMLButtonElement,
+  PaginationEdgeProps<typeof MantinePagination.Last>
+>(function PaginationLast(
+  { overStyled = false, withLabel, icon, ...rest },
+  ref,
+) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const computedIcon = withLabel ? LastWithLabel : undefined;
+  return (
+    <MantinePagination.Last
+      ref={ref}
+      {...sanitizedProps}
+      data-variant="text"
+      icon={withCallerOverride(computedIcon, icon) as any}
+    />
+  );
+});
+_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;
+    };
+
+    const labelsIcons = withLabels
+      ? {
+          nextIcon: NextWithLabel,
+          previousIcon: PrevWithLabel,
+          firstIcon: FirstWithLabel,
+          lastIcon: LastWithLabel,
+        }
+      : {};
+
+    return (
+      <MantinePagination
+        ref={ref}
+        {...labelsIcons}
+        {...(sanitizedProps as MantinePaginationProps)}
+        className={stylingParams.className}
+        classNames={stylingParams.classNames}
+        getControlProps={mergedGetControlProps}
+      />
+    );
+  },
+);
+_Pagination.displayName = "Pagination";
+
+export type PaginationControlProps =
+  RecursicaOverStyled<MantinePaginationControlProps>;
+
+const _PaginationControl = forwardRef<
+  HTMLButtonElement,
+  PaginationControlProps
+>(function PaginationControl({ overStyled = false, ...rest }, ref) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  return (
+    <MantinePagination.Control
+      ref={ref}
+      {...(sanitizedProps as unknown as MantinePaginationControlProps)}
+    />
+  );
+});
+_PaginationControl.displayName = "Pagination.Control";
+
+export type PaginationDotsProps =
+  RecursicaOverStyled<MantinePaginationDotsProps>;
+
+const _PaginationDots = forwardRef<HTMLDivElement, PaginationDotsProps>(
+  function PaginationDots({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    return (
+      <MantinePagination.Dots
+        ref={ref}
+        {...(sanitizedProps as unknown as MantinePaginationDotsProps)}
+      />
+    );
+  },
+);
+_PaginationDots.displayName = "Pagination.Dots";
+
+/**
+ * Recursica Pagination component wrapping Mantine's Pagination.
+ */
+export const Pagination = _Pagination as typeof _Pagination & {
+  Root: typeof _PaginationRoot;
+  Items: typeof MantinePagination.Items;
+  Control: typeof _PaginationControl;
+  Dots: typeof _PaginationDots;
+  Next: typeof _PaginationNext;
+  Previous: typeof _PaginationPrevious;
+  First: typeof _PaginationFirst;
+  Last: typeof _PaginationLast;
+  Icon: typeof PaginationIcon;
+};
+
+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.Control = _PaginationControl;
+Pagination.Dots = _PaginationDots;
+Pagination.Next = _PaginationNext;
+Pagination.Previous = _PaginationPrevious;
+Pagination.First = _PaginationFirst;
+Pagination.Last = _PaginationLast;
+Pagination.Icon = PaginationIcon;

package/src/components/Pagination/USAGE.md

@@ -0,0 +1,36 @@
+# Pagination - Usage Guide
+
+This document describes how to integrate and use the `Pagination` component in your projects using `@recursica/adapter-mantine-v8`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Pagination } from "@recursica/adapter-mantine-v8";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Pagination } from "@recursica/adapter-mantine-v8";
+
+export default function Demo() {
+  return <Pagination total={10} value={activePage} onChange={setPage} />;
+}
+```
+
+---
+
+## 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.

package/src/components/Pagination/index.ts

@@ -0,0 +1,5 @@
+export {
+  Pagination,
+  type PaginationProps,
+  type PaginationRootProps,
+} from "./Pagination";

package/src/components/Panel/PANEL_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,116 @@
+# Panel – Implementation Notes
+
+Decisions and design tweaks strictly tailored for the UI Kit's Panel wrapped against `@mantine/core`. This is a living document that tracks _why_ specific logic decisions exist.
+
+---
+
+## 1. Mapping to Mantine Drawer
+
+**Decision:** Panel maps to Mantine's `Drawer` component, not `Paper` or `Card`.
+
+**Implementation:** Per the Recursica design system specification, "Panels slide in or expand from the edge of the screen to reveal additional content or functionality." This is the exact behavior of Mantine's `Drawer` component, which provides:
+
+- Slide-in animation from any screen edge
+- Overlay/backdrop
+- Portal rendering
+- Focus trapping
+- Scroll locking
+- Close button and title in header
+
+Paper and Card are static containers; Drawer is an overlay that matches Panel's defined behavior.
+
+---
+
+## 2. Token Namespace: `panel`
+
+**Decision:** The CSS module exclusively uses variables from the `--recursica_ui-kit_components_panel_*` namespace.
+
+**Implementation:** The Recursica token system defines the `panel` namespace covering:
+
+- Geometry: border-radius, border-size, min-width (200px), max-width (960px)
+- Content padding: content-horizontal-padding (xl), content-vertical-padding (lg)
+- Header/Footer padding: header-footer-horizontal-padding (xl), header-footer-vertical-padding (md)
+- Spacing: header-close-gap (md), footer-button-gap (md)
+- Divider: divider-size (1px), divider-color
+- Elevation: elevation-3
+- Colors (layer-aware): background, border-color, content, divider-color, header-footer-background, title
+- Non-CSS: header-style ("h3") — see §7
+
+No tokens from other component namespaces are referenced.
+
+---
+
+## 3. ClassNames Mapping to Drawer
+
+**Decision:** Panel maps CSS module classes to Mantine Drawer's stylesNames.
+
+**Implementation:** The Drawer stylesNames used are:
+
+- `content` — Outer container (background, border, elevation)
+- `header` — Title bar with close button (padding, divider, gap)
+- `title` — Title text color
+- `body` — Scrollable content area (padding)
+
+Other stylesNames (`overlay`, `root`, `inner`, `close`) are left to Mantine defaults.
+
+---
+
+## 4. Default Placement Override
+
+**Decision:** Use `placement` instead of `position` for configuring slide-out direction, and default it to `"right"`.
+
+**Implementation:** The prop was renamed from `position` to `placement` to prevent collision with the CSS `position` keyword, which is strictly blocked by the styling gatekeeper (`BLOCKED_STYLING_KEYS`). This allows configuring the drawer direction natively while maintaining strict design-system boundaries. The `placement="right"` default is mapped internally to Mantine Drawer's `position` prop before any other sanitized props are applied. Right-side panels are the most common pattern for supplementary content, settings, and detail views.
+
+---
+
+## 5. Custom Panel.Footer
+
+**Decision:** A custom `Panel.Footer` sub-component is provided. Mantine's Drawer does not have a native footer.
+
+**Implementation:** `Panel.Footer` is a `<div>` with inline styles referencing Recursica CSS variables for:
+
+- `header-footer-background` and `header-footer-padding` tokens
+- Top divider using `divider-size` and `divider-color`
+- `footer-button-gap` for action button spacing
+- `margin-top: auto` to push the footer to the bottom
+
+Inline styles are used instead of a CSS module class because the footer is rendered inside the Drawer's `<body>` element, and the CSS variables are applied to the body's parent container. The inline styles ensure the footer correctly references the panel tokens regardless of DOM position.
+
+---
+
+## 6. Hardcoded Values
+
+### `border-style: solid` (CSS module, `.content`)
+
+Mantine's Drawer content does not set `border-style` natively. Without this, the border-width and border-color tokens have no visible effect. Same pattern as Card, Menu, HoverCard, Tooltip.
+
+---
+
+## 7. `header-style` Typography Utility Class
+
+**Decision:** The `header-style` token exports as the string `"h3"`, so we use the generated global utility class `.recursica_brand_typography_h3`.
+
+**Implementation:** The PostCSS compiler generates `.recursica_brand_typography_<typeName>` classes at the bottom of the scoped variables file to apply full typography definitions without assigning variables inline. We apply this to the `.title` class via `composes: recursica_brand_typography_h3 from global;`.
+
+---
+
+## 8. Panel Types: Standard vs Scrollable
+
+**Decision:** Both standard and scrollable types are supported natively.
+
+**Implementation:** Per the Recursica specification:
+
+- **Standard** — All content visible without scrolling. The default behavior when content fits.
+- **Scrollable** — Internal scrollbar enabled when content exceeds the panel height. Header and footer CTAs remain pinned.
+
+Mantine's Drawer handles this automatically — the `body` section scrolls when content overflows, while the `header` remains fixed. The `Panel.Footer` uses `margin-top: auto` to stay at the bottom.
+
+---
+
+## `.titleTruncate` descender clipping (Matt Massey, 2026-08-28)
+
+`.titleTruncate` used plain `overflow: hidden` to make `text-overflow: ellipsis` work, which also
+clips descenders (e.g. the "g" in a long title) whenever `text_line-height` is tighter than the
+font's natural ascent+descent. Switched to `overflow: clip; overflow-clip-margin: 0.35em;` — same
+truncation, but ink can bleed slightly past the line box before it's actually clipped.
+Project-wide fix; see Chip's `CHIP_IMPLEMENTATION_NOTES.md` for the original discovery.