@recursica/adapter-mantine-v8 1.0.0

package/src/components/Accordion/Accordion.tsx

@@ -0,0 +1,220 @@
+import { forwardRef } from "react";
+import {
+  Accordion as MantineAccordion,
+  type AccordionProps as MantineAccordionProps,
+  type AccordionItemProps,
+  type AccordionControlProps,
+  type AccordionPanelProps,
+} from "@mantine/core";
+import {
+  filterStylingProps,
+  omitUnsupportedProps,
+  mergeClassNames,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Accordion.module.css";
+
+import {
+  type RecursicaAccordionProps,
+  type RecursicaAccordionItemProps,
+  type RecursicaAccordionControlProps,
+  type RecursicaAccordionPanelProps,
+} from "@recursica/adapter-common";
+
+// ==== ACCORDION CONTAINER ====
+export type AccordionProps = RecursicaOverStyled<
+  Omit<
+    MantineAccordionProps,
+    "value" | "defaultValue" | "multiple" | "variant"
+  > &
+    RecursicaAccordionProps
+>;
+
+// Maps Recursica's public variant vocabulary to Mantine's own. `unstyled` is a Mantine
+// sentinel with no meaning to Recursica consumers — it exists only to suppress Mantine's
+// built-in variant CSS so our module CSS is the sole source of styling. Anything outside
+// this map (a caller-supplied custom variant string) passes straight through to Mantine.
+const mapVariant: Record<string, string> = {
+  default: "unstyled",
+};
+
+const AccordionBase = function Accordion({
+  variant = "default",
+  overStyled = false,
+  ...rest
+}: AccordionProps) {
+  const resolvedVariant =
+    typeof variant === "string" && mapVariant[variant]
+      ? mapVariant[variant]
+      : variant;
+
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const restRecord = sanitizedProps as Record<string, unknown>;
+
+  // Bind all deep CSS module references natively into the global class mapping schema
+  const mergedClassNames = mergeClassNames(
+    {
+      root: styles.root,
+      item: styles.item,
+      control: styles.control,
+      label: styles.label,
+      chevron: styles.chevron,
+      icon: styles.icon,
+      panel: styles.panel,
+      content: styles.content,
+    },
+    restRecord.classNames as Partial<Record<string, string>> | undefined,
+  );
+
+  const classNameProp = restRecord.className as string | undefined;
+
+  return (
+    <MantineAccordion
+      {...(sanitizedProps as unknown as MantineAccordionProps)}
+      variant={resolvedVariant as MantineAccordionProps["variant"]}
+      className={classNameProp}
+      classNames={mergedClassNames}
+    />
+  );
+};
+AccordionBase.displayName = "Accordion";
+
+// We need to omit and re-merge native props like in Badge
+export type AccordionItemWrapperProps = RecursicaOverStyled<
+  AccordionItemProps & RecursicaAccordionItemProps
+>;
+
+export const AccordionItem = forwardRef<
+  HTMLDivElement,
+  AccordionItemWrapperProps
+>(function AccordionItem(
+  {
+    title,
+    leftIcon,
+    divider = true,
+    children,
+    disabled = false,
+    overStyled = false,
+    ...rest
+  },
+  ref,
+) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const classNameProp = (sanitizedProps as Record<string, unknown>)
+    .className as string | undefined;
+
+  const finalClass =
+    [divider ? undefined : styles.noDivider, classNameProp]
+      .filter(Boolean)
+      .join(" ") || undefined;
+
+  // If the user utilizes the explicit 'title' prop from Recursica, we securely auto-construct the Mantine sub-hierarchy natively!
+  // If not, we defer to raw composable children (meaning the integrator maps `<Accordion.Control>` manually).
+  // `disabled` has no native concept at the Item level — only Control has a real `disabled`
+  // prop (it renders a `<button>`, so the native HTML `disabled` attribute alone blocks click,
+  // focus, and keyboard activation with no extra guards needed). We forward it there in the
+  // auto-composed path; a manually-composed `<Accordion.Control>` needs it passed explicitly.
+  return (
+    <MantineAccordion.Item
+      ref={ref}
+      {...(sanitizedProps as unknown as AccordionItemProps)}
+      className={finalClass}
+      data-disabled={disabled || undefined}
+    >
+      {title ? (
+        <>
+          <AccordionControl leftIcon={leftIcon} disabled={disabled}>
+            {title}
+          </AccordionControl>
+          <AccordionPanel>{children}</AccordionPanel>
+        </>
+      ) : (
+        children
+      )}
+    </MantineAccordion.Item>
+  );
+});
+AccordionItem.displayName = "AccordionItem";
+
+// ==== ACCORDION CONTROL ====
+export type AccordionControlWrapperProps = RecursicaOverStyled<
+  // Mantine's native `icon` slot is resolved internally from `leftIcon` — omitted so a
+  // caller can't silently override it by passing `icon` directly. Mantine's per-control
+  // `chevron` override is left as-is; nothing here computes it, so it passes through safely.
+  Omit<AccordionControlProps, "icon"> & RecursicaAccordionControlProps
+>;
+
+// Props this component intentionally doesn't support — deleted at runtime so they can't leak
+// through even if a caller forces them via plain JavaScript, bypassing the `Omit<>` above.
+const UNSUPPORTED_PROPS = [
+  "icon", // Mantine's native icon slot is fully computed here from `leftIcon`; the `Omit<>` on
+  // AccordionControlWrapperProps only stops a well-typed caller, this is the runtime backstop.
+] as const satisfies readonly (keyof AccordionControlProps)[];
+
+export const AccordionControl = forwardRef<
+  HTMLButtonElement,
+  AccordionControlWrapperProps
+>(function AccordionControl(
+  { leftIcon, children, overStyled = false, ...rest },
+  ref,
+) {
+  const sanitizedProps = omitUnsupportedProps(
+    filterStylingProps(rest, overStyled),
+    UNSUPPORTED_PROPS,
+  );
+  const classNameProp = (sanitizedProps as Record<string, unknown>)
+    .className as string | undefined;
+
+  return (
+    <MantineAccordion.Control
+      ref={ref}
+      {...(sanitizedProps as unknown as AccordionControlProps)}
+      className={classNameProp}
+      icon={
+        leftIcon ? (
+          <span className={styles.iconLeftWrapper} aria-hidden>
+            {leftIcon}
+          </span>
+        ) : undefined
+      }
+    >
+      {children}
+    </MantineAccordion.Control>
+  );
+});
+AccordionControl.displayName = "AccordionControl";
+
+// ==== ACCORDION PANEL ====
+export type AccordionPanelWrapperProps = RecursicaOverStyled<
+  AccordionPanelProps & RecursicaAccordionPanelProps
+>;
+
+export const AccordionPanel = forwardRef<
+  HTMLDivElement,
+  AccordionPanelWrapperProps
+>(function AccordionPanel({ overStyled = false, ...rest }, ref) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const classNameProp = (sanitizedProps as Record<string, unknown>)
+    .className as string | undefined;
+
+  return (
+    <MantineAccordion.Panel
+      ref={ref}
+      {...(sanitizedProps as unknown as AccordionPanelProps)}
+      className={classNameProp}
+    />
+  );
+});
+AccordionPanel.displayName = "AccordionPanel";
+
+// ==== DOT NOTATION EXPORT ====
+type AccordionComponent = typeof AccordionBase & {
+  Item: typeof AccordionItem;
+  Control: typeof AccordionControl;
+  Panel: typeof AccordionPanel;
+};
+
+export const Accordion = AccordionBase as AccordionComponent;
+Accordion.Item = AccordionItem;
+Accordion.Control = AccordionControl;
+Accordion.Panel = AccordionPanel;

