@recursica/adapter-mantine-v8 1.0.0

package/src/components/Chip/Chip.stories.tsx

@@ -0,0 +1,128 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Chip } from "./Chip";
+
+type ChipStoryProps = React.ComponentProps<typeof Chip>;
+
+const meta: Meta<ChipStoryProps> = {
+  title: "UI-Kit/Chip",
+  component: Chip,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "The Chip component is used to represent interactive selections, descriptive tags, or dynamic filters natively bounded to Recursica variables. It can be used as a toggleable input, can render a custom leading `icon`, and handles close constraints automatically via the `onDelete` property.",
+      },
+    },
+  },
+  argTypes: {
+    error: {
+      control: "boolean",
+      description: "Applies the error state styling dynamically.",
+    },
+    disabled: {
+      control: "boolean",
+      description: "Applies disabled token states.",
+    },
+    checked: {
+      control: "boolean",
+      description: "Forces the visual selected state.",
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<ChipStoryProps>;
+
+// The Default story exposing native properties for the playground.
+export const Default: Story = {
+  args: {
+    children: "Default Chip",
+    error: false,
+    disabled: false,
+    checked: false,
+  },
+  render: (args: ChipStoryProps) => <Chip {...args} />,
+};
+
+// Static Stories for Regression Snapshots
+export const Unselected: Story = {
+  args: {
+    children: "Unselected",
+    checked: false,
+  },
+  render: (args: ChipStoryProps) => <Chip {...args} />,
+};
+
+export const Selected: Story = {
+  args: {
+    children: "Selected",
+    checked: true,
+  },
+  render: (args: ChipStoryProps) => <Chip {...args} onChange={() => {}} />,
+};
+
+export const ErrorState: Story = {
+  args: {
+    children: "Error",
+    error: true,
+    checked: false,
+  },
+  render: (args: ChipStoryProps) => <Chip {...args} />,
+};
+
+export const ErrorSelected: Story = {
+  args: {
+    children: "Error Selected",
+    error: true,
+    checked: true,
+  },
+  render: (args: ChipStoryProps) => <Chip {...args} onChange={() => {}} />,
+};
+
+export const Removable: Story = {
+  args: {
+    children: "Dismissible",
+    checked: false,
+    onDelete: () => console.log("Removal Action Triggered"),
+  },
+  render: (args: ChipStoryProps) => <Chip {...args} />,
+};
+
+const leadingIcon = (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="2"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+  >
+    <circle cx="12" cy="12" r="10"></circle>
+    <path d="M12 8v4"></path>
+    <path d="M12 16h.01"></path>
+  </svg>
+);
+
+export const WithLeadingIcon: Story = {
+  args: {
+    children: "Leading Icon",
+    checked: false,
+    icon: leadingIcon,
+  },
+  render: (args: ChipStoryProps) => <Chip {...args} />,
+};
+
+// Selecting a chip with a leading icon swaps in the checkmark rather than showing both —
+// matches MUI's native behavior of the check icon overlaying the leading icon.
+export const WithLeadingIconSelected: Story = {
+  args: {
+    children: "Leading Icon Selected",
+    checked: true,
+    icon: leadingIcon,
+  },
+  render: (args: ChipStoryProps) => <Chip {...args} onChange={() => {}} />,
+};

package/src/components/Chip/Chip.test.tsx

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

package/src/components/Chip/Chip.tsx

@@ -0,0 +1,157 @@
+import React, { forwardRef } from "react";
+import {
+  Chip as MantineChip,
+  type ChipProps as MantineChipProps,
+} from "@mantine/core";
+import {
+  filterStylingProps,
+  mergeClassNames,
+  withCallerOverride,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Chip.module.css";
+import { type RecursicaChipProps } from "@recursica/adapter-common";
+
+export type ChipProps = RecursicaOverStyled<
+  Omit<MantineChipProps, "variant" | "size" | "color" | "radius"> &
+    RecursicaChipProps
+>;
+
+function CloseIcon(props: React.ComponentPropsWithoutRef<"svg">) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      {...props}
+    >
+      <line x1="18" y1="6" x2="6" y2="18"></line>
+      <line x1="6" y1="6" x2="18" y2="18"></line>
+    </svg>
+  );
+}
+
+export const Chip = forwardRef<HTMLInputElement, ChipProps>(function Chip(
+  {
+    error = false,
+    icon,
+    onDelete,
+    deleteLabel = "Delete",
+    deleteTabIndex,
+    deleteIconRef,
+    children,
+    checked,
+    overStyled = false,
+    wrapperProps,
+    tabIndex,
+    "aria-hidden": ariaHidden,
+    ...rest
+  },
+  ref,
+) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const restRecord = sanitizedProps as Record<string, unknown>;
+
+  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
+    ? `${styles.root} ${classNameProp}`
+    : styles.root;
+
+  // Determine state
+  const dataError = error ? "" : undefined;
+  const isIconOnly = !children && (!!icon || !!onDelete);
+  // A chip only counts as interactive when something actually responds to it — merely passing a
+  // `checked` value (e.g. to pin a display-only chip to a fixed visual state, as FileUpload's
+  // read-only file list does) isn't itself an interaction, since clicking it with no onChange/
+  // onClick wired does nothing observable.
+  const isInteractive =
+    onDelete !== undefined ||
+    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}
+      checked={checked}
+      className={finalClass}
+      classNames={mergedClassNames}
+      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}>
+        {/* When checked, Mantine's own check icon (rendered in its native iconWrapper slot,
+            ahead of this children span) overlays/replaces the leading icon rather than sitting
+            next to it — matching mui-adapter's `icon={checked ? checkIcon : icon}` swap. */}
+        {icon && !checked && (
+          <span className={styles.leadingIcon} aria-hidden>
+            {icon}
+          </span>
+        )}
+
+        <span className={styles.children}>{children}</span>
+
+        {onDelete && (
+          <span
+            ref={deleteIconRef}
+            role="button"
+            className={styles.deleteIcon}
+            onClick={(e) => {
+              e.preventDefault();
+              e.stopPropagation();
+              onDelete(e);
+            }}
+            aria-label={deleteLabel}
+            onKeyDown={(e) => {
+              if (e.key === "Enter" || e.key === " ") {
+                e.preventDefault();
+                e.stopPropagation();
+                onDelete(
+                  e as unknown as React.MouseEvent<HTMLSpanElement, MouseEvent>,
+                );
+              }
+            }}
+            tabIndex={deleteTabIndex ?? 0}
+          >
+            <CloseIcon />
+          </span>
+        )}
+      </span>
+    </MantineChip>
+  );
+});
+
+Chip.displayName = "Chip";

