@recursica/mantine-adapter 0.22.0 → 0.23.0

package/dist/src/components/DatePicker/DatePicker.d.ts

@@ -1,3 +1,9 @@
 import { default as React } from 'react';
-export type DatePickerProps = React.HTMLAttributes<HTMLDivElement>;
-export declare const DatePicker: React.FC<DatePickerProps>;
+import { DatePickerInputProps } from '@mantine/dates';
+import { ReadOnlyControlProps } from '@recursica/adapter-common';
+import { RecursicaOverStyled } from '../../utils/filterStylingProps';
+import { RecursicaFormControlWrapperProps } from '../FormControlWrapper/FormControlWrapper';
+export interface RecursicaDatePickerProps extends Omit<DatePickerInputProps, "size" | "variant" | "radius" | "wrapperProps" | "label" | "error" | "required" | "withAsterisk" | "id" | "description">, Pick<DatePickerInputProps, "label" | "error" | "required" | "withAsterisk" | "id">, Omit<RecursicaFormControlWrapperProps, "controlMaxWidth" | "controlMinWidth">, ReadOnlyControlProps {
+}
+export type DatePickerProps = RecursicaOverStyled<RecursicaDatePickerProps>;
+export declare const DatePicker: React.ForwardRefExoticComponent<DatePickerProps & React.RefAttributes<HTMLInputElement>>;

package/dist/src/components/Slider/Slider.d.ts

@@ -1,3 +1,25 @@
 import { default as React } from 'react';
-export type SliderProps = React.HTMLAttributes<HTMLDivElement>;
-export declare const Slider: React.FC<SliderProps>;
+import { SliderProps as MantineSliderProps, InputWrapperProps } from '@mantine/core';
+import { ReadOnlyControlProps } from '@recursica/adapter-common';
+import { RecursicaOverStyled } from '../../utils/filterStylingProps';
+import { RecursicaFormControlWrapperProps } from '../FormControlWrapper/FormControlWrapper';
+export interface RecursicaSliderProps extends Omit<MantineSliderProps, "size" | "variant" | "radius" | "wrapperProps" | "classNames" | "styles" | "label">, Omit<RecursicaFormControlWrapperProps, "controlMaxWidth" | "controlMinWidth">, Pick<InputWrapperProps, "error" | "required" | "withAsterisk">, ReadOnlyControlProps {
+    /** The form control label displayed above or beside the slider track. */
+    label?: React.ReactNode;
+    /** Floating tooltip shown above the thumb when dragging. Replaces Mantine's `label`. */
+    tooltipLabel?: MantineSliderProps["label"];
+    /** An optional icon rendered to the left of the slider track. */
+    icon?: React.ReactNode;
+    /** Whether to render a numeric input field side-by-side or stacked with the track. Defaults to false. */
+    showInput?: boolean;
+    /** Whether to render min and max labels below the track. Defaults to true. */
+    showMinMaxLabels?: boolean;
+}
+export type SliderProps = RecursicaOverStyled<RecursicaSliderProps>;
+/**
+ * Recursica Slider component wrapping Mantine's Slider.
+ *
+ * Implements a bidirectional text input field next to the slider track, responsive layouts,
+ * custom typography-bound min/max labels, an optional leading icon, and an explicit read-only layout.
+ */
+export declare const Slider: React.ForwardRefExoticComponent<SliderProps & React.RefAttributes<HTMLDivElement>>;

package/dist/test.html

@@ -0,0 +1 @@
+<h1>Hello Public</h1>

package/package.json

@@ -13,7 +13,7 @@
     "url": "git+https://github.com/borderux/recursica.git",
     "directory": "packages/mantine-adapter"
   },
-  "version": "0.22.0",
+  "version": "0.23.0",
   "type": "module",
   "main": "./dist/mantine-adapter.cjs",
   "module": "./dist/mantine-adapter.js",
@@ -47,7 +47,7 @@
     "build": "vite build --mode library",
     "build-storybook": "storybook build -o storybook-static",
     "lint": "eslint .",
-    "storybook": "storybook dev -p 6006",
+    "storybook": "storybook dev -p 6011",
     "analyze-tokens": "analyze-tokens --css recursica_variables_scoped.css --dir src/components --output token-analysis.json",
     "prebuild": "npm run analyze-tokens"
   },

package/src/components/Button/Button.tsx

@@ -117,7 +117,7 @@ const _Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
     : styles.root;
 
   const userLoaderProps = restRecord.loaderProps as
-    | Record<string, any>
+    | Record<string, unknown>
     | undefined;
 
   const resolvedLoaderSize =

package/src/components/DatePicker/DATEPICKER_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,16 @@
+# 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**: 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.
+
+## 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.

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

