@recursica/adapter-mantine-v8 1.0.0

package/src/components/DatePicker/DatePicker.stories.tsx

@@ -0,0 +1,158 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { DatePicker } from "./DatePicker";
+import { formControlArgTypes } from "../../../.storybook/commonArgTypes";
+
+const meta: Meta<typeof DatePicker> = {
+  title: "UI-Kit/DatePicker",
+  component: DatePicker,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The \`DatePicker\` primitive provides a unified calendar date selection input integrated directly into the \`FormControlWrapper\` architecture.
+
+### Architectural Decoupling
+Recursica overrides the internal Mantine \`DatePickerInput\` wrapper defaults, safely injecting the date picker into our rigid structural layout systems. State modifiers (e.g. Focus, Errors, ReadOnly) hook seamlessly back onto our native CSS mapping architecture.
+
+### Examples
+Always structure horizontal architectures via the generic \`formLayout\` parameter.
+\`\`\`tsx
+<DatePicker 
+  label="Start Date" 
+  assistiveText="Select the deployment kick-off date." 
+  formLayout="stacked" 
+/>
+\`\`\`
+`,
+      },
+    },
+  },
+  argTypes: {
+    ...formControlArgTypes,
+    disabled: {
+      control: "boolean",
+      description:
+        "Maps the formal disabled variable states structurally to the input core.",
+    },
+    error: {
+      control: "text",
+      description:
+        "Applies the strict error string boundary rendering invalid structures seamlessly.",
+    },
+    required: {
+      control: "boolean",
+    },
+    label: {
+      control: "text",
+    },
+    assistiveText: {
+      control: "text",
+    },
+    readOnly: {
+      control: "boolean",
+      description:
+        "Toggles structural read-only data presentation explicitly blocking standard component bindings.",
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof DatePicker>;
+
+export const Default: Story = {
+  args: {
+    disabled: false,
+    label: "Project Deadline",
+    assistiveText: "Specify the absolute cutoff for code submission.",
+  },
+};
+
+export const FormsSideBySide: Story = {
+  args: {
+    label: "Incident Start Date",
+    assistiveText: "When did the incident originally occur?",
+    formLayout: "side-by-side",
+  },
+};
+
+export const WithLeadingIcon: Story = {
+  args: {
+    label: "Launch Date",
+    leftSection: (
+      <svg
+        width="24"
+        height="24"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      >
+        <rect x="3" y="4" width="18" height="18" rx="2" ry="2"></rect>
+        <line x1="16" y1="2" x2="16" y2="6"></line>
+        <line x1="8" y1="2" x2="8" y2="6"></line>
+        <line x1="3" y1="10" x2="21" y2="10"></line>
+      </svg>
+    ),
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    label: "Disabled Date Range",
+    disabled: true,
+  },
+};
+
+export const ErrorState: Story = {
+  args: {
+    label: "Execution Date",
+    error: "The chosen date conflicts with an existing deployment freeze.",
+    required: true,
+  },
+};
+
+export const OpenedCalendar: Story = {
+  args: {
+    label: "Meeting Date",
+    assistiveText: "Calendar rendered open by default for styling review.",
+    // `popoverProps.opened` overrides Mantine's own internal disclosure state (see
+    // PickerInputBase's `opened: dropdownOpened, ...popoverProps` spread order), so the
+    // dropdown stays open with no click interaction needed — same convention as Menu's
+    // `opened: true` stories.
+    popoverProps: { opened: true },
+    // Fixed (not computed) so the selected-day fill is visible on load, alongside the
+    // today marker, for styling review. Local-component constructor, not an ISO date
+    // string — `new Date("2026-08-26")` parses as UTC midnight, which renders as the
+    // 25th in any timezone behind UTC.
+    defaultValue: new Date(2026, 7, 26),
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "The calendar dropdown renders open by default so its styling can be reviewed without a click interaction.",
+      },
+    },
+  },
+};
+
+export const StaticReadOnly: Story = {
+  args: {
+    label: "Static ReadOnly Review",
+    value: new Date("2026-05-21"),
+    readOnly: true,
+  },
+};
+
+export const EditableReadOnly: Story = {
+  args: {
+    label: "Editable ReadOnly Review",
+    defaultValue: new Date("2026-06-01"),
+    readOnly: true,
+    labelWithEditIcon: true,
+  },
+};

package/src/components/DatePicker/DatePicker.test.tsx

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

package/src/components/DatePicker/DatePicker.tsx

