@recursica/mui-adapter 0.24.0 → 0.26.0

package/src/components/DatePicker/DatePicker.tsx

@@ -1,47 +1,229 @@
-/* eslint-disable @typescript-eslint/no-unused-vars */
-import React from "react";
-import "./DatePicker.module.css";
-import { type RecursicaDatePickerProps } from "@recursica/adapter-common";
-
-export type DatePickerProps = Omit<
-  React.HTMLAttributes<HTMLDivElement>,
-  "value" | "onChange" | "defaultValue"
-> &
-  RecursicaDatePickerProps & {
-    disabled?: boolean;
-    label?: React.ReactNode;
-    assistiveText?: string;
-    error?: React.ReactNode;
-    required?: boolean;
-    withAsterisk?: boolean;
-    placeholder?: string;
-    value?: Date | null;
-    defaultValue?: Date | null;
-    onChange?: (value: Date | null) => void;
-    readOnly?: boolean;
-    formLayout?: "stacked" | "side-by-side";
-    leftSection?: React.ReactNode;
-    labelWithEditIcon?: boolean;
-    onLabelEditClick?: () => void;
-  };
-
-export const DatePicker: React.FC<DatePickerProps> = ({
-  disabled,
-  label,
-  assistiveText,
-  error,
-  required,
-  withAsterisk,
-  placeholder,
-  value,
-  defaultValue,
-  onChange,
-  readOnly,
-  formLayout,
-  leftSection,
-  labelWithEditIcon,
-  onLabelEditClick,
-  ...props
-}) => {
-  return <div {...props}>DatePicker</div>;
-};
+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

