@recursica/adapter-mui-v7 1.0.0

package/src/components/NumberInput/NumberInput.stories.tsx

@@ -0,0 +1,96 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { NumberInput } from "./NumberInput";
+
+const meta: Meta<typeof NumberInput> = {
+  title: "UI-Kit/NumberInput",
+  component: NumberInput,
+  tags: ["autodocs"],
+  argTypes: {
+    label: { control: "text" },
+    assistiveText: { control: "text" },
+    disabled: { control: "boolean" },
+    error: { control: "boolean" },
+    readOnly: { control: "boolean" },
+    required: { control: "boolean" },
+    hideControls: { control: "boolean" },
+    formLayout: {
+      control: "select",
+      options: ["stacked", "side-by-side"],
+    },
+    labelSize: {
+      control: "select",
+      options: ["small", "default", "large"],
+    },
+    assistiveWithIcon: { table: { disable: true } },
+    labelOptionalText: { table: { disable: true } },
+    labelWithEditIcon: { table: { disable: true } },
+    onLabelEditClick: { table: { disable: true } },
+    emptyValueComponent: { table: { disable: true } },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof NumberInput>;
+
+export const Default: Story = {
+  args: {
+    label: "Amount",
+    placeholder: "Enter an amount",
+    assistiveText: "Must be greater than 0",
+    defaultValue: 10,
+    min: 0,
+    max: 100,
+  },
+};
+
+export const SideBySideLayout: Story = {
+  args: {
+    ...Default.args,
+    formLayout: "side-by-side",
+  },
+};
+
+export const States: Story = {
+  render: () => (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "1rem",
+        maxWidth: 400,
+      }}
+    >
+      <NumberInput label="Default" placeholder="Enter a number" />
+      <NumberInput label="Disabled" placeholder="Disabled input" disabled />
+      <NumberInput label="Error" placeholder="Error state" error />
+      <NumberInput label="Read Only" value={42} readOnly />
+      <NumberInput label="Required" required />
+    </div>
+  ),
+};
+
+export const WithLeftIcon: Story = {
+  args: {
+    label: "Price",
+    placeholder: "0.00",
+    leftSection: <span>$</span>,
+  },
+};
+
+export const WithRightIcon: Story = {
+  args: {
+    label: "Percentage",
+    placeholder: "0",
+    rightSection: <span>%</span>,
+    hideControls: true, // Typically hiding controls if rightSection is occupied
+  },
+};
+
+export const HiddenControls: Story = {
+  args: {
+    label: "Zip Code",
+    placeholder: "Enter zip code",
+    hideControls: true,
+  },
+};

package/src/components/NumberInput/NumberInput.test.tsx

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

package/src/components/NumberInput/NumberInput.tsx

