@recursica/adapter-mui-v7 1.0.0

package/src/components/DatePicker/DatePicker.tsx

@@ -0,0 +1,229 @@
+import React, { forwardRef, useEffect, useState } from "react";
+import { LocalizationProvider } from "@mui/x-date-pickers/LocalizationProvider";
+import { AdapterDayjs } from "@mui/x-date-pickers/AdapterDayjs";
+import {
+  DatePicker as MuiDatePicker,
+  type DatePickerProps as MuiDatePickerProps,
+  type DatePickerSlotProps,
+  type DatePickerSlots,
+} from "@mui/x-date-pickers/DatePicker";
+import dayjs, { type Dayjs } from "dayjs";
+import { type ReadOnlyControlProps } from "@recursica/adapter-common";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import { type RecursicaFormControlWrapperProps } from "../FormControlWrapper/FormControlWrapper";
+import { WithReadOnlyWrapper } from "../ReadOnlyField/WithReadOnlyWrapper";
+import { CalendarIcon } from "./DatePicker.icons";
+import styles from "./DatePicker.module.css";
+
+import { type RecursicaDatePickerProps as BaseRecursicaDatePickerProps } from "@recursica/adapter-common";
+
+// Default display/entry format (dayjs format string), matching the mantine-adapter's DatePicker.
+const DATE_FORMAT = "MM/DD/YY";
+
+function toDayjs(value: Date | null | undefined): Dayjs | null {
+  return value ? dayjs(value) : null;
+}
+
+export interface RecursicaDatePickerProps
+  extends Omit<
+      MuiDatePickerProps,
+      | "value"
+      | "defaultValue"
+      | "onChange"
+      | "minDate"
+      | "maxDate"
+      | "format"
+      | "slots"
+      | "slotProps"
+    >,
+    Pick<
+      RecursicaFormControlWrapperProps,
+      | "label"
+      | "error"
+      | "required"
+      | "id"
+      | "assistiveText"
+      | "assistiveWithIcon"
+      | "formLayout"
+      | "labelSize"
+      | "labelAlignment"
+      | "labelOptionalText"
+      | "labelWithEditIcon"
+      | "onLabelEditClick"
+    >,
+    ReadOnlyControlProps,
+    BaseRecursicaDatePickerProps {
+  /** Selected date, matching the mantine-adapter convention of a plain `Date` value. */
+  value?: Date | null;
+  /** Uncontrolled initial date. */
+  defaultValue?: Date | null;
+  /** Fires with the new date, or `null` if cleared. */
+  onChange?: (value: Date | null) => void;
+  minDate?: Date;
+  maxDate?: Date;
+  /** Overridable component slots — e.g. `slots={{ openPickerIcon: MyIcon }}` to replace the default calendar icon. */
+  slots?: DatePickerSlots;
+  slotProps?: DatePickerSlotProps;
+  /** Caller-provided inline style, passed through to the FormControlWrapper root. */
+  style?: React.CSSProperties;
+}
+
+export type DatePickerProps = RecursicaOverStyled<RecursicaDatePickerProps>;
+
+export const DatePicker = forwardRef<HTMLDivElement, DatePickerProps>(
+  function DatePicker(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,
+      onChange,
+      minDate,
+      maxDate,
+      slots,
+      slotProps,
+      ...rest
+    } = props;
+
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+
+    // Internal Dayjs value: MUI X's DatePicker only speaks Dayjs (via AdapterDayjs); the public
+    // API stays plain `Date` to match the mantine-adapter convention.
+    const [internalValue, setInternalValue] = useState<Dayjs | null>(
+      () => toDayjs(value) ?? toDayjs(defaultValue) ?? null,
+    );
+
+    useEffect(() => {
+      if (value !== undefined) {
+        setInternalValue(toDayjs(value));
+      }
+    }, [value]);
+
+    const wrapperClass = className
+      ? `${styles.layoutOverride} ${className}`
+      : styles.layoutOverride;
+
+    const handleChange = (next: Dayjs | null) => {
+      setInternalValue(next);
+      onChange?.(next ? next.toDate() : null);
+    };
+
+    const readOnlyValue = (() => {
+      const source = value !== undefined ? value : defaultValue;
+      return toDayjs(source)?.format(DATE_FORMAT);
+    })();
+
+    // slotProps.field/desktopPaper are typed to also allow a `(ownerState) => props` function
+    // form; this adapter only ever merges plain objects (same assumption TextField/DatePicker's
+    // mantine counterpart make for consumer-supplied classNames), so narrow to that shape here.
+    const consumerFieldProps =
+      slotProps?.field && typeof slotProps.field === "object"
+        ? (slotProps.field as Record<string, unknown>)
+        : undefined;
+    const consumerDesktopPaperProps =
+      slotProps?.desktopPaper && typeof slotProps.desktopPaper === "object"
+        ? (slotProps.desktopPaper as Record<string, unknown>)
+        : undefined;
+
+    return (
+      <WithReadOnlyWrapper
+        ref={ref}
+        className={wrapperClass}
+        style={style}
+        controlMaxWidth={undefined}
+        controlMinWidth={undefined}
+        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}
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        readOnlyComponent={readOnlyComponent as any}
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        emptyValueComponent={(emptyValueComponent as any) || undefined}
+        readOnlyType="text"
+        readOnlyValue={readOnlyValue}
+        readOnlyNativeProps={props}
+        activeComponent={
+          /* Naked field execution safely decoupled from MUI X's own label/error macro handling,
+             same convention as TimePicker.tsx. Unlike TimePicker, the popup calendar IS used here
+             (and token-styled below) — see DATEPICKER_IMPLEMENTATION_NOTES.md. */
+          <div className={styles.root} data-error={error ? "true" : undefined}>
+            <LocalizationProvider dateAdapter={AdapterDayjs}>
+              <MuiDatePicker
+                {...(sanitizedProps as unknown as Partial<MuiDatePickerProps>)}
+                value={internalValue}
+                onChange={handleChange}
+                disabled={disabled}
+                format={DATE_FORMAT}
+                minDate={toDayjs(minDate) ?? undefined}
+                maxDate={toDayjs(maxDate) ?? undefined}
+                slots={{ openPickerIcon: CalendarIcon, ...slots }}
+                slotProps={
+                  {
+                    ...slotProps,
+                    field: {
+                      // Calendar icon opens the picker from the left side of the field, mirroring
+                      // the mantine-adapter's default `leftSection`; overridable via
+                      // `slots.openPickerIcon`. Only settable per-field, not at the picker's own
+                      // top level (MUI X has no top-level `openPickerButtonPosition` prop).
+                      openPickerButtonPosition: "start",
+                      ...consumerFieldProps,
+                      className: consumerFieldProps?.className
+                        ? `${styles.field} ${consumerFieldProps.className as string}`
+                        : styles.field,
+                    },
+                    // The popup surface is portaled to document.body, outside this component's own
+                    // DOM subtree, so — same constraint mantine-adapter's `popoverProps.classNames`
+                    // documents — it can only be reached by handing it a className directly, not a
+                    // descendant CSS selector.
+                    desktopPaper: {
+                      ...consumerDesktopPaperProps,
+                      className: consumerDesktopPaperProps?.className
+                        ? `${styles.dropdown} ${consumerDesktopPaperProps.className as string}`
+                        : styles.dropdown,
+                    },
+                  } as DatePickerSlotProps
+                }
+              />
+            </LocalizationProvider>
+          </div>
+        }
+      />
+    );
+  },
+);
+
+DatePicker.displayName = "DatePicker";

