@recursica/mui-adapter 0.32.1 → 0.34.0

package/src/components/Dropdown/Dropdown.module.css

@@ -366,12 +366,25 @@
   color: var(
     --recursica_ui-kit_components_dropdown_properties_colors_text-color
   );
-  padding: calc(
-      var(--recursica_ui-kit_components_dropdown_properties_vertical-padding) *
-        0.75
+  /* Padding/inter-item gap reuse the menu-item component's tokens (same reasoning as the icon/
+     supporting-text tokens below) instead of an arbitrary scaled dropdown padding — matches the
+     mantine-adapter's equivalent Menu.module.css `.item` padding + gap exactly. `!important` on
+     padding: MUI's `MenuItem` root sets its own paddingTop/Bottom (MenuItem.js) plus paddingLeft/
+     Right 16px via its `gutters` variant, both at equal selector specificity to this rule, so
+     without it the winner depends on emotion's injection order rather than this stylesheet. */
+  padding: var(
+      --recursica_ui-kit_components_menu-item_properties_vertical-padding
     )
-    var(--recursica_ui-kit_components_dropdown_properties_horizontal-padding);
+    var(--recursica_ui-kit_components_menu-item_properties_horizontal-padding) !important;
+  margin-bottom: var(--recursica_ui-kit_components_menu_properties_item-gap);
   cursor: pointer;
+  /* MUI's `MenuItem` also forces `white-space: nowrap` by default; override it so long
+     labels/supportingText wrap instead of overflowing. Same equal-specificity reasoning. */
+  white-space: normal !important;
+}
+
+.option:last-of-type {
+  margin-bottom: 0;
 }
 
 /* No per-option hovered token exists in the schema; use the generic overlay tint (same technique
@@ -402,3 +415,99 @@
     --recursica_ui-kit_components_menu-item_variants_selection-states_selected_properties_colors_text-color
   ) !important;
 }
+
+/* Rich option content (leadingIcon/supportingText — see MANTINE_ADAPTER_RICH_OPTION_DATA.md). No
+   dedicated dropdown-option icon or supporting-text token exists in the schema either; reuse the
+   menu-item component's tokens for the same reason the selected-state colors above do. Matches
+   the mantine-adapter's equivalent classes. */
+.optionContent {
+  display: flex;
+  align-items: center;
+  gap: var(--recursica_ui-kit_components_menu-item_properties_icon-text-gap);
+}
+
+.optionIcon {
+  display: flex;
+  flex-shrink: 0;
+  width: var(
+    --recursica_ui-kit_components_menu-item_properties_icon-leading-size
+  );
+  height: var(
+    --recursica_ui-kit_components_menu-item_properties_icon-leading-size
+  );
+  color: var(
+    --recursica_ui-kit_components_menu-item_variants_selection-states_unselected_properties_colors_leading-icon-color
+  );
+}
+
+.optionIcon :global(svg) {
+  width: 100%;
+  height: 100%;
+}
+
+.optionText {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  gap: var(--recursica_ui-kit_components_menu-item_properties_text-gap);
+}
+
+/* Default: label/supportingText each truncate to a single line with an ellipsis. */
+.optionText > * {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* Applied alongside .optionText when `wrapItemText` is true — long values wrap onto additional
+   lines instead of overflowing the fixed-width dropdown. */
+.optionTextWrap > * {
+  overflow: visible;
+  text-overflow: clip;
+  white-space: normal;
+  overflow-wrap: anywhere;
+}
+
+.optionSupportingText {
+  font-family: var(
+    --recursica_ui-kit_components_menu-item_properties_supporting-text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_menu-item_properties_supporting-text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_menu-item_properties_supporting-text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_menu-item_properties_supporting-text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_menu-item_properties_supporting-text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_menu-item_properties_supporting-text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_menu-item_properties_supporting-text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_menu-item_properties_supporting-text_text-transform
+  );
+  color: var(
+    --recursica_ui-kit_components_menu-item_variants_selection-states_unselected_properties_colors_supporting-text-color
+  );
+}
+
+.option[data-selected="true"] .optionIcon,
+.option[data-combobox-selected="true"] .optionIcon {
+  color: var(
+    --recursica_ui-kit_components_menu-item_variants_selection-states_selected_properties_colors_leading-icon-color
+  ) !important;
+}
+
+.option[data-selected="true"] .optionSupportingText,
+.option[data-combobox-selected="true"] .optionSupportingText {
+  color: var(
+    --recursica_ui-kit_components_menu-item_variants_selection-states_selected_properties_colors_supporting-text-color
+  ) !important;
+}

package/src/components/Dropdown/Dropdown.stories.tsx

@@ -2,6 +2,8 @@ import React from "react";
 import type { Meta, StoryObj } from "@storybook/react";
 import { Dropdown } from "./Dropdown";
 import { formControlArgTypes } from "../../../.storybook/commonArgTypes";
+import { renderRichOptionContent } from "../../utils/renderRichOption";
+import styles from "./Dropdown.module.css";
 
 type DropdownStoryProps = React.ComponentProps<typeof Dropdown>;
 
@@ -42,6 +44,11 @@ const meta: Meta<DropdownStoryProps> = {
     clearable: {
       control: "boolean",
     },
+    wrapItemText: {
+      control: "boolean",
+      description:
+        "Wraps option label/supportingText onto additional lines instead of truncating with an ellipsis.",
+    },
     containerWidth: {
       table: { disable: true },
     },
@@ -86,6 +93,148 @@ export const WithLeadingIcon: Story = {
   },
 };
 
+const UserIcon = (
+  <svg
+    width="16"
+    height="16"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="2"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+  >
+    <path d="M20 21v-2a4 4 0 0 0-4-4H8a4 4 0 0 0-4 4v2"></path>
+    <circle cx="12" cy="7" r="4"></circle>
+  </svg>
+);
+
+export const WithRichOptions: Story = {
+  args: {
+    label: "Assignee",
+    placeholder: "Pick a team member",
+    assistiveText:
+      "Each option can show a leading icon and supporting text — see MANTINE_ADAPTER_RICH_OPTION_DATA.md.",
+    data: [
+      {
+        value: "jdoe",
+        label: "Jane Doe",
+        leadingIcon: UserIcon,
+        supportingText: "jane.doe@example.com",
+      },
+      {
+        value: "asmith",
+        label: "Alex Smith",
+        leadingIcon: UserIcon,
+        supportingText: "alex.smith@example.com",
+      },
+      { value: "unassigned", label: "Unassigned" },
+    ],
+  },
+};
+
+export const WithRichOptionsWrapped: Story = {
+  args: {
+    label: "Assignee",
+    placeholder: "Pick a team member",
+    wrapItemText: true,
+    data: [
+      {
+        value: "jdoe",
+        label: "Jane Doe, Senior Staff Engineer, Platform Infrastructure",
+        leadingIcon: UserIcon,
+        supportingText:
+          "jane.doe@example.com — Platform Infrastructure team, on-call rotation lead",
+      },
+      { value: "unassigned", label: "Unassigned" },
+    ],
+    assistiveText:
+      "wrapItemText=true — long label/supportingText wrap instead of truncating.",
+  },
+};
+
+const optionRowPreviewClassNames = {
+  optionContent: styles.optionContent,
+  optionIcon: styles.optionIcon,
+  optionText: styles.optionText,
+  optionTextWrap: styles.optionTextWrap,
+  optionSupportingText: styles.optionSupportingText,
+};
+
+const OPTION_ROW_PREVIEW_ITEMS = [
+  {
+    value: "icon-and-supporting",
+    label: "Jane Doe",
+    leadingIcon: UserIcon,
+    supportingText: "jane.doe@example.com",
+  },
+  {
+    value: "no-icon",
+    label: "Alex Smith",
+    supportingText:
+      "No leadingIcon — label/supportingText shift left, no reserved icon space",
+  },
+  {
+    value: "no-supporting-text",
+    label: "Taylor Rivera",
+    leadingIcon: UserIcon,
+  },
+  {
+    value: "plain",
+    label: "Plain option — no leadingIcon, no supportingText",
+  },
+  {
+    value: "long-text",
+    label:
+      "A very long option label that, with wrapItemText, wraps onto a second line instead of overflowing the fixed-width dropdown — otherwise it truncates with an ellipsis",
+    leadingIcon: UserIcon,
+    supportingText:
+      "A similarly long supporting text string, to confirm the same wrap-or-truncate behavior applies to it too",
+  },
+];
+
+// Renders the option row content directly — outside the MUI Menu portal — inside a container
+// sized to Dropdown's own max-width token. Spacing between rows, icon/supportingText presence-
+// or-absence alignment, and long-text wrapping/truncation are all much easier to inspect this way
+// than by opening the real (portal-rendered) MUI Select menu. See
+// MANTINE_ADAPTER_RICH_OPTION_DATA.md.
+const renderOptionRowPreview = (wrapItemText: boolean) => (
+  <div
+    className={styles.dropdown}
+    style={{
+      width:
+        "var(--recursica_ui-kit_components_dropdown_variants_layouts_stacked_properties_max-width)",
+    }}
+  >
+    {OPTION_ROW_PREVIEW_ITEMS.map((item) => (
+      <div key={item.value} className={styles.option}>
+        {renderRichOptionContent(
+          item,
+          optionRowPreviewClassNames,
+          wrapItemText,
+        )}
+      </div>
+    ))}
+  </div>
+);
+
+// Default: `wrapItemText` is false — label/supportingText truncate to a single line with an
+// ellipsis instead of wrapping.
+export const RichOptionRowPreview: Story = {
+  parameters: {
+    controls: { disable: true },
+  },
+  render: () => renderOptionRowPreview(false),
+};
+
+// `wrapItemText: true` — label/supportingText wrap onto additional lines instead of truncating.
+export const RichOptionRowPreviewWrapped: Story = {
+  parameters: {
+    controls: { disable: true },
+  },
+  render: () => renderOptionRowPreview(true),
+};
+
 export const StaticError: Story = {
   args: {
     error: "You must choose a valid destination.",

package/src/components/Dropdown/Dropdown.tsx

@@ -5,7 +5,10 @@ import {
   SelectChangeEvent,
   MenuItem,
 } from "@mui/material";
-import { type ReadOnlyControlProps } from "@recursica/adapter-common";
+import {
+  type ReadOnlyControlProps,
+  normalizeComboboxData,
+} from "@recursica/adapter-common";
 import {
   filterStylingProps,
   omitUnsupportedProps,
@@ -13,6 +16,7 @@ import {
 } from "../../utils/filterStylingProps";
 import { type RecursicaFormControlWrapperProps } from "../FormControlWrapper/FormControlWrapper";
 import { WithReadOnlyWrapper } from "../ReadOnlyField/WithReadOnlyWrapper";
+import { renderRichOptionContent } from "../../utils/renderRichOption";
 import { ChevronIcon, ClearIcon } from "./Dropdown.icons";
 import styles from "./Dropdown.module.css";
 
@@ -86,6 +90,7 @@ export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
       // eslint-disable-next-line @typescript-eslint/no-unused-vars
       searchable, // Not natively supported by basic MUI Select, stubbed
       clearable,
+      wrapItemText = false,
       ...rest
     } = props;
     // Props this component intentionally doesn't support — deleted at runtime so they can't leak
@@ -151,9 +156,22 @@ export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
       ? `${styles.layoutOverride} ${className}`
       : styles.layoutOverride;
 
+    const optionClassNames = {
+      optionContent: styles.optionContent,
+      optionIcon: styles.optionIcon,
+      optionText: styles.optionText,
+      optionTextWrap: styles.optionTextWrap,
+      optionSupportingText: styles.optionSupportingText,
+    };
+
+    // See AutoComplete.tsx's identical use of `normalizeComboboxData` (adapter-common) — items
+    // always have a real `label` after this, so downstream code doesn't need its own `?? value`
+    // fallback at every read.
+    const normalizedData = normalizeComboboxData(data);
+
     const renderOptions = () => {
-      if (!data) return null;
-      return data.map((item, index) => {
+      if (!normalizedData) return null;
+      return normalizedData.map((item, index) => {
         if (typeof item === "string") {
           return (
             <MenuItem
@@ -179,12 +197,26 @@ export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
             disableRipple
             data-selected={item.value === internalValue ? "true" : undefined}
           >
-            {item.label}
+            {renderRichOptionContent(item, optionClassNames, wrapItemText)}
           </MenuItem>
         );
       });
     };
 
+    // MUI's closed-field display otherwise mirrors the selected `MenuItem`'s children directly —
+    // now that those can be a rich icon+label+supportingText row, `renderValue` keeps the closed
+    // field showing just the plain label, matching the field's own single-line text control.
+    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;
+    };
+
     const wrappedStartAdornment = startAdornment ? (
       <span className={styles.section} data-position="left">
         {startAdornment}
@@ -246,6 +278,7 @@ export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
             error={!!error}
             required={required}
             displayEmpty
+            renderValue={renderValue}
             className={styles.root}
             classes={{
               select: styles.input,

package/src/components/Dropdown/USAGE.md

@@ -46,3 +46,23 @@ All Recursica components in the `@recursica/mui-adapter` package adhere strictly
 
 - Pass `startAdornment` for a leading icon, and `clearable` (with a value present) to show a clear button — both render using the dropdown's own icon-color tokens, matching the mantine-adapter's `leftSection`/`clearable` behavior.
 - `onChange` follows MUI's native `Select` signature: `(event: SelectChangeEvent, child: ReactNode) => void`.
+- `data` items can carry a `leadingIcon` and `supportingText`, rendered inside each option row
+  (the closed field always shows the plain `label`, matching the mantine-adapter):
+
+  ```tsx
+  <Dropdown
+    label="Assignee"
+    data={[
+      {
+        value: "jdoe",
+        label: "Jane Doe",
+        leadingIcon: <UserIcon />,
+        supportingText: "jane.doe@example.com",
+      },
+      { value: "asmith", label: "Alex Smith" },
+    ]}
+  />
+  ```
+
+  By default `label`/`supportingText` truncate to a single line with an ellipsis. Set
+  `wrapItemText` to wrap them onto additional lines instead: `<Dropdown data={data} wrapItemText />`.

package/src/components/Menu/IMPLEMENTATION_NOTES.md

@@ -2,3 +2,4 @@
 
 - **Compositional API Dropped:** Mantine uses `<Menu.Target>`, `<Menu.Dropdown>`, `<Menu.Item>`, etc., and manages state natively via React context within `<Menu>`. MUI's API is fully monolithic.
 - **Monolithic API Adopted:** Following architectural review, we have abandoned the fabricated context wrappers for `mui-adapter`. We now natively export `Menu`, `MenuItem`, and `MenuDivider` wrapping their `@mui/material` counterparts. Developers are expected to manage `anchorEl` state themselves, just like native MUI. Storybook tests have been updated to simulate this open state so visual regressions still cover the dropdown menu visually.
+- **`maxHeight` Override:** `<Menu maxHeight={...}>` overrides the token-driven dropdown max-height with an explicit pixel (or other CSS length) value — the one deliberate exception to "no inline design tokens in TSX" (see `COMPONENT_DEV_GUIDE.md`). Implemented by merging `maxHeight` into `slotProps.paper.style`, alongside any caller-supplied `slotProps`, rather than a CSS module change; the CSS module's token-driven `max-height` stays untouched when the prop isn't passed.

package/src/components/Menu/Menu.stories.tsx

@@ -300,6 +300,43 @@ export const WithSubmenus: Story = {
   },
 };
 
+export const WithMaxHeight: Story = {
+  render: (args) => (
+    <InteractiveMenu {...args}>
+      <MenuItem>
+        <SettingsIcon style={{ marginRight: 8 }} /> Settings
+      </MenuItem>
+      <MenuItem>
+        <MessageIcon style={{ marginRight: 8 }} /> Messages
+      </MenuItem>
+      <MenuItem>
+        <ImageIcon style={{ marginRight: 8 }} /> Gallery
+      </MenuItem>
+      <MenuItem>
+        <SearchIcon style={{ marginRight: 8 }} /> Search
+      </MenuItem>
+      <MenuItem>
+        <ArrowsIcon style={{ marginRight: 8 }} /> Transfer my data
+      </MenuItem>
+      <MenuItem>
+        <TrashIcon style={{ marginRight: 8 }} /> Delete my account
+      </MenuItem>
+    </InteractiveMenu>
+  ),
+  args: {
+    opened: true,
+    maxHeight: 160,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "`maxHeight` overrides the token-driven dropdown max-height with an explicit pixel value, scrolling the item list once it's exceeded.",
+      },
+    },
+  },
+};
+
 // mui-adapter's Menu has no native hover-trigger support (unlike Mantine's `trigger` prop),
 // so this story implements open-on-hover itself: hovering the target opens the menu, and a
 // short close delay (mirroring Mantine's `closeDelay`) keeps it open while the pointer moves

package/src/components/Menu/Menu.tsx

@@ -1,4 +1,4 @@
-import { forwardRef } from "react";
+import { forwardRef, type CSSProperties } from "react";
 import {
   Menu as MuiMenu,
   type MenuProps as MuiMenuProps,
@@ -19,27 +19,47 @@ import { type RecursicaMenuProps } from "@recursica/adapter-common";
 export type MenuProps = RecursicaOverStyled<MuiMenuProps & RecursicaMenuProps>;
 
 export const Menu = forwardRef<HTMLDivElement, MenuProps>(function Menu(
-  { overStyled = false, className, ...rest },
+  { overStyled = false, className, maxHeight, ...rest },
   ref,
 ) {
   const sanitizedProps = filterStylingProps(rest, overStyled);
+  const restRecord = sanitizedProps as Record<string, unknown>;
 
   const mergedClassNames = mergeClassNames(
     {
       paper: styles.dropdown,
       list: styles.dropdown,
     },
-    (sanitizedProps as Record<string, unknown>).classes as
-      | Partial<Record<string, string>>
-      | undefined,
+    restRecord.classes as Partial<Record<string, string>> | undefined,
   );
 
+  // `maxHeight` is a caller-supplied override of the token-driven dropdown max-height, applied
+  // to the Paper slot's inline style — an explicit per-instance escape hatch, not a design token.
+  const callerSlotProps = restRecord.slotProps as
+    | { paper?: Record<string, unknown> }
+    | undefined;
+  const mergedSlotProps = maxHeight
+    ? {
+        ...callerSlotProps,
+        paper: {
+          ...callerSlotProps?.paper,
+          style: {
+            ...(callerSlotProps?.paper?.style as CSSProperties | undefined),
+            maxHeight,
+          },
+        },
+      }
+    : callerSlotProps;
+
   return (
     <MuiMenu
       ref={ref}
       {...(sanitizedProps as MuiMenuProps)}
       className={className}
       classes={mergedClassNames}
+      {...(mergedSlotProps
+        ? { slotProps: mergedSlotProps as MuiMenuProps["slotProps"] }
+        : {})}
     />
   );
 });

package/src/components/Menu/USAGE.md

@@ -45,3 +45,9 @@ 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. Notes
+
+- `maxHeight` on `<Menu>` overrides the dropdown's token-driven max-height with an explicit pixel (or other CSS length) value, e.g. `<Menu maxHeight={320}>`. It's a per-instance escape hatch, not a design token — leave it unset to use the token default.

package/src/utils/renderRichOption.tsx

@@ -0,0 +1,51 @@
+import React from "react";
+import { type RecursicaComboboxItemWithLabel } from "@recursica/adapter-common";
+
+export interface RichOptionClassNames {
+  optionContent: string;
+  optionIcon: string;
+  optionText: string;
+  /** Combined with `optionText` when `wrapItemText` is true — see `renderRichOptionContent` below. */
+  optionTextWrap: string;
+  optionSupportingText: string;
+}
+
+/**
+ * `MenuItem`/option children for Dropdown/Autocomplete that renders `leadingIcon`/`supportingText`
+ * (see MANTINE_ADAPTER_RICH_OPTION_DATA.md) inside the row. Falls back to plain `label` when
+ * neither is present, so items without the new fields render exactly as before.
+ *
+ * `wrapItemText` (default `false`) controls whether `label`/`supportingText` wrap onto additional
+ * lines or truncate to a single line with an ellipsis.
+ */
+export function renderRichOptionContent(
+  item: Pick<
+    RecursicaComboboxItemWithLabel,
+    "label" | "leadingIcon" | "supportingText"
+  >,
+  classNames: RichOptionClassNames,
+  wrapItemText = false,
+): React.ReactNode {
+  const { label, leadingIcon, supportingText } = item;
+  if (!leadingIcon && !supportingText) {
+    return label;
+  }
+  const optionTextClassName = wrapItemText
+    ? `${classNames.optionText} ${classNames.optionTextWrap}`
+    : classNames.optionText;
+  return (
+    <span className={classNames.optionContent}>
+      {leadingIcon && (
+        <span className={classNames.optionIcon}>{leadingIcon}</span>
+      )}
+      <span className={optionTextClassName}>
+        <span>{label}</span>
+        {supportingText && (
+          <span className={classNames.optionSupportingText}>
+            {supportingText}
+          </span>
+        )}
+      </span>
+    </span>
+  );
+}