@recursica/mantine-adapter 0.48.1 → 0.50.0

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 { renderRichOption } 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 floating/portal menu — 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) combobox dropdown. 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}>
+        {renderRichOption(
+          { option: 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

@@ -3,7 +3,10 @@ import {
   Select as MantineSelect,
   type SelectProps as MantineSelectProps,
 } from "@mantine/core";
-import { type ReadOnlyControlProps } from "@recursica/adapter-common";
+import {
+  type ReadOnlyControlProps,
+  normalizeComboboxData,
+} from "@recursica/adapter-common";
 import {
   filterStylingProps,
   omitUnsupportedProps,
@@ -12,6 +15,7 @@ import {
 } from "../../utils/filterStylingProps";
 import { type RecursicaFormControlWrapperProps } from "../FormControlWrapper/FormControlWrapper";
 import { WithReadOnlyWrapper } from "../ReadOnlyField/WithReadOnlyWrapper";
+import { renderRichOption } from "../../utils/renderRichOption";
 import styles from "./Dropdown.module.css";
 
 import { type RecursicaDropdownProps as BaseRecursicaDropdownProps } from "@recursica/adapter-common";
@@ -69,6 +73,8 @@ export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
       defaultValue,
       data,
       clearButtonProps,
+      renderOption,
+      wrapItemText = false,
       ...rest
     } = props;
     const sanitizedProps = omitUnsupportedProps(
@@ -77,6 +83,13 @@ export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
     );
     const restRecord = sanitizedProps as Record<string, unknown>;
 
+    // Mantine's own data parser only preserves extra fields (`leadingIcon`/`supportingText`) when
+    // an item already has both `value` and `label` — an item with `value` only is rebuilt into a
+    // bare `{value, label: value, disabled}` object, silently dropping them (see
+    // get-parsed-combobox-data.mjs, and AutoComplete.tsx's identical use of this). Matters here
+    // too now that `label` is optional (shared `RecursicaComboboxItem` — see adapter-common).
+    const normalizedData = normalizeComboboxData(data);
+
     // Mantine's own clear button (rendered when `clearable` + a value are both present) otherwise
     // renders unstyled — bare `CloseButton` defaults, no Recursica icon-button treatment. Merge in
     // our own class (see `.clearButton` in Dropdown.module.css) alongside anything the caller
@@ -104,6 +117,14 @@ export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
       restRecord.classNames as Partial<Record<string, string>> | undefined,
     );
 
+    const optionClassNames = {
+      optionContent: styles.optionContent,
+      optionIcon: styles.optionIcon,
+      optionText: styles.optionText,
+      optionTextWrap: styles.optionTextWrap,
+      optionSupportingText: styles.optionSupportingText,
+    };
+
     const injectedStyles = {
       ...((style as React.CSSProperties) || {}),
       width: containerWidth || "100%",
@@ -154,7 +175,14 @@ export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
             disabled={disabled}
             value={value}
             defaultValue={defaultValue}
-            data={(data as unknown as MantineSelectProps["data"]) || []}
+            data={
+              (normalizedData as unknown as MantineSelectProps["data"]) || []
+            }
+            renderOption={
+              renderOption ??
+              ((input) =>
+                renderRichOption(input, optionClassNames, wrapItemText))
+            }
             clearButtonProps={mergedClearButtonProps}
             label={undefined}
             description={undefined}

package/src/components/Dropdown/USAGE.md

@@ -46,3 +46,24 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 - `Dropdown` is styled independently from `TextField`; even though they look similar, they are themed using separate design tokens.
 - Pass `leftSection` 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.
+- `data` items can carry a `leadingIcon` and `supportingText`, rendered inside each option row:
+
+  ```tsx
+  <Dropdown
+    label="Assignee"
+    data={[
+      {
+        value: "jdoe",
+        label: "Jane Doe",
+        leadingIcon: <UserIcon />,
+        supportingText: "jane.doe@example.com",
+      },
+      { value: "asmith", label: "Alex Smith" },
+    ]}
+  />
+  ```
+
+  Pass your own `renderOption` to opt out of this default rendering for a given instance.
+
+  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/MENU_IMPLEMENTATION_NOTES.md

@@ -76,3 +76,13 @@ Decisions and design tweaks strictly tailored for the UI Kit's Menu wrapped agai
 - `pointer-events` on disabled items (Mantine handles disabled natively)
 
 **Rationale:** Early iterations included aggressive structural resets (like `overflow: hidden`, `box-sizing: border-box`, `margin: 0`) cargo-culted from the Dropdown component. These caused sub-menus to render clipped inside the parent dropdown with scrollbars. The lesson: default to Mantine's native behavior and only override what the Recursica token system explicitly needs to control.
+
+---
+
+## 9. `maxHeight` Override
+
+**Decision:** `<Menu maxHeight={...}>` lets a caller override the token-driven `.dropdown` max-height with an explicit pixel (or other CSS length) value.
+
+**Implementation:** This is the one deliberate exception to "no inline design tokens in TSX" (see `COMPONENT_DEV_GUIDE.md`) — it's applied via Mantine's per-part `styles` API (`styles={{ dropdown: { maxHeight } }}`), the same mechanism already used for `classNames`, merged with any caller-supplied `styles`. It only takes effect when `maxHeight` is actually passed; otherwise the CSS module's token-driven `max-height` is untouched.
+
+**Caveat:** Because sub-menu dropdowns inherit the root Menu's `classNames`/`styles` mapping (see §6), setting `maxHeight` on the root also caps `Menu.Sub.Dropdown`'s height, not just the top-level dropdown.

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

@@ -161,6 +161,11 @@ const meta: Meta = {
       description:
         "Controlled open state. Leave undefined for uncontrolled behavior.",
     },
+    maxHeight: {
+      control: "number",
+      description:
+        "Overrides the token-driven dropdown max-height with an explicit pixel value.",
+    },
   },
   parameters: {
     docs: {
@@ -303,6 +308,43 @@ export const WithSubmenus: Story = {
   },
 };
 
+export const WithMaxHeight: Story = {
+  args: {
+    position: "bottom-start",
+    maxHeight: 160,
+    // Rendered open by default so this story is diffable against the MUI adapter
+    // without an interaction step.
+    opened: true,
+  },
+  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.",
+      },
+    },
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  render: ({ withLayer, layer, ...args }: MenuStoryArgs) => {
+    return (
+      <Menu {...args}>
+        <Menu.Target>
+          <Button variant="solid">Menu with maxHeight</Button>
+        </Menu.Target>
+
+        <Menu.Dropdown>
+          <Menu.Item leftSection={<SettingsIcon />}>Settings</Menu.Item>
+          <Menu.Item leftSection={<MessageIcon />}>Messages</Menu.Item>
+          <Menu.Item leftSection={<ImageIcon />}>Gallery</Menu.Item>
+          <Menu.Item leftSection={<SearchIcon />}>Search</Menu.Item>
+          <Menu.Item leftSection={<ArrowsIcon />}>Transfer my data</Menu.Item>
+          <Menu.Item leftSection={<TrashIcon />}>Delete my account</Menu.Item>
+        </Menu.Dropdown>
+      </Menu>
+    );
+  },
+};
+
 export const HoverTrigger: Story = {
   args: {
     trigger: "click-hover",

package/src/components/Menu/Menu.tsx

@@ -1,4 +1,4 @@
-import { forwardRef } from "react";
+import { forwardRef, type CSSProperties } from "react";
 import {
   Menu as MantineMenu,
   type MenuProps as MantineMenuProps,
@@ -49,6 +49,7 @@ export type MenuProps = RecursicaOverStyled<
 const MenuBase = function Menu({ overStyled = false, ...rest }: MenuProps) {
   const sanitizedProps = filterStylingProps(rest, overStyled);
   const restRecord = sanitizedProps as Record<string, unknown>;
+  const { maxHeight, ...menuRestRecord } = restRecord;
 
   // Bind CSS module classes to Mantine's internal classNames API
   const mergedClassNames = mergeClassNames(
@@ -64,10 +65,31 @@ const MenuBase = function Menu({ overStyled = false, ...rest }: MenuProps) {
     restRecord.classNames as Partial<Record<string, string>> | undefined,
   );
 
+  // `maxHeight` is a caller-supplied override of the token-driven dropdown max-height, applied
+  // via Mantine's per-part `styles` API (same mechanism as `classNames` above) rather than a CSS
+  // module change, since it's an explicit per-instance escape hatch, not a design token. The CSS
+  // module deliberately leaves `overflow` unset (see MENU_IMPLEMENTATION_NOTES.md §8) so it
+  // doesn't clip sub-menus at the token default height; once a caller opts into a fixed
+  // `maxHeight`, though, items need to scroll instead of spilling out past the boundary.
+  const callerStyles = menuRestRecord.styles as
+    | Partial<Record<string, CSSProperties>>
+    | undefined;
+  const mergedStyles = maxHeight
+    ? {
+        ...callerStyles,
+        dropdown: {
+          ...callerStyles?.dropdown,
+          maxHeight: maxHeight as CSSProperties["maxHeight"],
+          overflowY: "auto" as CSSProperties["overflowY"],
+        },
+      }
+    : callerStyles;
+
   return (
     <MantineMenu
-      {...(sanitizedProps as unknown as MantineMenuProps)}
+      {...(menuRestRecord as unknown as MantineMenuProps)}
       classNames={mergedClassNames}
+      {...(mergedStyles ? { styles: mergedStyles } : {})}
     />
   );
 };

package/src/components/Menu/USAGE.md

@@ -52,3 +52,4 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 - The full Mantine composition API is supported, including sub-menus: `Menu`, `Menu.Target`, `Menu.Dropdown`, `Menu.Item`, `Menu.Divider`, `Menu.Label`, `Menu.Sub`, `Menu.Sub.Target`, `Menu.Sub.Item`, and `Menu.Sub.Dropdown`.
 - The `color` prop on `Menu.Item` (and `Menu.Sub.Item`) — used by Mantine for semantics like a "danger" item — is ignored unless `overStyled={true}` is set.
+- `maxHeight` on the root `<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,65 @@
+import React from "react";
+import {
+  type ComboboxStringItem,
+  type ComboboxLikeRenderOptionInput,
+} from "@mantine/core";
+
+// `ComboboxStringItem`/`ComboboxItem` only type `value`/`label`/`disabled` —
+// `leadingIcon`/`supportingText` are extra fields Mantine's own `getParsedComboboxData` passes
+// through untouched whenever an item already has both `value` and `label` (see
+// get-parsed-combobox-data.mjs), so they reach `option` here at runtime even though the upstream
+// type doesn't know about them. Generic over both Autocomplete's `ComboboxStringItem` (optional
+// `label`) and Dropdown's `ComboboxItem` (required `label`) — the same renderer serves both.
+type RichComboboxItem = ComboboxStringItem & {
+  label?: string;
+  leadingIcon?: React.ReactNode;
+  supportingText?: string;
+};
+
+export interface RichOptionClassNames {
+  optionContent: string;
+  optionIcon: string;
+  optionText: string;
+  /** Combined with `optionText` when `wrapItemText` is true — see `renderRichOption` below. */
+  optionTextWrap: string;
+  optionSupportingText: string;
+}
+
+/**
+ * `renderOption` for Autocomplete/Dropdown that renders an item's `leadingIcon`/`supportingText`
+ * (see MANTINE_ADAPTER_RICH_OPTION_DATA.md) inside the option row. Falls back to plain
+ * `option.label` — the same rendering Mantine uses when no `renderOption` is supplied at all — so
+ * items without the new fields are unaffected.
+ *
+ * `wrapItemText` (default `false`) controls whether `label`/`supportingText` wrap onto additional
+ * lines or truncate to a single line with an ellipsis.
+ */
+export function renderRichOption<T extends ComboboxStringItem>(
+  { option }: ComboboxLikeRenderOptionInput<T>,
+  classNames: RichOptionClassNames,
+  wrapItemText = false,
+): React.ReactNode {
+  const { label, leadingIcon, supportingText } = option as RichComboboxItem;
+  const displayLabel = label ?? option.value;
+  if (!leadingIcon && !supportingText) {
+    return displayLabel;
+  }
+  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>{displayLabel}</span>
+        {supportingText && (
+          <span className={classNames.optionSupportingText}>
+            {supportingText}
+          </span>
+        )}
+      </span>
+    </span>
+  );
+}