@recursica/mui-adapter 0.32.1 → 0.34.0

package/package.json

@@ -13,7 +13,7 @@
     "url": "git+https://github.com/borderux/recursica.git",
     "directory": "packages/mui-adapter"
   },
-  "version": "0.32.1",
+  "version": "0.34.0",
   "publishConfig": {
     "access": "public"
   },
@@ -102,7 +102,7 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@recursica/adapter-common": "^0.23.0",
+    "@recursica/adapter-common": "^0.25.0",
     "@recursica/official-release": "^2.8.0",
     "dayjs": "^1.11.21"
   },

package/src/components/Autocomplete/AUTOCOMPLETE_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,17 @@
+# Autocomplete 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). `Autocomplete.tsx` runs `data` through adapter-common's `normalizeComboboxData` first (backfills `label` from `value`, since `label` on the shared type is optional), then installs a default `renderOption` that renders each option's `<li>` via `renderRichOptionContent` (`../../utils/renderRichOption.tsx`, shared with `Dropdown`) — `leadingIcon`+`label`+`supportingText` when either new field is present, or just `label` otherwise. A caller-supplied `renderOption` always wins over the default. 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`.
+
+Unlike Dropdown, this doesn't need an explicit `renderValue`-equivalent fix: MUI's `Autocomplete` already separates the closed field's text (driven by `getOptionLabel`, which defaults to `option.label`) from the open dropdown's row rendering (`renderOption`), so enriching `renderOption` alone doesn't touch what the closed field shows.
+
+New CSS classes (`.optionContent`/`.optionIcon`/`.optionText`/`.optionSupportingText`) in `Autocomplete.module.css` reuse the menu-item component's icon/supporting-text tokens, matching the mantine-adapter's equivalent addition — no dedicated autocomplete-option tokens exist for either.
+
+## `wrapItemText`
+
+`label`/`supportingText` default to single-line truncation with an ellipsis (`.optionText > *` — `overflow: hidden; 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.
+
+## Selected Option Highlight (bug fix)
+
+There was previously no rule at all for "this option matches the current value" — only the shared neutral hover tint, and only while actually hovered. MUI's `Autocomplete` already stamps `aria-selected="true"` onto the matching option (`useAutocomplete.js`'s `getOptionProps`), and `defaultRenderOption` spreads `liProps` (which includes it) straight onto the `<li>`, so the DOM signal was already there — `.option[aria-selected="true"]` now maps it to the same menu-item selected-state background/text-color tokens Dropdown uses. Needs `!important`: MUI's own `.MuiAutocomplete-listbox .MuiAutocomplete-option[aria-selected="true"]` rule (`Autocomplete.js`) is a two-class descendant selector — higher specificity than this single-class rule — and paints its own default blue tint otherwise, same reasoning as the padding `!important` above. Verified via Playwright: `aria-selected="true"` plus the token background color both land on the correct option after a plain click-select-reopen.

package/src/components/Autocomplete/Autocomplete.module.css

@@ -227,26 +227,33 @@
   color: var(
     --recursica_ui-kit_components_autocomplete_properties_colors_text-color
   );
-  padding: calc(
-      var(
-          --recursica_ui-kit_components_autocomplete_properties_vertical-padding
-        ) *
-        0.5
+  /* 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 autocomplete padding — matches
+     the mantine-adapter's equivalent Menu.module.css `.item` padding + gap exactly. `!important`
+     needed on padding: MUI's own `.MuiAutocomplete-listbox .MuiAutocomplete-option` rule
+     (hardcoded `6px 16px`) is a two-class descendant selector, higher specificity than this
+     single-class rule, and otherwise wins regardless of source order. */
+  padding: var(
+      --recursica_ui-kit_components_menu-item_properties_vertical-padding
     )
-    var(
-      --recursica_ui-kit_components_autocomplete_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;
 }
 
-/* No per-option selected/hovered tokens exist in the schema; use the generic overlay tint
-   (same technique as Table/Dropdown) to highlight the active option. */
+.option:last-of-type {
+  margin-bottom: 0;
+}
+
+/* No per-option hovered token exists in the schema; use the generic overlay tint (same technique
+   as Table/Dropdown) to highlight a hovered-but-not-selected option. `data-combobox-selected`/
+   `data-combobox-active`/`data-hovered` are Mantine-only attributes that never actually appear on
+   this MUI-driven tree — kept here only so this stays shape-matched with the mantine-adapter's
+   equivalent file. */
 .option[data-selected="true"],
 .option[data-selected],
 .option[data-combobox-selected="true"],
 .option[data-combobox-selected],
-.option[data-combobox-active="true"],
-.option[data-combobox-active],
 .option[data-hovered="true"],
 .option[data-hovered],
 .option:hover {
@@ -258,6 +265,108 @@
   );
 }
 
+/* No dedicated autocomplete-option "selected" token exists in the schema either, but the
+   menu-item component's selected-state colors are the closest real token family for the same
+   concept (a selected row in a list) — same reuse Dropdown.module.css makes. MUI's Autocomplete
+   already stamps `aria-selected="true"` onto the option matching the current value (see
+   useAutocomplete.js's `getOptionProps`), and `defaultRenderOption` (Autocomplete.tsx) spreads
+   that straight onto the `<li>` — there was previously no rule keyed off it at all, so the
+   selected option never got a distinct highlight (only ever the same neutral hover tint above,
+   and only while actually hovered). `!important` needed: MUI's own
+   `.MuiAutocomplete-listbox .MuiAutocomplete-option[aria-selected="true"]` rule (Autocomplete.js)
+   is a two-class descendant selector, higher specificity than this single-class rule, and
+   otherwise wins with its default blue tint regardless of source order — same reasoning as the
+   padding `!important` above. */
+.option[aria-selected="true"] {
+  background-color: var(
+    --recursica_ui-kit_components_menu-item_variants_selection-states_selected_properties_colors_background-color
+  ) !important;
+  color: var(
+    --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 autocomplete-option icon or supporting-text token exists in the schema either; reuse
+   the menu-item component's tokens, same reasoning as Dropdown.module.css. */
+.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
+  );
+}
+
 /* -------------------------------------
    STATE CASCADE ARCHITECTURE
 -------------------------------------- */

package/src/components/Autocomplete/Autocomplete.stories.tsx

@@ -1,6 +1,8 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { Autocomplete as AutoComplete } from "./Autocomplete";
 import { formControlArgTypes } from "../../../.storybook/commonArgTypes";
+import { renderRichOptionContent } from "../../utils/renderRichOption";
+import styles from "./Autocomplete.module.css";
 
 const meta: Meta<typeof AutoComplete> = {
   title: "UI-Kit/AutoComplete",
@@ -55,6 +57,11 @@ Always structure horizontal architectures via the generic \`formLayout\` paramet
       description:
         "Toggles structural read-only data presentation explicitly blocking standard component bindings.",
     },
+    wrapItemText: {
+      control: "boolean",
+      description:
+        "Wraps option label/supportingText onto additional lines instead of truncating with an ellipsis.",
+    },
   },
 };
 
@@ -144,6 +151,148 @@ export const WithTrailingIcon: 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: "Search team members...",
+    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" },
+    ],
+    assistiveText:
+      "Each option can show a leading icon and supporting text — see MANTINE_ADAPTER_RICH_OPTION_DATA.md.",
+  },
+};
+
+export const WithRichOptionsWrapped: Story = {
+  args: {
+    label: "Assignee",
+    placeholder: "Search team members...",
+    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 Popper portal — inside a container
+// sized to Autocomplete'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 Autocomplete listbox. See
+// MANTINE_ADAPTER_RICH_OPTION_DATA.md.
+const renderOptionRowPreview = (wrapItemText: boolean) => (
+  <div
+    className={styles.dropdown}
+    style={{
+      width:
+        "var(--recursica_ui-kit_components_autocomplete_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 Disabled: Story = {
   args: {
     label: "Disabled Deployment Node",

package/src/components/Autocomplete/Autocomplete.tsx

@@ -5,7 +5,11 @@ import {
   TextField as MuiTextField,
   // removed InputWrapperProps
 } from "@mui/material";
-import { type ReadOnlyControlProps } from "@recursica/adapter-common";
+import {
+  type ReadOnlyControlProps,
+  type RecursicaComboboxItemWithLabel,
+  normalizeComboboxData,
+} from "@recursica/adapter-common";
 import {
   filterStylingProps,
   omitUnsupportedProps,
@@ -14,6 +18,7 @@ import {
 } from "../../utils/filterStylingProps";
 import { type RecursicaFormControlWrapperProps } from "../FormControlWrapper/FormControlWrapper";
 import { WithReadOnlyWrapper } from "../ReadOnlyField/WithReadOnlyWrapper";
+import { renderRichOptionContent } from "../../utils/renderRichOption";
 import styles from "./Autocomplete.module.css";
 
 import { type RecursicaAutocompleteProps as BaseRecursicaAutocompleteProps } from "@recursica/adapter-common";
@@ -77,6 +82,8 @@ export const Autocomplete = forwardRef<HTMLInputElement, AutocompleteProps>(
       rightSection,
       placeholder,
       ListboxProps,
+      renderOption,
+      wrapItemText = false,
       ...rest
     } = props;
     // Props this component intentionally doesn't support — deleted at runtime so they can't leak
@@ -128,6 +135,43 @@ export const Autocomplete = forwardRef<HTMLInputElement, AutocompleteProps>(
       ? `${styles.layoutOverride} ${className}`
       : styles.layoutOverride;
 
+    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) — items always
+    // have a real `label` after this, so `defaultRenderOption` below doesn't need its own fallback.
+    const normalizedData = normalizeComboboxData(data);
+
+    // Default per-option rendering — kept as a fallback so a caller-supplied `renderOption` (an
+    // escape hatch, see MANTINE_ADAPTER_RICH_OPTION_DATA.md) still wins.
+    const defaultRenderOption = (
+      liProps: React.HTMLAttributes<HTMLLIElement> & { key?: React.Key },
+      option: unknown,
+    ) => {
+      const { key, ...otherProps } = liProps;
+      if (typeof option === "string") {
+        return (
+          <li key={key} {...otherProps}>
+            {option}
+          </li>
+        );
+      }
+      return (
+        <li key={key} {...otherProps}>
+          {renderRichOptionContent(
+            option as RecursicaComboboxItemWithLabel,
+            optionClassNames,
+            wrapItemText,
+          )}
+        </li>
+      );
+    };
+
     return (
       <WithReadOnlyWrapper
         className={wrapperClass}
@@ -175,7 +219,8 @@ export const Autocomplete = forwardRef<HTMLInputElement, AutocompleteProps>(
               ...ListboxProps,
               className: mergedClassNames.listbox,
             }}
-            options={data || []}
+            options={normalizedData || []}
+            renderOption={renderOption ?? defaultRenderOption}
             renderInput={(params) => {
               const { InputProps, ...restParams } = params;
               return (

package/src/components/Autocomplete/USAGE.md

@@ -40,3 +40,29 @@ 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. Rich option content: `leadingIcon` / `supportingText`
+
+`data` items can carry an icon and a secondary line of text, rendered inside each option row:
+
+```tsx
+<Autocomplete
+  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: `<Autocomplete data={data} wrapItemText />`.

package/src/components/Dropdown/BareDropdown.tsx

@@ -1,14 +1,19 @@
-import React, { forwardRef } from "react";
+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";
 
 /**
@@ -26,10 +31,7 @@ export interface BareDropdownProps
     MuiSelectProps,
     "size" | "variant" | "classes" | "error" | "onChange"
   > {
-  data: (
-    | string
-    | { value: string; label: React.ReactNode; disabled?: boolean }
-  )[];
+  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. */
@@ -73,8 +75,19 @@ export const BareDropdown = forwardRef<
 
   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 = () =>
-    data.map((item, index) => {
+    normalizedData.map((item, index) => {
       if (typeof item === "string") {
         return (
           <MenuItem
@@ -98,11 +111,24 @@ export const BareDropdown = forwardRef<
           className={styles.option}
           data-selected={item.value === selectedValue ? "true" : undefined}
         >
-          {item.label}
+          {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}
@@ -112,6 +138,7 @@ export const BareDropdown = forwardRef<
       defaultValue={defaultValue}
       onChange={(event) => onChange?.((event.target.value as string) ?? null)}
       displayEmpty
+      renderValue={renderValue}
       error={!!error}
       className={mergedClassName}
       classes={{

package/src/components/Dropdown/DROPDOWN_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,15 @@
+# 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: hidden; 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.