@@ -1,45 +1,286 @@
-/*
- * EXEMPTIONS:
- * - DatePicker is a "Coming Soon" stub component.
- * - It renders a placeholder and has no active implementation or CSS stylesheet yet.
- * - The following tokens generated by Figma are ignored until the component is fully built.
- */
-
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_properties_border-radius */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_properties_horizontal-padding */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_properties_icon-size */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_properties_icon-text-gap */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_properties_min-height */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_properties_placeholder-opacity */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_properties_text_font-family */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_properties_text_font-size */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_properties_text_font-style */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_properties_text_font-weight */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_properties_text_letter-spacing */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_properties_text_line-height */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_properties_text_text-decoration */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_properties_text_text-transform */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_properties_vertical-padding */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_properties_width */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_variants_layouts_side-by-side_properties_top-bottom-margin */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_variants_layouts_stacked_properties_top-bottom-margin */
+/* EXEMPTIONS:
+   - state-specific 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_date-picker_variants_states_default_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 */
 /* recursica-ignore: --recursica_ui-kit_components_date-picker_variants_states_focus_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_variants_states_default_properties_colors_background */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_variants_states_default_properties_colors_border-color */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_variants_states_default_properties_colors_leading-icon */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_variants_states_default_properties_colors_text */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_variants_states_disabled_properties_colors_background */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_variants_states_disabled_properties_colors_border-color */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_variants_states_disabled_properties_colors_leading-icon */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_variants_states_disabled_properties_colors_text */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_variants_states_error_properties_colors_background */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_variants_states_error_properties_colors_border-color */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_variants_states_error_properties_colors_leading-icon */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_variants_states_error_properties_colors_text */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_variants_states_focus_properties_colors_background */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_variants_states_focus_properties_colors_border-color */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_variants_states_focus_properties_colors_leading-icon */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_variants_states_focus_properties_colors_text */
