@recursica/mantine-adapter 0.48.0 → 0.49.0

package/package.json

@@ -13,7 +13,7 @@
     "url": "git+https://github.com/borderux/recursica.git",
     "directory": "packages/mantine-adapter"
   },
-  "version": "0.48.0",
+  "version": "0.49.0",
   "type": "module",
   "main": "./dist/mantine-adapter.cjs",
   "module": "./dist/mantine-adapter.js",
@@ -94,7 +94,7 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@recursica/adapter-common": "^0.23.0",
+    "@recursica/adapter-common": "^0.24.0",
     "@recursica/official-release": "^2.8.0"
   },
   "peerDependencies": {

package/src/components/Accordion/Accordion.module.css

@@ -1,3 +1,14 @@
+/* Brand-layer exemptions (recursica-allow-brand) — see recursica-token-analyzer README.md.
+ * Global hover/focus/disabled state tokens (recursica_variables_scoped.css header, 'Hover & Focus states' / 'Disabled state' — implicit rule for every interactive element; components must not define their own per-component treatment).
+ *   recursica-allow-brand: --recursica_brand_states_disabled
+ *   recursica-allow-brand: --recursica_brand_states_focus_blur
+ *   recursica-allow-brand: --recursica_brand_states_focus_border-size
+ *   recursica-allow-brand: --recursica_brand_states_focus_color
+ *   recursica-allow-brand: --recursica_brand_states_focus_margin
+ *   recursica-allow-brand: --recursica_brand_states_hover_color
+ *   recursica-allow-brand: --recursica_brand_states_hover_opacity
+ */
+
 /* ==== ACCORDION CONTAINER ==== */
 .root {
   box-sizing: border-box;

package/src/components/AutoComplete/AUTOCOMPLETE_IMPLEMENTATION_NOTES.md

@@ -16,6 +16,22 @@ The Mantine `<Autocomplete>` dropdown menu and options are styled strictly using
 
 Focus, errors, and disabled visual states are enforced explicitly via the outer `<FormControlWrapper>` boundary emitting context down structurally (`[data-error]`, `[data-disabled]`) and evaluated efficiently against scoped nested selectors natively inside `AutoComplete.module.css`.
 
-## Missing Active Option Color
+## Missing Selected Option Highlight
 
-Currently, there is no explicit JSON token for the background color of an active/hovered option in the AutoComplete dropdown. We temporarily map `.option:hover` and `.option[data-combobox-active]` to the `--recursica_ui-kit_components_autocomplete_variants_states_focus_properties_colors_background` variable. Because this variable maps to the base field background, the highlight is currently invisible. This will be updated once the correct token is added to the UI kit.
+`.option:hover`/`.option[data-hovered="true"]` work — hover has a real background tint. There's no
+equivalent for "this option matches the current value" though, and it isn't fixable in CSS alone:
+Mantine's `Autocomplete` never passes a `value` prop into its internal `OptionsDropdown` (only
+`search`, for filtering — see `node_modules/@mantine/core/esm/components/Autocomplete/Autocomplete.mjs`),
+so `OptionsDropdown`'s `checked` (and the `data-combobox-active` attribute it drives — the same one
+`Dropdown`'s equivalent highlight below keys off) never gets set on any option, no matter what's
+typed into the field. See `Dropdown.module.css`'s `.option[data-combobox-active="true"]` rule for
+what a real fix would key off, if this ever gets solved upstream or by reimplementing option
+rendering with our own value comparison.
+
+## 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) — the same type `Dropdown` and both `mui-adapter` components use. `AutoComplete.tsx` installs a default `renderOption` (`../../utils/renderRichOption.tsx`, shared with `Dropdown`) that reads these off Mantine's parsed `option`. `label` on the shared type is optional — Mantine's `getParsedComboboxData` only preserves an item's extra fields when it already has both `value` and `label`; an item with `value` only is rebuilt into a bare `{value, label: value, disabled}` object first, dropping `leadingIcon`/`supportingText`. `AutoComplete.tsx` runs `data` through adapter-common's `normalizeComboboxData` (backfills `label` from `value`) before handing it to Mantine, so the rich fields always survive regardless of whether the caller set `label` (`Dropdown.tsx` does the same now that its `label` is optional too). New CSS classes (`.optionContent`/`.optionIcon`/`.optionText`/`.optionSupportingText`) reuse the menu-item component's icon/supporting-text tokens, matching Dropdown's equivalent addition — no dedicated autocomplete-option tokens exist for either. The icon is a conditional child (only rendered when `leadingIcon` is set, not a hidden reserved slot), so label/supportingText shift left when there's no icon; `.optionContent`'s `align-items: center` keeps the label vertically centered when there's no `supportingText`.
+
+## `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`, which re-enables wrapping (`white-space: normal; overflow-wrap: anywhere`) for both children — same later-cascade-wins mechanism (`.optionTextWrap > *` declared after `.optionText > *`, equal specificity) as the rest of this file's overrides. `renderRichOption`/`renderRichOptionContent` (shared util, both adapters) take `wrapItemText` as a third parameter and combine the two class names when it's true.

package/src/components/AutoComplete/AutoComplete.module.css

@@ -1,3 +1,13 @@
+/* Brand-layer exemptions (recursica-allow-brand) — see recursica-token-analyzer README.md.
+ * Global hover/focus/disabled state tokens (recursica_variables_scoped.css header, 'Hover & Focus states' / 'Disabled state' — implicit rule for every interactive element; components must not define their own per-component treatment).
+ *   recursica-allow-brand: --recursica_brand_states_focus_blur
+ *   recursica-allow-brand: --recursica_brand_states_focus_border-size
+ *   recursica-allow-brand: --recursica_brand_states_focus_color
+ *   recursica-allow-brand: --recursica_brand_states_focus_margin
+ *   recursica-allow-brand: --recursica_brand_states_hover_color
+ *   recursica-allow-brand: --recursica_brand_states_hover_opacity
+ */
+
 /* LAYOUT SPACING OVERRIDES:
    - Sets the --form-control-margin-bottom spacing hook to map component-specific layout tokens.
    - Also sets the --autocomplete-control-{max,min}-width hooks consumed inline in AutoComplete.tsx,
@@ -202,26 +212,31 @@
   color: var(
     --recursica_ui-kit_components_autocomplete_properties_colors_text-color
   );
-  padding: calc(
-      var(
-          --recursica_ui-kit_components_autocomplete_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 autocomplete padding — matches
+     Menu.module.css's `.item` padding + `margin-bottom` gap exactly. */
+  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);
+  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. Mantine's own
+   `data-combobox-selected` here is its transient keyboard-navigation highlight (imperatively
+   set/cleared via arrow keys — see use-combobox.mjs's `selectOption`/`clearSelectedItem` — not
+   the persistently-chosen value), so it belongs in this hover-equivalent bucket, not the real
+   selected-value rule below. */
 .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 {
@@ -233,6 +248,106 @@
   );
 }
 