package/src/components/DatePicker/USAGE.md

@@ -0,0 +1,49 @@
+# DatePicker - Usage Guide
+
+This document describes how to integrate and use the `DatePicker` component in your projects using `@recursica/adapter-mui-v7`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { DatePicker } from "@recursica/adapter-mui-v7";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { DatePicker } from "@recursica/adapter-mui-v7";
+
+export default function Demo() {
+  return <DatePicker label="Select Date" />;
+}
+```
+
+---
+
+## 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
+
+## Structural Constraints
+
+1. **Value Type**: `value`/`defaultValue`/`onChange` all speak plain `Date` objects (not MUI X's native `Dayjs`), matching the mantine-adapter's DatePicker convention — conversion to/from `Dayjs` happens internally.
+2. **Read-Only Rendering**: When rendered in read-only mode, the selected date is displayed formatted as `MM/DD/YY`. If you need custom date formatting, pass a `readOnlyComponent` prop to control how the value is rendered.
+3. **Calendar Popover Styling**: The UI Kit exports no calendar-specific tokens (surface, selected day, hover, today, in-range), so the calendar reuses the closest existing tokens — see `DATEPICKER_IMPLEMENTATION_NOTES.md` for the exact mapping, mirrored 1:1 from the mantine-adapter. The header's prev/next arrows and month-view toggle are styled as Recursica `text`-variant buttons.
+4. **Typing vs. Popover Entry**: Unlike the mantine-adapter (popover-only selection), MUI X's field supports typing a date directly into its masked `MM/DD/YY` segments, in addition to picking from the popup calendar.
+5. **Default Display/Entry Format**: `MM/DD/YY` (e.g. `08/19/26`), matching the mantine-adapter; pass your own `format` (a `dayjs` format string) via the standard MUI X `DatePicker` props to override.
+6. **Default Leading Icon**: A calendar icon opens the picker from the start of the field by default; pass `slots={{ openPickerIcon: MyIcon }}` to override it.

package/src/components/DatePicker/index.ts

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

package/src/components/Dropdown/BareDropdown.tsx

@@ -0,0 +1,168 @@
+import { forwardRef } from "react";
+import {
+  Select as MuiSelect,
+  type SelectProps as MuiSelectProps,
+  MenuItem,
+} from "@mui/material";
+import {
+  type RecursicaComboboxData,
+  normalizeComboboxData,
+} from "@recursica/adapter-common";
+import {
+  filterStylingProps,
+  omitUnsupportedProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import { renderRichOptionContent } from "../../utils/renderRichOption";
+import styles from "./Dropdown.module.css";
+
+/**
+ * Bare, unwrapped Select — no `FormControlWrapper`/`WithReadOnlyWrapper`, no label/assistiveText/
+ * error/required. Tied to the same `Dropdown.module.css` variables/classes as the public
+ * `Dropdown` component, so it looks identical, but is meant to be embedded inside another
+ * component that already owns its own `FormControlWrapper` (e.g. `TimePicker`'s AM/PM control) —
+ * nesting the full `Dropdown` there would double up `FormControl`/`FormControlLayout` wrapping.
+ *
+ * Not exported from this folder's `index.ts` — internal use only. Import it directly:
+ * `import { BareDropdown } from "../Dropdown/BareDropdown"`.
+ */
+export interface BareDropdownProps
+  extends Omit<
+    MuiSelectProps,
+    "size" | "variant" | "classes" | "error" | "onChange"
+  > {
+  data: RecursicaComboboxData;
+  /** Normalized to just the selected value, unlike MUI's raw (event, child) Select onChange. */
+  onChange?: (value: string | null) => void;
+  /** Applies the error visual state (via `data-error`) — no error message is rendered here. */
+  error?: boolean;
+}
+
+export type BareDropdownComponentProps = RecursicaOverStyled<BareDropdownProps>;
+
+export const BareDropdown = forwardRef<
+  HTMLInputElement,
+  BareDropdownComponentProps
+>(function BareDropdown(props, ref) {
+  const {
+    overStyled = false,
+    disabled,
+    data,
+    onChange,
+    className,
+    value,
+    defaultValue,
+    error,
+    ...rest
+  } = props;
+  // 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
+    "variant", // Recursica styles the naked select directly; MUI's standard/filled/outlined unused
+    "classes", // Recursica computes its own classes object below; caller's would silently clobber it
+  ] as const satisfies readonly (keyof MuiSelectProps)[];
+
+  const sanitizedProps = omitUnsupportedProps(
+    filterStylingProps(rest, overStyled),
+    UNSUPPORTED_PROPS,
+  );
+  const restRecord = sanitizedProps as Record<string, unknown>;
+
+  const mergedClassName = className
+    ? `${styles.root} ${className}`
+    : styles.root;
+
+  const selectedValue = value ?? defaultValue;
+
+  const optionClassNames = {
+    optionContent: styles.optionContent,
+    optionIcon: styles.optionIcon,
+    optionText: styles.optionText,
+    optionTextWrap: styles.optionTextWrap,
+    optionSupportingText: styles.optionSupportingText,
+  };
+
+  // See Dropdown.tsx's identical use of `normalizeComboboxData` (adapter-common).
+  const normalizedData = normalizeComboboxData(data) ?? [];
+
+  const renderOptions = () =>
+    normalizedData.map((item, index) => {
+      if (typeof item === "string") {
+        return (
+          <MenuItem
+            key={`${item}-${index}`}
+            value={item}
+            className={styles.option}
+            // Dropdown.module.css's own selected-state tint (`.option[data-selected="true"]`) needs
+            // this explicitly — MUI's own `Mui-selected` class carries its default primary-color
+            // tint instead, which is what shows through without it.
+            data-selected={item === selectedValue ? "true" : undefined}
+          >
+            {item}
+          </MenuItem>
+        );
+      }
+      return (
+        <MenuItem
+          key={`${item.value}-${index}`}
+          value={item.value}
+          disabled={item.disabled}
+          className={styles.option}
+          data-selected={item.value === selectedValue ? "true" : undefined}
+        >
+          {renderRichOptionContent(item, optionClassNames)}
+        </MenuItem>
+      );
+    });
+
+  // See Dropdown.tsx's identical `renderValue` — keeps the closed field showing just the plain
+  // label now that a MenuItem's children can be a rich icon+label+supportingText row.
+  const renderValue = (selected: unknown) => {
+    if (selected === "" || selected === undefined || selected === null) {
+      return "";
+    }
+    const match = normalizedData.find((item) =>
+      typeof item === "string" ? item === selected : item.value === selected,
+    );
+    if (!match) return "";
+    return typeof match === "string" ? match : match.label;
+  };
+
+  return (
+    <MuiSelect
+      ref={ref}
+      {...(sanitizedProps as unknown as MuiSelectProps)}
+      disabled={disabled}
+      value={value}
+      defaultValue={defaultValue}
+      onChange={(event) => onChange?.((event.target.value as string) ?? null)}
+      displayEmpty
+      renderValue={renderValue}
+      error={!!error}
+      className={mergedClassName}
+      classes={{
+        select: styles.input,
+        icon: styles.icon,
+      }}
+      MenuProps={{
+        classes: { paper: styles.dropdown },
+      }}
+      // Dropdown.module.css's error/disabled state rules key off `.root[data-error]`/
+      // `[data-disabled]` (the outer Select element, matching mergedClassName above) —
+      // `inputProps` only reaches the nested accessibility <input>, which that selector never
+      // matches, so these need to be set here too (mirrors the same fix in Dropdown.tsx).
+      data-disabled={disabled ? "true" : undefined}
+      data-error={error ? "true" : undefined}
+      inputProps={{
+        "data-disabled": disabled ? "true" : undefined,
+        "data-error": error ? "true" : undefined,
+        ...(restRecord.inputProps as Record<string, unknown>),
+      }}
+    >
+      {renderOptions()}
+    </MuiSelect>
+  );
+});
+
+BareDropdown.displayName = "BareDropdown";

package/src/components/Dropdown/DROPDOWN_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,45 @@
+# Dropdown Implementation Notes
+
+## Rich Option Content (`leadingIcon`/`supportingText`)
+
+`data` items accept optional `leadingIcon`/`supportingText` fields, via the shared `RecursicaComboboxItem` type in `@recursica/adapter-common` (see `MANTINE_ADAPTER_RICH_OPTION_DATA.md` at the repo root — proposed against the mantine-adapter, but Forge needs both adapters to accept the same `data` shape, hence the type living in adapter-common rather than being redeclared per adapter). `Dropdown.tsx` and `BareDropdown.tsx` both build `MenuItem` children directly from `data` (there's no Mantine-style `renderOption` indirection here), so rendering the new fields is a straight change to that existing per-item mapping — `renderRichOptionContent` (`../../utils/renderRichOption.tsx`, shared with `Autocomplete`) renders `leadingIcon`+`label`+`supportingText` when either new field is present, or just `label` otherwise. The icon is only rendered as a child when `leadingIcon` is set (not a hidden reserved slot), so label/supportingText shift left when there's no icon; the row's `align-items: center` keeps the label vertically centered when there's no `supportingText` to stack under it.
+
+`label` on the shared type is optional (falls back to `value`) — both components run `data` through adapter-common's `normalizeComboboxData` first (`const normalizedData = normalizeComboboxData(data)`), so every downstream read of `item.label` is a real string, with no per-call-site `?? value` fallback needed.
+
+MUI's closed-field display has no separate slot analogous to Mantine's `option.label` — without a `renderValue`, MUI shows whichever `MenuItem`'s children matched the selected value, which would leak the rich icon/supporting-text row into the closed field. Both components now pass a `renderValue` that looks the selected item back up by value and returns its plain `label`, keeping the closed field a single line of text regardless of what the open dropdown renders.
+
+New CSS classes (`.optionContent`/`.optionIcon`/`.optionText`/`.optionSupportingText`) in `Dropdown.module.css` reuse the menu-item component's icon/supporting-text tokens, matching the mantine-adapter's equivalent addition — no dedicated dropdown-option tokens exist for either.
+
+## `wrapItemText`
+
+`label`/`supportingText` default to single-line truncation with an ellipsis (`.optionText > *` — `overflow: clip; overflow-clip-margin: 0.35em; text-overflow: ellipsis; white-space: nowrap`). Passing `wrapItemText` adds `.optionTextWrap` alongside `.optionText`, re-enabling wrapping (`white-space: normal; overflow-wrap: anywhere`) for both children — later-cascade-wins, equal specificity. `renderRichOptionContent` takes `wrapItemText` as a third parameter and combines the two class names when it's true. `Dropdown.tsx` exposes this as a public prop; `BareDropdown.tsx` (internal-only, not part of the public `Dropdown`/`AutoComplete` API this was requested for) doesn't take the prop and always truncates.
+
+`.optionText > *` used plain `overflow: hidden` until 2026-08-28 (Matt Massey) — it clipped
+descenders (e.g. "g") whenever `text_line-height` is tighter than the font's natural
+ascent+descent. `overflow-clip-margin` gives ink a small bleed allowance while still clipping
+genuinely overflowing text; same project-wide fix as Chip's `CHIP_IMPLEMENTATION_NOTES.md`.
+
+## Missing placeholder (bug fix, Matt Massey, 2026-08-30)
+
+`placeholder` (a real prop on `RecursicaDropdownProps` via `adapter-common`) was accepted but
+silently did nothing — it fell through to `...rest`/`sanitizedProps` and got spread onto
+`<MuiSelect>`, which only forwards it to its own hidden accessibility `<input>` (invisible to the
+user); MUI's `Select` is not a native text `<input>`, so it has no `::placeholder` rendering path
+of its own. mantine-adapter's `Select` supports `placeholder` natively, so the equivalent bug never
+existed there. Fixed by destructuring `placeholder` explicitly and rendering it from `renderValue`
+when the field is empty, wrapped in a new `.placeholder` class (same opacity treatment as
+`.input::placeholder`) since a `<span>` inside a non-input element has no pseudo-element to target.
+
+The `ui-kit-dropdown--with-rich-options`/`-wrapped` stories were also flagged as "text isn't
+vertically centered" — with no placeholder rendering, MUI's empty `.MuiSelect-select` fell back to
+its own zero-width-space filler content (`&#8203;`, used internally to preserve the box's height),
+which doesn't establish the same line box a real placeholder string does. Rendering the actual
+placeholder text resolved this too — verified via screenshot, no separate CSS change needed.
+
+## Missing input-to-menu gap (Matt Massey, ROUND 2 2026-08-31)
+
+Same gap AutoComplete had: MUI's Select renders its open menu flush against the input, no offset
+token exists in the schema for it either. Fixed with the identical technique — `margin-top: var(
+--recursica_brand_dimensions_general_default)` on `.dropdown` (the `MenuProps.classes.paper`
+target). Unlike AutoComplete's Popper, Select's menu is a Popover, which positions via computed
+`top`/`left` rather than an inline `margin: 0`, so no `!important` was needed here.

package/src/components/Dropdown/Dropdown.icons.tsx

@@ -0,0 +1,33 @@
+import React from "react";
+
+/**
+ * Chevron rendered in the right section alongside the clear button (item 3a). Only used for that
+ * combined case — MUI's own default `IconComponent` (`ArrowDropDown`) is left untouched everywhere
+ * else, so this is a hand-rolled copy of the exact same MUI glyph path, not a new icon design.
+ */
+export function ChevronIcon(props: React.SVGProps<SVGSVGElement>) {
+  return (
+    <svg viewBox="0 0 24 24" fill="currentColor" aria-hidden {...props}>
+      <path d="M7 10l5 5 5-5z" />
+    </svg>
+  );
+}
+
+/** Clear ("x") icon for the clearable Dropdown's clear button (item 3a). */
+export function ClearIcon(props: React.SVGProps<SVGSVGElement>) {
+  return (
+    <svg
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden
+      {...props}
+    >
+      <line x1="18" y1="6" x2="6" y2="18" />
+      <line x1="6" y1="6" x2="18" y2="18" />
+    </svg>
+  );
+}