@recursica/adapter-mui-v7 1.0.0

package/src/components/Chip/Chip.tsx

@@ -0,0 +1,168 @@
+import React, { forwardRef } from "react";
+import { Chip as MuiChip, type ChipProps as MuiChipProps } from "@mui/material";
+import {
+  filterStylingProps,
+  mergeClassNames,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Chip.module.css";
+
+import { type RecursicaChipProps } from "@recursica/adapter-common";
+
+export type ChipProps = RecursicaOverStyled<
+  Omit<MuiChipProps, "variant" | "size" | "color" | "radius" | "children"> &
+    RecursicaChipProps & {
+      // MUI's own ChipProps types `children` as `null | undefined` (MUI's Chip expects `label`
+      // instead) — this component's actual API is `children` (see the `label={...}` JSX below,
+      // which always wins over any caller-supplied `label` in `sanitizedProps`), so restore a
+      // real type for it here.
+      children?: React.ReactNode;
+    }
+>;
+
+function CloseIcon(props: React.ComponentPropsWithoutRef<"svg">) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      {...props}
+    >
+      <line x1="18" y1="6" x2="6" y2="18"></line>
+      <line x1="6" y1="6" x2="18" y2="18"></line>
+    </svg>
+  );
+}
+
+function CheckIcon(props: React.ComponentPropsWithoutRef<"svg">) {
+  return (
+    <svg
+      viewBox="0 0 10 7"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+    >
+      <path
+        d="M4 4.586L1.707 2.293A1 1 0 1 0 .293 3.707l3 3a.997.997 0 0 0 1.414 0l5-5A1 1 0 1 0 8.293.293L4 4.586z"
+        fill="currentColor"
+        fillRule="evenodd"
+        clipRule="evenodd"
+      />
+    </svg>
+  );
+}
+
+export const Chip = forwardRef<HTMLInputElement, ChipProps>(function Chip(
+  {
+    error = false,
+    icon,
+    onDelete,
+    deleteLabel = "Delete",
+    deleteTabIndex,
+    deleteIconRef,
+    children,
+    checked,
+    overStyled = false,
+    ...rest
+  },
+  ref,
+) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const restRecord = sanitizedProps as Record<string, unknown>;
+
+  // Note MUI's actual prop is "classes", not "classNames" (that's Mantine's naming) — this
+  // used to read the wrong key, silently no-op-ing any caller-supplied classes.
+  const mergedClassNames = mergeClassNames(
+    {
+      root: styles.root,
+      label: styles.label,
+      icon: styles.leadingIcon,
+      deleteIcon: styles.deleteIconWrapper,
+    },
+    restRecord.classes as Partial<Record<string, string>> | undefined,
+  );
+
+  const classNameProp = restRecord.className as string | undefined;
+  const finalClass = classNameProp
+    ? `${styles.root} ${classNameProp}`
+    : styles.root;
+
+  // Determine state
+  const dataError = error ? "" : undefined;
+  const dataChecked = checked ? "" : undefined;
+  const isIconOnly = !children && (!!icon || !!onDelete);
+  // A chip only counts as interactive when something actually responds to it — merely passing a
+  // `checked` value (e.g. to pin a display-only chip to a fixed visual state, as FileUpload's
+  // read-only file list does) isn't itself an interaction, since clicking it with no onChange/
+  // onClick wired does nothing observable.
+  const isInteractive =
+    onDelete !== undefined ||
+    restRecord.onClick !== undefined ||
+    restRecord.onChange !== undefined;
+
+  return (
+    <MuiChip
+      ref={ref}
+      className={finalClass}
+      classes={mergedClassNames}
+      {...(dataError !== undefined ? { "data-error": "" } : {})}
+      {...(dataChecked !== undefined ? { "data-checked": "" } : {})}
+      {...(isIconOnly ? { "data-icon-only": "" } : {})}
+      {...(isInteractive ? { "data-interactive": "" } : {})}
+      {...sanitizedProps}
+      icon={
+        checked ? (
+          <span className={styles.checkIconWrapper} aria-hidden>
+            <CheckIcon />
+          </span>
+        ) : icon ? (
+          <span className={styles.leadingIcon} aria-hidden>
+            {icon}
+          </span>
+        ) : undefined
+      }
+      onDelete={onDelete}
+      deleteIcon={
+        onDelete ? (
+          <span
+            ref={deleteIconRef}
+            role="button"
+            className={styles.deleteIconWrapper}
+            aria-label={deleteLabel}
+            tabIndex={deleteTabIndex ?? 0}
+            onKeyDown={(e) => {
+              // MUI's native `onDelete` wiring (distinct from our own `onDelete` prop above) only
+              // reacts to Backspace/Delete, and only when this span itself is both the event's
+              // target and currentTarget — neither holds once a parent (e.g. FileUpload's
+              // roving-tabindex group) moves real focus onto this span directly. A plain `<span>`
+              // also gets no native Enter/Space-triggers-click behavior the way a real `<button>`
+              // would, so it's handled explicitly here instead.
+              if (e.key === "Enter" || e.key === " ") {
+                e.preventDefault();
+                e.stopPropagation();
+                onDelete(
+                  e as unknown as React.MouseEvent<HTMLSpanElement, MouseEvent>,
+                );
+              }
+            }}
+          >
+            <CloseIcon />
+          </span>
+        ) : undefined
+      }
+      label={
+        <span className={styles.innerWrapper}>
+          <span className={styles.children}>{children}</span>
+        </span>
+      }
+    />
+  );
+});
+
+Chip.displayName = "Chip";