+/* 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. Despite the name,
+   Mantine's `data-combobox-active` is the attribute it sets when an option's value matches the
+   current field value (see OptionsDropdown.mjs: `active: checked`) — the actual "this is the
+   selected item" flag, distinct from the transient `data-combobox-selected` keyboard-highlight
+   grouped with hover above. Keying this rule off `data-combobox-selected` instead (as it
+   previously did) is why the selected option only showed a highlight while arrow-key navigating,
+   and lost it as soon as the dropdown was reopened normally. */
+.option[data-combobox-active="true"],
+.option[data-combobox-active] {
+  background-color: var(
+    --recursica_ui-kit_components_menu-item_variants_selection-states_selected_properties_colors_background-color
+  );
+  color: var(
+    --recursica_ui-kit_components_menu-item_variants_selection-states_selected_properties_colors_text-color
+  );
+}
+
+/* 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 } from "./AutoComplete";
 import { formControlArgTypes } from "../../../.storybook/commonArgTypes";
+import { renderRichOption } 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 floating/portal menu — 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) combobox dropdown. 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}>
+        {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 Disabled: Story = {
   args: {
     label: "Disabled Deployment Node",

package/src/components/AutoComplete/AutoComplete.tsx

@@ -4,7 +4,10 @@ import {
   type AutocompleteProps as MantineAutocompleteProps,
   type InputWrapperProps,
 } from "@mantine/core";
-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 { renderRichOption } from "../../utils/renderRichOption";
 import styles from "./AutoComplete.module.css";
 
 import { type RecursicaAutocompleteProps as BaseRecursicaAutocompleteProps } from "@recursica/adapter-common";
@@ -80,6 +84,9 @@ export const AutoComplete = forwardRef<HTMLInputElement, AutoCompleteProps>(
       emptyValueComponent,
       value,
       defaultValue,
+      data,
+      renderOption,
+      wrapItemText = false,
       ...rest
     } = props;
 
@@ -89,6 +96,13 @@ export const AutoComplete = forwardRef<HTMLInputElement, AutoCompleteProps>(
     );
     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). `normalizeComboboxData` backfills `label` so the rich fields
+    // always survive regardless of whether the caller set it.
+    const normalizedData = normalizeComboboxData(data);
+
     // Securely map core native blocks down ensuring nested CSS modules map precisely
     const mergedClassNames = mergeClassNames(
       {
@@ -101,6 +115,14 @@ export const AutoComplete = forwardRef<HTMLInputElement, AutoCompleteProps>(
       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 wrapperClass = className
       ? `${styles.layoutOverride} ${className}`
       : styles.layoutOverride;
@@ -141,6 +163,12 @@ export const AutoComplete = forwardRef<HTMLInputElement, AutoCompleteProps>(
             value={value as string | undefined}
             defaultValue={defaultValue as string | undefined}
             error={!!error}
+            data={normalizedData as unknown as MantineAutocompleteProps["data"]}
+            renderOption={
+              renderOption ??
+              ((input) =>
+                renderRichOption(input, optionClassNames, wrapItemText))
+            }
           />
         }
       />

package/src/components/AutoComplete/USAGE.md

@@ -45,6 +45,36 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 ## 4. Key Integration Features & Constraints
 
-### Known Limitation: Active Option Highlight
+### Rich option content: `leadingIcon` / `supportingText`
 
-The background highlight for a hovered or active option in the dropdown is not currently visible. This will be addressed in a future update.
+`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" },
+  ]}
+/>
+```
+
+- `label` is optional, same as always — items with `value` only still work, falling back to
+  `value` as the displayed/matched text.
+- Pass your own `renderOption` to opt out of this default rendering entirely for a given
+  component instance.
+- By default `label`/`supportingText` truncate to a single line with an ellipsis. Set
+  `wrapItemText` to wrap them onto additional lines instead:
+
+```tsx
+<AutoComplete data={data} wrapItemText />
+```
+
+### Known Limitation: Selected Option Highlight
+
+Hover works (see `.option:hover`/`.option[data-hovered="true"]`), but there's no distinct "this option matches the current value" background — unlike `Dropdown`, which has one. This isn't a styling gap: Mantine's `Autocomplete` never passes a `value` prop into its internal `OptionsDropdown` (only `search`, for filtering — see `Autocomplete.mjs`), so `checked`/`data-combobox-active` (the attribute that drives `Dropdown`'s equivalent highlight) never gets set on any option, regardless of what's typed into the field. There's no other DOM signal to key a CSS rule off. Would need either an upstream Mantine change or reimplementing option rendering ourselves with a value comparison.

package/src/components/Button/Button.module.css

@@ -1,3 +1,13 @@
+/* Brand-layer exemptions (recursica-allow-brand) — see recursica-token-analyzer README.md.
+ * Global hover/focus/disabled state tokens (recursica_variables_scoped.css header, 'Hover & Focus states' / 'Disabled state' — implicit rule for every interactive element; components must not define their own per-component treatment).
+ *   recursica-allow-brand: --recursica_brand_states_focus_blur
+ *   recursica-allow-brand: --recursica_brand_states_focus_border-size
+ *   recursica-allow-brand: --recursica_brand_states_focus_color
+ *   recursica-allow-brand: --recursica_brand_states_focus_margin
+ *   recursica-allow-brand: --recursica_brand_states_hover_color
+ *   recursica-allow-brand: --recursica_brand_states_hover_opacity
+ */
+
 /**
  * IMPLEMENTATION NOTES:
  * 

package/src/components/Card/Card.stories.tsx

@@ -37,8 +37,7 @@ export const Default: Story = {
       <div
         style={{
           padding: "48px",
-          backgroundColor:
-            "var(--recursica_brand_palettes_neutral_050_color_tone)",
+          backgroundColor: "#e9ecef",
         }}
       >
         <Layer layer={0}>
@@ -73,8 +72,7 @@ export const HeaderlessAndFooterless: Story = {
       <div
         style={{
           padding: "48px",
-          backgroundColor:
-            "var(--recursica_brand_palettes_neutral_050_color_tone)",
+          backgroundColor: "#e9ecef",
         }}
       >
         <Layer layer={0}>

package/src/components/Chip/Chip.module.css

@@ -1,3 +1,12 @@
+/* Brand-layer exemptions (recursica-allow-brand) — see recursica-token-analyzer README.md.
+ * Global hover/focus/disabled state tokens (recursica_variables_scoped.css header, 'Hover & Focus states' / 'Disabled state' — implicit rule for every interactive element; components must not define their own per-component treatment).
+ *   recursica-allow-brand: --recursica_brand_states_disabled
+ *   recursica-allow-brand: --recursica_brand_states_focus_blur
+ *   recursica-allow-brand: --recursica_brand_states_focus_border-size
+ *   recursica-allow-brand: --recursica_brand_states_focus_color
+ *   recursica-allow-brand: --recursica_brand_states_focus_margin
+ */
+
 /* HARDCODED VALUES
    border-style: solid;  (Baseline reset)
    box-sizing: border-box; (Baseline reset)

package/src/components/DatePicker/DatePicker.module.css

@@ -1,3 +1,19 @@
+/* Brand-layer exemptions (recursica-allow-brand) — see recursica-token-analyzer README.md.
+ * No ui-kit_components_date-picker radius token exists for the calendar day cells; reuses the brand default border-radius.
+ *   recursica-allow-brand: --recursica_brand_dimensions_border-radii_default
+ * Global hover/focus/disabled state tokens (recursica_variables_scoped.css header, 'Hover & Focus states' / 'Disabled state' — implicit rule for every interactive element; components must not define their own per-component treatment).
+ *   recursica-allow-brand: --recursica_brand_states_disabled
+ *   recursica-allow-brand: --recursica_brand_states_focus_blur
+ *   recursica-allow-brand: --recursica_brand_states_focus_border-size
+ *   recursica-allow-brand: --recursica_brand_states_focus_color
+ *   recursica-allow-brand: --recursica_brand_states_focus_margin
+ *   recursica-allow-brand: --recursica_brand_states_hover_color
+ *   recursica-allow-brand: --recursica_brand_states_hover_opacity
+ * No ui-kit_components_date-picker in-range token exists; the generic overlay tint fills the range-selection band (see inline comment above .day[data-in-range]).
+ *   recursica-allow-brand: --recursica_brand_states_overlay_color
+ *   recursica-allow-brand: --recursica_brand_states_overlay_opacity
+ */
+
 /* LAYOUT SPACING OVERRIDES:
    - Sets the --form-control-margin-bottom spacing hook to map component-specific layout tokens. */
 .layoutOverride {

package/src/components/Dropdown/DROPDOWN_IMPLEMENTATION_NOTES.md

@@ -7,3 +7,6 @@ The `Dropdown` component is mapped explicitly to Mantine's `<Select>` following
 3. **Dropdown Appendages:** To correctly map Mantine's detached Popover `.dropdown` and list `.option` items, we targeted focus and geometric bindings appending standard padding structures matched to the dropdown height overrides dynamically into our `Dropdown.module.css`.
 4. **Popup Vertical Padding:** The gap above/below the option list inside `.dropdown` is explicitly set from the same `--recursica_..._dropdown_properties_vertical-padding` token the closed control uses — it was previously left to Mantine's own untokenized `--combobox-padding` (4px) default.
 5. **Clear Button Styling:** Mantine's native clear button (`clearButtonProps`, shown when `clearable` + a value are both present) is a bare `CloseButton` with its own hardcoded gray icon/hover styling by default. `Dropdown.tsx` merges in a `.clearButton` class (Dropdown.module.css) that overrides it with the same icon-size/trailing-icon-color/focus-ring tokens as the rest of the right section, using the double-class-selector specificity trick (same as Chip.module.css's `.root.root`) to beat Mantine's own CSS module rule without `!important`.