+
+/* LAYOUT SPACING OVERRIDES:
+   - Sets the --form-control-margin-bottom spacing hook to map component-specific layout tokens. */
+.layoutOverride {
+  --form-control-margin-bottom: var(
+    --recursica_ui-kit_components_date-picker_variants_layouts_stacked_properties_top-bottom-margin
+  );
+}
+
+.layoutOverride[data-form-layout="side-by-side"] {
+  --form-control-margin-bottom: var(
+    --recursica_ui-kit_components_date-picker_variants_layouts_side-by-side_properties_top-bottom-margin
+  );
+}
+
+/* HARDCODED VALUES:
+   - border-width: 1px. Native geometric boundary for the input box.
+   - border-style: solid. Native structural rendering rule.
+   - outline: none. Bypassing browser focus rings to rely strictly on Recursica focus states natively.
+   - flex/layout: display: flex on the root wrapper safely encapsulating internal section rendering.
+*/
+
+.root {
+  display: flex;
+  position: relative;
+  width: var(--recursica_ui-kit_components_date-picker_properties_width, 100%);
+  min-height: var(
+    --recursica_ui-kit_components_date-picker_properties_min-height
+  );
+
+  /* Override Mantine native Input variables governing section spacing padding mathematics safely */
+  --input-left-section-size: calc(
+    var(
+        --recursica_ui-kit_components_date-picker_properties_horizontal-padding
+      ) +
+      var(--recursica_ui-kit_components_date-picker_properties_icon-size) +
+      var(--recursica_ui-kit_components_date-picker_properties_icon-text-gap)
+  );
+  --input-right-section-size: calc(
+    var(
+        --recursica_ui-kit_components_date-picker_properties_horizontal-padding
+      ) +
+      var(--recursica_ui-kit_components_date-picker_properties_icon-size) +
+      var(--recursica_ui-kit_components_date-picker_properties_icon-text-gap)
+  );
+}
+
+.input {
+  /* Structural Overrides */
+  width: 100%;
+  box-sizing: border-box;
+  margin: 0;
+
+  /* Box Geometry */
+  min-height: var(
+    --recursica_ui-kit_components_date-picker_properties_min-height
+  );
+  padding-top: var(
+    --recursica_ui-kit_components_date-picker_properties_vertical-padding
+  );
+  padding-bottom: var(
+    --recursica_ui-kit_components_date-picker_properties_vertical-padding
+  );
+  padding-left: var(
+    --recursica_ui-kit_components_date-picker_properties_horizontal-padding
+  );
+  padding-right: var(
+    --recursica_ui-kit_components_date-picker_properties_horizontal-padding
+  );
+  border-radius: var(
+    --recursica_ui-kit_components_date-picker_properties_border-radius
+  );
+  border-width: 1px;
+  border-style: solid;
+
+  /* Strict Typography Unification */
+  font-family: var(
+    --recursica_ui-kit_components_date-picker_properties_text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_date-picker_properties_text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_date-picker_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_date-picker_properties_text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_date-picker_properties_text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_date-picker_properties_text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_date-picker_properties_text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_date-picker_properties_text_text-transform
+  );
+
+  /* Base State Default Execution */
+  background-color: var(
+    --recursica_ui-kit_components_date-picker_variants_states_default_properties_colors_background
+  );
+  border-color: var(
+    --recursica_ui-kit_components_date-picker_variants_states_default_properties_colors_border-color
+  );
+  color: var(
+    --recursica_ui-kit_components_date-picker_variants_states_default_properties_colors_text
+  );
+
+  outline: none;
+}
+
+.input::placeholder {
+  opacity: var(
+    --recursica_ui-kit_components_date-picker_properties_placeholder-opacity
+  );
+  color: inherit;
+}
+
+/* Dynamic Padding Overrides */
+.root[data-with-left-section] .input {
+  padding-left: var(--input-left-section-size);
+}
+
+.root[data-with-right-section] .input {
+  padding-right: var(--input-right-section-size);
+}
+
+/* Flexible End-Caps (Icons, actions) */
+.section {
+  display: flex;
+  align-items: center;
+  height: 100%;
+}
+
+.section[data-position="left"] {
+  justify-content: flex-start;
+  padding-left: var(
+    --recursica_ui-kit_components_date-picker_properties_horizontal-padding
+  );
+}
+
+.section[data-position="right"] {
+  justify-content: flex-end;
+  padding-right: var(
+    --recursica_ui-kit_components_date-picker_properties_horizontal-padding
+  );
+}
+
+.section :global(svg) {
+  width: var(--recursica_ui-kit_components_date-picker_properties_icon-size);
+  height: var(--recursica_ui-kit_components_date-picker_properties_icon-size);
+  color: var(
+    --recursica_ui-kit_components_date-picker_variants_states_default_properties_colors_leading-icon
+  );
+}
+
+/* -------------------------------------
+   STATE CASCADE ARCHITECTURE
+-------------------------------------- */
+
+/* Focus State Mapping (Triggered internally via browser pseudo-pseudo-class) */
+.input:focus-within,
+.input:focus {
+  border-color: var(
+    --recursica_ui-kit_components_date-picker_variants_states_focus_properties_colors_border-color
+  );
+  background-color: var(
+    --recursica_ui-kit_components_date-picker_variants_states_focus_properties_colors_background
+  );
+  color: var(
+    --recursica_ui-kit_components_date-picker_variants_states_focus_properties_colors_text
+  );
+}
+
+.root:focus-within .section[data-position="left"] :global(svg) {
+  color: var(
+    --recursica_ui-kit_components_date-picker_variants_states_focus_properties_colors_leading-icon
+  );
+}
+
+/* Error State Mapping (Propagated strictly down from the wrapper DOM context) */
+.root[data-error] .input {
+  border-color: var(
+    --recursica_ui-kit_components_date-picker_variants_states_error_properties_colors_border-color
+  ) !important;
+  background-color: var(
+    --recursica_ui-kit_components_date-picker_variants_states_error_properties_colors_background
+  ) !important;
+  color: var(
+    --recursica_ui-kit_components_date-picker_variants_states_error_properties_colors_text
+  ) !important;
+}
+
+.root[data-error] .section[data-position="left"] :global(svg) {
+  color: var(
+    --recursica_ui-kit_components_date-picker_variants_states_error_properties_colors_leading-icon
+  ) !important;
+}
+
+/* Disabled State Mapping (Propagated strictly down from the wrapper DOM context) */
+.root[data-disabled] .input {
+  border-color: var(
+    --recursica_ui-kit_components_date-picker_variants_states_disabled_properties_colors_border-color
+  ) !important;
+  background-color: var(
+    --recursica_ui-kit_components_date-picker_variants_states_disabled_properties_colors_background
+  ) !important;
+  color: var(
+    --recursica_ui-kit_components_date-picker_variants_states_disabled_properties_colors_text
+  ) !important;
+  cursor: not-allowed;
+}
+
+.root[data-disabled] .section[data-position="left"] :global(svg) {
+  color: var(
+    --recursica_ui-kit_components_date-picker_variants_states_disabled_properties_colors_leading-icon
+  ) !important;
+}
+
+/* =========================================
+   CALENDAR POPOVER OVERRIDES
+   Maps generic popover & solid button tokens
+   to enforce Recursica's global styling.
+   ========================================= */
+
+.dropdown {
+  background-color: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_colors_background
+  );
+  border: var(
+      --recursica_ui-kit_components_hover-card-popover_properties_border-size
+    )
+    solid
+    var(
+      --recursica_ui-kit_components_hover-card-popover_properties_colors_border-color
+    );
+  border-radius: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_border-radius
+  );
+  box-shadow: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_elevation
+  );
+  padding: var(
+      --recursica_ui-kit_components_hover-card-popover_properties_vertical-padding
+    )
+    var(
+      --recursica_ui-kit_components_hover-card-popover_properties_horizontal-padding
+    );
+  font-family: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_content-text_font-family
+  );
+}
+
+.calendarHeader {
+  color: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_colors_content
+  );
+}
+
+.day {
+  color: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_colors_content
+  );
+  border-radius: var(--recursica_brand_dimensions_border-radii_default, 4px);
+}
+
+.day[data-selected],
+.day[data-selected]:hover {
+  background-color: var(
+    --recursica_ui-kit_components_button_variants_styles_solid_properties_colors_background
+  );
+  color: var(
+    --recursica_ui-kit_components_button_variants_styles_solid_properties_colors_text
+  );
+}

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