package/src/components/Chip/USAGE.md

@@ -0,0 +1,55 @@
+# Chip - Usage Guide
+
+This document describes how to integrate and use the `Chip` component in your projects using `@recursica/adapter-mui-v7`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Chip } from "@recursica/adapter-mui-v7";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Chip } from "@recursica/adapter-mui-v7";
+
+export default function Demo() {
+  return <Chip defaultChecked>Clickable Chip</Chip>;
+}
+```
+
+---
+
+## 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.
+
+---
+
+## 4. Key Integration Features & Constraints
+
+### Sizing
+
+Chip does not support a `size` prop; chips render at a fixed size.
+
+### Building a keyboard-navigable chip group
+
+`deleteTabIndex` and `deleteIconRef` are optional escape hatches for composing a _group_ of chips
+with roving-tabindex keyboard navigation (Tab reaches one chip at a time, arrow keys move between
+them) — see `FileUpload`'s file list for a working example. Ignore both for a standalone chip; they
+default to a normal `tabIndex={0}` delete icon with no ref.
+
+Also pass a plain `tabIndex={-1}` on the `<Chip>` itself in a group like this — MUI's `Chip` root
+becomes a focusable element on its own whenever `onDelete` is set, which would otherwise be a
+second, unwanted tab stop ahead of the delete icon (see `CHIP_IMPLEMENTATION_NOTES.md`).

package/src/components/Chip/index.ts

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

package/src/components/Container/Container.stories.tsx

@@ -0,0 +1,118 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Container } from "./Container";
+import { Text } from "../Text/Text";
+
+type ContainerStoryProps = React.ComponentProps<typeof Container>;
+
+const meta: Meta<ContainerStoryProps> = {
+  title: "UI-Kit/Container",
+  component: Container,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Container is a generic layout wrapper that safely maps to Mantine's Container, standardizing maximum content widths across the application.",
+      },
+    },
+  },
+  args: {
+    size: "md",
+    fluid: false,
+  },
+  argTypes: {
+    size: {
+      control: "select",
+      options: [
+        "xs",
+        "sm",
+        "md",
+        "lg",
+        "xl",
+        "rec-sm",
+        "rec-default",
+        "rec-md",
+        "rec-lg",
+        "rec-xl",
+        "rec-2xl",
+      ],
+      description:
+        "Maximum width defined by Mantine system sizes or Recursica sizes",
+    },
+    fluid: {
+      control: "boolean",
+      description: "If true, overrides size and sets max-width to 100%",
+    },
+    defaultChecked: {
+      table: { disable: true },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<ContainerStoryProps>;
+
+export const Default: Story = {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <div style={{ backgroundColor: "#f0f0f0", padding: "16px" }}>
+      <Container
+        {...args}
+        style={{
+          backgroundColor: "white",
+          padding: "16px",
+          border: "1px solid #ccc",
+        }}
+      >
+        <Text>
+          This is a Container holding centered content. The background and
+          border are added just to demonstrate the layout bounds visually.
+        </Text>
+      </Container>
+    </div>
+  ),
+};
+
+export const SmallContainer: Story = {
+  args: {
+    size: "sm",
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <div style={{ backgroundColor: "#f0f0f0", padding: "16px" }}>
+      <Container
+        {...args}
+        style={{
+          backgroundColor: "white",
+          padding: "16px",
+          border: "1px solid #ccc",
+        }}
+      >
+        <Text>Small Container Layout</Text>
+      </Container>
+    </div>
+  ),
+};
+
+export const FluidContainer: Story = {
+  args: {
+    fluid: true,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <div style={{ backgroundColor: "#f0f0f0", padding: "16px" }}>
+      <Container
+        {...args}
+        style={{
+          backgroundColor: "white",
+          padding: "16px",
+          border: "1px solid #ccc",
+        }}
+      >
+        <Text>Fluid Container Layout</Text>
+      </Container>
+    </div>
+  ),
+};

package/src/components/Container/Container.test.tsx

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

package/src/components/Container/Container.tsx

@@ -0,0 +1,51 @@
+/**
+ * Container layout wrapper.
+ *
+ * NOTE: As a foundational structural boundary, the Container component DOES NOT use
+ * the `RecursicaOverStyled` gatekeeper. Furthermore, unlike other primitive layouts
+ * (Stack, Group, Flex), Container explicitly ALLOWS the `sx` prop as an escape hatch
+ * for advanced layout positioning.
+ */
+import { forwardRef } from "react";
+import {
+  Container as MUIContainer,
+  type ContainerProps as MUIContainerProps,
+} from "@mui/material";
+
+import { type WithRecursicaSpacing } from "../../utils/filterStylingProps";
+import { type RecursicaContainerProps } from "@recursica/adapter-common";
+
+export type ContainerProps = WithRecursicaSpacing<
+  Omit<MUIContainerProps, "maxWidth"> & RecursicaContainerProps
+>;
+
+export const Container = forwardRef<HTMLDivElement, ContainerProps>(
+  function Container({ children, size, fluid, ...rest }, ref) {
+    const mapSize: Record<string, "xs" | "sm" | "md" | "lg" | "xl"> = {
+      "rec-sm": "sm",
+      "rec-default": "md",
+      "rec-md": "md",
+      "rec-lg": "lg",
+      "rec-xl": "xl",
+      "rec-2xl": "xl",
+    };
+
+    const resolvedSize = fluid
+      ? false
+      : typeof size === "string" && mapSize[size]
+        ? mapSize[size]
+        : size;
+
+    return (
+      <MUIContainer
+        ref={ref}
+        maxWidth={resolvedSize as MUIContainerProps["maxWidth"]}
+        {...rest}
+      >
+        {children}
+      </MUIContainer>
+    );
+  },
+);
+
+Container.displayName = "Container";

package/src/components/Container/IMPLEMENTATION_NOTES.md

@@ -0,0 +1,5 @@
+# Container Implementation Notes
+
+## `sx` Prop Exemption
+
+By design, the `Container` component explicitly allows the `sx` prop to pass through to the underlying MUI `Container`. Unlike standard UI kit components (which use the `RecursicaOverStyled` gatekeeper) or flex layout primitives (which strip `sx` via `OmitSx` and `filterSxProp`), `Container` acts as a structural boundary where advanced, one-off positioning adjustments may be required by the consuming application.

package/src/components/Container/USAGE.md

@@ -0,0 +1,48 @@
+# Container - Usage Guide
+
+This document describes how to integrate and use the `Container` component in your projects using `@recursica/adapter-mui-v7`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Container } from "@recursica/adapter-mui-v7";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Container } from "@recursica/adapter-mui-v7";
+
+export default function Demo() {
+  return (
+    <Container size="lg">
+      <Text>Centered content container constrained by maximum width.</Text>
+    </Container>
+  );
+}
+```
+
+---
+
+## 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.
+
+---
+
+## 4. Key Integration Features & Constraints
+
+## `sx` Prop Exemption
+
+By design, the `Container` component always allows the `sx` prop to pass through, without requiring `overStyled`. This makes it useful as a structural boundary where advanced, one-off positioning adjustments may be required by the consuming application.