+6. **Rich Option Content (`leadingIcon`/`supportingText`):** `data` items now 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) — the same type `AutoComplete` and both `mui-adapter` components use, so it's declared once and not redeclared per component/adapter. `label` on that shared type is optional, falling back to `value` (matches Mantine's own runtime default for both `Select` and `Autocomplete`). `Dropdown.tsx` installs a default `renderOption` (`../../utils/renderRichOption.tsx`, shared with `AutoComplete`) that reads `leadingIcon`/`supportingText` straight off Mantine's own parsed `option` — no separate lookup-by-value map is needed, since Mantine's `getParsedComboboxData` passes extra fields on an item through untouched whenever the item already has both `value` and `label`. Because `label` is now optional, `data` is first run through adapter-common's `normalizeComboboxData` (backfilling `label` from `value`) before being handed to Mantine, so items missing `label` don't have their `leadingIcon`/`supportingText` silently dropped by that same parser (see `AutoComplete.tsx`'s identical, longer-standing use of this — `Dropdown`'s `label` used to be required, which is why it didn't need this before). A caller-supplied `renderOption` always wins over the default. New CSS classes (`.optionContent`/`.optionIcon`/`.optionText`/`.optionSupportingText`) reuse the menu-item component's icon/supporting-text tokens — no dedicated dropdown-option tokens exist for either, same reasoning as the `.option[data-selected]` reuse above. The icon is only rendered when `leadingIcon` is present (a conditional child, not a hidden reserved slot), so label/supportingText shift left when there's no icon; `.optionContent`'s `align-items: center` keeps the label vertically centered when there's no `supportingText` to stack under it.
+7. **`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, same mechanism as this file's other CSS overrides. `renderRichOption`/`renderRichOptionContent` take `wrapItemText` as a third parameter and combine the two class names when it's true.
+8. **Selected Option Highlight (bug fix):** The `.option[data-selected="true"], .option[data-combobox-active="true"]` background/text-color rule (and the matching `.optionIcon`/`.optionSupportingText` color rules) used to key off `data-combobox-selected` instead of `data-combobox-active`. Despite the name, `data-combobox-active` is what Mantine sets when an option's value matches the current field value (`OptionsDropdown.mjs`: `active: checked`, consumed by `ComboboxOption.mjs`'s `mod` map); `data-combobox-selected` is an unrelated, transient keyboard-navigation highlight that Mantine sets/clears imperatively via `element.setAttribute` outside React (`use-combobox.mjs`'s `selectOption`/`clearSelectedItem`), not tied to the chosen value at all. The bug: the real selected option only showed the brand background while being arrow-key-navigated, and lost it entirely on a normal open/close (matches Playwright verification — `data-combobox-active="true"` is present and gets the token background after a plain click-select-reopen, with no keyboard involved).