package/src/components/Accordion/USAGE.md

@@ -0,0 +1,51 @@
+# Accordion - Usage Guide
+
+This document describes how to integrate and use the `Accordion` component in your projects using `@recursica/adapter-mantine-v8`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Accordion } from "@recursica/adapter-mantine-v8";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Accordion } from "@recursica/adapter-mantine-v8";
+
+export default function Demo() {
+  return (
+    <Accordion>
+      <Accordion.Item value="item-1">
+        <Accordion.Control>Section 1</Accordion.Control>
+        <Accordion.Panel>Section 1 content</Accordion.Panel>
+      </Accordion.Item>
+    </Accordion>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/adapter-mantine-v8` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.
+
+---
+
+## 4. Key Integration Features & Constraints
+
+### Composition Patterns
+
+`Accordion.Item` supports two ways of providing content: pass `title` (and optionally `leftIcon`) directly on `Accordion.Item` for a simple control/panel pair, with `children` treated as the panel content; or omit `title` and compose manually with `Accordion.Control` and `Accordion.Panel` for full control over the control's contents.

package/src/components/Accordion/index.ts

@@ -0,0 +1 @@
+export * from "./Accordion";

package/src/components/AssistiveElement/ASSISTIVEELEMENT_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,45 @@
+# AssistiveElement – implementation notes
+
+Decisions and design tweaks specific to the UI Kit's AssistiveElement wrapped against
+`@mantine/core`.
+
+---
+
+## 1. Plain `<div>` — no underlying component wrapped
+
+**Decision:** Unlike most components in this adapter, `AssistiveElement` doesn't wrap any real
+`@mantine/core` component at all — it's a bare `<div>` with two `<span>` wrappers (icon, text).
+Mantine has no dedicated helper/error-text component to wrap in the first place (it composes
+that presentation ad hoc per-field via `TextInput`'s own `error`/`description` props instead of
+a standalone component), so there's nothing here to inherit layout or ARIA semantics from.
+**Implementation:** A `<div>` is a reasonable generic container, but it carries no semantic
+meaning of its own. `role="alert"` is now defaulted automatically for the `"error"` variant
+(see §3) — the one piece of ARIA behavior that genuinely belongs at this component's own level.
+`aria-describedby`/`aria-errormessage` association with a field is a different story: this
+component has no reference to any sibling field, so it can't wire that itself. It's already
+handled one layer up, in `FormControlWrapper` — which generates the ids, passes them down via
+this component's own `id` prop, and clones `aria-describedby`/`aria-errormessage` onto the
+field. Only a fully standalone `<AssistiveElement>` used outside `FormControlWrapper` still
+needs that wiring done by hand, via the standard HTML attributes that pass through `{...rest}`.
+
+---
+
+## 2. Fixed icon per variant, no custom icon slot
+
+**Decision:** `assistiveWithIcon` only toggles visibility — there's no prop to swap in a custom
+icon. The icon is always the one belonging to the current `assistiveVariant` (`InfoIcon` for
+`"help"`, `AlertIcon` for `"error"`).
+**Implementation:** `IconComponent = assistiveVariant === "error" ? AlertIcon : InfoIcon` is
+resolved directly in the render body; there's no icon prop in `RecursicaAssistiveElementProps`
+to intercept.
+
+---
+
+## 3. `role="alert"` defaults on for the error variant
+
+**Decision:** Error text needs to be announced by assistive tech as it appears or changes;
+static help text doesn't. Rather than requiring every integrator to remember `role="alert"`,
+`assistiveVariant="error"` defaults it automatically.
+**Implementation:** `role` is destructured out and resolved as `role ?? (assistiveVariant ===
+"error" ? "alert" : undefined)` before the spread — an explicit caller-supplied `role` always
+wins over the default, and `"help"` gets no default at all.

package/src/components/AssistiveElement/AssistiveElement.module.css

@@ -0,0 +1,111 @@
+/**
+ * AssistiveElement.module.css
+ * 
+ * HARDCODED VALUES:
+ * - margin / padding: 0 — Structural resets.
+ * - display: flex / align-items: flex-start — layout alignment.
+ */
+
+.root {
+  display: flex !important;
+  align-items: flex-start !important; /* Forces the icon to align with the first line of text */
+  margin: 0 !important; /* HARDCODE: structural reset */
+  padding: 0 !important; /* HARDCODE: structural reset */
+
+  gap: var(
+    --recursica_ui-kit_components_assistive-element_properties_icon-text-gap
+  );
+  margin-top: var(
+    --recursica_ui-kit_components_assistive-element_properties_top-margin
+  ) !important;
+  max-width: var(
+    --recursica_ui-kit_components_assistive-element_properties_max-width
+  );
+}
+
+.textWrapper {
+  /* Text properties securely governed via layout mappings */
+  font-family: var(
+    --recursica_ui-kit_components_assistive-element_properties_text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_assistive-element_properties_text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_assistive-element_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_assistive-element_properties_text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_assistive-element_properties_text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_assistive-element_properties_text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_assistive-element_properties_text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_assistive-element_properties_text_text-transform
+  );
+
+  /* Fallback text wrap structures */
+  overflow-wrap: break-word;
+  white-space: normal;
+}
+
+.iconWrapper {
+  flex-shrink: 0 !important; /* Prevent squishing */
+  display: flex !important;
+  align-items: center !important;
+  justify-content: center !important;
+
+  width: var(
+    --recursica_ui-kit_components_assistive-element_properties_icon-size
+  ) !important;
+  height: calc(
+    var(
+        --recursica_ui-kit_components_assistive-element_properties_text_line-height
+      ) *
+      var(
+        --recursica_ui-kit_components_assistive-element_properties_text_font-size
+      )
+  ) !important; /* Forces exact centering bounds within the first text line vertically */
+}
+
+.iconWrapper svg {
+  width: var(
+    --recursica_ui-kit_components_assistive-element_properties_icon-size
+  ) !important;
+  height: var(
+    --recursica_ui-kit_components_assistive-element_properties_icon-size
+  ) !important;
+}
+
+/* 
+ * VARIANT MAPPINGS 
+ * Inherits colors natively mapped per variant. 
+ */
+
+.root[data-variant="help"] .textWrapper {
+  color: var(
+    --recursica_ui-kit_components_assistive-element_variants_types_help_properties_colors_text-color
+  ) !important;
+}
+.root[data-variant="help"] .iconWrapper svg {
+  color: var(
+    --recursica_ui-kit_components_assistive-element_variants_types_help_properties_colors_icon-color
+  ) !important;
+}
+
+.root[data-variant="error"] .textWrapper {
+  color: var(
+    --recursica_ui-kit_components_assistive-element_variants_types_error_properties_colors_text-color
+  ) !important;
+}
+.root[data-variant="error"] .iconWrapper svg {
+  color: var(
+    --recursica_ui-kit_components_assistive-element_variants_types_error_properties_colors_icon-color
+  ) !important;
+}

package/src/components/AssistiveElement/AssistiveElement.stories.tsx

@@ -0,0 +1,68 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { AssistiveElement } from "./AssistiveElement";
+
+const meta: Meta<typeof AssistiveElement> = {
+  title: "UI-Kit/AssistiveElement",
+  component: AssistiveElement,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "The `AssistiveElement` is a semantic structural primitive designed to standardize Helper and Error descriptive blocks natively beneath form components globally. By explicitly wiring to the `--recursica_ui-kit_components_assistive-element` layout tokens, this component safely injects custom SVGs (Alerts vs Info circles) alongside constrained flex-wrapping typography strings, preserving flawless line-height and alignment logic entirely decoupled from underlying input engine frameworks.",
+      },
+    },
+  },
+  argTypes: {
+    assistiveVariant: {
+      control: "radio",
+      options: ["help", "error"],
+    },
+    assistiveWithIcon: {
+      control: "boolean",
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof AssistiveElement>;
+
+export const DefaultHelp: Story = {
+  args: {
+    children:
+      "This is a standard assistive layout explaining specific configurations.",
+    assistiveVariant: "help",
+    assistiveWithIcon: true,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <AssistiveElement {...args} />
+  ),
+};
+
+export const ErrorState: Story = {
+  args: {
+    children:
+      "Invalid property. You must satisfy the constraints outlined above.",
+    assistiveVariant: "error",
+    assistiveWithIcon: true,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <AssistiveElement {...args} />
+  ),
+};
+
+export const NoIconHelp: Story = {
+  args: {
+    children:
+      "Fallback textual representation without visual injection targets.",
+    assistiveVariant: "help",
+    assistiveWithIcon: false,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <AssistiveElement {...args} />
+  ),
+};

package/src/components/AssistiveElement/AssistiveElement.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future AssistiveElement component tests. Add tests here if/when needed.

package/src/components/AssistiveElement/AssistiveElement.tsx

@@ -0,0 +1,93 @@
+import React, { forwardRef } from "react";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./AssistiveElement.module.css";
+
+import { type RecursicaAssistiveElementProps } from "@recursica/adapter-common";
+
+export type AssistiveElementProps = RecursicaOverStyled<
+  React.HTMLAttributes<HTMLDivElement> & RecursicaAssistiveElementProps
+>;
+
+const InfoIcon = () => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="2"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+  >
+    <circle cx="12" cy="12" r="10" />
+    <path d="M12 16v-4" />
+    <path d="M12 8h.01" />
+  </svg>
+);
+
+const AlertIcon = () => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="2"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+  >
+    <path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3Z" />
+    <path d="M12 9v4" />
+    <path d="M12 17h.01" />
+  </svg>
+);
+
+export const AssistiveElement = forwardRef<
+  HTMLDivElement,
+  AssistiveElementProps
+>(function AssistiveElement(
+  {
+    assistiveVariant = "help",
+    assistiveWithIcon = true,
+    children,
+    className,
+    role,
+    overStyled = false,
+    ...rest
+  },
+  ref,
+) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const restRecord = sanitizedProps as Record<string, unknown>;
+
+  const rootClass = styles.root;
+  const finalClass = className ? `${rootClass} ${className}` : rootClass;
+
+  const IconComponent = assistiveVariant === "error" ? AlertIcon : InfoIcon;
+
+  // Announce error text as it appears/changes; a caller-supplied `role` always wins. No
+  // default for `help` — static descriptive text doesn't need a live region.
+  const resolvedRole =
+    role ?? (assistiveVariant === "error" ? "alert" : undefined);
+
+  return (
+    <div
+      ref={ref}
+      {...restRecord} // Spread standard HTML attributes (like id, aria-*) natively.
+      className={finalClass}
+      data-variant={assistiveVariant}
+      role={resolvedRole}
+      style={restRecord.style as React.CSSProperties}
+    >
+      {assistiveWithIcon && (
+        <span className={styles.iconWrapper}>
+          <IconComponent />
+        </span>
+      )}
+      <span className={styles.textWrapper}>{children}</span>
+    </div>
+  );
+});
+
+AssistiveElement.displayName = "AssistiveElement";

package/src/components/AssistiveElement/USAGE.md

@@ -0,0 +1,36 @@
+# AssistiveElement - Usage Guide
+
+This document describes how to integrate and use the `AssistiveElement` component in your projects using `@recursica/adapter-mantine-v8`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { AssistiveElement } from "@recursica/adapter-mantine-v8";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { AssistiveElement } from "@recursica/adapter-mantine-v8";
+
+export default function Demo() {
+  return <AssistiveElement state="error" message="This field is required" />;
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/adapter-mantine-v8` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **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.

package/src/components/AutoComplete/AUTOCOMPLETE_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,42 @@
+# AutoComplete Implementation Notes
+
+## Form Control Wrapping
+
+The `AutoComplete` component is wrapped using the `WithReadOnlyWrapper` to seamlessly bridge standard `InputWrapperProps` attributes (like `label`, `error`, `assistiveText`) directly onto the macro Recursica `<FormControlWrapper>`.
+
+## CSS Layout Execution
+
+The baseline structure maps identical `HARDCODED VALUES` as standard text inputs (`border-width: 1px`, `display: flex`). The `.root` dynamically overrides the `--input-left-section-size` and `--input-right-section-size` to accurately allocate whitespace for prepended or appended icons natively matching the underlying UI token layout system securely.
+
+## Dropdown Styling
+
+The Mantine `<Autocomplete>` dropdown menu and options are styled strictly using native UI-Kit variables mapping border radii, shadows, and base colors (`.dropdown` and `.option`).
+
+## State Cascade Architecture
+
+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 Selected Option Highlight
+
+`.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: clip; overflow-clip-margin: 0.35em; 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.
+
+`.optionText > *` used plain `overflow: hidden` until 2026-08-28 (Matt Massey) — it clipped
+descenders (e.g. "g") whenever `text_line-height` is tighter than the font's natural
+ascent+descent. `overflow-clip-margin` gives ink a small bleed allowance while still clipping
+genuinely overflowing text; same project-wide fix as Chip's `CHIP_IMPLEMENTATION_NOTES.md`.