@@ -0,0 +1,273 @@
+import React, { forwardRef, useCallback } from "react";
+import { InputBase, type InputBaseProps } from "@mui/material";
+import { type ReadOnlyControlProps } from "@recursica/adapter-common";
+import {
+  filterStylingProps,
+  omitUnsupportedProps,
+  mergeClassNames,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import { type RecursicaFormControlWrapperProps } from "../FormControlWrapper/FormControlWrapper";
+import { WithReadOnlyWrapper } from "../ReadOnlyField/WithReadOnlyWrapper";
+import styles from "./NumberInput.module.css";
+
+import { type RecursicaNumberInputProps as BaseRecursicaNumberInputProps } from "@recursica/adapter-common";
+
+export interface RecursicaNumberInputProps
+  extends Omit<
+      InputBaseProps,
+      | "color"
+      | "size"
+      | "startAdornment"
+      | "endAdornment"
+      | "autoComplete"
+      | "error"
+    >,
+    Pick<
+      RecursicaFormControlWrapperProps,
+      | "label"
+      | "error"
+      | "required"
+      | "id"
+      | "assistiveText"
+      | "assistiveWithIcon"
+      | "formLayout"
+      | "labelSize"
+      | "labelAlignment"
+      | "labelOptionalText"
+      | "labelWithEditIcon"
+      | "onLabelEditClick"
+    >,
+    ReadOnlyControlProps,
+    BaseRecursicaNumberInputProps {}
+
+export type NumberInputProps = RecursicaOverStyled<RecursicaNumberInputProps>;
+
+// Props this component intentionally doesn't support — deleted at runtime so they can't leak
+// through even if a caller forces them via plain JavaScript, bypassing the `Omit<>` above.
+const UNSUPPORTED_PROPS = [
+  "size", // Recursica controls sizing via design tokens, not MUI's native small/medium size
+  "color", // Colors are token-driven; MUI's native palette isn't exposed
+] as const satisfies readonly (keyof InputBaseProps)[];
+
+// Keys a plain, non-destructive keystroke always passes through (navigation, editing, shortcuts).
+const NON_CHARACTER_KEYS = new Set([
+  "Backspace",
+  "Delete",
+  "Tab",
+  "Escape",
+  "Enter",
+  "ArrowLeft",
+  "ArrowRight",
+  "ArrowUp",
+  "ArrowDown",
+  "Home",
+  "End",
+]);
+
+/**
+ * Restricts keystrokes to what a numeric value can legally contain — digits, a single decimal
+ * point, and (when negative values are allowed) a single leading minus sign. Mirrors Mantine's
+ * `NumberInput`, which parses/rejects non-numeric characters internally; MUI's `InputBase` has
+ * no such behavior built in, so it has to be reimplemented here.
+ */
+function isAllowedNumericKeystroke(
+  event: React.KeyboardEvent<HTMLInputElement>,
+  allowNegative: boolean,
+): boolean {
+  if (event.ctrlKey || event.metaKey || event.altKey) return true;
+  if (NON_CHARACTER_KEYS.has(event.key)) return true;
+  if (/^[0-9]$/.test(event.key)) return true;
+
+  const target = event.currentTarget;
+  if (event.key === "." && !target.value.includes(".")) return true;
+  if (
+    allowNegative &&
+    event.key === "-" &&
+    target.selectionStart === 0 &&
+    !target.value.includes("-")
+  ) {
+    return true;
+  }
+
+  return false;
+}
+
+export const NumberInput = forwardRef<HTMLInputElement, NumberInputProps>(
+  function NumberInput(props, ref) {
+    const {
+      overStyled = false,
+      formLayout = "stacked",
+
+      // Label & Wrapper Maps
+      labelSize,
+      labelAlignment,
+      labelOptionalText,
+      labelWithEditIcon,
+      onLabelEditClick,
+
+      label,
+      assistiveText,
+      assistiveWithIcon,
+      error,
+      required,
+      id,
+      className,
+      style,
+      disabled,
+      readOnly,
+      readOnlyComponent,
+      emptyValueComponent,
+      value,
+      defaultValue,
+      leftSection,
+      rightSection,
+      min,
+      max,
+      step,
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      hideControls = false,
+      ...rest
+    } = props;
+
+    const sanitizedProps = omitUnsupportedProps(
+      filterStylingProps(rest, overStyled),
+      UNSUPPORTED_PROPS,
+    );
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    // Securely map core native blocks down ensuring nested CSS modules map precisely. The
+    // caller-facing "root"/"input" slot names (MUI's own InputBase `classes` shape) are
+    // translated to this component's internal "wrapper"/"input" naming below.
+    const callerClasses = restRecord.classes as
+      | Partial<Record<string, string>>
+      | undefined;
+    const mergedClassNames = mergeClassNames(
+      {
+        wrapper: styles.root, // The nested Input internal relative wrapper bounding box
+        input: styles.input,
+        section: styles.section,
+        controls: styles.controls,
+        control: styles.control,
+      },
+      callerClasses && {
+        wrapper: callerClasses.root,
+        input: callerClasses.input,
+      },
+    );
+
+    const wrapperClass = className
+      ? `${styles.layoutOverride} ${className}`
+      : styles.layoutOverride;
+
+    const startAdornment = leftSection ? (
+      <div className={mergedClassNames.section} data-position="left">
+        {leftSection}
+      </div>
+    ) : undefined;
+
+    const endAdornment = rightSection ? (
+      <div className={mergedClassNames.section} data-position="right">
+        {rightSection}
+      </div>
+    ) : undefined;
+
+    // Mantine's NumberInput refuses a leading "-" once `min` rules out negative values; mirror
+    // that here since it also drives what a keystroke is allowed to produce.
+    const allowNegative = min === undefined || min < 0;
+
+    const handleKeyDown = useCallback(
+      (event: React.KeyboardEvent<HTMLInputElement>) => {
+        if (!isAllowedNumericKeystroke(event, allowNegative)) {
+          event.preventDefault();
+        }
+        (
+          restRecord.onKeyDown as
+            | React.KeyboardEventHandler<HTMLInputElement>
+            | undefined
+        )?.(event);
+      },
+      [allowNegative, restRecord.onKeyDown],
+    );
+
+    const handlePaste = useCallback(
+      (event: React.ClipboardEvent<HTMLInputElement>) => {
+        const pasted = event.clipboardData.getData("text");
+        const pattern = allowNegative
+          ? /^-?[0-9]*\.?[0-9]*$/
+          : /^[0-9]*\.?[0-9]*$/;
+        if (!pattern.test(pasted)) {
+          event.preventDefault();
+        }
+        (
+          restRecord.onPaste as
+            | React.ClipboardEventHandler<HTMLInputElement>
+            | undefined
+        )?.(event);
+      },
+      [allowNegative, restRecord.onPaste],
+    );
+
+    return (
+      <WithReadOnlyWrapper
+        className={wrapperClass}
+        style={style as React.CSSProperties}
+        controlMaxWidth="var(--number-input-control-max-width)"
+        controlMinWidth="var(--number-input-control-min-width)"
+        overStyled={overStyled as true}
+        formLayout={formLayout}
+        labelSize={labelSize}
+        labelAlignment={labelAlignment}
+        labelOptionalText={labelOptionalText}
+        labelWithEditIcon={labelWithEditIcon}
+        onLabelEditClick={onLabelEditClick}
+        label={label}
+        assistiveText={assistiveText}
+        assistiveWithIcon={assistiveWithIcon}
+        error={error}
+        required={required}
+        id={id}
+        readOnly={readOnly}
+        readOnlyComponent={readOnlyComponent}
+        emptyValueComponent={emptyValueComponent}
+        readOnlyType="text"
+        readOnlyValue={
+          value !== undefined ? value?.toString() : defaultValue?.toString()
+        }
+        readOnlyNativeProps={props}
+        activeComponent={
+          /* Naked Input execution safely decoupled from Mui's macro Input.Wrapper DOM hooks */
+          <InputBase
+            inputRef={ref}
+            {...(sanitizedProps as unknown as InputBaseProps)}
+            classes={{
+              root: mergedClassNames.wrapper,
+              input: mergedClassNames.input,
+            }}
+            disabled={disabled}
+            value={value}
+            defaultValue={defaultValue}
+            startAdornment={startAdornment}
+            endAdornment={endAdornment}
+            inputMode="decimal"
+            onKeyDown={handleKeyDown}
+            onPaste={handlePaste}
+            inputProps={{
+              min,
+              max,
+              step,
+              ...(restRecord.inputProps as Record<string, unknown>),
+            }}
+            // Bind native CSS selectors for errors / adornments explicitly to the root boundary
+            data-disabled={disabled ? "true" : undefined}
+            data-error={error ? "true" : undefined}
+            data-with-left-section={leftSection ? "true" : undefined}
+            data-with-right-section={rightSection ? "true" : undefined}
+          />
+        }
+      />
+    );
+  },
+);
+
+NumberInput.displayName = "NumberInput";

package/src/components/NumberInput/USAGE.md

@@ -0,0 +1,36 @@
+# NumberInput - Usage Guide
+
+This document describes how to integrate and use the `NumberInput` component in your projects using `@recursica/adapter-mui-v7`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { NumberInput } from "@recursica/adapter-mui-v7";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { NumberInput } from "@recursica/adapter-mui-v7";
+
+export default function Demo() {
+  return <NumberInput label="Quantity" min={1} max={10} defaultValue={1} />;
+}
+```
+
+---
+
+## 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/NumberInput/index.ts

@@ -0,0 +1 @@
+export * from "./NumberInput";

package/src/components/Pagination/IMPLEMENTATION_NOTES.md

@@ -0,0 +1,40 @@
+# Pagination Implementation Notes
+
+- **Compositional API Dropped:** Mantine's original `Pagination` component relies heavily on dot-notation sub-components (`Pagination.Root`, `Pagination.Items`, `Pagination.Control`, etc.). MUI's `<Pagination>` is fundamentally monolithic. Following architectural review, we have decided to drop the dot-notation wrappers for `adapter-mui-v7` and rely strictly on MUI's monolithic API. Storybook and visual regression tests have been updated to reflect this divergence while retaining core property mapping compatibility.
+
+## `renderItem` was never wired up (source-of-truth audit, 2026-08-30)
+
+`Pagination.module.css` already had complete, correctly-tokenized rules for `.control` (the
+circle/pill for every page/nav item), `.dots` (the ellipsis), `.iconWithLabel`, and `.baseIcon` —
+and `Pagination.icons.tsx` already had `PaginationIcon` plus `NextWithLabel`/`PrevWithLabel`/
+`FirstWithLabel`/`LastWithLabel` fully built. None of it was ever applied: `Pagination.tsx` only
+mapped MUI `Pagination`'s top-level `classes` prop (`root`/`ul` — the _only_ two slots MUI's own
+`Pagination` component exposes) and silently discarded the `withLabels` prop entirely. Every
+page/nav button rendered as MUI's own completely unstyled default `PaginationItem` — explaining
+the whole cluster of reported issues at once: undersized circles (no `.control` height/width),
+grey selected state and missing outline (no `.control`/`[data-active]` colors), wrong font color,
+default MUI arrow icons in the wrong color (no `PaginationIcon`), default ripple (MUI's
+`PaginationItem` uses `ButtonBase` with ripple enabled by default), and no text labels ever
+possible (`withLabels` was read and thrown away).
+
+**Fix:** `Pagination.tsx` now passes a `renderItem` to `MuiPagination` that renders every item as
+`<PaginationItem className={styles.control} data-active={item.selected} data-variant={isNavigation
+? "text" : undefined} disableRipple slots={...} />` (ellipsis items get `styles.dots` instead).
+`slots.first/last/next/previous` point at `PaginationIcon` (plain) or the `*WithLabel` components
+(when `withLabels` is true) — both were already correctly built to work as MUI `PaginationItem`
+icon slots (only the icon itself receives MUI's forwarded className/props via `{...props}` spread
+onto the inner `PaginationIcon`, not the outer label-wrapping `<div>`, so the label text isn't
+constrained by MUI's icon-sized styled wrapper).
+
+Also added a local `--pagination-control-size` bridge variable (bound to the Button height token
+`.control` is already sized from) — `.baseIcon`'s `calc(var(--pagination-control-size) / 1.8)`
+was copied verbatim from mantine-adapter, where `--pagination-control-size` is a _native_ Mantine
+CSS variable Mantine's own `Pagination` stamps onto the DOM already; MUI has no equivalent, so
+the calc silently resolved to `NaN`/`0` here until this bridge was added.
+
+**Residual, not fixed:** the previous/next chevron control renders ~3.8px wider in mantine
+(51.8px vs. mui's exact 48px square) — mantine's own icon-only nav button apparently doesn't
+collapse fully to `min-width` the way mui's `PaginationItem` does. Pixel-matched everywhere else
+(page-number circle size/color/border, selected state, ellipsis centering, chevron colors, hover
+treatment, ripple removal, text labels) — not investigated further given the small, cosmetic
+scope of this one remaining gap.

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

@@ -0,0 +1,66 @@
+import styles from "./Pagination.module.css";
+
+const NextPath =
+  "M8.781 8l-3.3-3.3.943-.943L10.667 8l-4.243 4.243-.943-.943 3.3-3.3z";
+const PrevPath =
+  "M7.219 8l3.3 3.3-.943.943L5.333 8l4.243-4.243.943.943-3.3 3.3z";
+const FirstPath =
+  "M6.85355 3.85355C7.04882 3.65829 7.04882 3.34171 6.85355 3.14645C6.65829 2.95118 6.34171 2.95118 6.14645 3.14645L2.14645 7.14645C1.95118 7.34171 1.95118 7.65829 2.14645 7.85355L6.14645 11.8536C6.34171 12.0488 6.65829 12.0488 6.85355 11.8536C7.04882 11.6583 7.04882 11.3417 6.85355 11.1464L3.20711 7.5L6.85355 3.85355ZM12.8536 3.85355C13.0488 3.65829 13.0488 3.34171 12.8536 3.14645C12.6583 2.95118 12.3417 2.95118 12.1464 3.14645L8.14645 7.14645C7.95118 7.34171 7.95118 7.65829 8.14645 7.85355L12.1464 11.8536C12.3417 12.0488 12.6583 12.0488 12.8536 11.8536C13.0488 11.6583 13.0488 11.3417 12.8536 11.1464L9.20711 7.5L12.8536 3.85355Z";
+const LastPath =
+  "M2.14645 11.1464C1.95118 11.3417 1.95118 11.6583 2.14645 11.8536C2.34171 12.0488 2.65829 12.0488 2.85355 11.8536L6.85355 7.85355C7.04882 7.65829 7.04882 7.34171 6.85355 7.14645L2.85355 3.14645C2.65829 2.95118 2.34171 2.95118 2.14645 3.14645C1.95118 3.34171 1.95118 3.65829 2.14645 3.85355L5.79289 7.5L2.14645 11.1464ZM8.14645 11.1464C7.95118 11.3417 7.95118 11.6583 8.14645 11.8536C8.34171 12.0488 8.65829 12.0488 8.85355 11.8536L12.8536 7.85355C13.0488 7.65829 13.0488 7.34171 12.8536 7.14645L8.85355 3.14645C8.65829 2.95118 8.34171 2.95118 8.14645 3.14645C7.95118 3.34171 7.95118 3.65829 8.14645 3.85355L11.7929 7.5L8.14645 11.1464Z";
+
+export type PaginationIconType = "next" | "prev" | "first" | "last";
+
+const paths: Record<PaginationIconType, string> = {
+  next: NextPath,
+  prev: PrevPath,
+  first: FirstPath,
+  last: LastPath,
+};
+
+export const PaginationIcon = ({
+  type,
+  className,
+  ...props
+}: React.ComponentProps<"svg"> & { type: PaginationIconType }) => (
+  <svg
+    viewBox="0 0 16 16"
+    xmlns="http://www.w3.org/2000/svg"
+    className={`${styles.baseIcon} ${className || ""}`.trim()}
+    {...props}
+  >
+    <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>
+);