@recursica/mui-adapter 0.27.0 → 0.28.0

package/package.json

@@ -13,7 +13,7 @@
     "url": "git+https://github.com/borderux/recursica.git",
     "directory": "packages/mui-adapter"
   },
-  "version": "0.27.0",
+  "version": "0.28.0",
   "publishConfig": {
     "access": "public"
   },

package/src/components/Breadcrumb/Breadcrumb.module.css

@@ -3,18 +3,21 @@
 */
 
 .root {
-  /* HARDCODE: Basic structural flex layout for breadcrumbs */
-  display: flex;
-  align-items: center;
-
   /* Base style resets */
   background-color: transparent;
   color: inherit;
 
   /* Apply global breadcrumb properties */
   padding: var(--recursica_ui-kit_components_breadcrumb_properties_padding);
+}
+
+/* MUI renders items/separators inside the <ol>, not directly under <nav> (.root) — the
+   gap must live here to land uniformly between item/separator/item, matching Mantine. */
+.ol {
+  /* HARDCODE: Basic structural flex layout for breadcrumbs */
+  display: flex;
+  align-items: center;
 
-  /* Mantine's breadcrumbs uses gap on the root or pseudo classes, but standard gap is safest since flex is used */
   gap: var(--recursica_ui-kit_components_breadcrumb_properties_item-gap);
 }
 
@@ -23,4 +26,6 @@
   display: flex;
   align-items: center;
   justify-content: center;
+  /* Neutralize MUI's built-in 8px marginLeft/marginRight so .ol's gap alone controls spacing */
+  margin: 0;
 }

package/src/components/Breadcrumb/Breadcrumb.stories.tsx

@@ -56,12 +56,6 @@ export const Default: Story = {
   },
 };
 
-export const StaticExample: Story = {
-  args: {
-    items: ["Store", "Electronics", "Computers", "Laptops"],
-  },
-};
-
 export const CustomSeparator: Story = {
   args: {
     items: ["Root", "Branch", "Leaf"],

package/src/components/Breadcrumb/Breadcrumb.tsx

@@ -28,6 +28,7 @@ export const Breadcrumb = forwardRef<HTMLDivElement, BreadcrumbProps>(
     const mergedClassNames = mergeClassNames(
       {
         root: styles.root,
+        ol: styles.ol,
         separator: styles.separator,
       },
       (sanitizedProps as Record<string, unknown>).classes as

package/src/components/Dropdown/Dropdown.icons.tsx

@@ -0,0 +1,33 @@
+import React from "react";
+
+/**
+ * Chevron rendered in the right section alongside the clear button (item 3a). Only used for that
+ * combined case — MUI's own default `IconComponent` (`ArrowDropDown`) is left untouched everywhere
+ * else, so this is a hand-rolled copy of the exact same MUI glyph path, not a new icon design.
+ */
+export function ChevronIcon(props: React.SVGProps<SVGSVGElement>) {
+  return (
+    <svg viewBox="0 0 24 24" fill="currentColor" aria-hidden {...props}>
+      <path d="M7 10l5 5 5-5z" />
+    </svg>
+  );
+}
+
+/** Clear ("x") icon for the clearable Dropdown's clear button (item 3a). */
+export function ClearIcon(props: React.SVGProps<SVGSVGElement>) {
+  return (
+    <svg
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden
+      {...props}
+    >
+      <line x1="18" y1="6" x2="6" y2="18" />
+      <line x1="6" y1="6" x2="18" y2="18" />
+    </svg>
+  );
+}

package/src/components/Dropdown/Dropdown.module.css

@@ -59,20 +59,28 @@
   box-sizing: border-box;
   margin: 0;
 
-  /* Box Geometry */
-  min-height: var(--recursica_ui-kit_components_dropdown_properties_min-height);
+  /* Box Geometry
+     `!important` throughout: MUI's own `.MuiSelect-select`/`.MuiOutlinedInput-input` styled rules
+     (e.g. `minHeight: 1.4375em`, and outlined-variant default padding) are equal-specificity
+     single-class selectors injected by emotion at runtime, after this CSS module's own stylesheet
+     — on that tie they win by source order, which is what silently shrank the control below the
+     min-height token (measured 42.8px vs Mantine's 48px) even though the token was already wired
+     here. Same root cause as the notchedOutline double-border fix below. */
+  min-height: var(
+    --recursica_ui-kit_components_dropdown_properties_min-height
+  ) !important;
   padding-top: var(
     --recursica_ui-kit_components_dropdown_properties_vertical-padding
-  );
+  ) !important;
   padding-bottom: var(
     --recursica_ui-kit_components_dropdown_properties_vertical-padding
-  );
+  ) !important;
   padding-left: var(
     --recursica_ui-kit_components_dropdown_properties_horizontal-padding
-  );
+  ) !important;
   padding-right: var(
     --recursica_ui-kit_components_dropdown_properties_horizontal-padding
-  );
+  ) !important;
   border-radius: var(
     --recursica_ui-kit_components_dropdown_properties_border-radius
   );