@@ -0,0 +1,218 @@
+import React, { forwardRef } from "react";
+import {
+  DatePickerInput,
+  type DatePickerInputProps,
+  getFormattedDate,
+} from "@mantine/dates";
+import { type ReadOnlyControlProps } from "@recursica/adapter-common";
+import {
+  filterStylingProps,
+  omitUnsupportedProps,
+  withCallerOverride,
+  mergeClassNames,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import { type RecursicaFormControlWrapperProps } from "../FormControlWrapper/FormControlWrapper";
+import { WithReadOnlyWrapper } from "../ReadOnlyField/WithReadOnlyWrapper";
+import { CalendarIcon } from "./DatePicker.icons";
+import styles from "./DatePicker.module.css";
+
+import { type RecursicaDatePickerProps as BaseRecursicaDatePickerProps } from "@recursica/adapter-common";
+
+export interface RecursicaDatePickerProps
+  extends Omit<
+      DatePickerInputProps,
+      | "size"
+      | "variant"
+      | "radius"
+      | "wrapperProps"
+      | "label"
+      | "error"
+      | "required"
+      | "withAsterisk"
+      | "id"
+      | "description"
+    >,
+    Pick<
+      DatePickerInputProps,
+      "label" | "error" | "required" | "withAsterisk" | "id"
+    >,
+    Omit<
+      RecursicaFormControlWrapperProps,
+      "controlMaxWidth" | "controlMinWidth"
+    >,
+    ReadOnlyControlProps,
+    BaseRecursicaDatePickerProps {}
+
+export type DatePickerProps = RecursicaOverStyled<RecursicaDatePickerProps>;
+
+// 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 = [
+  "size", // Recursica controls sizing via the `size` variant + design tokens, not raw dimensions.
+  "variant", // Colors/variants are token-driven; the library's native palette isn't exposed.
+  "radius", // Recursica does not expose the library's native corner-radius system.
+  "description", // Managed by FormControlWrapper via assistiveText.
+] as const satisfies readonly (keyof DatePickerInputProps)[];
+
+export const DatePicker = forwardRef<HTMLButtonElement, DatePickerProps>(
+  function DatePicker(props, ref) {
+    const {
+      overStyled = false,
+      formLayout = "stacked",
+
+      // Label & Wrapper Maps
+      labelSize,
+      labelAlignment,
+      labelOptionalText,
+      labelWithEditIcon,
+      onLabelEditClick,
+
+      label,
+      assistiveText,
+      assistiveWithIcon,
+      error,
+      required,
+      withAsterisk,
+      id,
+      className,
+      style,
+      disabled,
+      readOnly,
+      readOnlyComponent,
+      emptyValueComponent,
+      value,
+      defaultValue,
+      highlightToday = true, // Default on so today is visually marked; consumers can still override.
+      valueFormat = "MM/DD/YY", // Default display format; consumers can still override.
+      placeholder = "MM / DD / YY", // Default placeholder; consumers can still override.
+      leftSection, // Default leading icon computed below; consumers can still override.
+      ...rest
+    } = props;
+
+    const sanitizedProps = omitUnsupportedProps(
+      filterStylingProps(rest, overStyled) as Record<string, unknown>,
+      UNSUPPORTED_PROPS,
+    );
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    // Securely map core native blocks down ensuring nested CSS modules map precisely
+    const mergedClassNames = mergeClassNames(
+      {
+        wrapper: styles.root, // The nested Input internal relative wrapper bounding box
+        input: styles.input,
+        section: styles.section,
+        day: styles.day,
+        weekday: styles.weekday,
+        calendarHeader: styles.calendarHeader,
+        calendarHeaderControl: styles.calendarHeaderControl,
+        calendarHeaderLevel: styles.calendarHeaderLevel,
+        calendarHeaderControlIcon: styles.calendarHeaderControlIcon,
+      },
+      restRecord.classNames as Partial<Record<string, string>> | undefined,
+    );
+
+    // The calendar popover surface (.dropdown) is styled by Mantine's underlying `Popover`
+    // component, not `DatePickerInput` itself — it only accepts classNames via `popoverProps`,
+    // not the top-level `classNames` map above (which only reaches the Input/Calendar parts).
+    const popoverPropsInput = restRecord.popoverProps;
+    const consumerPopoverProps =
+      popoverPropsInput &&
+      typeof popoverPropsInput === "object" &&
+      !Array.isArray(popoverPropsInput)
+        ? (popoverPropsInput as Record<string, unknown>)
+        : undefined;
+    const consumerPopoverClassNames =
+      consumerPopoverProps?.classNames &&
+      typeof consumerPopoverProps.classNames === "object" &&
+      !Array.isArray(consumerPopoverProps.classNames)
+        ? (consumerPopoverProps.classNames as Partial<Record<string, string>>)
+        : undefined;
+    delete restRecord["popoverProps"];
+    const mergedPopoverProps = {
+      ...consumerPopoverProps,
+      classNames: mergeClassNames(
+        { dropdown: styles.dropdown },
+        consumerPopoverClassNames,
+      ),
+    };
+
+    const wrapperClass = className
+      ? `${styles.layoutOverride} ${className}`
+      : styles.layoutOverride;
+
+    return (
+      <WithReadOnlyWrapper
+        className={wrapperClass}
+        style={style as React.CSSProperties}
+        controlMaxWidth={undefined}
+        controlMinWidth={undefined}
+        overStyled={overStyled as true}
+        formLayout={formLayout}
+        labelSize={labelSize}
+        labelAlignment={labelAlignment}
+        labelOptionalText={labelOptionalText}
+        labelWithEditIcon={labelWithEditIcon}
+        onLabelEditClick={onLabelEditClick}
+        label={label}
+        assistiveText={assistiveText}
+        assistiveWithIcon={assistiveWithIcon}
+        error={error}
+        required={required}
+        withAsterisk={withAsterisk}
+        id={id}
+        readOnly={readOnly}
+        readOnlyComponent={readOnlyComponent}
+        emptyValueComponent={emptyValueComponent}
+        readOnlyType="text"
+        readOnlyValue={(() => {
+          const readOnlyDate = value !== undefined ? value : defaultValue;
+          // `DatePickerInput` formats its own displayed value via `valueFormat` internally
+          // (using this same `getFormattedDate` helper) — the read-only text swap-in bypassed
+          // that entirely and rendered `String(date)` instead (a raw JS `Date.toString()`, e.g.
+          // "Wed May 20 2026 17:00:00 GMT-0700 (Pacific Daylight Time)"), so a read-only
+          // DatePicker never matched what the same value looks like while editable.
+          return readOnlyDate
+            ? getFormattedDate({
+                type: "default",
+                date: readOnlyDate,
+                locale: "en",
+                format: valueFormat,
+                labelSeparator: "",
+              })
+            : undefined;
+        })()}
+        readOnlyNativeProps={props}
+        activeComponent={
+          /* Naked Input execution safely decoupled from Mantine's macro Input.Wrapper DOM hooks */
+          <DatePickerInput
+            ref={ref}
+            {...(sanitizedProps as unknown as DatePickerInputProps)}
+            classNames={mergedClassNames}
+            disabled={disabled}
+            value={value}
+            defaultValue={defaultValue}
+            label={undefined} // Disable Mantine's native label
+            description={undefined} // Disable Mantine's native description
+            error={undefined} // Disable Mantine's native error text (handled by wrapper)
+            withAsterisk={false} // Handled by wrapper
+            highlightToday={highlightToday}
+            valueFormat={valueFormat}
+            placeholder={placeholder}
+            leftSection={withCallerOverride<React.ReactNode>(
+              <CalendarIcon />,
+              leftSection,
+            )}
+            wrapperProps={{
+              "data-disabled": disabled ? "true" : undefined,
+              "data-error": error ? "true" : undefined,
+            }}
+            popoverProps={mergedPopoverProps}
+          />
+        }
+      />
+    );
+  },
+);
+
+DatePicker.displayName = "DatePicker";

