@recursica/adapter-mui-v7 1.0.0

package/src/components/Dropdown/Dropdown.stories.tsx

@@ -0,0 +1,252 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Dropdown } from "./Dropdown";
+import { formControlArgTypes } from "../../../.storybook/commonArgTypes";
+import { renderRichOptionContent } from "../../utils/renderRichOption";
+import styles from "./Dropdown.module.css";
+
+type DropdownStoryProps = React.ComponentProps<typeof Dropdown>;
+
+const meta: Meta<DropdownStoryProps> = {
+  title: "UI-Kit/Dropdown",
+  component: Dropdown,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Dropdown provides a selectable list of options, mapping natively over Mantine's Select component encapsulated within the standardized FormControlWrapper.",
+      },
+    },
+  },
+  args: {
+    label: "Country Selection",
+    assistiveText: "Select your country of origin.",
+    placeholder: "Pick value",
+    data: ["United States", "Canada", "Mexico", "United Kingdom", "France"],
+    disabled: false,
+    required: false,
+    readOnly: false,
+    clearable: false,
+  },
+  argTypes: {
+    disabled: {
+      control: "boolean",
+    },
+    ...formControlArgTypes,
+    readOnly: {
+      control: "boolean",
+    },
+    clearable: {
+      control: "boolean",
+    },
+    wrapItemText: {
+      control: "boolean",
+      description:
+        "Wraps option label/supportingText onto additional lines instead of truncating with an ellipsis.",
+    },
+    containerWidth: {
+      table: { disable: true },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<DropdownStoryProps>;
+
+export const Default: Story = {
+  args: {},
+};
+
+export const Clearable: Story = {
+  args: {
+    label: "Clearable Options",
+    clearable: true,
+  },
+};
+
+export const WithLeadingIcon: Story = {
+  args: {
+    label: "Destination",
+    startAdornment: (
+      <svg
+        width="24"
+        height="24"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      >
+        <path d="M21 10c0 7-9 13-9 13s-9-6-9-13a9 9 0 0 1 18 0z"></path>
+        <circle cx="12" cy="10" r="3"></circle>
+      </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: "Pick a team member",
+    assistiveText:
+      "Each option can show a leading icon and supporting text — see MANTINE_ADAPTER_RICH_OPTION_DATA.md.",
+    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" },
+    ],
+  },
+};
+
+export const WithRichOptionsWrapped: Story = {
+  args: {
+    label: "Assignee",
+    placeholder: "Pick a team member",
+    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 Menu portal — inside a container
+// sized to Dropdown'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 Select menu. See
+// MANTINE_ADAPTER_RICH_OPTION_DATA.md.
+const renderOptionRowPreview = (wrapItemText: boolean) => (
+  <div
+    className={styles.dropdown}
+    style={{
+      width:
+        "var(--recursica_ui-kit_components_dropdown_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 StaticError: Story = {
+  args: {
+    error: "You must choose a valid destination.",
+    value: "Invalid Island",
+  },
+};
+
+export const StaticDisabled: Story = {
+  args: {
+    disabled: true,
+    value: "United States",
+  },
+};
+
+export const StaticReadOnly: Story = {
+  args: {
+    label: "Read Only View",
+    readOnly: true,
+    value: "Canada",
+  },
+};

package/src/components/Dropdown/Dropdown.test.tsx

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

package/src/components/Dropdown/Dropdown.tsx

@@ -0,0 +1,319 @@
+import React, { forwardRef, ReactNode, useEffect, useState } from "react";
+import {
+  Select as MuiSelect,
+  SelectProps as MuiSelectProps,
+  SelectChangeEvent,
+  MenuItem,
+} from "@mui/material";
+import {
+  type ReadOnlyControlProps,
+  normalizeComboboxData,
+} from "@recursica/adapter-common";
+import {
+  filterStylingProps,
+  omitUnsupportedProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import { type RecursicaFormControlWrapperProps } from "../FormControlWrapper/FormControlWrapper";
+import { WithReadOnlyWrapper } from "../ReadOnlyField/WithReadOnlyWrapper";
+import { renderRichOptionContent } from "../../utils/renderRichOption";
+import { ChevronIcon, ClearIcon } from "./Dropdown.icons";
+import styles from "./Dropdown.module.css";
+
+import { type RecursicaDropdownProps as BaseRecursicaDropdownProps } from "@recursica/adapter-common";
+
+// Swapped in for MUI's default `IconComponent` only when we're rendering our own combined
+// clear+chevron `endAdornment` (see `showClear` below) — a stable reference so it isn't recreated
+// every render.
+function HiddenIcon() {
+  return null;
+}
+
+export interface RecursicaDropdownProps
+  extends Omit<
+      MuiSelectProps,
+      | keyof React.HTMLAttributes<HTMLDivElement>
+      | "size"
+      | "variant"
+      | "classes"
+      | "inputProps"
+      | "SelectDisplayProps"
+      | "ref"
+      | "error"
+    >,
+    // `onChange` is swept up by the `keyof React.HTMLAttributes<HTMLDivElement>` omission above
+    // (it's a standard DOM attribute name too) even though MUI's own `Select#onChange` has a
+    // completely different, non-DOM signature — add it back explicitly with MUI's real signature.
+    Pick<MuiSelectProps, "onChange">,
+    Omit<
+      RecursicaFormControlWrapperProps,
+      "controlMaxWidth" | "controlMinWidth" | "onChange"
+    >,
+    ReadOnlyControlProps,
+    BaseRecursicaDropdownProps {}
+
+export type DropdownProps = RecursicaOverStyled<RecursicaDropdownProps>;
+
+export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
+  function Dropdown(props, ref) {
+    const {
+      overStyled = false,
+      formLayout = "stacked",
+      containerWidth,
+
+      // 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,
+      onChange,
+      data,
+      startAdornment,
+      clearable,
+      wrapItemText = false,
+      placeholder,
+      ...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
+      "variant", // Recursica styles the naked select directly; MUI's standard/filled/outlined unused
+    ] as const satisfies readonly (keyof MuiSelectProps)[];
+
+    const sanitizedProps = omitUnsupportedProps(
+      filterStylingProps(rest, overStyled),
+      UNSUPPORTED_PROPS,
+    );
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    // MUI's basic `Select` has no built-in "clearable" concept (unlike Mantine's `Select`, which
+    // manages its own internal value so it can reset itself to `null` on demand) — the clear
+    // button needs somewhere to write an empty value to, so the value is lifted here rather than
+    // left for MUI's own internal uncontrolled state.
+    const [internalValue, setInternalValue] = useState<unknown>(
+      () => value ?? defaultValue ?? "",
+    );
+
+    useEffect(() => {
+      if (value !== undefined) setInternalValue(value);
+    }, [value]);
+
+    const handleChange = (
+      event: SelectChangeEvent<unknown>,
+      child: ReactNode,
+    ) => {
+      setInternalValue(event.target.value);
+      (
+        onChange as
+          | ((event: SelectChangeEvent<unknown>, child: ReactNode) => void)
+          | undefined
+      )?.(event, child);
+    };
+
+    const hasValue =
+      internalValue !== "" &&
+      internalValue !== null &&
+      internalValue !== undefined;
+    const showClear = !!clearable && hasValue && !disabled && !readOnly;
+
+    const handleClear = (event: React.MouseEvent) => {
+      event.preventDefault();
+      event.stopPropagation();
+      setInternalValue("");
+      (
+        onChange as
+          | ((event: SelectChangeEvent<unknown>, child: ReactNode) => void)
+          | undefined
+      )?.({ target: { value: "" } } as SelectChangeEvent<unknown>, null);
+    };
+
+    const injectedStyles = {
+      ...((style as React.CSSProperties) || {}),
+      width: containerWidth || "100%",
+    };
+
+    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 AutoComplete.tsx's identical use of `normalizeComboboxData` (adapter-common) — items
+    // always have a real `label` after this, so downstream code doesn't need its own `?? value`
+    // fallback at every read.
+    const normalizedData = normalizeComboboxData(data);
+
+    const renderOptions = () => {
+      if (!normalizedData) return null;
+      return normalizedData.map((item, index) => {
+        if (typeof item === "string") {
+          return (
+            <MenuItem
+              key={`${item}-${index}`}
+              value={item}
+              className={styles.option}
+              disableRipple
+              // Dropdown.module.css's own selected-state tint (`.option[data-selected="true"]`)
+              // needs this explicitly — MUI's own `Mui-selected` class carries its default primary-
+              // color tint instead, which is what shows through without it.
+              data-selected={item === internalValue ? "true" : undefined}
+            >
+              {item}
+            </MenuItem>
+          );
+        }
+        return (
+          <MenuItem
+            key={`${item.value}-${index}`}
+            value={item.value}
+            disabled={item.disabled}
+            className={styles.option}
+            disableRipple
+            data-selected={item.value === internalValue ? "true" : undefined}
+          >
+            {renderRichOptionContent(item, optionClassNames, wrapItemText)}
+          </MenuItem>
+        );
+      });
+    };
+
+    // MUI's closed-field display otherwise mirrors the selected `MenuItem`'s children directly —
+    // now that those can be a rich icon+label+supportingText row, `renderValue` keeps the closed
+    // field showing just the plain label, matching the field's own single-line text control.
+    const renderValue = (selected: unknown) => {
+      if (selected === "" || selected === undefined || selected === null) {
+        return placeholder ? (
+          <span className={styles.placeholder}>{placeholder}</span>
+        ) : (
+          ""
+        );
+      }
+      const match = normalizedData?.find((item) =>
+        typeof item === "string" ? item === selected : item.value === selected,
+      );
+      if (!match) return "";
+      return typeof match === "string" ? match : match.label;
+    };
+
+    const wrappedStartAdornment = startAdornment ? (
+      <span className={styles.section} data-position="left">
+        {startAdornment}
+      </span>
+    ) : undefined;
+
+    const wrappedEndAdornment = showClear ? (
+      <span className={styles.section} data-position="right">
+        <button
+          type="button"
+          className={styles.clearButton}
+          aria-label="Clear"
+          onClick={handleClear}
+        >
+          <ClearIcon />
+        </button>
+        <ChevronIcon />
+      </span>
+    ) : undefined;
+
+    return (
+      <WithReadOnlyWrapper
+        className={wrapperClass}
+        style={injectedStyles}
+        controlMaxWidth="var(--dropdown-control-max-width)"
+        controlMinWidth="var(--dropdown-control-min-width)"
+        overStyled={overStyled as true}
+        formLayout={formLayout}
+        labelSize={labelSize}
+        labelAlignment={labelAlignment}
+        labelOptionalText={labelOptionalText}
+        labelWithEditIcon={labelWithEditIcon}
+        onLabelEditClick={onLabelEditClick}
+        label={label as ReactNode}
+        assistiveText={assistiveText}
+        assistiveWithIcon={assistiveWithIcon}
+        error={!!error}
+        required={required}
+        id={id}
+        readOnly={readOnly}
+        readOnlyComponent={readOnlyComponent}
+        emptyValueComponent={emptyValueComponent}
+        readOnlyType="text"
+        readOnlyValue={
+          value !== undefined
+            ? String(value)
+            : defaultValue
+              ? String(defaultValue)
+              : undefined
+        }
+        readOnlyNativeProps={props}
+        activeComponent={
+          <MuiSelect
+            ref={ref}
+            {...(sanitizedProps as unknown as MuiSelectProps)}
+            disabled={disabled}
+            value={internalValue}
+            onChange={handleChange}
+            error={!!error}
+            required={required}
+            displayEmpty
+            renderValue={renderValue}
+            className={styles.root}
+            classes={{
+              select: styles.input,
+              icon: styles.icon,
+            }}
+            IconComponent={showClear ? HiddenIcon : undefined}
+            startAdornment={wrappedStartAdornment}
+            endAdornment={wrappedEndAdornment}
+            MenuProps={{
+              classes: { paper: styles.dropdown },
+            }}
+            // Dropdown.module.css's error/disabled state rules key off `.root[data-error]`/
+            // `[data-disabled]` (the outer Select element, matching the `className={styles.root}`
+            // above) — `inputProps` below only reaches the nested accessibility <input>, which that
+            // selector never matches, so these need to be set here too. (Previously only set via
+            // inputProps, which meant the error border never actually appeared on the Dropdown.)
+            data-disabled={disabled ? "true" : undefined}
+            data-error={error ? "true" : undefined}
+            data-with-left-section={startAdornment ? "true" : undefined}
+            data-with-right-section={showClear ? "true" : undefined}
+            inputProps={{
+              "data-disabled": disabled ? "true" : undefined,
+              "data-error": error ? "true" : undefined,
+              ...(restRecord.inputProps as Record<string, unknown>),
+            }}
+          >
+            {renderOptions()}
+          </MuiSelect>
+        }
+      />
+    );
+  },
+);
+
+Dropdown.displayName = "Dropdown";

package/src/components/Dropdown/USAGE.md

@@ -0,0 +1,68 @@
+# Dropdown - Usage Guide
+
+This document describes how to integrate and use the `Dropdown` component in your projects using `@recursica/adapter-mui-v7`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Dropdown } from "@recursica/adapter-mui-v7";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Dropdown } from "@recursica/adapter-mui-v7";
+
+export default function Demo() {
+  return (
+    <Dropdown placeholder="Select an option">
+      <Dropdown.Item value="1">Option 1</Dropdown.Item>
+      <Dropdown.Item value="2">Option 2</Dropdown.Item>
+    </Dropdown>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/adapter-mui-v7` 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. Notes
+
+- Pass `startAdornment` for a leading icon, and `clearable` (with a value present) to show a clear button — both render using the dropdown's own icon-color tokens, matching the mantine-adapter's `leftSection`/`clearable` behavior.
+- `onChange` follows MUI's native `Select` signature: `(event: SelectChangeEvent, child: ReactNode) => void`.
+- `data` items can carry a `leadingIcon` and `supportingText`, rendered inside each option row
+  (the closed field always shows the plain `label`, matching the mantine-adapter):
+
+  ```tsx
+  <Dropdown
+    label="Assignee"
+    data={[
+      {
+        value: "jdoe",
+        label: "Jane Doe",
+        leadingIcon: <UserIcon />,
+        supportingText: "jane.doe@example.com",
+      },
+      { value: "asmith", label: "Alex Smith" },
+    ]}
+  />
+  ```
+
+  By default `label`/`supportingText` truncate to a single line with an ellipsis. Set
+  `wrapItemText` to wrap them onto additional lines instead: `<Dropdown data={data} wrapItemText />`.

package/src/components/Dropdown/index.ts

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