@@ -125,23 +133,47 @@
   color: inherit;
 }
 
+/* MUI's outlined variant renders its own `<fieldset class="MuiOutlinedInput-notchedOutline">` as a
+   separate absolutely-positioned sibling of `.input` — independent of the border we already draw
+   on `.input` above. Left alone, it shows its own default/focused/error border (theme grays/blue/
+   red) UNDERNEATH ours, which is what produced the double border (bug: static-error story showing
+   a leftover dark border under the red one) and MUI's own blue focus ring leaking in alongside the
+   Recursica focus box-shadow. We own the border entirely via `.input`, so this native outline is
+   never needed — always neutralize it. */
+.root :global(.MuiOutlinedInput-notchedOutline) {
+  border: none !important;
+}
+
 /* Dynamic Padding Overrides */
 .root[data-with-left-section] .input {
-  padding-left: var(--input-left-section-size);
+  padding-left: var(--input-left-section-size) !important;
 }
 
 .root[data-with-right-section] .input {
-  padding-right: var(--input-right-section-size);
+  padding-right: var(--input-right-section-size) !important;
 }
 
-/* Flexible End-Caps (Icons, actions) */
+/* Flexible End-Caps (Icons, actions)
+   Absolutely positioned within `.root` (already `position: relative`), NOT flex siblings of
+   `.input` in the row. MUI passes `startAdornment`/`endAdornment` as ordinary flex children next
+   to the select div, so as siblings they'd add their own width on top of `.input`'s already-100%-
+   width box instead of sharing it — the reserved padding above only carves out space *inside*
+   `.input`'s own bordered box, so a sibling rendered outside that box overflows past the visible
+   border (bug: leading icon / the clear+chevron pair sat outside the control's right edge).
+   Absolute positioning is Mantine's own technique for the equivalent `Input.Section` slot, which
+   is why the mantine-adapter never had this bug. */
 .section {
+  position: absolute;
+  top: 0;
+  bottom: 0;
   display: flex;
   align-items: center;
-  height: 100%;
+  gap: var(--recursica_ui-kit_components_dropdown_properties_icon-text-gap);
+  pointer-events: none;
 }
 
 .section[data-position="left"] {
+  left: 0;
   justify-content: flex-start;
   padding-left: var(
     --recursica_ui-kit_components_dropdown_properties_horizontal-padding
@@ -149,10 +181,14 @@
 }
 
 .section[data-position="right"] {
+  right: 0;
   justify-content: flex-end;
   padding-right: var(
     --recursica_ui-kit_components_dropdown_properties_horizontal-padding
   );
+  /* Unlike the left section (decorative icon only), this one can hold the interactive clear
+     button, so it needs to opt back into pointer events itself. */
+  pointer-events: auto;
 }
 
 .section :global(svg) {
@@ -169,6 +205,42 @@
   );
 }
 
+/* Clear ("x") button rendered inside the right section when `clearable` and a value is present.
+   Sized/colored via the same icon tokens as the rest of the right section (rather than any
+   default browser/library button chrome), same treatment as the mantine-adapter's equivalent
+   fix to its native clear button (see DROPDOWN_IMPLEMENTATION_NOTES.md). */
+.clearButton {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: var(--recursica_ui-kit_components_dropdown_properties_icon-size);
+  height: var(--recursica_ui-kit_components_dropdown_properties_icon-size);
+  padding: 0;
+  border: none;
+  border-radius: 50%;
+  background: transparent;
+  color: var(
+    --recursica_ui-kit_components_dropdown_properties_colors_trailing-icon
+  );
+  cursor: pointer;
+  outline: none;
+}
+
+.clearButton svg {
+  width: 100%;
+  height: 100%;
+}
+
+.clearButton:focus-visible {
+  box-shadow:
+    0 0 0 var(--recursica_brand_states_focus_border-size)
+      var(--recursica_brand_states_focus_color),
+    0 0 var(--recursica_brand_states_focus_blur)
+      var(--recursica_brand_states_focus_margin)
+      var(--recursica_brand_states_focus_color);
+}
+
 /* -------------------------------------
    STATE CASCADE ARCHITECTURE
 -------------------------------------- */
