@recursica/mui-adapter 0.34.0 → 0.34.3

package/src/components/Grid/Grid.tsx

@@ -1,22 +1,30 @@
 /**
  * Grid layout wrapper.
  *
- * NOTE: MUI merges "container" and "item" into a single Grid component (no separate
- * Grid.Col in the underlying library, and no native `order`, `justifyContent`,
- * `alignItems`, or breakpoint-visibility support). To preserve API parity with the
- * mantine-adapter (Grid + Grid.Col dot notation, matching Mantine's own Grid/Grid.Col),
- * this file splits MUI's single component back into two wrappers: Grid always renders
- * MUI's `<Grid container>`, GridCol always renders MUI's `<Grid>` in item mode.
+ * MUI merges "container" and "item" into a single `Grid` component (no separate Grid.Col,
+ * unlike Mantine). To preserve the Grid/Grid.Col dot-notation shape across adapters, this
+ * file splits MUI's single component back into two thin wrappers: Grid always renders MUI's
+ * `<Grid container>`, GridCol always renders a plain MUI `<Grid>` (item mode).
+ *
+ * Per the layout-components rule, both wrappers simply pass through MUI's own Grid props
+ * (`size`, `offset`, `spacing`, `columns`, `direction`, `wrap`) with no Recursica renaming.
+ * MUI has no per-item "grow to fill remaining space" container flag like Mantine's `grow`;
+ * use MUI's own `size="grow"` on individual columns instead. `visibleFrom`/`hiddenFrom`
+ * don't exist in MUI at all, so — per the rule that a missing kit feature is built following
+ * Mantine's own shape — they're added here via CSS classes, keyed on MUI's own breakpoint
+ * scale (`xs`/`sm`/`md`/`lg`/`xl`).
+ *
+ * `justifyContent`/`alignItems` (container) and `order` (item) are typed on `MuiGridProps`
+ * (inherited generically from `SystemProps`) but MUI's Grid style generator — verified by
+ * reading `@mui/system`'s `gridGenerator.js`/`createGrid.js` — only wires up `size`, `offset`,
+ * `columns`, `spacing`/`rowSpacing`/`columnSpacing`, `direction`, and `wrap`; passing these
+ * three straight through would silently no-op. They're pulled out and applied via inline
+ * `style` instead, still using MUI's own native names.
  *
  * Like Flex, Stack, Group, and Container, this is a primitive layout component and
  * does not use the `RecursicaOverStyled` gatekeeper — only the `sx` prop is stripped.
  */
