@recursica/adapter-mui-v7 1.0.0

package/src/components/AutoComplete/AutoComplete.stories.tsx

@@ -0,0 +1,336 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { 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",
+  component: AutoComplete,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The \`AutoComplete\` primitive provides a text input with a dropdown menu for displaying suggestions as the user types.
+
+### Architectural Decoupling
+Recursica wraps the internal Mantine \`<Autocomplete>\` component inside the \`WithReadOnlyWrapper\`, ensuring it integrates perfectly with the strict design system form architecture.
+
+### Examples
+Always structure horizontal architectures via the generic \`formLayout\` parameter.
+\`\`\`tsx
+<AutoComplete 
+  label="Country" 
+  assistiveText="Select your country of residence." 
+  data={["United States", "Canada", "Mexico", "United Kingdom", "France"]}
+  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.",
+    },
+    wrapItemText: {
+      control: "boolean",
+      description:
+        "Wraps option label/supportingText onto additional lines instead of truncating with an ellipsis.",
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof AutoComplete>;
+
+export const Default: Story = {
+  args: {
+    disabled: false,
+    readOnly: false,
+    label: "Country Selection",
+    placeholder: "Start typing...",
+    data: [
+      "United States",
+      "Canada",
+      "Mexico",
+      "United Kingdom",
+      "France",
+      "Germany",
+      "Japan",
+      "Brazil",
+      "India",
+      "Australia",
+    ],
+    assistiveText: "Search from a predefined list of countries.",
+  },
+};
+
+export const FormsSideBySide: Story = {
+  args: {
+    label: "Primary Region",
+    placeholder: "Select region...",
+    data: ["US-East", "US-West", "EU-Central", "AP-South", "SA-East"],
+    assistiveText:
+      "Select the primary region for the deployment. This violently long string tests native textual wrapping safely mapping alongside inputs.",
+    formLayout: "side-by-side",
+  },
+};
+
+export const WithLeadingIcon: Story = {
+  args: {
+    label: "Search Projects",
+    placeholder: "Project name...",
+    data: ["Alpha", "Beta", "Gamma", "Delta", "Epsilon"],
+    leftSection: (
+      <svg
+        width="24"
+        height="24"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      >
+        <circle cx="11" cy="11" r="8"></circle>
+        <line x1="21" y1="21" x2="16.65" y2="16.65"></line>
+      </svg>
+    ),
+  },
+};
+
+export const WithTrailingIcon: Story = {
+  args: {
+    label: "Validation URL",
+    placeholder: "https://recursica.dev",
+    data: [
+      "https://recursica.dev",
+      "https://beta.recursica.dev",
+      "https://api.recursica.dev",
+    ],
+    rightSection: (
+      <svg
+        width="24"
+        height="24"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      >
+        <polyline points="20 6 9 17 4 12"></polyline>
+      </svg>
+    ),
+  },
+};
+
+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",
+    placeholder: "Disabled primitive map...",
+    data: ["Node 1", "Node 2", "Node 3"],
+    disabled: true,
+  },
+};
+
+export const ErrorState: Story = {
+  args: {
+    label: "Cluster Failure",
+    placeholder: "Failing component instance...",
+    data: ["Cluster A", "Cluster B", "Cluster C"],
+    defaultValue: "Invalid Cluster",
+    error:
+      "Critical runtime node disconnect detected traversing DOM architecture.",
+    required: true,
+  },
+};
+
+export const StaticReadOnly: Story = {
+  args: {
+    label: "Static ReadOnly Review",
+    placeholder: "Ignored...",
+    data: ["Option 1", "Option 2"],
+    value: "Explicitly Uneditable Bound Output",
+    readOnly: true,
+  },
+};
+
+export const EditableReadOnly: Story = {
+  args: {
+    label: "Editable ReadOnly Review",
+    placeholder: "Ignored until active...",
+    data: ["Option 1", "Option 2"],
+    defaultValue: "Waiting for Edit Execution",
+    readOnly: true,
+    labelWithEditIcon: true,
+  },
+};

package/src/components/AutoComplete/AutoComplete.test.tsx

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

package/src/components/AutoComplete/AutoComplete.tsx

@@ -0,0 +1,266 @@
+import React, { forwardRef } from "react";
+import {
+  Autocomplete as MuiAutocomplete,
+  type AutocompleteProps as MuiAutocompleteProps,
+  TextField as MuiTextField,
+  // removed InputWrapperProps
+} from "@mui/material";
+import {
+  type ReadOnlyControlProps,
+  type RecursicaComboboxItemWithLabel,
+  normalizeComboboxData,
+} from "@recursica/adapter-common";
+import {
+  filterStylingProps,
+  omitUnsupportedProps,
+  mergeClassNames,
+  type RecursicaOverStyled,
+} 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";
+
+export interface RecursicaAutocompleteProps
+  extends Omit<
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      MuiAutocompleteProps<any, any, any, any, "div">,
+      | "variant"
+      | "size"
+      | "wrapperProps"
+      | "radius"
+      | "renderInput"
+      | "classes"
+      | "defaultValue"
+    >,
+    Omit<
+      RecursicaFormControlWrapperProps,
+      | "controlMaxWidth"
+      | "controlMinWidth"
+      | "error"
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      | keyof MuiAutocompleteProps<any, any, any, any, "div">
+    >,
+    ReadOnlyControlProps,
+    BaseRecursicaAutocompleteProps {}
+
+export type AutoCompleteProps = RecursicaOverStyled<RecursicaAutocompleteProps>;
+
+export const AutoComplete = forwardRef<HTMLInputElement, AutoCompleteProps>(
+  function AutoComplete(props, ref) {
+    const {
+      overStyled = false,
+      formLayout = "stacked",
+
+      // Label & Wrapper Maps
+      labelSize,
+      labelAlignment,
+      labelOptionalText,
+      labelWithEditIcon,
+      onLabelEditClick,
+
+      label,
+      assistiveText,
+      assistiveWithIcon,
+      error,
+      required,
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      withAsterisk,
+      id,
+      className,
+      style,
+      disabled,
+      readOnly,
+      readOnlyComponent,
+      emptyValueComponent,
+      value,
+      defaultValue,
+      data,
+      leftSection,
+      rightSection,
+      placeholder,
+      ListboxProps,
+      renderOption,
+      wrapItemText = false,
+      ...rest
+    } = props;
+    // 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 design tokens, not MUI's native small/medium size
+    ] as const satisfies readonly (keyof MuiAutocompleteProps<
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      any,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      any,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      any,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      any,
+      "div"
+    >)[];
+
+    const sanitizedProps = omitUnsupportedProps(
+      filterStylingProps(rest, overStyled),
+      UNSUPPORTED_PROPS,
+    );
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    // Securely map core native blocks down ensuring nested CSS modules map precisely. Note MUI's
+    // actual prop is "classes", not "classNames" (that's Mantine's naming) — this used to read
+    // the wrong key, silently no-op-ing any caller-supplied classes. The caller-facing slot names
+    // below (wrapper/input/dropdown/option) mirror the mantine-adapter's own Autocomplete
+    // classNames slots, translated to MUI's real classes slot names (root/inputRoot/listbox/option).
+    const callerClasses = restRecord.classes as
+      | Partial<Record<string, string>>
+      | undefined;
+    const mergedClassNames = mergeClassNames(
+      {
+        root: styles.root,
+        inputRoot: styles.input, // Map Mantine .input (wrapper) to MUI's inputRoot
+        listbox: styles.dropdown, // Map Mantine .dropdown to MUI's listbox
+        option: styles.option,
+      },
+      callerClasses && {
+        root: callerClasses.wrapper,
+        inputRoot: callerClasses.input,
+        listbox: callerClasses.dropdown,
+        option: callerClasses.option,
+      },
+    );
+
+    const wrapperClass = className
+      ? `${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}
+        style={style as React.CSSProperties}
+        controlMaxWidth="var(--autocomplete-control-max-width)"
+        controlMinWidth="var(--autocomplete-control-min-width)"
+        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}
+        id={id}
+        disabled={disabled}
+        readOnly={readOnly}
+        readOnlyComponent={readOnlyComponent}
+        emptyValueComponent={emptyValueComponent}
+        readOnlyType="text"
+        readOnlyValue={value !== undefined ? value : defaultValue}
+        readOnlyNativeProps={props}
+        activeComponent={
+          /* Naked Input execution safely decoupled from Mui's macro Input.Wrapper DOM hooks */
+          <MuiAutocomplete
+            ref={ref}
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            {...(sanitizedProps as any)}
+            freeSolo
+            disableClearable
+            classes={mergedClassNames}
+            disabled={disabled}
+            value={value}
+            defaultValue={defaultValue}
+            forcePopupIcon={false}
+            data-error={error ? "true" : undefined}
+            data-disabled={disabled ? "true" : undefined}
+            data-with-left-section={leftSection ? "true" : undefined}
+            data-with-right-section={rightSection ? "true" : undefined}
+            ListboxProps={{
+              ...ListboxProps,
+              className: mergedClassNames.listbox,
+            }}
+            slotProps={{
+              ...(restRecord.slotProps as Record<string, unknown> | undefined),
+              popper: {
+                ...((restRecord.slotProps as { popper?: object } | undefined)
+                  ?.popper ?? {}),
+                className: styles.popper,
+              },
+            }}
+            options={normalizedData || []}
+            renderOption={renderOption ?? defaultRenderOption}
+            renderInput={(params) => {
+              const { InputProps, ...restParams } = params;
+              return (
+                <MuiTextField
+                  {...restParams}
+                  placeholder={placeholder}
+                  variant="standard"
+                  InputProps={{
+                    ...InputProps,
+                    startAdornment: leftSection ? (
+                      <span className={styles.section} data-position="left">
+                        {leftSection}
+                      </span>
+                    ) : (
+                      InputProps.startAdornment
+                    ),
+                    endAdornment: rightSection ? (
+                      <span className={styles.section} data-position="right">
+                        {rightSection}
+                      </span>
+                    ) : (
+                      InputProps.endAdornment
+                    ),
+                  }}
+                />
+              );
+            }}
+          />
+        }
+      />
+    );
+  },
+);
+
+AutoComplete.displayName = "AutoComplete";