@@ -256,6 +328,21 @@
   overflow: hidden;
 }
 
+/* The visible top/bottom gap inside the open menu, before/after the option list, is MUI's own
+   `.MuiList-padding` default (8px) on the inner `<ul>` — not driven by any Recursica token. Wire
+   it to the same dropdown vertical-padding token the closed control itself uses, matching the
+   mantine-adapter fix (its `.dropdown` had the same gap, driven by Mantine's own untokenized
+   4px `--combobox-padding` default). `!important` needed to beat MUI's own emotion-generated
+   `.MuiList-padding` rule at equal selector specificity. */
+.dropdown :global(.MuiMenu-list) {
+  padding-top: var(
+    --recursica_ui-kit_components_dropdown_properties_vertical-padding
+  ) !important;
+  padding-bottom: var(
+    --recursica_ui-kit_components_dropdown_properties_vertical-padding
+  ) !important;
+}
+
 .option {
   font-family: var(
     --recursica_ui-kit_components_dropdown_properties_text_font-family
@@ -277,10 +364,11 @@
   cursor: pointer;
 }
 
-/* No per-option selected/hovered tokens exist in the schema; use the generic overlay tint
-   (same technique as the Mantine reference implementation) to highlight the active option. */
-.option[data-selected="true"],
-.option[data-combobox-selected="true"],
+/* No per-option hovered token exists in the schema; use the generic overlay tint (same technique
+   as the Mantine reference implementation) to highlight a hovered-but-not-selected option.
+   `!important` is required here: MUI's own `.Mui-selected` (and `.Mui-selected:hover`) classes
+   carry their own default primary-blue tint at equal selector specificity, and without it that
+   default tint wins over this token-driven one. */
 .option[data-hovered="true"],
 .option:hover {
   background-color: color-mix(
@@ -288,5 +376,19 @@
     var(--recursica_brand_states_hover_color)
       calc(var(--recursica_brand_states_hover_opacity) * 100%),
     transparent
-  );
+  ) !important;
+}
+
+/* No dedicated dropdown-option "selected" token exists in the schema either, but the menu-item
+   component's selected-state colors are the closest real token family for the same concept (a
+   selected row in a list) — reused here rather than the neutral hover tint above, which is what
+   previously made the selected option read as grey instead of Recursica's brand color. */
+.option[data-selected="true"],
+.option[data-combobox-selected="true"] {
+  background-color: var(
+    --recursica_ui-kit_components_menu-item_variants_selection-states_selected_properties_colors_background-color
+  ) !important;
+  color: var(
+    --recursica_ui-kit_components_menu-item_variants_selection-states_selected_properties_colors_text-color
+  ) !important;
 }

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

@@ -65,6 +65,27 @@ export const SearchableClearable: Story = {
   },
 };
 
+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>
+    ),
+  },
+};
+
 export const StaticError: Story = {
   args: {
     error: "You must choose a valid destination.",

package/src/components/Dropdown/Dropdown.tsx

@@ -1,7 +1,8 @@
-import React, { forwardRef, ReactNode } from "react";
+import React, { forwardRef, ReactNode, useEffect, useState } from "react";
 import {
   Select as MuiSelect,
   SelectProps as MuiSelectProps,
+  SelectChangeEvent,
   MenuItem,
 } from "@mui/material";
 import { type ReadOnlyControlProps } from "@recursica/adapter-common";
@@ -12,10 +13,18 @@ import {
 } from "../../utils/filterStylingProps";
 import { type RecursicaFormControlWrapperProps } from "../FormControlWrapper/FormControlWrapper";
 import { WithReadOnlyWrapper } from "../ReadOnlyField/WithReadOnlyWrapper";
+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,
@@ -28,9 +37,13 @@ export interface RecursicaDropdownProps
       | "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"
+      "controlMaxWidth" | "controlMinWidth" | "onChange"
     >,
     ReadOnlyControlProps,
     BaseRecursicaDropdownProps {}
@@ -67,11 +80,12 @@ export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
       emptyValueComponent,
       value,
       defaultValue,
+      onChange,
       data,
+      startAdornment,
       // eslint-disable-next-line @typescript-eslint/no-unused-vars
       searchable, // Not natively supported by basic MUI Select, stubbed
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
-      clearable, // Not natively supported by basic MUI Select, stubbed
+      clearable,
       ...rest
     } = props;
     // Props this component intentionally doesn't support — deleted at runtime so they can't leak
@@ -87,6 +101,47 @@ export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
     );
     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%",