-import {
-  createContext,
-  forwardRef,
-  useContext,
-  type CSSProperties,
-} from "react";
+import { forwardRef, type CSSProperties } from "react";
 import { Grid as MuiGrid, type GridProps as MuiGridProps } from "@mui/material";
 import {
   SPACING_MAP,
@@ -26,81 +34,9 @@ import {
 } from "../../utils/filterStylingProps";
 import styles from "./Grid.module.css";
 
-import {
-  type RecursicaGridProps,
-  type RecursicaGridColProps,
-} from "@recursica/adapter-common";
-
 type Breakpoint = "xs" | "sm" | "md" | "lg" | "xl";
-type RecursicaBreakpoint = "base" | Breakpoint;
-
-const GridContext = createContext<{ grow: boolean }>({ grow: false });
-
-/** Remaps the Recursica-only "base" breakpoint key to MUI's "xs" (its smallest breakpoint). */
-function remapBase<T>(
-  value: T | Partial<Record<RecursicaBreakpoint, T>> | undefined,
-): T | Partial<Record<Breakpoint, T>> | undefined {
-  if (value === undefined || typeof value !== "object") {
-    return value as T | undefined;
-  }
-  const { base, ...rest } = value as Partial<Record<RecursicaBreakpoint, T>>;
-  return base !== undefined
-    ? ({ xs: base, ...rest } as Partial<Record<Breakpoint, T>>)
-    : (rest as Partial<Record<Breakpoint, T>>);
-}
-
-/**
- * Recursica's "auto" (grow to fill remaining space) and "content" (size to content)
- * are the inverse of MUI's own "auto" (size to content) and "grow" (fill remaining
- * space) keywords.
- */
-function mapSpanValue(
-  value: number | "auto" | "content" | undefined,
-): number | "auto" | "grow" | undefined {
-  if (value === "auto") return "grow";
-  if (value === "content") return "auto";
-  return value;
-}
-
-function mapSpan(span: RecursicaGridColProps["span"]): MuiGridProps["size"] {
-  const remapped = remapBase(span);
-  if (remapped === undefined || typeof remapped !== "object") {
-    return mapSpanValue(remapped as number | "auto" | "content" | undefined);
-  }
-  const mapped: Partial<Record<Breakpoint, number | "auto" | "grow">> = {};
-  (
-    Object.entries(remapped) as [Breakpoint, number | "auto" | "content"][]
-  ).forEach(([key, value]) => {
-    mapped[key] = mapSpanValue(value);
-  });
-  return mapped as MuiGridProps["size"];
-}
-
-function mapOffset(
-  offset: RecursicaGridColProps["offset"],
-): MuiGridProps["offset"] {
-  return remapBase(offset) as MuiGridProps["offset"];
-}
-
-/**
- * `order` has no native MUI Grid equivalent. A fixed number is applied directly.
- * A responsive object is NOT fully supported in this v1 — the smallest specified
- * breakpoint's value is applied as a single static order (documented in
- * IMPLEMENTATION_NOTES.md), rather than building bespoke per-breakpoint CSS for it.
- */
-function resolveOrder(
-  order: RecursicaGridColProps["order"],
-): number | undefined {
-  if (order === undefined || typeof order === "number") {
-    return order;
-  }
-  const remapped = remapBase(order) as Partial<Record<Breakpoint, number>>;
-  return (
-    remapped.xs ?? remapped.sm ?? remapped.md ?? remapped.lg ?? remapped.xl
-  );
-}
 
-const HIDDEN_FROM_CLASS: Partial<Record<Breakpoint, string>> = {
+const HIDDEN_FROM_CLASS: Record<Breakpoint, string> = {
   xs: styles.hiddenFromXs,
   sm: styles.hiddenFromSm,
   md: styles.hiddenFromMd,
@@ -108,7 +44,7 @@ const HIDDEN_FROM_CLASS: Partial<Record<Breakpoint, string>> = {
   xl: styles.hiddenFromXl,
 };
 
-// "xs"/"base" intentionally absent: visible from the smallest breakpoint means never hidden.
+// "xs" intentionally absent: visible from the smallest breakpoint means never hidden.
 const VISIBLE_FROM_CLASS: Partial<Record<Breakpoint, string>> = {
   sm: styles.visibleFromSm,
   md: styles.visibleFromMd,
@@ -116,56 +52,47 @@ const VISIBLE_FROM_CLASS: Partial<Record<Breakpoint, string>> = {
   xl: styles.visibleFromXl,
 };
 
-function normalizeBreakpoint(bp: RecursicaBreakpoint): Breakpoint {
-  return bp === "base" ? "xs" : bp;
-}
-
 // ============================================================
 // GRID
 // ============================================================
 
 export type GridProps = WithRecursicaSpacing<
-  OmitSx<Omit<MuiGridProps, "container" | "size" | "offset">> &
-    RecursicaGridProps
->;
+  OmitSx<Omit<MuiGridProps, "container" | "justifyContent" | "alignItems">>
+> & {
+  /** Sets `justify-content` on the container. Applied via inline style — see notes above. */
+  justifyContent?: CSSProperties["justifyContent"];
+  /** Sets `align-items` on the container. Applied via inline style — see notes above. */
+  alignItems?: CSSProperties["alignItems"];
+};
 
 const GridBase = forwardRef<HTMLDivElement, GridProps>(function Grid(
   {
     children,
-    gap = "rec-default",
-    columns = 12,
-    grow = false,
-    justify,
-    align,
+    spacing = "rec-default",
+    justifyContent,
+    alignItems,
     style,
     ...rest
   },
   ref,
 ) {
   const safeProps = filterSxProp(rest as Record<string, unknown>);
-  const resolvedGap =
-    typeof gap === "string" && gap in SPACING_MAP
-      ? SPACING_MAP[gap as keyof typeof SPACING_MAP]
-      : gap;
+  const resolvedSpacing =
+    typeof spacing === "string" && spacing in SPACING_MAP
+      ? SPACING_MAP[spacing as keyof typeof SPACING_MAP]
+      : spacing;
 
   return (
-    <GridContext.Provider value={{ grow }}>
-      <MuiGrid
-        ref={ref}
-        {...(safeProps as unknown as MuiGridProps)}
-        container
-        columns={columns}
-        spacing={resolvedGap}
-        className={styles.root}
-        style={{
-          justifyContent: justify,
-          alignItems: align,
-          ...(style as CSSProperties),
-        }}
-      >
-        {children}
-      </MuiGrid>
-    </GridContext.Provider>
+    <MuiGrid
+      ref={ref}
+      {...(safeProps as unknown as MuiGridProps)}
+      container
+      spacing={resolvedSpacing}
+      className={styles.root}
+      style={{ justifyContent, alignItems, ...(style as CSSProperties) }}
+    >
+      {children}
+    </MuiGrid>
   );
 });
 GridBase.displayName = "Grid";
@@ -175,33 +102,27 @@ GridBase.displayName = "Grid";
 // ============================================================
 
 export type GridColProps = WithRecursicaSpacing<
-  OmitSx<Omit<MuiGridProps, "container" | "size" | "offset">> &
-    RecursicaGridColProps
->;
+  OmitSx<Omit<MuiGridProps, "container" | "order">>
+> & {
+  /** Sets the CSS `order` property. Applied via inline style — see notes above. */
+  order?: number;
+  /** Hides the column below the given breakpoint. MUI has no native equivalent. */
+  visibleFrom?: Breakpoint;
+  /** Hides the column above the given breakpoint. MUI has no native equivalent. */
+  hiddenFrom?: Breakpoint;
+};
 
 export const GridCol = forwardRef<HTMLDivElement, GridColProps>(
   function GridCol(
-    {
-      children,
-      span,
-      offset,
-      order,
-      visibleFrom,
-      hiddenFrom,
-      style,
-      className,
-      ...rest
-    },
+    { children, order, visibleFrom, hiddenFrom, style, className, ...rest },
     ref,
   ) {
-    const { grow } = useContext(GridContext);
     const safeProps = filterSxProp(rest as Record<string, unknown>);
-    const resolvedOrder = resolveOrder(order);
 
     const visibilityClass = visibleFrom
-      ? VISIBLE_FROM_CLASS[normalizeBreakpoint(visibleFrom)]
+      ? VISIBLE_FROM_CLASS[visibleFrom]
       : hiddenFrom
-        ? HIDDEN_FROM_CLASS[normalizeBreakpoint(hiddenFrom)]
+        ? HIDDEN_FROM_CLASS[hiddenFrom]
         : undefined;
 
     const finalClassName = [styles.col, visibilityClass, className]
@@ -211,15 +132,9 @@ export const GridCol = forwardRef<HTMLDivElement, GridColProps>(
     return (
       <MuiGrid
         ref={ref}
-        size={mapSpan(span)}
-        offset={mapOffset(offset)}
         className={finalClassName}
         {...(safeProps as unknown as MuiGridProps)}
-        style={{
-          order: resolvedOrder,
-          ...(grow ? { flexGrow: 1 } : {}),
-          ...(style as CSSProperties),
-        }}
+        style={{ order, ...(style as CSSProperties) }}
       >
         {children}
       </MuiGrid>

package/src/components/Grid/IMPLEMENTATION_NOTES.md

@@ -1,16 +1,16 @@
 # Grid Implementation Notes
 
-MUI has no native Grid/Grid.Col split — MUI's own `Grid` component merges "container" and "item" behavior into one component (toggled by the `container` boolean and a `size` prop). To keep the exact same public API as the mantine-adapter (`Grid` + `Grid.Col` dot notation, matching Mantine's own `Grid`/`Grid.Col`), this file hand-composes two wrappers around that single underlying component: `Grid` always renders `<MuiGrid container>`, `Grid.Col` always renders `<MuiGrid>` in item mode. A `GridContext` (internal, not exported) carries the parent's `grow` flag down to `Grid.Col`, since MUI has no equivalent React context of its own for this and siblings can't share props directly.
+MUI has no native Grid/Grid.Col split — MUI's own `Grid` component merges "container" and "item" behavior into one component (toggled by the `container` boolean and a `size` prop). To keep the same `Grid` + `Grid.Col` dot-notation shape as the mantine-adapter, this file hand-composes two thin wrappers around that single underlying component: `Grid` always renders `<MuiGrid container>`, `Grid.Col` always renders `<MuiGrid>` in item mode. This is a structural convenience only — the props on each wrapper are MUI's own, not a Recursica-defined contract.
 
-Prop mapping details and divergences from a literal 1:1 MUI wrap:
+Per the layout-components rule (no formal Recursica common props definition — layout components simply pass through the underlying kit's own props), this Grid does **not** attempt prop-name parity with the mantine-adapter's Grid. Its public API is MUI's own vocabulary:
 
-- **`gap` → `spacing`**: MUI's own container-spacing prop is `spacing` (not `gutter`, which is Mantine's term). Resolved through the same `rec-*` → `SPACING_MAP` lookup used elsewhere in this adapter.
-- **`span` keyword inversion**: Recursica's `"auto"` (fill remaining space) and `"content"` (size to content) are the _inverse_ of MUI's own `size` keywords — MUI's `"auto"` means size-to-content and `"grow"` means fill-remaining-space. `mapSpanValue()` translates between them so the public `span` prop matches Mantine's semantics exactly. Verified against `@mui/system`'s `generateGridSizeStyles` (`grow` → `flexGrow:1`, `auto` → `flexBasis:auto`).
-- **`offset`**: Maps directly to MUI's own `offset` prop — same name, same responsive shape and semantics. No translation needed.
-- **`"base"` breakpoint key**: Recursica's breakpoint objects (matching Mantine's `Grid.Col` shape) use `base` for the default/smallest value; MUI has no `"base"` key, only `xs` as its smallest breakpoint (`min-width: 0`). `remapBase()` renames `base` → `xs` (an explicit `xs` in the same object wins over `base` if both are present).
-- **`order`**: MUI's Grid has no `order` prop at all. A fixed number is applied via inline `style.order` (inline style always wins the cascade, so this works regardless of MUI's generated styles). A responsive object is **not** fully implemented — building full per-breakpoint CSS custom-property cascading for a rarely-used prop wasn't judged worth the added CSS surface for v1. `resolveOrder()` currently just takes the smallest specified breakpoint's value and applies it as a single static order. This is a known, documented gap, not a silent one — revisit if a real per-breakpoint ordering need comes up.
-- **`grow`**: MUI's Grid has no equivalent. Mantine's own implementation (and this one) relies on a CSS quirk: setting `flex-grow: 1` on every column in a row only visibly affects the _last, incomplete_ row — fully-filled rows have zero remaining space to grow into. Applied via inline `style.flexGrow` on `Grid.Col`, read from `GridContext`.
-- **`visibleFrom` / `hiddenFrom`**: No native MUI Grid mechanism. Implemented via `Grid.module.css` media-query classes, hardcoded to MUI's own default `theme.breakpoints` pixel values (`xs:0, sm:600, md:900, lg:1200, xl:1536`). If the consuming app customizes its MUI theme breakpoints, these thresholds won't follow — structural layout mechanics, not a design token, so this doesn't go through the token pipeline.
-- **`justifyContent` / `alignItems`**: MUI's `Grid` does not register these as recognized style-system props the way `Box` does (confirmed by reading `@mui/system`'s `gridGenerator.js` — no generator function reads them), so passing them as bare props would silently do nothing. They're applied via inline `style` instead.
+- **`spacing`** (not Mantine's `gutter`/the old Recursica `gap` alias) — MUI's own container-spacing prop. Still accepts `rec-*` tokens, resolved through the same `SPACING_MAP` lookup used elsewhere in this adapter.
+- **`size`** (not Mantine's `span`) — MUI's own item-sizing prop on `Grid.Col`: a column count, `"auto"` (size to content), `"grow"` (fill remaining space), or a responsive object keyed by MUI's own breakpoints. No inversion/translation against Mantine's `span` semantics.
+- **`offset`** — MUI's own prop, used as-is.
+- **Breakpoint objects** use MUI's own scale (`xs`/`sm`/`md`/`lg`/`xl`) directly. There is no `"base"` alias — `xs` is MUI's smallest breakpoint, same role Mantine's own smallest breakpoint plays.
+- **`grow` (container-level)**: not implemented. Mantine's container `grow` flag ("last row's columns expand to fill available space") has no MUI equivalent, but MUI's own `size="grow"` on individual `Grid.Col`s already covers the same real-world need — set it per-column instead of on the container.
+- **`order`**: MUI types `order` generically (via `SystemProps`) but its Grid style generator (`gridGenerator.js`/`createGrid.js`, read directly to confirm) never wires it up — passing it straight through silently no-ops. Applied here via inline `style.order` instead, single value only (no per-breakpoint object).
+- **`justifyContent` / `alignItems`** (container only): same issue as `order` — typed but not read by MUI's Grid generator (confirmed by reading `gridGenerator.js`: only `size`, `offset`, `columns`, spacing, `direction`, and `wrap` have generator functions). Applied via inline `style` instead, using MUI's own prop names (not Mantine's `justify`/`align`).
+- **`visibleFrom` / `hiddenFrom`**: no native MUI Grid mechanism at all, so — per the rule that a missing kit feature is built following Mantine's own shape — implemented via `Grid.module.css` media-query classes, hardcoded to MUI's own default `theme.breakpoints` pixel values (`xs:0, sm:600, md:900, lg:1200, xl:1536`). If the consuming app customizes its MUI theme breakpoints, these thresholds won't follow — structural layout mechanics, not a design token.
 
-**Cross-adapter parity caveat**: `visibleFrom`/`hiddenFrom` (and the eventual full responsive `order`) are pinned to MUI's default breakpoints here, while the mantine-adapter's equivalent behavior is driven by Mantine's own default breakpoints (576/768/992/1200/1408). The two adapters' Grid stories may show different columns at the exact same viewport width in the `adapter-tester` visual-regression suite as a result — a real, structural difference between the two underlying libraries' breakpoint scales, not a bug in either adapter.
+**Cross-adapter parity caveat**: `visibleFrom`/`hiddenFrom` are pinned to MUI's default breakpoints here, while the mantine-adapter's equivalent behavior is driven by Mantine's own default breakpoints (576/768/992/1200/1408). The two adapters' Grid stories may show different columns at the exact same viewport width in the `adapter-tester` visual-regression suite as a result — a real, structural difference between the two underlying libraries' breakpoint scales, not a bug in either adapter. The two adapters' Grid APIs are also no longer prop-name-identical (`spacing`/`size` here vs. `gutter`/`span` in mantine-adapter) — this is intentional per the layout-components rule; each adapter's Grid speaks its own kit's vocabulary.

package/src/components/Grid/USAGE.md

@@ -20,9 +20,9 @@ import { Grid } from "@recursica/mui-adapter";
 
 export default function Demo() {
   return (
-    <Grid gap="rec-default">
-      <Grid.Col span={6}>Half width</Grid.Col>
-      <Grid.Col span={{ base: 12, sm: 6, md: 3 }}>Responsive width</Grid.Col>
+    <Grid spacing="rec-default">
+      <Grid.Col size={6}>Half width</Grid.Col>
+      <Grid.Col size={{ xs: 12, sm: 6, md: 3 }}>Responsive width</Grid.Col>
     </Grid>
   );
 }
@@ -44,8 +44,10 @@ All Recursica components in the `@recursica/mui-adapter` package adhere strictly
 
 ## 4. Key Integration Features & Constraints
 
-- `gap` controls the spacing between grid items.
-- `span` accepts a column count, `"auto"`, `"content"`, or a responsive object (`{ base, sm, md, ... }`).
+This Grid uses MUI's own prop vocabulary directly (see [IMPLEMENTATION_NOTES.md](./IMPLEMENTATION_NOTES.md)) — it is not name-for-name identical to the mantine-adapter's Grid.
+
+- `spacing` controls the space between grid items (accepts `rec-*` tokens).
+- `size` accepts a column count, `"auto"`, `"grow"`, or a responsive object (`{ xs, sm, md, ... }`).
 - `offset` shifts a column by a number of columns.
-- `order` accepts a fixed number to control a column's visual order. A responsive object (`{ base, sm, md, ... }`) is **not** fully supported yet — only the smallest specified breakpoint's value is applied.
+- `order` accepts a fixed number to control a column's visual order (single value only, no responsive object).
 - `visibleFrom`/`hiddenFrom` show or hide a column at the standard breakpoints (600/900/1200/1536px).

package/src/components/Group/Group.test.tsx

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

package/src/components/Group/Group.tsx

@@ -1,3 +1,12 @@
+/**
+ * Group layout wrapper.
+ *
+ * NOTE: MUI has no native `<Group>` component. Per the layout-components rule, when a UI kit
+ * lacks an equivalent component it's built following a prop definition similar to Mantine's
+ * own `Group` (gap/rowGap/columnGap/justify/align/wrap) — this shape is owned locally here,
+ * not shared as a formal cross-adapter Recursica contract. It's implemented as a row-direction,
+ * wrapping MUI `Stack`.
+ */
 import { forwardRef } from "react";
 import {
   Stack as MUIStack,
@@ -10,10 +19,23 @@ import {
   type WithRecursicaSpacing,
 } from "../../utils/filterStylingProps";
 
-import { type RecursicaGroupProps } from "@recursica/adapter-common";
+interface GroupOwnProps {
+  /** Gap spacing */
+  gap?: string | number;
+  /** Row gap spacing */
+  rowGap?: string | number;
+  /** Column gap spacing */
+  columnGap?: string | number;
+  /** Align items justify properties */
+  justify?: React.CSSProperties["justifyContent"];
+  /** Align items vertical alignment */
+  align?: React.CSSProperties["alignItems"];
+  /** Flex-wrap settings */
+  wrap?: React.CSSProperties["flexWrap"];
+}
 
 export type GroupProps = WithRecursicaSpacing<
-  OmitSx<Omit<MUIStackProps, "spacing" | "direction"> & RecursicaGroupProps>
+  OmitSx<Omit<MUIStackProps, "spacing" | "direction"> & GroupOwnProps>
 >;
 
 export const Group = forwardRef<HTMLDivElement, GroupProps>(function Group(

package/src/components/HoverCard/HoverCard.test.tsx

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

package/src/components/Label/Label.test.tsx

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

package/src/components/Link/Link.test.tsx

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

package/src/components/Loader/Loader.test.tsx

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

package/src/components/Menu/Menu.test.tsx

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

package/src/components/Modal/Modal.module.css

@@ -1,3 +1,14 @@
+/* Brand-layer exemptions (recursica-allow-brand) — see recursica-token-analyzer README.md.
+ * Close button is styled to match the Button component's text/icon-only variant, so it reuses
+ * the same global hover/focus state tokens Button.module.css exempts.
+ *   recursica-allow-brand: --recursica_brand_states_focus_blur
+ *   recursica-allow-brand: --recursica_brand_states_focus_border-size
+ *   recursica-allow-brand: --recursica_brand_states_focus_color
+ *   recursica-allow-brand: --recursica_brand_states_focus_margin
+ *   recursica-allow-brand: --recursica_brand_states_hover_color
+ *   recursica-allow-brand: --recursica_brand_states_hover_opacity
+ */
+
 .root {
 }
 
@@ -40,6 +51,9 @@
 }
 
 .header {
+  display: flex; /* HARDCODE: puts the title and close button side-by-side so the title has a bounded width to truncate against */
+  align-items: center;
+  justify-content: space-between;
   padding: var(
       --recursica_ui-kit_components_modal_properties_header-footer-vertical-padding
     )
@@ -50,6 +64,12 @@
 }
 
 .title {
+  flex: 1 1 auto; /* HARDCODE: let the title claim the space between the header edge and the close button */
+  min-width: 0; /* HARDCODE: required for text-overflow ellipsis to take effect on a flex child */
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+
   color: var(--recursica_ui-kit_components_modal_properties_colors_title);
 
   /* Direct Figma Typography Mapping */
@@ -173,5 +193,87 @@
 }
 
 .close {
-  /* Inherits standard icon button tokens natively, but we can override if required */
+  /* Matches the Button component's text-variant, icon-only, small-size visual treatment
+     (see Button.module.css) so the modal close control looks like a Recursica Button
+     rather than MUI's native IconButton. */
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  position: relative;
+  overflow: hidden;
+  transition: all 0.2s ease;
+
+  height: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_height
+  );
+  min-width: var(
+    --recursica_ui-kit_components_button_variants_content_icon-only_variants_sizes_small_properties_min-width
+  );
+  padding: 0
+    var(
+      --recursica_ui-kit_components_button_variants_content_icon-only_variants_sizes_small_properties_horizontal-padding
+    );
+  border-radius: var(
+    --recursica_ui-kit_components_button_variants_content_icon-only_variants_sizes_small_properties_border-radius
+  );
+
+  border-style: solid;
+  border-width: var(
+    --recursica_ui-kit_components_button_variants_styles_text_properties_border-size
+  );
+  border-color: var(
+    --recursica_ui-kit_components_button_variants_styles_text_properties_colors_border-color
+  );
+  background-color: var(
+    --recursica_ui-kit_components_button_variants_styles_text_properties_colors_background-color
+  );
+  color: var(
+    --recursica_ui-kit_components_button_variants_styles_text_properties_colors_icon-color
+  );
+}
+
+.close svg {
+  position: relative;
+  z-index: 1;
+  width: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_icon
+  );
+  height: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_icon
+  );
+}
+
+.close::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+  z-index: 0;
+  pointer-events: none;
+  transition: opacity 150ms ease;
+  opacity: 0;
+  background-color: var(--recursica_brand_states_hover_color);
+}
+.close:hover:not(:disabled)::after {
+  opacity: var(--recursica_brand_states_hover_opacity);
+}
+
+/* MuiIconButton injects its own `:hover` background via emotion at render time, which lands in
+   the DOM after this stylesheet and wins the tie at equal specificity — same class of conflict
+   documented in DatePicker.module.css's error/disabled state overrides. `!important` keeps the
+   button's own background transparent so only the `::after` overlay above renders the hover
+   feedback, matching Button's single-overlay hover treatment exactly. */
+.close:hover {
+  background-color: transparent !important;
+}
+
+.close:focus-visible {
+  outline: none;
+  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);
 }

package/src/components/Modal/Modal.stories.tsx

@@ -19,7 +19,8 @@ export default meta;
 type Story = StoryObj<typeof Modal>;
 
 const DefaultWrapper = (args: ModalProps) => {
-  const [opened, setOpened] = useState(false);
+  // Starts opened so the modal is visible without pressing a button first.
+  const [opened, setOpened] = useState(true);
   return (
     <>
       <Modal {...args} opened={opened} onClose={() => setOpened(false)}>
@@ -43,8 +44,33 @@ export const Default: Story = {
   render: (args) => <DefaultWrapper {...args} />,
 };
 
+const LongTitleWrapper = (args: ModalProps) => {
+  const [opened, setOpened] = useState(true);
+  return (
+    <>
+      <Modal {...args} opened={opened} onClose={() => setOpened(false)}>
+        The title above is longer than the header can display, so it truncates
+        with an ellipsis instead of wrapping onto a second line.
+        <Modal.Footer>
+          <Button onClick={() => setOpened(false)}>Got it</Button>
+        </Modal.Footer>
+      </Modal>
+      <Button onClick={() => setOpened(true)}>Open Modal</Button>
+    </>
+  );
+};
+
+export const LongTitle: Story = {
+  args: {
+    title:
+      "This Modal Title Is Deliberately Long Enough To Exceed The Available Header Width",
+  },
+  render: (args) => <LongTitleWrapper {...args} />,
+};
+
 const ScrollingWrapper = (args: ModalProps) => {
-  const [opened, setOpened] = useState(false);
+  // Starts opened so the modal is visible without pressing a button first.
+  const [opened, setOpened] = useState(true);
   return (
     <>
       <Modal {...args} opened={opened} onClose={() => setOpened(false)}>

package/src/components/Modal/Modal.test.tsx

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

package/src/components/NumberInput/NumberInput.test.tsx

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

package/src/components/Pagination/Pagination.test.tsx

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

package/src/components/Panel/Panel.test.tsx

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

package/src/components/Popover/Popover.test.tsx

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

package/src/components/Radio/Radio.test.tsx

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

package/src/components/ReadOnlyField/ReadOnlyField.test.tsx

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

package/src/components/SegmentedControl/SegmentedControl.test.tsx

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

package/src/components/Slider/Slider.test.tsx

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