@@ -19,7 +19,7 @@ import React from "react";
 import { DatePicker } from "@recursica/mui-adapter";
 
 export default function Demo() {
-  return <DatePicker label="Select Date" placeholder="Pick a date" />;
+  return <DatePicker label="Select Date" />;
 }
 ```
 
@@ -34,3 +34,16 @@ All Recursica components in the `@recursica/mui-adapter` package adhere strictly
 > - **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/Dropdown/Dropdown.module.css

@@ -1,10 +1,3 @@
-/* EXEMPTIONS:
-   - state-specific border-size variables are ignored because a uniform 1px border is applied globally to prevent
-     unexpected layout shift or flickering during focus, disabled, or error state transitions. */
-/* recursica-ignore: --recursica_ui-kit_components_dropdown_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_dropdown_variants_states_disabled_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_dropdown_variants_states_error_properties_border-size */
-
 /* LAYOUT SPACING OVERRIDES:
    - Sets the --form-control-margin-bottom spacing hook to map component-specific layout tokens.
    - Also sets the --dropdown-control-{max,min}-width hooks consumed inline in Dropdown.tsx, since

package/src/components/FileInput/FileInput.module.css

@@ -1,24 +1,3 @@
-/* EXEMPTIONS:
-   - The disabled/error states' own border-size variables are ignored so the border never changes
-     thickness across states and shifts the layout — same house policy as TextField/DatePicker.
-     The flat, state-agnostic properties_border-size token below is applied uniformly instead.
-   - There is no forge-defined focus state for file-input (no `states.focus` axis, unlike its
-     disabled/error siblings) — the generic recursica_brand_states_focus_* ring is used instead,
-     same fallback TextField/DatePicker use for the same reason.
-   - properties_icon-text-gap doubles as the gap between chips: file-input has no dedicated
-     chip-gap token (unlike file-upload's properties_item-gap).
-   - The trailing clear-all affordance is now a real shared `Button` (icon-only, "text" variant)
-     rather than a bespoke span, so it gets its own real button semantics/keyboard handling —
-     same pattern as Tree's expand/collapse button. It renders through Button's own tokened
-     color states (including disabled), so file-input's own trailing-icon color tokens — which
-     have no "clear button is disabled/errored" equivalent state of their own anyway — are no
-     longer consumed here. */
-/* recursica-ignore: --recursica_ui-kit_components_file-input_variants_states_disabled_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_file-input_variants_states_error_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_file-input_properties_colors_trailing-icon */
-/* recursica-ignore: --recursica_ui-kit_components_file-input_variants_states_error_properties_colors_trailing-icon */
-/* recursica-ignore: --recursica_ui-kit_components_file-input_variants_states_disabled_properties_colors_trailing-icon */
-
 /* LAYOUT SPACING OVERRIDES:
    - Sets the --form-control-margin-bottom spacing hook to map component-specific layout tokens.
    - Also sets the --file-input-control-{max,min}-width hooks consumed inline in FileInput.tsx,

package/src/components/FileInput/FileInput.tsx

@@ -387,6 +387,12 @@ export const FileInput = forwardRef<HTMLDivElement, FileInputProps>(
                 e.stopPropagation();
                 handleClearAll();
               }}
+              onKeyDown={(e) => {
+                if (e.key !== "Enter" && e.key !== " ") return;
+                e.preventDefault();
+                e.stopPropagation();
+                handleClearAll();
+              }}
             />
           )}
 

package/src/components/FileUpload/FileUpload.module.css

@@ -1,14 +1,3 @@
-/* EXEMPTIONS:
-   - border-style has no usable var(...) form: the Figma-exported token's value is the literal
-     string `"dashed"` (quotes included), which is not a valid CSS <line-style> keyword — the same
-     class of "structural, not tokenized" property the canonical guide already treats border-style
-     as (see .root's own HARDCODED VALUES note below and TimePicker/DatePicker's identical
-     hardcoded `border-style: solid`). Hardcoded to the keyword `dashed` instead.
-   - properties_icon-size has no equivalent: unlike TextField/DatePicker, file-upload has no
-     dedicated icon-size token. Sized to visually match the Figma reference instead (see
-     HARDCODED VALUES below). */
-/* recursica-ignore: --recursica_ui-kit_components_file-upload_properties_border-style */
-
 /* HARDCODED VALUES:
    - .root: display: flex; flex-direction: column; width: 100% — structural layout, not a design
      token concern (matches how other block-level components like Layer are laid out).

package/src/components/HoverCard/HoverCard.module.css

@@ -5,13 +5,7 @@
      and positioning (-arrowSize/2) calculations that cannot be CSS-driven. The default matches
      the Recursica beak-size token (16px). See COMPONENT_ISSUES.md for details.
    - All structural layout (display, position, overflow) is deferred to Mantine's native
-     behavior. We only override visual design tokens (colors, typography, spacing, borders).
-/* EXEMPTIONS:
-   - beak-size is ignored here because Mantine's popover arrows compute their sizing and positional offsets
-     dynamically within the React rendering engine (requires inline pixel number rather than standard CSS variables).
-     The beak size is checked in JS against a fixed value of 16px. If this variable changes, the TSX components
-     need to be reviewed/re-compiled. */
-/* recursica-ignore: --recursica_ui-kit_components_hover-card-popover_properties_beak-size = 16px */
+     behavior. We only override visual design tokens (colors, typography, spacing, borders). */
 
 /* ======================================
    DROPDOWN CONTAINER

package/src/components/Label/Label.module.css

@@ -1,9 +1,3 @@
-/* EXEMPTIONS:
-   - layouts_stacked sizes width variables are ignored because stacked labels naturally occupy 100% width block-level
-     real estate in HTML rendering, making explicit width properties redundant. Mirrors the mantine-adapter reference. */
-/* recursica-ignore: --recursica_ui-kit_components_label_variants_layouts_stacked_variants_sizes_default_properties_width */
-/* recursica-ignore: --recursica_ui-kit_components_label_variants_layouts_stacked_variants_sizes_small_properties_width */
-
 .root {
   /* Prevent default MUI absolute positioning logic */
   position: relative;

package/src/components/Link/Link.module.css

@@ -1,8 +1,3 @@
-/* EXEMPTIONS:
-   - text_text-transform is ignored because links naturally inherit casing directly from text
-     children rather than requiring custom CSS transforms. Mirrors the mantine-adapter reference. */
-/* recursica-ignore: --recursica_ui-kit_components_link_properties_text_text-transform */
-
 /*
 HARDCODED VALUES:
 - display: inline-flex; (Base layout to align icon and text correctly)
@@ -79,11 +74,3 @@ HARDCODED VALUES:
   /* HARDCODE: allows text truncation if bounded */
   min-width: 0;
 }
-
-/* EXEMPTIONS:
-   text_text-transform across multiple link states (default, hover, visited, visited-hover) is ignored
-   because links naturally inherit casing directly from text children rather than requiring custom CSS transforms. */
-/* recursica-ignore: --recursica_ui-kit_components_link_variants_states_default_properties_text_text-transform */
-/* recursica-ignore: --recursica_ui-kit_components_link_variants_states_hover_properties_text_text-transform */
-/* recursica-ignore: --recursica_ui-kit_components_link_variants_states_visited_properties_text_text-transform */
-/* recursica-ignore: --recursica_ui-kit_components_link_variants_states_visited-hover_properties_text_text-transform */

package/src/components/Menu/Menu.module.css

@@ -1,8 +1,3 @@
-/* EXEMPTIONS:
-   - colors_supporting-text-color (selected variant) is ignored because selected menu items do not render
-     supporting secondary text, making the selected-state override for supporting text colors obsolete. */
-/* recursica-ignore: --recursica_ui-kit_components_menu-item_variants_selection-states_selected_properties_colors_supporting-text-color */
-
 /* HARDCODED VALUES:
    - border-style: solid. Structural rendering rule for the dropdown border (Mantine uses Paper which may not set border natively).
    - NOTE: overflow is intentionally NOT set on .dropdown. Mantine renders sub-menu dropdowns

package/src/components/Modal/Modal.module.css

@@ -1,14 +1,3 @@
-/* EXEMPTIONS:
-   - content-style and header-style parent variables represent raw JSON styling objects rather than
-     direct CSS variables and cannot be applied directly in standard CSS files.
-     Sub-properties are fully and individually mapped to elements natively.
-   - header/footer background-color are ignored because .header/.footer are intentionally
-     transparent (inheriting .content's background), matching Panel's header/footer treatment. */
-/* recursica-ignore: --recursica_ui-kit_components_modal_properties_content-style */
-/* recursica-ignore: --recursica_ui-kit_components_modal_properties_header-style */
-/* recursica-ignore: --recursica_ui-kit_components_modal_properties_colors_footer-background-color */
-/* recursica-ignore: --recursica_ui-kit_components_modal_properties_colors_header-background-color */
-
 .root {
 }
 

package/src/components/NumberInput/NumberInput.module.css

@@ -1,10 +1,3 @@
-/* EXEMPTIONS:
-   - border-size variables are ignored because the input box uses a uniform static boundary to prevent
-     unexpected layout shifts or flickering when switching between focused, disabled, or error states. */
-/* recursica-ignore: --recursica_ui-kit_components_number-input_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_number-input_variants_states_disabled_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_number-input_variants_states_error_properties_border-size */
-
 /* LAYOUT SPACING OVERRIDES:
    - Sets the --form-control-margin-bottom spacing hook to map component-specific layout tokens.
    - Also sets the --number-input-control-{max,min}-width hooks consumed inline in NumberInput.tsx,

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

@@ -1,84 +1,3 @@
-/* EXEMPTIONS:
-   - All pagination subcomponent properties (active-pages, inactive-pages, navigation-controls) are ignored
-     because we are not implementing custom subcomponent styling for pagination. Instead, pagination items
-     directly inherit the unified, standard brand button components for complete UI/UX consistency, rendering 
-     these generated subcomponent tokens redundant. */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_active-pages_subcomponent_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_active-pages_subcomponent_disabled-opacity */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_active-pages_subcomponent_elevation */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_active-pages_subcomponent_height */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_active-pages_subcomponent_horizontal-padding */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_active-pages_subcomponent_hover-color */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_active-pages_subcomponent_hover-elevation */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_active-pages_subcomponent_hover-opacity */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_active-pages_subcomponent_icon */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_active-pages_subcomponent_icon-text-gap */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_active-pages_subcomponent_max-label-width */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_active-pages_subcomponent_min-width */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_active-pages_subcomponent_text_font-family */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_active-pages_subcomponent_text_font-size */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_active-pages_subcomponent_text_font-style */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_active-pages_subcomponent_text_font-weight */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_active-pages_subcomponent_text_letter-spacing */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_active-pages_subcomponent_text_line-height */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_active-pages_subcomponent_text_text-decoration */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_active-pages_subcomponent_text_text-transform */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_active-pages_subcomponent_colors_background */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_active-pages_subcomponent_colors_border-color */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_active-pages_subcomponent_colors_icon-color */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_active-pages_subcomponent_colors_text */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_active-pages_subcomponent_colors_text-hover */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_inactive-pages_subcomponent_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_inactive-pages_subcomponent_disabled-opacity */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_inactive-pages_subcomponent_elevation */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_inactive-pages_subcomponent_height */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_inactive-pages_subcomponent_horizontal-padding */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_inactive-pages_subcomponent_hover-color */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_inactive-pages_subcomponent_hover-elevation */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_inactive-pages_subcomponent_hover-opacity */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_inactive-pages_subcomponent_icon */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_inactive-pages_subcomponent_icon-text-gap */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_inactive-pages_subcomponent_max-label-width */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_inactive-pages_subcomponent_min-width */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_inactive-pages_subcomponent_text_font-family */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_inactive-pages_subcomponent_text_font-size */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_inactive-pages_subcomponent_text_font-style */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_inactive-pages_subcomponent_text_font-weight */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_inactive-pages_subcomponent_text_letter-spacing */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_inactive-pages_subcomponent_text_line-height */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_inactive-pages_subcomponent_text_text-decoration */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_inactive-pages_subcomponent_text_text-transform */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_inactive-pages_subcomponent_colors_background */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_inactive-pages_subcomponent_colors_border-color */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_inactive-pages_subcomponent_colors_icon-color */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_inactive-pages_subcomponent_colors_text */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_inactive-pages_subcomponent_colors_text-hover */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_navigation-controls_subcomponent_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_navigation-controls_subcomponent_disabled-opacity */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_navigation-controls_subcomponent_elevation */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_navigation-controls_subcomponent_height */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_navigation-controls_subcomponent_horizontal-padding */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_navigation-controls_subcomponent_hover-color */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_navigation-controls_subcomponent_hover-elevation */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_navigation-controls_subcomponent_hover-opacity */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_navigation-controls_subcomponent_icon */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_navigation-controls_subcomponent_icon-text-gap */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_navigation-controls_subcomponent_max-label-width */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_navigation-controls_subcomponent_min-width */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_navigation-controls_subcomponent_text_font-family */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_navigation-controls_subcomponent_text_font-size */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_navigation-controls_subcomponent_text_font-style */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_navigation-controls_subcomponent_text_font-weight */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_navigation-controls_subcomponent_text_letter-spacing */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_navigation-controls_subcomponent_text_line-height */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_navigation-controls_subcomponent_text_text-decoration */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_navigation-controls_subcomponent_text_text-transform */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_navigation-controls_subcomponent_colors_background */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_navigation-controls_subcomponent_colors_border-color */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_navigation-controls_subcomponent_colors_icon-color */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_navigation-controls_subcomponent_colors_text */
-/* recursica-ignore: --recursica_ui-kit_components_pagination_properties_navigation-controls_subcomponent_colors_text-hover */
-
 .root {
   display: flex;
   align-items: center;

package/src/components/Popover/IMPLEMENTATION_NOTES.md

@@ -0,0 +1,22 @@
+# Popover Implementation Notes
+
+- **Built on Mui's Tooltip, in click-controlled mode:** Rather than Mui's `Popover`/`Modal` primitives, this component reuses `@mui/material`'s `Tooltip` — the same base HoverCard and Tooltip already use in this adapter — with `disableHoverListener`/`disableFocusListener`/`disableTouchListener` all set, and `open` fully controlled by this component. This keeps the arrow/placement/token-namespace conventions identical to HoverCard and Tooltip instead of introducing a second, unrelated positioning primitive.
+- **Composable API preserved via child extraction:** Like HoverCard, `Popover.Target`/`Popover.Dropdown` are never rendered themselves — `PopoverBase` walks `children` looking for those `displayName`s and extracts their inner content, then renders the target as Tooltip's single child and the dropdown as Tooltip's `title`.
+- **Diverges from HoverCard on missing Target/Dropdown:** HoverCard silently falls back to an empty `<div />` if the expected child isn't found. Popover throws instead — a silent empty popover is a worse failure mode for a click-triggered disclosure than for a hover card, and the repo convention is to let structural misuse fail loudly rather than mask it.
+- **Click toggle + outside-click close is custom:** Mui's Tooltip has no notion of "click to open" or "click outside to close" once its native hover/focus/touch listeners are disabled — Mantine's Popover provides both natively. This component clones the target element to attach an `onClick` toggle handler and a ref, and closes on outside click via a `mousedown` listener on `document` that ignores clicks inside either the target (`targetRef`) or the dropdown content (`dropdownRef`, a wrapper `<div>` around the dropdown children solely for this hit-test — not a styling root). Escape-to-close comes for free from Tooltip's own internal Escape handling once `onClose` is wired up.
+- **`beak-size` token exemption:** Mui's Tooltip arrow is a fixed CSS shape (`1em`/`0.71em`, relative to the tooltip's own `font-size`) with no JS size prop, unlike Mantine's `arrowSize`. There's no hook to bind `--recursica_ui-kit_components_hover-card-popover_properties_beak-size` to, so it's `recursica-ignore`d here (same conceptual gap as HoverCard/Tooltip's existing exemptions for this token family, just for a different reason — those wrote a comment referencing Mantine's inline-pixel arrow calculations, which doesn't apply in this adapter; this file's comment describes the actual Mui-specific reason).
+- **Arrow fill uses `color`, not `border-color`:** HoverCard's and Tooltip's `.arrow` rules in this adapter set `border-color`, which has no visual effect — Mui's Tooltip arrow is a solid rotated-square filled via `background-color: currentColor` in its `::before`, not a bordered shape. This component's `.arrow` instead sets `color` to the panel's `background-color` token, which actually renders. Intentional deviation from the HoverCard/Tooltip precedent for correctness; not fixed there as it's out of scope for this change.
+- **Shared token namespace:** Same as HoverCard, this component's CSS module exclusively uses `--recursica_ui-kit_components_hover-card-popover_*` tokens (geometry, typography, elevation, layer-aware colors) — no Popover-specific token namespace exists in the schema.
+- **`width` and controlled `opened`/`onChange`:** Not present in the shared `RecursicaPopoverProps` (adapter-common only defines `withBeak`), these are defined locally in `PopoverOwnProps` to match Mantine's own `PopoverProps` surface, since there is no single Mui library type that already provides them.
+
+## Gap larger than Mantine's on `withBeak={false}` (Matt Massey, 2026-08-19)
+
+**Root cause:** Mui's `Tooltip` styled component ships its own hardcoded per-placement margin (`marginTop`/`marginBottom`: `14px`, or `24px` in touch mode) on the tooltip content div, applied whenever `arrow` is falsy (the `arrow` variant resets it to `margin: 0`). This stacked on top of the `offset` popper modifier already applied in `Popover.tsx` (which alone reproduces Mantine's own gap — Mantine's Popover defaults to an 8px `offset`, the same value used here), so the visible gap was `8 + 14 = 22px` instead of `8px` with `withBeak={false}`.
+
+**Fix:** neutralize Mui's built-in margin in `Popover.module.css` via `:global(.MuiTooltip-popper[data-popper-placement]) .dropdown { margin: 0; }`, matching Mui's own rule's specificity (class + attribute + class) so it wins on source order under `injectFirst`. The `offset` modifier is now the single source of truth for the gap, matching Mantine.
+
+## Beak had no visible edge against the dropdown body (Matt Massey, 2026-08-19)
+
+**Root cause:** Mantine's arrow is a bordered shape — `.arrow { border-color: ... }` — visible because Mantine's own arrow implementation sets `border-width` natively. Mui's arrow `::before` pseudo-element has no border at all by default (just `background-color: currentColor`), so setting only `color` (as this component already did, to fill the triangle) left it with zero visible edge against a similarly-colored panel.
+
+**Fix:** added `.arrow::before { border-style: solid; border-width: ...border-size; border-color: ...colors_border-color; }`, the same border tokens the `.dropdown` container itself uses — verified live (Playwright) that the arrow now shows a visible border matching Mantine's.