package/src/components/DatePicker/USAGE.md

@@ -0,0 +1,49 @@
+# DatePicker - Usage Guide
+
+This document describes how to integrate and use the `DatePicker` component in your projects using `@recursica/adapter-mantine-v8`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { DatePicker } from "@recursica/adapter-mantine-v8";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { DatePicker } from "@recursica/adapter-mantine-v8";
+
+export default function Demo() {
+  return <DatePicker label="Select Date" />;
+}
+```
+
+---
+
+## 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
+
+## Structural Constraints
+
+1. **Read-Only Rendering**: When rendered in read-only mode, the selected date is displayed via a plain string conversion of the value. If you need custom date formatting, pass a `readOnlyComponent` prop to control how the value is rendered.
+2. **Calendar Popover Styling**: The UI Kit exports no calendar-specific tokens (surface, selected day, hover, today, weekend, in-range), so the calendar reuses the closest existing tokens — see `DATEPICKER_IMPLEMENTATION_NOTES.md` for the exact mapping. All calendar states are token-driven; none are left on Mantine's un-tokenized defaults. The header's prev/next arrows and month/year label are styled as Recursica `text`-variant buttons.
+3. **Today Highlighting**: `highlightToday` defaults to `true` so the current day is always visually marked; pass `highlightToday={false}` to turn it off.
+4. **Default Value Format**: Displayed values default to `MM/DD/YY` (e.g. `08/19/26`); pass your own `valueFormat` (a `dayjs` format string) to override.
+5. **Default Leading Icon**: A calendar icon is shown in the left section by default; pass your own `leftSection` to override it.
+6. **Default Placeholder**: Defaults to `"MM / DD / YY"` when not set; pass your own `placeholder` to override it.

package/src/components/Dropdown/BareDropdown.tsx

@@ -0,0 +1,97 @@
+import { forwardRef } from "react";
+import {
+  Select as MantineSelect,
+  type SelectProps as MantineSelectProps,
+} from "@mantine/core";
+import {
+  filterStylingProps,
+  omitUnsupportedProps,
+  mergeClassNames,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Dropdown.module.css";
+
+/**
+ * Bare, unwrapped Select — no `FormControlWrapper`/`WithReadOnlyWrapper`, no label/assistiveText/
+ * error/required. Tied to the same `Dropdown.module.css` variables/classes as the public
+ * `Dropdown` component, so it looks identical, but is meant to be embedded inside another
+ * component that already owns its own `FormControlWrapper` (e.g. `TimePicker`'s AM/PM control) —
+ * nesting the full `Dropdown` there would double up `FormControl`/`FormControlLayout` wrapping.
+ *
+ * Not exported from this folder's `index.ts` — internal use only. Import it directly:
+ * `import { BareDropdown } from "../Dropdown/BareDropdown"`.
+ */
+export interface BareDropdownProps
+  extends Omit<
+    MantineSelectProps,
+    | "size"
+    | "variant"
+    | "radius"
+    | "wrapperProps"
+    | "label"
+    | "description"
+    | "error"
+  > {
+  data: MantineSelectProps["data"];
+  /** Applies the error visual state (via `data-error`) — no error message is rendered here. */
+  error?: boolean;
+}
+
+export type BareDropdownComponentProps = RecursicaOverStyled<BareDropdownProps>;
+
+// 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 = [
+  "size", // Recursica controls sizing via the `size` variant + design tokens, not raw dimensions.
+  "variant", // Colors/variants are token-driven; the library's native palette isn't exposed.
+  "radius", // Recursica does not expose the library's native corner-radius system.
+] as const satisfies readonly (keyof MantineSelectProps)[];
+
+export const BareDropdown = forwardRef<
+  HTMLInputElement,
+  BareDropdownComponentProps
+>(function BareDropdown(props, ref) {
+  const { overStyled = false, className, disabled, error, ...rest } = props;
+  const sanitizedProps = omitUnsupportedProps(
+    filterStylingProps(rest, overStyled) as Record<string, unknown>,
+    UNSUPPORTED_PROPS,
+  );
+  const restRecord = sanitizedProps as Record<string, unknown>;
+
+  const mergedClassNames = mergeClassNames(
+    {
+      wrapper: className ? `${styles.root} ${className}` : styles.root,
+      input: styles.input,
+      section: styles.section,
+      dropdown: styles.dropdown,
+      option: styles.option,
+    },
+    restRecord.classNames as Partial<Record<string, string>> | undefined,
+  );
+
+  return (
+    <MantineSelect
+      ref={ref}
+      {...(sanitizedProps as unknown as MantineSelectProps)}
+      classNames={mergedClassNames}
+      disabled={disabled}
+      label={undefined}
+      description={undefined}
+      error={undefined}
+      // `wrapperProps` targets Mantine's *outer* `Input.Wrapper` (the label/description/error
+      // stacking element) — a different, ancestor element from the "wrapper" styles-api slot that
+      // actually carries `styles.root`'s border/background. Dropdown.module.css's error/disabled
+      // rules (`.root[data-error]`/`[data-disabled]`) need the attribute on that inner element, so
+      // `attributes.wrapper` (which targets the same slot as `classNames.wrapper`/`styles.wrapper`)
+      // is the correct hook here, not `wrapperProps`. See TIMEPICKER_IMPLEMENTATION_NOTES.md.
+      attributes={{
+        wrapper: {
+          "data-disabled": disabled ? "true" : undefined,
+          "data-error": error ? "true" : undefined,
+        },
+      }}
+    />
+  );
+});
+
+BareDropdown.displayName = "BareDropdown";

package/src/components/Dropdown/DROPDOWN_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,12 @@
+# Dropdown Implementation Notes
+
+The `Dropdown` component is mapped explicitly to Mantine's `<Select>` following the exact same strict encapsulation rules as `TextField`.
+
+1. **Naked Primitive Mapping:** Mantine's `Select` natively executes macro-label generation. To decouple it, we explicitly disable internal labels (`label={undefined}`) and inject it purely inside our generic `FormControlWrapper`.
+2. **Strict Dropdown Design Tokens:** The adapter implements strictly sandboxed styling utilizing only `--recursica_ui-kit_components_dropdown_...` variables. It explicitly does NOT inherit general `text-field` tokens despite geometric similarities, ensuring dropdown menus can be themed independently.
+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: clip; overflow-clip-margin: 0.35em; 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. `.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`.
+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).