package/src/components/AutoComplete/IMPLEMENTATION_NOTES.md

@@ -0,0 +1,37 @@
+# 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: 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. `renderRichOptionContent` takes `wrapItemText` as a third parameter and combines 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`.
+
+## Missing gap between the input and the open menu (bug fix, Matt Massey, 2026-08-30)
+
+MUI's `Autocomplete` sets an inline `margin: 0px` on its own `.MuiAutocomplete-popper`, so the open
+menu rendered flush against the input's bottom border — mantine-adapter's equivalent (`Combobox`,
+built on Mantine's own `Popover`) has an 8px gap there. That gap isn't a Recursica token: it's
+Mantine's own `Popover` untokenized default (`offset: 8` in `@mantine/core`'s `Popover.mjs`), not
+anything mantine-adapter itself wires up — there's no dedicated "menu offset" entry in the token
+schema. Rather than hardcode an unexplained `8px` in adapter-mui-v7, reused
+`--recursica_brand_dimensions_general_default` (also 8px) — the closest real token with a matching
+value — via `slotProps.popper.className` + a new `.popper { margin-top: ...; }` rule (`!important`
+needed: MUI's inline `margin: 0px` otherwise always wins). If the token schema ever adds a real gap
+token for this, prefer it over this one. `Dropdown`'s own MUI `Select`/`MenuProps` popup has the
+identical gap-less behavior, unfixed here — out of scope for this pass, flagged in
+`OPEN_QUESTIONS.txt`.
+
+## 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.