@recursica/mantine-adapter 0.42.0 → 0.43.0

package/src/components/DatePicker/DatePicker.module.css

@@ -1,10 +1,3 @@
-/* EXEMPTIONS:
-   - border-size variables are ignored because a uniform 1px border is applied globally to prevent
-     unexpected layout shift or flickering during focused, disabled, or error state transitions. */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_variants_states_disabled_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_variants_states_error_properties_border-size */
-
 /* LAYOUT SPACING OVERRIDES:
    - Sets the --form-control-margin-bottom spacing hook to map component-specific layout tokens. */
 .layoutOverride {
@@ -117,6 +110,14 @@
   );
 
   outline: none;
+
+  /* Single-line enforcement: DatePickerInput renders its value/placeholder as a <button>'s text
+     content (not a native <input>), so it wraps by default like any other block text — clip it to
+     one line with ellipsis instead, same convention as FileInput's .value. */
+  white-space: nowrap;
+  text-overflow: ellipsis;
+  overflow-x: clip;
+  overflow-y: visible;
 }
 
 .input::placeholder {
@@ -263,10 +264,257 @@
   );
 }
 
+/* Month label + prev/next nav controls: styled as Recursica's own "text" button variant (small
+   size) rather than bare popover text — same border/background/color/typography tokens Button
+   uses for data-variant="text", since these are functionally buttons inside the popover. */
+.calendarHeaderControl,
+.calendarHeaderLevel {
+  position: relative;
+  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
+  );
+  box-shadow: var(
+    --recursica_ui-kit_components_button_variants_styles_text_properties_elevation
+  );
+  color: var(
+    --recursica_ui-kit_components_button_variants_styles_text_properties_colors_text-color
+  );
+  font-family: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_text_letter-spacing
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_text_text-transform
+  );
+  transition: all 0.2s ease;
+}
+
+/* Prev/next nav: icon-only button sizing (small). */
+.calendarHeaderControl {
+  min-width: var(
+    --recursica_ui-kit_components_button_variants_content_icon-only_variants_sizes_small_properties_min-width
+  );
+  height: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_height
+  );
+  border-radius: var(
+    --recursica_ui-kit_components_button_variants_content_icon-only_variants_sizes_small_properties_border-radius
+  );
+  padding: 0
+    var(
+      --recursica_ui-kit_components_button_variants_content_icon-only_variants_sizes_small_properties_horizontal-padding
+    );
+}
+
+/* Month/year label: label-content button sizing (small). */
+.calendarHeaderLevel {
+  height: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_height
+  );
+  border-radius: var(
+    --recursica_ui-kit_components_button_variants_content_label_variants_sizes_small_properties_border-radius
+  );
+  padding: 0
+    var(
+      --recursica_ui-kit_components_button_variants_content_label_variants_sizes_small_properties_horizontal-padding
+    );
+}
+
+/* Neutralize Mantine's own native :hover background-color (gray-0/dark-5) so only our
+   token-driven overlay below is visible — same reasoning as .day above. */
+.calendarHeaderControl:hover:not(:disabled, [data-disabled]),
+.calendarHeaderLevel:hover:not(:disabled, [data-disabled]) {
+  background-color: transparent;
+}
+
+.calendarHeaderControl::after,
+.calendarHeaderLevel::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+  z-index: -1;
+  pointer-events: none;
+  background-color: var(--recursica_brand_states_hover_color);
+  opacity: 0;
+  transition: opacity 150ms ease;
+}
+
+.calendarHeaderControl:hover:not(:disabled, [data-disabled])::after,
+.calendarHeaderLevel:hover:not(:disabled, [data-disabled])::after {
+  opacity: var(--recursica_brand_states_hover_opacity);
+}
+
+.calendarHeaderControl:disabled,
+.calendarHeaderControl[data-disabled],
+.calendarHeaderLevel:disabled,
+.calendarHeaderLevel[data-disabled] {
+  opacity: var(
+    --recursica_ui-kit_components_button_variants_styles_text_variants_states_disabled_properties_opacity
+  );
+  box-shadow: var(
+    --recursica_ui-kit_components_button_variants_styles_text_variants_states_disabled_properties_elevation
+  );
+}
+
+/* Focus ring, same convention as Button's own :focus-visible treatment. */
+.calendarHeaderControl:focus-visible,
+.calendarHeaderLevel: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);
+}
+
+.calendarHeaderControlIcon {
+  color: var(
+    --recursica_ui-kit_components_button_variants_styles_text_properties_colors_icon-color
+  );
+  width: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_icon
+  );
+  height: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_icon
+  );
+}
+
+/* Weekday row (Mo, Tu, We...) */
+.weekday {
+  color: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_colors_content
+  );
+}
+
 .day {
+  position: relative;
+  color: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_colors_content
+  );
+  border-radius: var(--recursica_brand_dimensions_border-radii_default);
+}
+
+/* Weekend days: Mantine's default colors them red; the UI Kit has no such concept, so they're
+   intentionally kept identical to any other day rather than left on Mantine's un-tokenized default. */
+.day[data-weekend] {
   color: var(
     --recursica_ui-kit_components_hover-card-popover_properties_colors_content
   );
+}
+
+/* Today marker: reuse the popover border-size/color tokens already used for the dropdown
+   surface itself, since the UI Kit exports no dedicated "today" indicator token. */
+.day[data-today][data-highlight-today]:not([data-selected], [data-in-range]) {
+  border-style: solid;
+  border-width: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_border-size
+  );
+  border-color: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_colors_border-color
+  );
+}
+
+/* Outside-month & disabled days: dim with the generic disabled-opacity token used everywhere else
+   in the design system for elements with no dedicated disabled token. */
+.day[data-outside],
+.day[data-disabled] {
+  opacity: var(--recursica_brand_states_disabled);
+}
+
+.day[data-disabled] {
+  cursor: not-allowed;
+}
+
+/* Unlike Button (a plain button with no built-in library hover), Mantine's Day ships its own
+   native :hover background-color (gray-0/dark-5) — neutralize it so only our token-driven
+   overlay below is visible. Same specificity as Mantine's own selector, so this relies on our
+   CSS module loading after @mantine/dates' stylesheet to win the tie (true today; see
+   DATEPICKER_IMPLEMENTATION_NOTES.md if that load order ever changes). */
+.day:hover:not(:disabled, [data-disabled], [data-static]) {
+  background-color: transparent;
+}
+
+/* Hover overlay, same generic mechanism used by Button/Menu for components without a dedicated
+   hover token. Unlike Button, the day number here is a bare text node (Mantine's Day renders it
+   directly, with no wrapping span to z-index above the overlay), so this sits at z-index: -1
+   instead — still scoped to .day's own positioned box, just painted behind the digit rather than
+   in front of it. */
+.day::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+  z-index: -1;
+  pointer-events: none;
+  background-color: var(--recursica_brand_states_hover_color);
+  opacity: 0;
+  transition: opacity 150ms ease;
+}
+
+.day:hover:not(:disabled, [data-disabled], [data-static])::after {
+  opacity: var(--recursica_brand_states_hover_opacity);
+}
+
+/* Range selection (type="range"): the UI Kit exports no dedicated in-range token, so the generic
+   overlay token — meant for exactly this kind of translucent tint — fills the band between the
+   two selected endpoints. Painted via ::before (behind the day number and the ::after hover
+   overlay) so the fill's opacity never dims the text itself. */
+.day[data-in-range] {
+  border-radius: 0;
+}
+
+.day[data-in-range]::before {
+  content: "";
+  position: absolute;
+  inset: 0;
+  z-index: -1;
+  pointer-events: none;
+  background-color: var(--recursica_brand_states_overlay_color);
+  opacity: var(--recursica_brand_states_overlay_opacity);
+}
+
+.day[data-first-in-range] {
+  border-radius: 0;
+  border-start-start-radius: var(
+    --recursica_brand_dimensions_border-radii_default
+  );
+  border-end-start-radius: var(
+    --recursica_brand_dimensions_border-radii_default
+  );
+}
+
+.day[data-last-in-range] {
+  border-radius: 0;
+  border-end-end-radius: var(--recursica_brand_dimensions_border-radii_default);
+  border-start-end-radius: var(
+    --recursica_brand_dimensions_border-radii_default
+  );
+}
+
+.day[data-first-in-range][data-last-in-range] {
   border-radius: var(--recursica_brand_dimensions_border-radii_default);
 }
 
