@recursica/mantine-adapter 0.42.0 → 0.43.0

package/src/components/Card/Card.tsx

@@ -7,6 +7,8 @@ import {
 } from "@mantine/core";
 import {
   filterStylingProps,
+  omitUnsupportedProps,
+  mergeClassNames,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import styles from "./Card.module.css";
@@ -32,11 +34,23 @@ export type CardProps = RecursicaOverStyled<
 /**
  * The root Card elevation box. It establishes the global background color, border radius, nested component gap, and outer shadow governed by the current `Layer` context.
  */
+// 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. `Card.module.css` unconditionally
+// drives these from Recursica UI Kit tokens on `.root`; the native prop is never consulted.
+const UNSUPPORTED_PROPS = [
+  "radius", // Border radius is token-driven (`--recursica_..._borders_border-radius`), not caller-set.
+  "withBorder", // Border is always applied via tokens on `.root`; not an optional caller toggle.
+  "padding", // Padding is token-driven (`--card-padding`), not Mantine's spacing-scale prop.
+] as const satisfies readonly (keyof MantineCardProps)[];
+
 const CardBase = forwardRef<HTMLDivElement, CardProps>(function Card(
   { overStyled = false, ...rest },
   ref,
 ) {
-  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const sanitizedProps = omitUnsupportedProps(
+    filterStylingProps(rest, overStyled),
+    UNSUPPORTED_PROPS,
+  );
 
   // Expose outer layout/flexbox properties on Card to allow structuring alongside siblings
   const safeCardLayoutKeys = [
@@ -56,25 +70,14 @@ const CardBase = forwardRef<HTMLDivElement, CardProps>(function Card(
     }
   });
 
-  const mergedClassNames: Partial<Record<string, string>> = {
-    root: styles.root,
-  };
-
-  const classNamesProp = (sanitizedProps as Record<string, unknown>).classNames;
-  if (
-    classNamesProp &&
-    typeof classNamesProp === "object" &&
-    !Array.isArray(classNamesProp)
-  ) {
-    const o = classNamesProp as Record<string, string>;
-    Object.keys(o).forEach((key) => {
-      if (mergedClassNames[key]) {
-        mergedClassNames[key] = `${mergedClassNames[key]} ${o[key]}`;
-      } else {
-        mergedClassNames[key] = o[key];
-      }
-    });
-  }
+  const mergedClassNames = mergeClassNames(
+    {
+      root: styles.root,
+    },
+    (sanitizedProps as Record<string, unknown>).classNames as
+      | Partial<Record<string, string>>
+      | undefined,
+  );
 
   const classNameProp = (sanitizedProps as Record<string, unknown>)
     .className as string | undefined;
@@ -82,9 +85,9 @@ const CardBase = forwardRef<HTMLDivElement, CardProps>(function Card(
   return (
     <MantineCard
       ref={ref}
+      {...(sanitizedProps as unknown as MantineCardProps)}
       className={classNameProp}
       classNames={mergedClassNames}
-      {...(sanitizedProps as unknown as MantineCardProps)}
     />
   );
 });
@@ -106,10 +109,10 @@ export const CardSection = forwardRef<HTMLDivElement, CardSectionProps>(
     return (
       <MantineCard.Section
         ref={ref}
+        {...(sanitizedProps as unknown as MantineCardSectionProps)}
         className={
           classNameProp ? `${styles.section} ${classNameProp}` : styles.section
         }
-        {...(sanitizedProps as unknown as MantineCardSectionProps)}
       />
     );
   },
@@ -122,19 +125,32 @@ export type CardHeaderProps = RecursicaOverStyled<RecursicaCardSectionProps>;
 /**
  * Replaces standard generic Mantine `<Card.Section>` wrappers by directly injecting the strict Recursica design tokens for header sizing, background drops, and intrinsic padding limits.
  */
+// 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. `CardHeaderProps` already omits all
+// native Mantine section props from the public type, but that alone doesn't stop a forced-typed
+// caller from smuggling one through `...rest`; `.header` in Card.module.css unconditionally
+// drives background/padding/border from Recursica tokens, so these native toggles are meaningless.
+const HEADER_FOOTER_UNSUPPORTED_PROPS = [
+  "withBorder", // The divider border is always applied via tokens on `.header`/`.footer`.
+  "inheritPadding", // Padding is fixed by the `.header`/`.footer` token-driven padding, not Mantine's default.
+] as const satisfies readonly (keyof MantineCardSectionProps)[];
+
 export const CardHeader = forwardRef<HTMLDivElement, CardHeaderProps>(
   function CardHeader({ overStyled = false, ...rest }, ref) {
-    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const sanitizedProps = omitUnsupportedProps(
+      filterStylingProps(rest, overStyled),
+      HEADER_FOOTER_UNSUPPORTED_PROPS,
+    );
     const classNameProp = (sanitizedProps as Record<string, unknown>)
       .className as string | undefined;
 
     return (
       <MantineCard.Section
         ref={ref}
+        {...(sanitizedProps as unknown as MantineCardSectionProps)}
         className={
           classNameProp ? `${styles.header} ${classNameProp}` : styles.header
         }
-        {...(sanitizedProps as unknown as MantineCardSectionProps)}
       />
     );
   },
@@ -149,17 +165,22 @@ export type CardFooterProps = RecursicaOverStyled<RecursicaCardSectionProps>;
  */
 export const CardFooter = forwardRef<HTMLDivElement, CardFooterProps>(
   function CardFooter({ overStyled = false, ...rest }, ref) {
-    const sanitizedProps = filterStylingProps(rest, overStyled);
+    // Reuses HEADER_FOOTER_UNSUPPORTED_PROPS (declared above with CardHeader) — same rationale
+    // applies: `.footer` in Card.module.css unconditionally drives padding/border from tokens.
+    const sanitizedProps = omitUnsupportedProps(
+      filterStylingProps(rest, overStyled),
+      HEADER_FOOTER_UNSUPPORTED_PROPS,
+    );
     const classNameProp = (sanitizedProps as Record<string, unknown>)
       .className as string | undefined;
 
     return (
       <MantineCard.Section
         ref={ref}
+        {...(sanitizedProps as unknown as MantineCardSectionProps)}
         className={
           classNameProp ? `${styles.footer} ${classNameProp}` : styles.footer
         }
-        {...(sanitizedProps as unknown as MantineCardSectionProps)}
       />
     );
   },
@@ -183,10 +204,10 @@ export const CardContent = forwardRef<HTMLDivElement, CardContentProps>(
     return (
       <div
         ref={ref}
+        {...sanitizedProps}
         className={
           classNameProp ? `${styles.content} ${classNameProp}` : styles.content
         }
-        {...sanitizedProps}
       />
     );
   },

package/src/components/Checkbox/Checkbox.tsx

@@ -7,6 +7,8 @@ import { type ReadOnlyControlProps } from "@recursica/adapter-common";
 import { CheckboxGroup } from "./CheckboxGroup";
 import {
   filterStylingProps,
+  omitUnsupportedProps,
+  mergeClassNames,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import {
@@ -56,49 +58,34 @@ export const Checkbox = forwardRef<HTMLInputElement, CheckboxProps>(
       ...rest
     } = props;
     // Checkbox doesn't use Label onLabelEditClick natively since it isn't mapped inside FormControlWrapper intrinsically.
-    const sanitizedProps = filterStylingProps(rest, overStyled);
+    // 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 Checkbox.module.css variables, not Mantine's native size scale.
+      "color", // Colors are token-driven via Checkbox.module.css; Mantine's native palette isn't exposed.
+      "radius", // Corner radius is fixed by Recursica tokens in Checkbox.module.css, not caller-configurable.
+      "variant", // Checkbox has a single Recursica-defined visual treatment; Mantine's variant isn't exposed.
+      "iconColor", // Icon color is token-driven via Checkbox.module.css, not a native Mantine override.
+    ] as const satisfies readonly (keyof MantineCheckboxProps)[];
+
+    const sanitizedProps = omitUnsupportedProps(
+      filterStylingProps(rest, overStyled) as Record<string, unknown>,
+      UNSUPPORTED_PROPS,
+    ) as Partial<typeof rest>;
     const restRecord = sanitizedProps as Record<string, unknown>;
 
-    // Actively delete dimension bindings that bypass the abstraction
-    delete restRecord["size"];
-    delete restRecord["color"];
-    delete restRecord["radius"];
-    delete restRecord["variant"];
-    delete restRecord["iconColor"];
-
-    const mergedClassNames: Partial<Record<string, string>> = {
-      root: styles.root,
-      body: styles.body,
-      inner: styles.inner,
-      input: styles.input,
-      icon: styles.icon,
-      labelWrapper: styles.labelWrapper,
-      label: styles.label,
-    };
-
-    const classNamesProp = restRecord.classNames;
-    if (
-      classNamesProp &&
-      typeof classNamesProp === "object" &&
-      !Array.isArray(classNamesProp)
-    ) {
-      const o = classNamesProp as Partial<Record<string, string>>;
-      mergedClassNames.root = o.root ? `${styles.root} ${o.root}` : styles.root;
-      mergedClassNames.body = o.body ? `${styles.body} ${o.body}` : styles.body;
-      mergedClassNames.inner = o.inner
-        ? `${styles.inner} ${o.inner}`
-        : styles.inner;
-      mergedClassNames.input = o.input
-        ? `${styles.input} ${o.input}`
-        : styles.input;
-      mergedClassNames.icon = o.icon ? `${styles.icon} ${o.icon}` : styles.icon;
-      mergedClassNames.labelWrapper = o.labelWrapper
-        ? `${styles.labelWrapper} ${o.labelWrapper}`
-        : styles.labelWrapper;
-      mergedClassNames.label = o.label
-        ? `${styles.label} ${o.label}`
-        : styles.label;
-    }
+    const mergedClassNames = mergeClassNames(
+      {
+        root: styles.root,
+        body: styles.body,
+        inner: styles.inner,
+        input: styles.input,
+        icon: styles.icon,
+        labelWrapper: styles.labelWrapper,
+        label: styles.label,
+      },
+      restRecord.classNames as Partial<Record<string, string>> | undefined,
+    );
 
     const classNameProp = restRecord.className as string | undefined;
     const finalClass = classNameProp
@@ -136,10 +123,10 @@ export const Checkbox = forwardRef<HTMLInputElement, CheckboxProps>(
     const checkboxNode = (
       <MantineCheckbox
         ref={ref}
+        {...(sanitizedProps as unknown as MantineCheckboxProps)}
         className={finalClass}
         classNames={mergedClassNames}
         disabled={readOnly || disabled}
-        {...(sanitizedProps as unknown as MantineCheckboxProps)}
       />
     );
 

package/src/components/Checkbox/CheckboxGroup.tsx

@@ -7,6 +7,7 @@ import {
 import { type ReadOnlyControlProps } from "@recursica/adapter-common";
 import {
   filterStylingProps,
+  omitUnsupportedProps,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import { type RecursicaFormControlWrapperProps } from "../FormControlWrapper/FormControlWrapper";
@@ -62,11 +63,17 @@ export const CheckboxGroup = forwardRef<HTMLDivElement, CheckboxGroupProps>(
       defaultValue,
       ...rest
     } = props;
-    const sanitizedProps = filterStylingProps(rest, overStyled);
-    const restRecord = sanitizedProps as Record<string, unknown>;
+    // 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 Checkbox.module.css variables, not Mantine's native size scale.
+    ] as const satisfies readonly (keyof MantineCheckboxGroupProps)[];
 
-    // Delete prohibited sizing hooks from bypassing the variables
-    delete restRecord["size"];
+    const sanitizedProps = omitUnsupportedProps(
+      filterStylingProps(rest, overStyled) as Record<string, unknown>,
+      UNSUPPORTED_PROPS,
+    ) as Partial<typeof rest>;
+    const restRecord = sanitizedProps as Record<string, unknown>;
 
     // Mantine's own `Checkbox.Group` always establishes a context whose `value` defaults to
     // `[]` (see @mantine/core's `useUncontrolled({ finalValue: [] })`), and its `Checkbox` spreads
@@ -123,8 +130,8 @@ export const CheckboxGroup = forwardRef<HTMLDivElement, CheckboxGroupProps>(
           ) : (
             <div
               ref={ref}
-              role="group"
               {...(sanitizedProps as Record<string, unknown>)}
+              role="group"
               className={styles.groupRoot}
               data-layout={formLayout}
             >

package/src/components/Chip/Chip.module.css

@@ -1,19 +1,3 @@
-/* EXEMPTIONS:
-   - close-icon-color, leading-icon-color, and select-specific state icon variables are ignored because 
-     Chip uses explicit state color definitions (e.g. unselected, selected, error, error-selected variant colors) 
-     to drive pixel-perfect hover and click transitions, rather than generic single-color overrides.
-   - text-size is ignored since actual chip sizing is dynamically driven by precise vertical padding and line-heights. */
-/* recursica-ignore: --recursica_ui-kit_components_chip_properties_close-icon-color */
-/* recursica-ignore: --recursica_ui-kit_components_chip_properties_leading-icon-color */
-/* recursica-ignore: --recursica_ui-kit_components_chip_properties_text-size */
-/* recursica-ignore: --recursica_ui-kit_components_chip_variants_selection-states_unselected_variants_states_error_properties_colors_leading-icon-color */
-/* recursica-ignore: --recursica_ui-kit_components_chip_variants_selection-states_unselected_variants_states_error_properties_colors_selected-icon-color */
-/* recursica-ignore: --recursica_ui-kit_components_chip_variants_selection-states_unselected_variants_states_error_properties_colors_icon-color */
-/* recursica-ignore: --recursica_ui-kit_components_chip_variants_selection-states_selected_variants_states_error_properties_colors_icon-color */
-/* recursica-ignore: --recursica_ui-kit_components_chip_variants_selection-states_selected_variants_states_error_properties_colors_leading-icon-color */
-/* recursica-ignore: --recursica_ui-kit_components_chip_variants_selection-states_selected_properties_colors_leading-icon-color */
-/* recursica-ignore: --recursica_ui-kit_components_chip_variants_selection-states_unselected_properties_colors_selected-icon-color */
-
 /* HARDCODED VALUES
    border-style: solid;  (Baseline reset)
    box-sizing: border-box; (Baseline reset)

package/src/components/Chip/Chip.tsx

@@ -5,6 +5,8 @@ import {
 } from "@mantine/core";
 import {
   filterStylingProps,
+  mergeClassNames,
+  withCallerOverride,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import styles from "./Chip.module.css";
@@ -45,6 +47,9 @@ export const Chip = forwardRef<HTMLInputElement, ChipProps>(function Chip(
     removeIconRef,
     children,
     overStyled = false,
+    wrapperProps,
+    tabIndex,
+    "aria-hidden": ariaHidden,
     ...rest
   },
   ref,
@@ -52,26 +57,16 @@ export const Chip = forwardRef<HTMLInputElement, ChipProps>(function Chip(
   const sanitizedProps = filterStylingProps(rest, overStyled);
   const restRecord = sanitizedProps as Record<string, unknown>;
 
-  const mergedClassNames: Partial<Record<string, string>> = {
-    root: styles.root,
-    label: styles.label,
-    input: styles.input,
-    iconWrapper: styles.mantineIconWrapper,
-    checkIcon: styles.checkIcon,
-  };
-
-  const classNamesProp = restRecord.classNames;
-  if (
-    classNamesProp &&
-    typeof classNamesProp === "object" &&
-    !Array.isArray(classNamesProp)
-  ) {
-    const o = classNamesProp as Partial<Record<string, string>>;
-    mergedClassNames.root = o.root ? `${styles.root} ${o.root}` : styles.root;
-    mergedClassNames.label = o.label
-      ? `${styles.label} ${o.label}`
-      : styles.label;
-  }
+  const mergedClassNames = mergeClassNames(
+    {
+      root: styles.root,
+      label: styles.label,
+      input: styles.input,
+      iconWrapper: styles.mantineIconWrapper,
+      checkIcon: styles.checkIcon,
+    },
+    restRecord.classNames as Partial<Record<string, string>> | undefined,
+  );
 
   const classNameProp = restRecord.className as string | undefined;
   const finalClass = classNameProp
@@ -90,18 +85,30 @@ export const Chip = forwardRef<HTMLInputElement, ChipProps>(function Chip(
     restRecord.onClick !== undefined ||
     restRecord.onChange !== undefined;
 
+  // Our own computed default for Mantine's `wrapperProps` — flags the internal error/interactive
+  // CSS hooks. This is a real Mantine `ChipProps` slot a caller could legitimately pass their own
+  // value for, so it must merge via `withCallerOverride`, not silently clobber theirs.
+  const computedWrapperProps = {
+    ...(dataError !== undefined ? { "data-error": "" } : {}),
+    ...(isInteractive ? { "data-interactive": "" } : {}),
+  } as NonNullable<MantineChipProps["wrapperProps"]>;
+
   return (
     <MantineChip
       ref={ref}
+      {...sanitizedProps}
       className={finalClass}
       classNames={mergedClassNames}
-      wrapperProps={{
-        ...(dataError !== undefined ? { "data-error": "" } : {}),
-        ...(isInteractive ? { "data-interactive": "" } : {}),
-      }}
-      {...(isIconOnly ? { "data-icon-only": "" } : {})}
-      {...(!isInteractive ? { tabIndex: -1, "aria-hidden": true } : {})}
-      {...sanitizedProps}
+      wrapperProps={withCallerOverride(computedWrapperProps, wrapperProps)}
+      data-icon-only={isIconOnly ? "" : undefined}
+      tabIndex={withCallerOverride<number | undefined>(
+        isInteractive ? undefined : -1,
+        tabIndex,
+      )}
+      aria-hidden={withCallerOverride<boolean | "true" | "false" | undefined>(
+        isInteractive ? undefined : true,
+        ariaHidden,
+      )}
     >
       <span className={styles.innerWrapper}>
         {icon && (

package/src/components/DatePicker/DATEPICKER_IMPLEMENTATION_NOTES.md

@@ -8,9 +8,22 @@ The `DatePicker` component is a wrapper around the `@mantine/dates` `DatePickerI
 
 1. **Naked Input Usage**: We intentionally pass `label={undefined}`, `description={undefined}`, and `error={undefined}` to the Mantine `DatePickerInput` component. This suppresses Mantine's internal macro form wrapping and ensures that only our `WithReadOnlyWrapper` > `FormControlWrapper` orchestrates labels, description text, and ARIA state error boundaries.
 2. **Read-Only Implementation**: Since the value type for `DatePickerInput` can be a date object, string, or array, the `WithReadOnlyWrapper` attempts to safely cast the output value using standard `String(value)`. For production apps utilizing heavy date formatting logic, developers can pass a custom `readOnlyComponent` explicitly to bypass this default cast.
-3. **Calendar Portal/Dropdown (Figma Token Issue)**: The Recursica UI Kit's `date-picker` component in Figma fails to export any explicit structural or color properties for the calendar popover itself (e.g. elevation, surface background, selected day colors). To solve this organically within the framework without breaking strict token adherence, we manually override the Mantine `.dropdown` and `.day[data-selected]` classes using `--recursica_ui-kit_components_hover-card-popover` tokens for elevation/padding/surfaces, and `--recursica_ui-kit_components_button_variants_styles_solid` tokens for the selected primary blue day. This guarantees strict visual adherence to the system until explicitly mapped tokens are provided in the UI Kit.
+3. **Calendar Portal/Dropdown (Figma Token Issue)**: The Recursica UI Kit's `date-picker` component in Figma fails to export any explicit structural or color properties for the calendar popover itself (e.g. elevation, surface background, selected day colors, hover, today, in-range). To solve this organically within the framework without breaking strict token adherence, we manually map every calendar state to the closest existing Recursica token instead of leaving any of it on Mantine's own un-tokenized defaults:
+   - **Surface** (`.dropdown`) & **selected day** (`.day[data-selected]`): `--recursica_ui-kit_components_hover-card-popover` tokens for elevation/padding/surface, `--recursica_ui-kit_components_button_variants_styles_solid` tokens for the selected day fill (unchanged from before).
+   - **Header content, weekday row** (`.calendarHeader`, `.weekday`): the hover-card-popover content-color token — previously unmapped, so these leaked Mantine's own text colors.
+   - **Header nav controls & month/year label** (`.calendarHeaderControl`, `.calendarHeaderLevel`, `.calendarHeaderControlIcon`): these are functionally buttons, so they're now styled with `--recursica_ui-kit_components_button_variants_styles_text` tokens (border/background/color/elevation) plus small-size `Button` sizing tokens (height, icon-only vs. label-content border-radius/padding/min-width, icon size, typography) — the same tokens `Button`'s `data-variant="text"` uses. Disabled opacity/elevation and the focus-visible ring also mirror `Button`'s own treatment instead of the generic brand tokens used elsewhere in this file.
+   - **Hover** (any day cell, header nav, header level button): the generic `--recursica_brand_states_hover_color`/`_hover_opacity` pair, via the same `::after`-overlay technique used by `Button`/`Menu` — the standard convention for components with no dedicated hover token. Unlike `Button`, the day number is a bare text node with no wrapping span to `z-index` above the overlay, so here the overlay sits at `z-index: -1` instead of the text getting `z-index: 1` — same visual effect, opposite side of the layering. Also unlike `Button` (a plain button with no library-native hover CSS), Mantine's `Day`/`CalendarHeaderControl`/`CalendarHeaderLevel` all ship their own native `:hover { background-color: ... }` rule — an explicit `background-color: transparent` reset on `:hover` was needed first, or the overlay would just layer on top of Mantine's own gray-0/dark-5 fill instead of replacing it. (Caught in review: the first pass added the overlay without this reset, and the visible hover color was indistinguishable from Mantine's plain default — confirmed via computed-style diffing, not just eyeballing the screenshot.)
+   - **Disabled / outside-month days**: the generic `--recursica_brand_states_disabled` opacity token — the same one used repo-wide (Button, Chip, Tree, Pagination, Accordion) for elements with no dedicated disabled token. **Disabled header nav/label controls** use `Button`'s own text-variant disabled opacity/elevation tokens instead, since they're now styled as `Button`.
+   - **Today marker**: no dedicated token exists, so it reuses the hover-card-popover border-size/color tokens already used for the dropdown surface's own border (previously hardcoded `1px`). `highlightToday` is now defaulted to `true` in `DatePicker.tsx` (Mantine ships it `false`, meaning today was never marked at all before this pass).
+   - **Weekend days**: Mantine's default colors these red; the UI Kit has no such concept, so weekend text is explicitly forced back to the same color as any other day rather than left on that unrelated default.
+   - **Range selection** (`.day[data-in-range]`/`[data-first-in-range]`/`[data-last-in-range]`): styled with the generic `--recursica_brand_states_overlay_color`/`_overlay_opacity` pair — previously unused anywhere in the codebase, but its name and shape (a translucent tint token) is exactly this use case. **Not currently reachable through our public API**: `RecursicaDatePickerProps` doesn't discriminate on `type`, so `value`/`defaultValue` are typed for single-date selection only — `type="range"` fails typecheck for consumers. This CSS is forward-compatible groundwork, not a demoed feature; proper range-mode typing would be a separate, larger follow-up. Also flagged as a judgment call on the token pairing itself: first usage anywhere, no prior precedent or design-team confirmation.
 
 ## Styling Quirks
 
 - The `DatePickerInput` mimics Mantine's `Input` structure natively (`.input`, `.wrapper`, `.section`). We attach our `styles.input` and `styles.root` classes exactly like `TextField`.
 - The global layout margin override (`.layoutOverride`) utilizes `--form-control-margin-bottom` driven by specific stacked/side-by-side design tokens.
+- **Popover `classNames` gotcha (bug fix)**: `.dropdown` was previously passed via the top-level `classNames` prop alongside `wrapper`/`input`/`section`/`day`/etc., which silently did nothing — the calendar surface is rendered by Mantine's internal `Popover`, whose style API is a separate namespace only reachable via `popoverProps.classNames` (`PickerInputBaseProps.popoverProps: Partial<Omit<PopoverProps, 'children'>>`). The `.dropdown` CSS (background/border/border-radius/box-shadow/padding/font-family, matching `Popover`'s own `.dropdown` rules 1:1) was never actually applied until this was fixed — confirmed via computed styles before/after (`box-shadow: none` → the real elevation token). `DatePicker.tsx` now merges any consumer-supplied `popoverProps`/`popoverProps.classNames` with our default instead of overwriting them.
+- **Default value format**: `valueFormat="MM/DD/YY"` (a `dayjs` format string, Mantine's default is `"MMMM D, YYYY"`), set before the `sanitizedProps` spread so consumers can still override via their own `valueFormat` prop.
+- **Default leading icon**: `leftSection={<CalendarIcon />}` (new `DatePicker.icons.tsx`, following the existing local-inline-SVG convention used by `Pagination.icons.tsx` — no icon library is a dependency of either adapter) is set the same way, overridable via `leftSection`.
+- **Default placeholder**: `placeholder="MM / DD / YY"`, set the same way (before `sanitizedProps`, so consumers can override).
+- **Single-line enforcement (bug fix)**: `DatePickerInput` renders its value/placeholder as a `<button>`'s text content, not a native `<input>` — it wraps like any other block text by default. A long placeholder (e.g. the original story's `"Select a deadline..."`) wrapped to two lines, inflating the field's height well past its `min-height` token and making the field visually look narrower than its actual `width` token value even though the box itself was always the right size. Fixed with `white-space: nowrap`/`text-overflow: ellipsis`/`overflow-x: clip`/`overflow-y: visible` on `.input`, the same convention `FileInput.module.css`'s `.value` uses.

package/src/components/DatePicker/DatePicker.icons.tsx

@@ -0,0 +1,27 @@
+import React from "react";
+
+/**
+ * Default leading icon for DatePicker's left section. Consumers can override it by passing
+ * their own `leftSection` prop (see DatePicker.tsx). Sized/colored entirely via the generic
+ * `.section :global(svg)` rule in DatePicker.module.css, same as the icon in the
+ * WithLeadingIcon story — no width/height/color hardcoded here on purpose.
+ */
+export function CalendarIcon(props: React.SVGProps<SVGSVGElement>) {
+  return (
+    <svg
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden
+      {...props}
+    >
+      <rect x="3" y="4" width="18" height="18" rx="2" ry="2" />
+      <line x1="16" y1="2" x2="16" y2="6" />
+      <line x1="8" y1="2" x2="8" y2="6" />
+      <line x1="3" y1="10" x2="21" y2="10" />
+    </svg>
+  );
+}