@recursica/adapter-mui-v7 1.0.0

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

@@ -0,0 +1,197 @@
+/* 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);
+
+  /* Mantine's own native Pagination CSS defines `--pagination-control-size` (their
+     internal size scale) on the DOM already, which mantine-adapter's `.baseIcon`
+     below reads directly. MUI has no equivalent variable, so it's bridged here to
+     the same Button height token `.control` itself is sized from, keeping the
+     chevron glyphs proportional to the actual rendered circle size. */
+  --pagination-control-size: var(
+    --recursica_ui-kit_components_button_variants_sizes_default_properties_height
+  );
+}
+
+.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,123 @@
+import { forwardRef, type ComponentProps } from "react";
+import {
+  Pagination as MuiPagination,
+  PaginationItem,
+  type PaginationProps as MuiPaginationProps,
+  type PaginationRenderItemParams,
+} from "@mui/material";
+import {
+  filterStylingProps,
+  mergeClassNames,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Pagination.module.css";
+import {
+  PaginationIcon,
+  NextWithLabel,
+  PrevWithLabel,
+  FirstWithLabel,
+  LastWithLabel,
+} from "./Pagination.icons";
+
+import { type RecursicaPaginationProps } from "@recursica/adapter-common";
+
+export type PaginationProps = RecursicaOverStyled<
+  MuiPaginationProps & RecursicaPaginationProps
+>;
+
+function usePaginationClassNames(restRecord: Record<string, unknown>): {
+  className: string;
+  classNames: Partial<Record<string, string>>;
+} {
+  const mergedClassNames = mergeClassNames(
+    { root: styles.root, ul: styles.ul },
+    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 };
+}
+
+// Plain (non-labeled) icon slots — MUI's own default `NavigateBefore`/`NavigateNext`/
+// `FirstPage`/`LastPage` icons never read our tokens, so every nav control is always
+// replaced with our own `PaginationIcon` regardless of `withLabels`.
+const iconSlots = {
+  next: (p: ComponentProps<"svg">) => <PaginationIcon {...p} type="next" />,
+  previous: (p: ComponentProps<"svg">) => <PaginationIcon {...p} type="prev" />,
+  first: (p: ComponentProps<"svg">) => <PaginationIcon {...p} type="first" />,
+  last: (p: ComponentProps<"svg">) => <PaginationIcon {...p} type="last" />,
+};
+
+const labeledIconSlots = {
+  next: NextWithLabel,
+  previous: PrevWithLabel,
+  first: FirstWithLabel,
+  last: LastWithLabel,
+};
+
+const _Pagination = forwardRef<HTMLDivElement, PaginationProps>(
+  function Pagination(props, ref) {
+    const {
+      overStyled = false,
+      withLabels = false,
+      total,
+      withEdges,
+      withControls,
+      ...rest
+    } = props;
+
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const stylingParams = usePaginationClassNames(
+      sanitizedProps as Record<string, unknown>,
+    );
+
+    const renderItem = (item: PaginationRenderItemParams) => {
+      if (item.type === "start-ellipsis" || item.type === "end-ellipsis") {
+        return <PaginationItem {...item} className={styles.dots} />;
+      }
+      const isNavigation = item.type !== "page";
+      // `disableRipple` is a genuine `ButtonBase` prop `PaginationItemPage` forwards
+      // at runtime, but MUI's own `PaginationItem` type declarations don't expose it
+      // (same category of MUI type-gap other components in this adapter cast around,
+      // e.g. `Card.tsx`/`Radio.tsx`'s `as unknown as MuiXProps`).
+      const itemProps: Record<string, unknown> = {
+        ...item,
+        disableRipple: true,
+        className: styles.control,
+        "data-active": item.selected || undefined,
+        "data-variant": isNavigation ? "text" : undefined,
+        slots: withLabels ? labeledIconSlots : iconSlots,
+      };
+      return (
+        <PaginationItem
+          {...(itemProps as unknown as ComponentProps<typeof PaginationItem>)}
+        />
+      );
+    };
+
+    return (
+      <div ref={ref} className={stylingParams.className}>
+        <MuiPagination
+          {...(sanitizedProps as MuiPaginationProps)}
+          count={total}
+          showFirstButton={withEdges}
+          showLastButton={withEdges}
+          hidePrevButton={withControls === false ? true : undefined}
+          hideNextButton={withControls === false ? true : undefined}
+          classes={stylingParams.classNames}
+          renderItem={renderItem}
+        />
+      </div>
+    );
+  },
+);
+_Pagination.displayName = "Pagination";
+
+/**
+ * Recursica Pagination component wrapping Mui's Pagination.
+ */
+export const Pagination = _Pagination;

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-mui-v7`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Pagination } from "@recursica/adapter-mui-v7";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Pagination } from "@recursica/adapter-mui-v7";
+
+export default function Demo() {
+  return <Pagination total={10} value={activePage} onChange={setPage} />;
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/adapter-mui-v7` 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 @@
+export * from "./Pagination";

package/src/components/Panel/PANEL_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,133 @@
+# Panel – Implementation Notes
+
+Decisions and design tweaks strictly tailored for the UI Kit's Panel wrapped against `@mui/material`. This is a living document that tracks _why_ specific logic decisions exist.
+
+---
+
+## 1. Mapping to MUI Drawer
+
+**Decision:** Panel maps to MUI'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 MUI's `Drawer` component, which provides:
+
+- Slide-in animation from any screen edge (using the `anchor` prop)
+- Backdrop/overlay support
+- Focus trap and overlay portal management
+- Internal scroll lock when open
+
+---
+
+## 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")
+
+No tokens from other component namespaces are referenced.
+
+---
+
+## 3. 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 MUI Drawer's `anchor` prop before any other sanitized props are applied. Right-side panels are the most common pattern for supplementary content, settings, and detail views.
+
+---
+
+## 4. Custom Panel.Footer
+
+**Decision:** A custom `Panel.Footer` sub-component is provided. MUI's Drawer does not have a native footer.
+
+**Implementation:** `Panel.Footer` is a `<div>` with styling 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
+
+---
+
+## 5. Visibility Mapping (`opened` -> `open`)
+
+**Decision:** Accept `opened` prop to match the standard Recursica component API.
+
+**Implementation:** MUI Drawer natively expects the `open` boolean prop. The wrapper maps the incoming framework-agnostic `opened` prop to MUI's `open={Boolean(opened)}`, allowing consistent usage across both adapter implementations.
+
+---
+
+## Panel covered the whole viewport with no header (Matt Massey, 2026-08-30)
+
+**Symptom:** `ui-kit-panel--default` rendered as an unstyled white box covering the entire
+viewport (full width and height, no border/radius/shadow, no dark overlay), with no header,
+title, or close button visible at all — not merely off-screen, never rendered.
+
+**Root cause:** Two compounding bugs, both from writing this component as if MUI's `Drawer`
+had Mantine's convenience API:
+
+1. `classes={{ content, header, title, body, inner }}` — MUI's `Drawer` `classes` prop only
+   recognizes its own slot names (`root`, `paper`, `docked`, `paperAnchorRight`, ...). It has no
+   `content`/`header`/`title`/`body`/`inner` slots the way Mantine's `classNames` does, so every
+   key in that object was silently ignored — none of this file's CSS Module classes were ever
+   attached to any DOM node. Confirmed via the rendered Paper's `className`: only MUI's own
+   default `MuiPaper-root MuiDrawer-paper MuiDrawer-paperAnchorRight` classes were present.
+2. `title`, `withOverlay`, `withCloseButton` were spread straight through onto `<MuiDrawer>` as
+   if it were Mantine's `<Drawer title="..." withCloseButton>`, which builds a Header/Title/
+   CloseButton internally from those props. MUI's `Drawer` has no such feature — it only takes
+   `children`. `title` landed as a plain HTML `title` (tooltip) attribute on the root div;
+   `withOverlay`/`withCloseButton` were dropped entirely (not valid DOM or Drawer props). No
+   header ever rendered.
+
+Both bugs together meant Paper had zero width/height/border constraints of its own (MUI's
+default temporary-variant Paper only fixes position, not size) and no header to visually anchor
+against — hence "covers the whole viewport."
+
+**Fix:** Rebuilt Panel the same way `Modal.tsx` builds its header/body/footer — as real JSX
+children of `<MuiDrawer>`, not through the `classes` prop:
+
+- `title`, `withOverlay`, `withCloseButton`, `onClose`, `children` are now destructured and used
+  directly: a manually-built `.header` div (title + close `IconButton`, only rendered when
+  `title` or `withCloseButton` is set) and `.body` div wrap the real children; `withOverlay`
+  maps to MUI's own `hideBackdrop={!withOverlay}`.
+- `classes` now only maps `paper` (MUI's actual slot) to a new `.paper` rule that zeroes out
+  Paper's own default background/box-shadow, so the box-model chrome (border, radius, shadow,
+  `min-width`/`max-width` bounds) lives entirely on the new `.content` wrapper div rendered
+  inside Paper — mirroring where Mantine's own `.content` slot sits (it wraps header/body
+  already), just as an explicit element instead of a slot name MUI doesn't have.
+- Added `display: flex` + `justify-content: space-between` to `.header` and a `.close` rule —
+  Mantine's own `Drawer.Header` is flex out of the box; this manually-built div needed it
+  declared. No dedicated close-button token namespace exists for Panel (Mantine's own Panel
+  doesn't style one either — it renders Mantine's plain default `CloseButton`), so `.close` only
+  sets `flex-shrink: 0` and reuses a plain `IconButton`.
+- Removed the `.inner { left: 0 }` rule — that was a Mantine-only positioning hack (`Drawer.Inner`
+  has no MUI equivalent; MUI's own `paperAnchorLeft`/`paperAnchorRight` classes already position
+  Paper correctly).
+
+Verified live in Storybook against `@recursica/mantine-adapter`'s Panel for `Default`,
+`LeftPlacement`, `ScrollableContent`, and `LongTitle` — header renders, close button works,
+title truncation and the sticky scrolling footer all behave correctly. Width is now bounded by
+`--recursica_ui-kit_components_panel_properties_min-width`/`max-width` (200–960px) via
+shrink-to-fit, same mechanism as Modal's `.content`; this is narrower/wider than mantine's own
+default rendered width in some stories, because Mantine's Panel CSS (identical file, shared
+copy) never added the `flex: 0 1 auto` override Mantine's own Modal has to make width
+content-driven instead of Mantine's fixed `--drawer-size` default — that's a source-of-truth-side
+gap, out of scope here.
+
+---
+
+## `.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.