@@ -278,4 +526,5 @@
   color: var(
     --recursica_ui-kit_components_button_variants_styles_solid_properties_colors_text-color
   );
+  opacity: 1;
 }

package/src/components/DatePicker/DatePicker.stories.tsx

@@ -65,7 +65,6 @@ export const Default: Story = {
   args: {
     disabled: false,
     label: "Project Deadline",
-    placeholder: "Select a deadline...",
     assistiveText: "Specify the absolute cutoff for code submission.",
   },
 };
@@ -73,7 +72,6 @@ export const Default: Story = {
 export const FormsSideBySide: Story = {
   args: {
     label: "Incident Start Date",
-    placeholder: "Pick date...",
     assistiveText: "When did the incident originally occur?",
     formLayout: "side-by-side",
   },
@@ -82,7 +80,6 @@ export const FormsSideBySide: Story = {
 export const WithLeadingIcon: Story = {
   args: {
     label: "Launch Date",
-    placeholder: "Select launch date...",
     leftSection: (
       <svg
         width="24"
@@ -106,7 +103,6 @@ export const WithLeadingIcon: Story = {
 export const Disabled: Story = {
   args: {
     label: "Disabled Date Range",
-    placeholder: "Disabled selection...",
     disabled: true,
   },
 };
@@ -114,7 +110,6 @@ export const Disabled: Story = {
 export const ErrorState: Story = {
   args: {
     label: "Execution Date",
-    placeholder: "Pick a valid date...",
     error: "The chosen date conflicts with an existing deployment freeze.",
     required: true,
   },
@@ -123,7 +118,6 @@ export const ErrorState: Story = {
 export const StaticReadOnly: Story = {
   args: {
     label: "Static ReadOnly Review",
-    placeholder: "Ignored...",
     value: new Date("2026-05-21"),
     readOnly: true,
   },
@@ -132,7 +126,6 @@ export const StaticReadOnly: Story = {
 export const EditableReadOnly: Story = {
   args: {
     label: "Editable ReadOnly Review",
-    placeholder: "Ignored until active...",
     defaultValue: new Date("2026-06-01"),
     readOnly: true,
     labelWithEditIcon: true,

package/src/components/DatePicker/DatePicker.tsx

@@ -3,10 +3,14 @@ import { DatePickerInput, type DatePickerInputProps } from "@mantine/dates";
 import { type ReadOnlyControlProps } from "@recursica/adapter-common";
 import {
   filterStylingProps,
+  omitUnsupportedProps,
+  withCallerOverride,
+  mergeClassNames,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import { type RecursicaFormControlWrapperProps } from "../FormControlWrapper/FormControlWrapper";
 import { WithReadOnlyWrapper } from "../ReadOnlyField/WithReadOnlyWrapper";
+import { CalendarIcon } from "./DatePicker.icons";
 import styles from "./DatePicker.module.css";
 
 import { type RecursicaDatePickerProps as BaseRecursicaDatePickerProps } from "@recursica/adapter-common";
@@ -38,6 +42,15 @@ export interface RecursicaDatePickerProps
 
 export type DatePickerProps = RecursicaOverStyled<RecursicaDatePickerProps>;
 
+// 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 the `size` variant + design tokens, not raw dimensions.
+  "variant", // Colors/variants are token-driven; the library's native palette isn't exposed.
+  "radius", // Recursica does not expose the library's native corner-radius system.
+  "description", // Managed by FormControlWrapper via assistiveText.
+] as const satisfies readonly (keyof DatePickerInputProps)[];
+
 export const DatePicker = forwardRef<HTMLButtonElement, DatePickerProps>(
   function DatePicker(props, ref) {
     const {
@@ -66,45 +79,59 @@ export const DatePicker = forwardRef<HTMLButtonElement, DatePickerProps>(
       emptyValueComponent,
       value,
       defaultValue,
+      highlightToday = true, // Default on so today is visually marked; consumers can still override.
+      valueFormat = "MM/DD/YY", // Default display format; consumers can still override.
+      placeholder = "MM / DD / YY", // Default placeholder; consumers can still override.
+      leftSection, // Default leading icon computed below; consumers can still override.
       ...rest
     } = props;
 
-    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const sanitizedProps = omitUnsupportedProps(
+      filterStylingProps(rest, overStyled) as Record<string, unknown>,
+      UNSUPPORTED_PROPS,
+    );
     const restRecord = sanitizedProps as Record<string, unknown>;
 
-    // Delete prohibited sizing hooks from bypassing variables natively
-    delete restRecord["size"];
-    delete restRecord["variant"];
-    delete restRecord["radius"];
-    delete restRecord["description"]; // Managed by FormControlWrapper via assistiveText
-
     // Securely map core native blocks down ensuring nested CSS modules map precisely
-    const mergedClassNames: Partial<Record<string, string>> = {
-      wrapper: styles.root, // The nested Input internal relative wrapper bounding box
-      input: styles.input,
-      section: styles.section,
-      dropdown: styles.dropdown,
-      day: styles.day,
-      calendarHeader: styles.calendarHeader,
-    };
+    const mergedClassNames = mergeClassNames(
+      {
+        wrapper: styles.root, // The nested Input internal relative wrapper bounding box
+        input: styles.input,
+        section: styles.section,
+        day: styles.day,
+        weekday: styles.weekday,
+        calendarHeader: styles.calendarHeader,
+        calendarHeaderControl: styles.calendarHeaderControl,
+        calendarHeaderLevel: styles.calendarHeaderLevel,
+        calendarHeaderControlIcon: styles.calendarHeaderControlIcon,
+      },
+      restRecord.classNames as Partial<Record<string, string>> | undefined,
+    );
 
-    const classNamesProp = restRecord.classNames;
-    if (
-      classNamesProp &&
-      typeof classNamesProp === "object" &&
-      !Array.isArray(classNamesProp)
-    ) {
-      const o = classNamesProp as Partial<Record<string, string>>;
-      mergedClassNames.wrapper = o.wrapper
-        ? `${styles.root} ${o.wrapper}`
-        : styles.root;
-      mergedClassNames.input = o.input
-        ? `${styles.input} ${o.input}`
-        : styles.input;
-      mergedClassNames.section = o.section
-        ? `${styles.section} ${o.section}`
-        : styles.section;
-    }
+    // The calendar popover surface (.dropdown) is styled by Mantine's underlying `Popover`
+    // component, not `DatePickerInput` itself — it only accepts classNames via `popoverProps`,
+    // not the top-level `classNames` map above (which only reaches the Input/Calendar parts).
+    const popoverPropsInput = restRecord.popoverProps;
+    const consumerPopoverProps =
+      popoverPropsInput &&
+      typeof popoverPropsInput === "object" &&
+      !Array.isArray(popoverPropsInput)
+        ? (popoverPropsInput as Record<string, unknown>)
+        : undefined;
+    const consumerPopoverClassNames =
+      consumerPopoverProps?.classNames &&
+      typeof consumerPopoverProps.classNames === "object" &&
+      !Array.isArray(consumerPopoverProps.classNames)
+        ? (consumerPopoverProps.classNames as Partial<Record<string, string>>)
+        : undefined;
+    delete restRecord["popoverProps"];
+    const mergedPopoverProps = {
+      ...consumerPopoverProps,
+      classNames: mergeClassNames(
+        { dropdown: styles.dropdown },
+        consumerPopoverClassNames,
+      ),
+    };
 
     const wrapperClass = className
       ? `${styles.layoutOverride} ${className}`
@@ -146,6 +173,7 @@ export const DatePicker = forwardRef<HTMLButtonElement, DatePickerProps>(
           /* Naked Input execution safely decoupled from Mantine's macro Input.Wrapper DOM hooks */
           <DatePickerInput
             ref={ref}
+            {...(sanitizedProps as unknown as DatePickerInputProps)}
             classNames={mergedClassNames}
             disabled={disabled}
             value={value}
@@ -154,11 +182,18 @@ export const DatePicker = forwardRef<HTMLButtonElement, DatePickerProps>(
             description={undefined} // Disable Mantine's native description
             error={undefined} // Disable Mantine's native error text (handled by wrapper)
             withAsterisk={false} // Handled by wrapper
+            highlightToday={highlightToday}
+            valueFormat={valueFormat}
+            placeholder={placeholder}
+            leftSection={withCallerOverride<React.ReactNode>(
+              <CalendarIcon />,
+              leftSection,
+            )}
             wrapperProps={{
               "data-disabled": disabled ? "true" : undefined,
               "data-error": error ? "true" : undefined,
             }}
-            {...(sanitizedProps as unknown as DatePickerInputProps)}
+            popoverProps={mergedPopoverProps}
           />
         }
       />

package/src/components/DatePicker/USAGE.md

@@ -19,7 +19,7 @@ import React from "react";
 import { DatePicker } from "@recursica/mantine-adapter";
 
 export default function Demo() {
-  return <DatePicker label="Select Date" placeholder="Pick a date" />;
+  return <DatePicker label="Select Date" />;
 }
 ```
 
@@ -42,4 +42,8 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 ## Structural Constraints
 
 1. **Read-Only Rendering**: When rendered in read-only mode, the selected date is displayed via a plain string conversion of the value. If you need custom date formatting, pass a `readOnlyComponent` prop to control how the value is rendered.
-2. **Calendar Popover Styling**: The calendar popover is not yet fully styled by design tokens.
+2. **Calendar Popover Styling**: The UI Kit exports no calendar-specific tokens (surface, selected day, hover, today, weekend, in-range), so the calendar reuses the closest existing tokens — see `DATEPICKER_IMPLEMENTATION_NOTES.md` for the exact mapping. All calendar states are token-driven; none are left on Mantine's un-tokenized defaults. The header's prev/next arrows and month/year label are styled as Recursica `text`-variant buttons.
+3. **Today Highlighting**: `highlightToday` defaults to `true` so the current day is always visually marked; pass `highlightToday={false}` to turn it off.
+4. **Default Value Format**: Displayed values default to `MM/DD/YY` (e.g. `08/19/26`); pass your own `valueFormat` (a `dayjs` format string) to override.
+5. **Default Leading Icon**: A calendar icon is shown in the left section by default; pass your own `leftSection` to override it.
+6. **Default Placeholder**: Defaults to `"MM / DD / YY"` when not set; pass your own `placeholder` to override it.

package/src/components/Dropdown/BareDropdown.tsx

@@ -5,6 +5,8 @@ import {
 } from "@mantine/core";
 import {
   filterStylingProps,
+  omitUnsupportedProps,
+  mergeClassNames,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import styles from "./Dropdown.module.css";
@@ -37,29 +39,40 @@ export interface BareDropdownProps
 
 export type BareDropdownComponentProps = RecursicaOverStyled<BareDropdownProps>;
 
+// 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 the `size` variant + design tokens, not raw dimensions.
+  "variant", // Colors/variants are token-driven; the library's native palette isn't exposed.
+  "radius", // Recursica does not expose the library's native corner-radius system.
+] as const satisfies readonly (keyof MantineSelectProps)[];
+
 export const BareDropdown = forwardRef<
   HTMLInputElement,
   BareDropdownComponentProps
 >(function BareDropdown(props, ref) {
   const { overStyled = false, className, disabled, error, ...rest } = props;
-  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const sanitizedProps = omitUnsupportedProps(
+    filterStylingProps(rest, overStyled) as Record<string, unknown>,
+    UNSUPPORTED_PROPS,
+  );
   const restRecord = sanitizedProps as Record<string, unknown>;
 
-  delete restRecord["size"];
-  delete restRecord["variant"];
-  delete restRecord["radius"];
-
-  const mergedClassNames: Partial<Record<string, string>> = {
-    wrapper: className ? `${styles.root} ${className}` : styles.root,
-    input: styles.input,
-    section: styles.section,
-    dropdown: styles.dropdown,
-    option: styles.option,
-  };
+  const mergedClassNames = mergeClassNames(
+    {
+      wrapper: className ? `${styles.root} ${className}` : styles.root,
+      input: styles.input,
+      section: styles.section,
+      dropdown: styles.dropdown,
+      option: styles.option,
+    },
+    restRecord.classNames as Partial<Record<string, string>> | undefined,
+  );
 
   return (
     <MantineSelect
       ref={ref}
+      {...(sanitizedProps as unknown as MantineSelectProps)}
       classNames={mergedClassNames}
       disabled={disabled}
       label={undefined}
@@ -77,7 +90,6 @@ export const BareDropdown = forwardRef<
           "data-error": error ? "true" : undefined,
         },
       }}
-      {...(sanitizedProps as unknown as MantineSelectProps)}
     />
   );
 });

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

@@ -1,10 +1,3 @@
-/* EXEMPTIONS:
-   - border-size variables are ignored because a uniform 1px border is applied globally to prevent
-     unexpected layout shift or flickering during focus, disabled, or error state transitions. */
-/* recursica-ignore: --recursica_ui-kit_components_dropdown_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_dropdown_variants_states_disabled_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_dropdown_variants_states_error_properties_border-size */
-
 /* LAYOUT SPACING OVERRIDES:
    - Sets the --form-control-margin-bottom spacing hook to map component-specific layout tokens.
    - Also sets the --dropdown-control-{max,min}-width hooks consumed inline in Dropdown.tsx, since