package/src/components/Chip/USAGE.md

@@ -0,0 +1,55 @@
+# Chip - Usage Guide
+
+This document describes how to integrate and use the `Chip` component in your projects using `@recursica/adapter-mantine-v8`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Chip } from "@recursica/adapter-mantine-v8";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Chip } from "@recursica/adapter-mantine-v8";
+
+export default function Demo() {
+  return <Chip defaultChecked>Clickable Chip</Chip>;
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/adapter-mantine-v8` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.
+
+---
+
+## 4. Key Integration Features & Constraints
+
+### Accessibility of Remove Action
+
+The remove/close action is keyboard accessible — it can be activated via keyboard as well as mouse click.
+
+### Sizing
+
+Chip does not support a `size` prop; chips render at a fixed size.
+
+### Building a keyboard-navigable chip group
+
+`deleteTabIndex` and `deleteIconRef` are optional escape hatches for composing a _group_ of chips
+with roving-tabindex keyboard navigation (Tab reaches one chip at a time, arrow keys move between
+them) — see `FileUpload`'s file list for a working example. Ignore both for a standalone chip; they
+default to a normal `tabIndex={0}` delete icon with no ref.

package/src/components/Container/CONTAINER_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,4 @@
+# Container Implementation Notes
+
+The `Container` component is a generic layout wrapper mapped directly to Mantine's `Container`.
+It serves to provide standardized centered max-width bounds around content. Mantine handles the width boundaries inherently based on size properties.

package/src/components/Container/Container.module.css

@@ -0,0 +1,7 @@
+/* HARDCODED VALUES:
+ * None. This is a generic layout wrapper.
+ */
+
+.root {
+  /* Mantine handles container constraints natively. */
+}

package/src/components/Container/Container.stories.tsx

@@ -0,0 +1,118 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Container } from "./Container";
+import { Text } from "../Text/Text";
+
+type ContainerStoryProps = React.ComponentProps<typeof Container>;
+
+const meta: Meta<ContainerStoryProps> = {
+  title: "UI-Kit/Container",
+  component: Container,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Container is a generic layout wrapper that safely maps to Mantine's Container, standardizing maximum content widths across the application.",
+      },
+    },
+  },
+  args: {
+    size: "md",
+    fluid: false,
+  },
+  argTypes: {
+    size: {
+      control: "select",
+      options: [
+        "xs",
+        "sm",
+        "md",
+        "lg",
+        "xl",
+        "rec-sm",
+        "rec-default",
+        "rec-md",
+        "rec-lg",
+        "rec-xl",
+        "rec-2xl",
+      ],
+      description:
+        "Maximum width defined by Mantine system sizes or Recursica sizes",
+    },
+    fluid: {
+      control: "boolean",
+      description: "If true, overrides size and sets max-width to 100%",
+    },
+    defaultChecked: {
+      table: { disable: true },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<ContainerStoryProps>;
+
+export const Default: Story = {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <div style={{ backgroundColor: "#f0f0f0", padding: "16px" }}>
+      <Container
+        {...args}
+        style={{
+          backgroundColor: "white",
+          padding: "16px",
+          border: "1px solid #ccc",
+        }}
+      >
+        <Text>
+          This is a Container holding centered content. The background and
+          border are added just to demonstrate the layout bounds visually.
+        </Text>
+      </Container>
+    </div>
+  ),
+};
+
+export const SmallContainer: Story = {
+  args: {
+    size: "sm",
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <div style={{ backgroundColor: "#f0f0f0", padding: "16px" }}>
+      <Container
+        {...args}
+        style={{
+          backgroundColor: "white",
+          padding: "16px",
+          border: "1px solid #ccc",
+        }}
+      >
+        <Text>Small Container Layout</Text>
+      </Container>
+    </div>
+  ),
+};
+
+export const FluidContainer: Story = {
+  args: {
+    fluid: true,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <div style={{ backgroundColor: "#f0f0f0", padding: "16px" }}>
+      <Container
+        {...args}
+        style={{
+          backgroundColor: "white",
+          padding: "16px",
+          border: "1px solid #ccc",
+        }}
+      >
+        <Text>Fluid Container Layout</Text>
+      </Container>
+    </div>
+  ),
+};

package/src/components/Container/Container.test.tsx

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

package/src/components/Container/Container.tsx

@@ -0,0 +1,69 @@
+import { forwardRef } from "react";
+import {
+  Container as MantineContainer,
+  type ContainerProps as MantineContainerProps,
+} from "@mantine/core";
+import styles from "./Container.module.css";
+
+import { type WithRecursicaSpacing } from "../../utils/filterStylingProps";
+import { type RecursicaContainerProps } from "@recursica/adapter-common";
+
+/**
+ * Container layout wrapper.
+ *
+ * Note: Unlike complex UI components, primitive layout components (Flex, Stack, Group, Container)
+ * DO NOT use the `RecursicaOverStyled` gatekeeper. Developers must be able to freely pass
+ * width, height, padding, margins, and flexbox alignment props to construct structural layouts.
+ */
+export type ContainerProps = WithRecursicaSpacing<
+  Omit<MantineContainerProps, "size"> & RecursicaContainerProps
+>;
+
+export const Container = forwardRef<HTMLDivElement, ContainerProps>(
+  function Container({ children, size, ...rest }, ref) {
+    const mapSize: Record<string, string> = {
+      "rec-sm": "sm",
+      "rec-default": "md",
+      "rec-md": "md",
+      "rec-lg": "lg",
+      "rec-xl": "xl",
+      "rec-2xl": "xl",
+    };
+
+    const resolvedSize =
+      typeof size === "string" && mapSize[size] ? mapSize[size] : size;
+
+    const mergedClassNames: Partial<Record<string, string>> = {
+      root: styles.root,
+    };
+
+    const classNamesProp = rest.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;
+    }
+
+    const classNameProp = rest.className as string | undefined;
+    const finalClass = classNameProp
+      ? `${styles.root} ${classNameProp}`
+      : styles.root;
+
+    return (
+      <MantineContainer
+        ref={ref}
+        size={resolvedSize}
+        className={finalClass}
+        classNames={mergedClassNames}
+        {...rest}
+      >
+        {children}
+      </MantineContainer>
+    );
+  },
+);
+
+Container.displayName = "Container";

package/src/components/Container/USAGE.md

@@ -0,0 +1,47 @@
+# Container - Usage Guide
+
+This document describes how to integrate and use the `Container` component in your projects using `@recursica/adapter-mantine-v8`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Container } from "@recursica/adapter-mantine-v8";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Container } from "@recursica/adapter-mantine-v8";
+
+export default function Demo() {
+  return (
+    <Container size="lg">
+      <Text>Centered content container constrained by maximum width.</Text>
+    </Container>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/adapter-mantine-v8` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.
+
+---
+
+## 4. Key Integration Features & Constraints
+
+The `Container` component is a generic layout wrapper mapped directly to Mantine's `Container`.
+It serves to provide standardized centered max-width bounds around content. Mantine handles the width boundaries inherently based on size properties.

package/src/components/DatePicker/DATEPICKER_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,31 @@
+# DatePicker Implementation Notes
+
+## Architecture Overview
+
+The `DatePicker` component is a wrapper around the `@mantine/dates` `DatePickerInput` component, implementing the `FormControlWrapper` macro structure for Recursica. This ensures that the component visually and structurally aligns with standard Recursica input primitives.
+
+## Structural Constraints
+
+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**: `readOnlyValue` is formatted via `@mantine/dates`' own `getFormattedDate` helper using the same `valueFormat` the editable `DatePickerInput` renders with — so a read-only date reads identically to that same value while editable (`05/20/26`, not a raw JS `Date.toString()`). Developers can still pass a custom `readOnlyComponent` to fully replace this rendering.
+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.
+- **Day focus ring (bug fix)**: Mantine's `Day` ships no built-in `:focus-visible` style of its own (unlike `.calendarHeaderControl`/`.calendarHeaderLevel`, which are styled as `Button` and inherited a focus ring from that treatment), so a focused day — e.g. the auto-focused selected/today day when the calendar opens — fell through to the browser's native blue outline instead of a Recursica token. Fixed by adding `.day:focus-visible` with the same generic `--recursica_brand_states_focus_*` box-shadow ring already used by `.input` and `.calendarHeaderControl`/`.calendarHeaderLevel`. mui-adapter's `.MuiPickerDay-root.Mui-focusVisible` already had this — only the adapter-mantine-v8 side was missing it.
+- **Read-only value format (bug fix, 2026-08-30)**: `readOnlyValue` used to be a bare `String(value)`/`String(defaultValue)` cast — `Date`'s own `toString()`, e.g. `"Wed May 20 2026 17:00:00 GMT-0700 (Pacific Daylight Time)"` — completely ignoring `valueFormat`, so `ui-kit-datepicker--static-read-only` rendered a totally different (and far less usable) date string than the same value shown editable, or than mui-adapter's equivalent (which already formats its read-only text via dayjs). Fixed by running the value through `@mantine/dates`' exported `getFormattedDate({ type: "default", date, locale: "en", format: valueFormat, labelSeparator: "" })` — the same formatter `DatePickerInput` uses internally — so read-only and editable rendering of the same value always agree.

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>
+  );
+}