@@ -1,12 +1,61 @@
+import React from "react";
 import type { Meta, StoryObj } from "@storybook/react";
 import { DatePicker } from "./DatePicker";
-import { ComingSoon } from "@recursica/storybook-template";
+import { formControlArgTypes } from "../../../.storybook/commonArgTypes";
 
 const meta: Meta<typeof DatePicker> = {
-  title: "UI-Kit/🚧 DatePicker",
+  title: "UI-Kit/DatePicker",
   component: DatePicker,
   tags: ["autodocs"],
-  argTypes: {},
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The \`DatePicker\` primitive provides a unified calendar date selection input integrated directly into the \`FormControlWrapper\` architecture.
+
+### Architectural Decoupling
+Recursica overrides the internal Mantine \`DatePickerInput\` wrapper defaults, safely injecting the date picker into our rigid structural layout systems. State modifiers (e.g. Focus, Errors, ReadOnly) hook seamlessly back onto our native CSS mapping architecture.
+
+### Examples
+Always structure horizontal architectures via the generic \`formLayout\` parameter.
+\`\`\`tsx
+<DatePicker 
+  label="Start Date" 
+  assistiveText="Select the deployment kick-off date." 
+  formLayout="stacked" 
+/>
+\`\`\`
+`,
+      },
+    },
+  },
+  argTypes: {
+    ...formControlArgTypes,
+    disabled: {
+      control: "boolean",
+      description:
+        "Maps the formal disabled variable states structurally to the input core.",
+    },
+    error: {
+      control: "text",
+      description:
+        "Applies the strict error string boundary rendering invalid structures seamlessly.",
+    },
+    required: {
+      control: "boolean",
+    },
+    label: {
+      control: "text",
+    },
+    assistiveText: {
+      control: "text",
+    },
+    readOnly: {
+      control: "boolean",
+      description:
+        "Toggles structural read-only data presentation explicitly blocking standard component bindings.",
+    },
+  },
 };
 
 export default meta;
@@ -14,5 +63,79 @@ export default meta;
 type Story = StoryObj<typeof DatePicker>;
 
 export const Default: Story = {
-  render: () => <ComingSoon componentName="DatePicker" />,
+  args: {
+    disabled: false,
+    label: "Project Deadline",
+    placeholder: "Select a deadline...",
+    assistiveText: "Specify the absolute cutoff for code submission.",
+  },
+};
+
+export const FormsSideBySide: Story = {
+  args: {
+    label: "Incident Start Date",
+    placeholder: "Pick date...",
+    assistiveText: "When did the incident originally occur?",
+    formLayout: "side-by-side",
+  },
+};
+
+export const WithLeadingIcon: Story = {
+  args: {
+    label: "Launch Date",
+    placeholder: "Select launch date...",
+    leftSection: (
+      <svg
+        width="24"
+        height="24"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      >
+        <rect x="3" y="4" width="18" height="18" rx="2" ry="2"></rect>
+        <line x1="16" y1="2" x2="16" y2="6"></line>
+        <line x1="8" y1="2" x2="8" y2="6"></line>
+        <line x1="3" y1="10" x2="21" y2="10"></line>
+      </svg>
+    ),
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    label: "Disabled Date Range",
+    placeholder: "Disabled selection...",
+    disabled: true,
+  },
+};
+
+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,
+  },
+};
+
+export const StaticReadOnly: Story = {
+  args: {
+    label: "Static ReadOnly Review",
+    placeholder: "Ignored...",
+    value: new Date("2026-05-21"),
+    readOnly: true,
+  },
+};
+
+export const EditableReadOnly: Story = {
+  args: {
+    label: "Editable ReadOnly Review",
+    placeholder: "Ignored until active...",
+    defaultValue: new Date("2026-06-01"),
+    readOnly: true,
+    labelWithEditIcon: true,
+  },
 };