package/src/components/Container/index.ts

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

package/src/components/DatePicker/DATEPICKER_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,29 @@
+# DatePicker Implementation Notes
+
+## Architecture Overview
+
+The `DatePicker` component is a wrapper around MUI X's `@mui/x-date-pickers` `DatePicker`, implementing the `FormControlWrapper` macro structure for Recursica. This ensures that the component visually and structurally aligns with standard Recursica input primitives, and mirrors the mantine-adapter's own `DatePicker` behavior and token mapping wherever the two libraries' APIs allow it.
+
+## Structural Constraints
+
+1. **Naked Field Usage**: We intentionally pass `label={undefined}`/`description`/`error` through `WithReadOnlyWrapper` rather than MUI X's own field label/helper-text props, so only our `WithReadOnlyWrapper` > `FormControlWrapper` orchestrates labels, description text, and ARIA state error boundaries — same convention as TimePicker.tsx.
+2. **Value Type**: MUI X's `DatePicker` only speaks `Dayjs` (via `AdapterDayjs`); the public API converts to/from plain `Date` internally so `value`/`defaultValue`/`onChange` match the mantine-adapter's convention exactly.
+3. **Read-Only Rendering**: The selected date is displayed formatted as `MM/DD/YY` (via `dayjs(...).format(...)`), not a raw `String(value)` cast (unlike the mantine-adapter, which has no reason to reach for `dayjs` outside read-only formatting). Pass `readOnlyComponent` to override.
+4. **Typing vs. Popover Entry**: Unlike the mantine-adapter (`DatePickerInput`, popover-only), MUI X's field natively supports typing directly into masked date segments in addition to the popup calendar — no adapter code needed to enable this, it's the library default.
+5. **Calendar Popover (Figma Token Issue)**: Same root cause as the mantine-adapter — the UI Kit's `date-picker` component exports no calendar-specific tokens (surface, selected day, hover, today, in-range) — so the calendar reuses the closest existing tokens, mapped 1:1 to the mantine-adapter's choices:
+   - **Surface** (`.dropdown`, applied to `slotProps.desktopPaper`) & **selected day** (`.MuiPickerDay-root.Mui-selected`): `--recursica_ui-kit_components_hover-card-popover` tokens for elevation/padding/surface, `--recursica_ui-kit_components_button_variants_styles_solid` tokens for the selected day fill.
+   - **Header content, weekday row** (`.MuiPickersCalendarHeader-root`, `.MuiDayCalendar-weekDayLabel`): the hover-card-popover content-color token.
+   - **Header nav controls** (`.MuiPickersArrowSwitcher-button`, `.MuiPickersCalendarHeader-switchViewButton`) **& month/year label** (`.MuiPickersCalendarHeader-label`): styled with `--recursica_ui-kit_components_button_variants_styles_text` tokens (border/background/color/elevation) plus small-size `Button` sizing tokens — the same tokens the mantine-adapter's `.calendarHeaderControl`/`.calendarHeaderLevel` use. Note the DOM shape differs from mantine: MUI splits the month/year control into a plain, non-interactive `.label` text node (`role="none"` on its `labelContainer` parent) plus a separate small `.switchViewButton` that's the actual clickable control — only the label's _color/typography_ is recolored to match (no border/background chrome on a non-interactive element), while the switchViewButton gets the full button treatment.
+   - **Hover** (day cells, header nav, header level button): the generic `--recursica_brand_states_hover_color`/`_hover_opacity` pair via the same `::after`-overlay technique the mantine-adapter and `Button`/`Menu` use — a plain `background-color`+`opacity` change on the element itself would dim its icon/text along with the fill, not just tint the surface.
+   - **Disabled / outside-month days** (`.Mui-disabled`, `.MuiPickerDay-dayOutsideMonth`): the generic `--recursica_brand_states_disabled` opacity token, same convention used repo-wide. Disabled header nav/label controls use `Button`'s own text-variant disabled opacity/elevation tokens instead.
+   - **Today marker** (`.MuiPickerDay-today`): reuses the hover-card-popover border-size/color tokens already used for the dropdown surface's own border — same reasoning as mantine-adapter (no dedicated "today" token exists). MUI ships its own default light-primary-color background tint on this class, which is explicitly reset to `transparent` since the design system has no equivalent.
+   - **Range selection / weekend styling**: not mapped. MUI X's default `DatePicker` doesn't render range selection or weekend-specific styling at all (unlike Mantine, which colors weekends red by default and needed an explicit override), so neither state needed a Recursica mapping.
+
+## Styling Quirks
+
+- **Native field decoration suppression**: MUI X's field variant can't be forced to a bare/unstyled mode from this component's public API (same constraint TimePicker.module.css documents) — whichever native outline/underline decoration it renders by default is suppressed via `:global(...)` overrides, and `.field` draws the Recursica border/background/color instead.
+- **Popover `slotProps` gotcha, same shape as mantine-adapter's `popoverProps` bug**: the calendar popup is portaled to `document.body`, entirely outside this component's own DOM subtree, so it can only be reached by handing MUI X's `slotProps.desktopPaper` a `className` directly — a descendant CSS selector from `.root` would never match it. `DatePicker.tsx` merges any consumer-supplied `slotProps.field`/`slotProps.desktopPaper` (and their `className`s) with our own defaults instead of overwriting them.
+- **`.dropdown`'s `!important`s**: unlike the mantine-adapter's equivalent rule (plain CSS-module specificity, no `!important` needed — `@mantine/dates`' own stylesheet reliably loads first), MUI X injects its own `Paper`/`Popper` styles at runtime via emotion, with no guaranteed load-order relative to this CSS module. `!important` here just re-asserts token values against a same-specificity emotion rule that could otherwise win on source order alone.
+- **Default display/entry format**: `format="MM/DD/YY"` (a `dayjs` format string, MUI X's own default is `"MM/DD/YYYY"`), matching the mantine-adapter's `valueFormat` default.
+- **Default leading icon**: the calendar icon is MUI X's own built-in "open picker" button (`slots.openPickerIcon`, positioned via `openPickerButtonPosition="start"` on the field slot) rather than a separate decorative `InputAdornment` — clicking it opens the calendar, unlike the mantine-adapter's purely decorative `leftSection` icon (there, the whole field is the click target). Overridable via `slots={{ openPickerIcon: MyIcon }}`, following the same override-prop convention as `leftSection` elsewhere in this adapter.
+- **No native `::placeholder`**: empty date segments ("MM", "DD", "YYYY") render via MUI X's own internal placeholder styling, not a native `::placeholder` pseudo-element — there's no selector to hook the `placeholder-opacity` token onto, same constraint TimePicker.module.css documents for its own empty sections.

package/src/components/DatePicker/DatePicker.icons.tsx

@@ -0,0 +1,35 @@
+import React from "react";
+
+/**
+ * Default calendar icon rendered in the field's open-picker button (start position, see
+ * DatePicker.tsx). Consumers can override it by passing their own `slots.openPickerIcon`.
+ * Rendered by MUI X as an `SvgIcon`-like component and handed `className`/`style` only — sized/
+ * colored entirely via the generic `.section :global(svg)` rule in DatePicker.module.css, same
+ * convention as the mantine-adapter's CalendarIcon.
+ */
+export function CalendarIcon({
+  className,
+  style,
+}: {
+  className?: string;
+  style?: React.CSSProperties;
+}) {
+  return (
+    <svg
+      className={className}
+      style={style}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden
+    >
+      <rect x="3" y="4" width="18" height="18" rx="2" ry="2" />
+      <line x1="16" y1="2" x2="16" y2="6" />
+      <line x1="8" y1="2" x2="8" y2="6" />
+      <line x1="3" y1="10" x2="21" y2="10" />
+    </svg>
+  );
+}