@@ -105,12 +160,11 @@ export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
               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 === (value ?? defaultValue) ? "true" : undefined
-              }
+              data-selected={item === internalValue ? "true" : undefined}
             >
               {item}
             </MenuItem>
@@ -122,9 +176,8 @@ export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
             value={item.value}
             disabled={item.disabled}
             className={styles.option}
-            data-selected={
-              item.value === (value ?? defaultValue) ? "true" : undefined
-            }
+            disableRipple
+            data-selected={item.value === internalValue ? "true" : undefined}
           >
             {item.label}
           </MenuItem>
@@ -132,6 +185,26 @@ export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
       });
     };
 
+    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}
@@ -168,8 +241,8 @@ export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
             ref={ref}
             {...(sanitizedProps as unknown as MuiSelectProps)}
             disabled={disabled}
-            value={value}
-            defaultValue={defaultValue}
+            value={internalValue}
+            onChange={handleChange}
             error={!!error}
             required={required}
             displayEmpty
@@ -178,6 +251,9 @@ export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
               select: styles.input,
               icon: styles.icon,
             }}
+            IconComponent={showClear ? HiddenIcon : undefined}
+            startAdornment={wrappedStartAdornment}
+            endAdornment={wrappedEndAdornment}
             MenuProps={{
               classes: { paper: styles.dropdown },
             }}
@@ -188,6 +264,8 @@ export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
             // 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,

package/src/components/Dropdown/USAGE.md

@@ -39,3 +39,10 @@ All Recursica components in the `@recursica/mui-adapter` package adhere strictly
 > - **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`.

package/src/components/HoverCard/HoverCard.module.css

@@ -5,7 +5,13 @@
      and positioning (-arrowSize/2) calculations that cannot be CSS-driven. The default matches
      the Recursica beak-size token (16px). See COMPONENT_ISSUES.md for details.
    - All structural layout (display, position, overflow) is deferred to Mantine's native
-     behavior. We only override visual design tokens (colors, typography, spacing, borders). */
+     behavior. We only override visual design tokens (colors, typography, spacing, borders).
+   - margin: 0 !important on .dropdown. Mui's Tooltip hardcodes a per-placement margin
+     (14px, reset to 0 only when arrow is enabled) on top of whatever offset the popper
+     "offset" modifier applies, so with withBeak=false the trigger-to-dropdown gap was
+     offset + 14px instead of just offset. There is no Recursica token for this spacing —
+     the gap is driven purely by the `offset` prop (a plain number, same as Mantine's
+     HoverCard), so we zero out Mui's extra margin to make offset the only source of gap. */
 
 /* ======================================
    DROPDOWN CONTAINER
@@ -72,14 +78,30 @@
   color: var(
     --recursica_ui-kit_components_hover-card-popover_properties_colors_content
   );
+
+  margin: 0 !important; /* HARDCODE: cancel Mui's built-in per-placement margin, see note above */
 }
 
 /* ======================================
    ARROW / BEAK
    ====================================== */
 
+/* Mui's arrow is a rotated square (via ::before, background-color: currentColor)
+   sized in em units off font-size, not a bordered CSS triangle. `color` (not
+   border-color) is what actually fills it, which is why setting border-color here
+   previously had no visible effect and left it defaulting to the inherited text
+   color (solid black). Fill it with the same background-color token the card body
+   uses so it blends into the card exactly like Mantine's beak, and size it off the
+   beak-size token instead of Mui's default 1em/0.71em (font-size-relative) box. */
 .arrow {
-  border-color: var(
-    --recursica_ui-kit_components_hover-card-popover_properties_colors_border-color
+  color: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_colors_background-color
+  );
+  width: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_beak-size
   );
+  height: calc(
+    var(--recursica_ui-kit_components_hover-card-popover_properties_beak-size) *
+      0.7071
+  ); /* = width / sqrt(2), same ratio Mui's default arrow uses */
 }

package/src/components/Menu/Menu.module.css

@@ -271,4 +271,7 @@
   position: relative;
   z-index: 1;
   color: inherit;
+  /* HARDCODE: prevent the flex row from shrinking the chevron below its intrinsic 14px size
+     when the row is tight, which otherwise reads as the submenu indicator being clipped. */
+  flex-shrink: 0;
 }