@recursica/mantine-adapter 0.13.0 → 0.14.0

package/src/components/HoverCard/HoverCard.tsx

@@ -1,7 +1,156 @@
-import React from "react";
+import {
+  HoverCard as MantineHoverCard,
+  type HoverCardProps as MantineHoverCardProps,
+  type HoverCardTargetProps as MantineHoverCardTargetProps,
+  type HoverCardDropdownProps as MantineHoverCardDropdownProps,
+} from "@mantine/core";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./HoverCard.module.css";
 
-export type HoverCardProps = React.HTMLAttributes<HTMLDivElement>;
+// ============================================================
+// HOVERCARD ROOT
+// ============================================================
 
-export const HoverCard: React.FC<HoverCardProps> = (props) => {
-  return <div {...props}>HoverCard</div>;
+/**
+ * Recursica-specific props for HoverCard.
+ */
+export interface RecursicaHoverCardProps {
+  /**
+   * Whether to display a beak (arrow) pointing from the dropdown to the target.
+   * This is the Recursica equivalent of Mantine's `withArrow`.
+   * When both `withBeak` and `withArrow` are provided, `withBeak` takes precedence.
+   */
+  withBeak?: boolean;
+}
+
+/**
+ * Recursica HoverCard component wrapping Mantine's composable HoverCard.
+ *
+ * Displays a dropdown panel when the user hovers over a target element.
+ * Uses the composable dot-notation pattern:
+ * ```tsx
+ * <HoverCard withBeak>
+ *   <HoverCard.Target>
+ *     <Button>Hover me</Button>
+ *   </HoverCard.Target>
+ *   <HoverCard.Dropdown>
+ *     Content displayed on hover
+ *   </HoverCard.Dropdown>
+ * </HoverCard>
+ * ```
+ */
+export type HoverCardProps = RecursicaOverStyled<
+  MantineHoverCardProps & RecursicaHoverCardProps
+>;
+
+const HoverCardBase = function HoverCard({
+  overStyled = false,
+  withBeak = true,
+  ...rest
+}: HoverCardProps) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+
+  // Bind CSS module classes to Mantine's internal classNames API
+  const mergedClassNames: Partial<Record<string, string>> = {
+    dropdown: styles.dropdown,
+    arrow: styles.arrow,
+  };
+
+  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];
+      }
+    });
+  }
+
+  // arrowSize must be a JS number prop — Mantine uses it for inline width/height
+  // and positioning offset (-arrowSize/2) calculations that cannot be CSS-driven.
+  // Default to 16 to match the Recursica beak-size token (16px).
+  const arrowSize =
+    ((sanitizedProps as Record<string, unknown>).arrowSize as
+      | number
+      | undefined) ?? 16;
+
+  // Resolve withBeak (Recursica) vs withArrow (Mantine).
+  // withBeak takes precedence when both are provided.
+  const withArrow = (sanitizedProps as Record<string, unknown>).withArrow as
+    | boolean
+    | undefined;
+  const resolvedWithArrow = withBeak ?? withArrow;
+
+  return (
+    <MantineHoverCard
+      position="top" /* Recursica default; Mantine defaults to "bottom" */
+      arrowSize={arrowSize}
+      withArrow={resolvedWithArrow}
+      classNames={mergedClassNames}
+      {...(sanitizedProps as unknown as MantineHoverCardProps)}
+    />
+  );
+};
+HoverCardBase.displayName = "HoverCard";
+
+// ============================================================
+// HOVERCARD TARGET
+// ============================================================
+
+/**
+ * Wrapper for the element that triggers the hover card.
+ * Requires a single child element that supports ref forwarding.
+ */
+export type HoverCardTargetProps = MantineHoverCardTargetProps;
+
+const HoverCardTarget = function HoverCardTarget(props: HoverCardTargetProps) {
+  return <MantineHoverCard.Target {...props} />;
+};
+HoverCardTarget.displayName = "HoverCardTarget";
+
+// ============================================================
+// HOVERCARD DROPDOWN
+// ============================================================
+
+/** The dropdown panel displayed when hovering over the target. */
+export type HoverCardDropdownProps =
+  RecursicaOverStyled<MantineHoverCardDropdownProps>;
+
+const HoverCardDropdown = function HoverCardDropdown({
+  overStyled = false,
+  ...rest
+}: HoverCardDropdownProps) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const classNameProp = (sanitizedProps as Record<string, unknown>)
+    .className as string | undefined;
+
+  return (
+    <MantineHoverCard.Dropdown
+      className={classNameProp}
+      {...(sanitizedProps as unknown as MantineHoverCardDropdownProps)}
+    />
+  );
 };
+HoverCardDropdown.displayName = "HoverCardDropdown";
+
+// ============================================================
+// DOT NOTATION EXPORT
+// ============================================================
+
+type HoverCardComponent = typeof HoverCardBase & {
+  Target: typeof HoverCardTarget;
+  Dropdown: typeof HoverCardDropdown;
+};
+
+export const HoverCard = HoverCardBase as HoverCardComponent;
+HoverCard.Target = HoverCardTarget;
+HoverCard.Dropdown = HoverCardDropdown;

package/src/components/Loader/LOADER_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,25 @@
+# Loader Implementation Notes
+
+## Architecture & Integration
+
+The `Loader` component acts as a strictly tokenized wrapper bridging the Recursica UI-Kit `loader` variables to the generic Mantine `@mantine/core` `Loader` primitive.
+
+### Key Decisions:
+
+- **Variant Mapping:** Recursica's `variant` directly proxies to Mantine's `type` prop for `"oval" | "bars" | "dots"`.
+- **Property Overrides Disabled:** Natively overriding specific structural variants directly on the JSX interface like `thickness` and `borderRadius` has been intentionally omitted. Component rendering relies entirely on variables exposed by the underlying UI Kit mappings tied to the size prop.
+
+### Token Mapping:
+
+Sizes are bound through `data-size` attributes (`sm`, `md`, `lg` parsing to target `<div data-size="small">`, etc.).
+
+Mantine natively sets sizing dynamically at the component root and parses thickness/variants differently natively (e.g., `oval` styles its geometry strictly via CSS `border`, while `bars` and `dots` utilize specific DOM inner spans `span.dot` / `span.bar`).
+
+#### Specific CSS Targeting Hacks Used
+
+- `border-width` structurally styles the `thickness` configuration of the `oval` variant by resolving `--recursica_ui-kit_components_loader_variants_sizes_..._properties_thickness`.
+- For non-oval variants, `border-radius` natively maps downwards to targeting component `span` children within the wrapper to capture `<span className="mantine-Loader-dot" />` geometries safely without polluting the flex wrapper natively.
+
+### Unsupported Properties
+
+- **xs and xl Sizing:** These sizes are explicitly unsupported in the Recursica standard logic (as surfaced in `filterStylingProps` and UI Kit mappings). Attempting to use them will safely default back or fallthrough statically unless defined later. See `COMPONENT_ISSUES.md`.

package/src/components/NumberInput/NUMBER_INPUT_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,18 @@
+# NumberInput Implementation Notes
+
+This document contains specific design decisions, architectural constraints, and hacks required to bridge the Recursica design system with Mantine's underlying `NumberInput` primitive.
+
+## 1. Native Macro Wrapper Bypass
+
+**Decision:** The `<NumberInput>` component explicitly bypasses Mantine's native `Input.Wrapper` DOM injections.
+**Implementation:** We pass `label={undefined}`, `description={undefined}`, and `error={undefined}` directly into the primitive `<MantineNumberInput>`. All visual form control geometry is delegated exclusively to our unified `<FormControlWrapper>`, ensuring 100% token adherence for label spacing and assistive text styling without duplicate DOM rendering.
+
+## 2. Right Section & Controls Override
+
+**Decision:** Passing a `rightSection` element will natively remove the increment/decrement arrow controls.
+**Implementation:** Mantine inherently renders its stepper controls inside the `rightSection` DOM slot. Providing a custom right-aligned icon or text element intentionally overwrites this slot. If a layout strictly requires both a custom right-aligned element and the stepper controls simultaneously, the integrator must manually rebuild the arrows using Mantine's `handlersRef` within a custom right-section wrapper.
+
+## 3. Controls Styling
+
+**Decision:** The increment/decrement control arrows rely partially on native Mantine CSS inheritance.
+**Implementation:** The current Recursica design system tokens do not provide explicit UI styling parameters (`background`, `border`, `hover` states) for the inner number-input arrows. We have explicitly removed Mantine's default borders to cleanly nest them inside the unified input box, and mapped the icon colors to the generic `trailing-icon` token variable, but further visual configurations currently fall back to Mantine defaults.

package/src/components/NumberInput/NumberInput.module.css

@@ -0,0 +1,250 @@
+/* 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.
+   - Controls: Hardcoded to bypass Mantine's default borders and backgrounds on the increment/decrement arrows.
+*/
+
+.root {
+  display: flex;
+  position: relative;
+  width: 100%;
+  min-height: var(
+    --recursica_ui-kit_components_number-input_properties_min-height
+  );
+
+  /* Override Mantine native Input variables governing section spacing padding mathematics safely */
+  --input-left-section-size: calc(
+    var(--recursica_ui-kit_components_number-input_properties_icon-size) +
+      (
+        var(
+            --recursica_ui-kit_components_number-input_properties_horizontal-padding
+          ) *
+          2
+      )
+  );
+  --input-right-section-size: calc(
+    var(--recursica_ui-kit_components_number-input_properties_icon-size) +
+      (
+        var(
+            --recursica_ui-kit_components_number-input_properties_horizontal-padding
+          ) *
+          2
+      )
+  );
+}
+
+.input {
+  /* Structural Overrides */
+  width: 100%;
+  box-sizing: border-box;
+  margin: 0;
+
+  /* Box Geometry */
+  min-height: var(
+    --recursica_ui-kit_components_number-input_properties_min-height
+  );
+  padding-top: var(
+    --recursica_ui-kit_components_number-input_properties_vertical-padding
+  );
+  padding-bottom: var(
+    --recursica_ui-kit_components_number-input_properties_vertical-padding
+  );
+  padding-left: var(
+    --recursica_ui-kit_components_number-input_properties_horizontal-padding
+  );
+  padding-right: var(
+    --recursica_ui-kit_components_number-input_properties_horizontal-padding
+  );
+  border-radius: var(
+    --recursica_ui-kit_components_number-input_properties_border-radius
+  );
+  border-width: 1px;
+  border-style: solid;
+
+  /* Strict Typography Unification */
+  font-family: var(
+    --recursica_ui-kit_components_number-input_properties_text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_number-input_properties_text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_number-input_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_number-input_properties_text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_number-input_properties_text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_number-input_properties_text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_number-input_properties_text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_number-input_properties_text_text-transform
+  );
+
+  /* Base State Default Execution */
+  background-color: var(
+    --recursica_ui-kit_components_number-input_variants_states_default_properties_colors_background
+  );
+  border-color: var(
+    --recursica_ui-kit_components_number-input_variants_states_default_properties_colors_border-color
+  );
+  color: var(
+    --recursica_ui-kit_components_number-input_variants_states_default_properties_colors_text
+  );
+
+  outline: none;
+}
+
+.input::placeholder {
+  opacity: var(
+    --recursica_ui-kit_components_number-input_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;
+  justify-content: center;
+  height: 100%;
+}
+
+.section :global(svg) {
+  width: var(--recursica_ui-kit_components_number-input_properties_icon-size);
+  height: var(--recursica_ui-kit_components_number-input_properties_icon-size);
+  color: var(
+    --recursica_ui-kit_components_number-input_variants_states_default_properties_colors_leading-icon
+  );
+}
+
+.section[data-position="right"] :global(svg) {
+  color: var(
+    --recursica_ui-kit_components_number-input_variants_states_default_properties_colors_trailing-icon
+  );
+}
+
+/* -------------------------------------
+   CONTROLS (Mantine Specific Up/Down Arrows)
+-------------------------------------- */
+
+.controls {
+  /* Adjust right padding so controls do not overlap borders */
+  padding-right: var(
+    --recursica_ui-kit_components_number-input_properties_horizontal-padding
+  );
+}
+
+.control {
+  /* Override Mantine borders for the inner controls */
+  border: none;
+  background: transparent;
+  color: var(
+    --recursica_ui-kit_components_number-input_variants_states_default_properties_colors_trailing-icon
+  );
+}
+
+.control:hover {
+  background: transparent;
+}
+
+/* -------------------------------------
+   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_number-input_variants_states_focus_properties_colors_border-color
+  );
+  background-color: var(
+    --recursica_ui-kit_components_number-input_variants_states_focus_properties_colors_background
+  );
+  color: var(
+    --recursica_ui-kit_components_number-input_variants_states_focus_properties_colors_text
+  );
+}
+
+.root:focus-within .section[data-position="left"] :global(svg) {
+  color: var(
+    --recursica_ui-kit_components_number-input_variants_states_focus_properties_colors_leading-icon
+  );
+}
+
+.root:focus-within .section[data-position="right"] :global(svg),
+.root:focus-within .control {
+  color: var(
+    --recursica_ui-kit_components_number-input_variants_states_focus_properties_colors_trailing-icon
+  );
+}
+
+/* Error State Mapping (Propagated strictly down from the wrapper DOM context) */
+.root[data-error] .input {
+  border-color: var(
+    --recursica_ui-kit_components_number-input_variants_states_error_properties_colors_border-color
+  ) !important;
+  background-color: var(
+    --recursica_ui-kit_components_number-input_variants_states_error_properties_colors_background
+  ) !important;
+  color: var(
+    --recursica_ui-kit_components_number-input_variants_states_error_properties_colors_text
+  ) !important;
+}
+
+.root[data-error] .section[data-position="left"] :global(svg) {
+  color: var(
+    --recursica_ui-kit_components_number-input_variants_states_error_properties_colors_leading-icon
+  ) !important;
+}
+
+.root[data-error] .section[data-position="right"] :global(svg),
+.root[data-error] .control {
+  color: var(
+    --recursica_ui-kit_components_number-input_variants_states_error_properties_colors_trailing-icon
+  ) !important;
+}
+
+/* Disabled State Mapping (Propagated strictly down from the wrapper DOM context) */
+.root[data-disabled] .input {
+  border-color: var(
+    --recursica_ui-kit_components_number-input_variants_states_disabled_properties_colors_border-color
+  ) !important;
+  background-color: var(
+    --recursica_ui-kit_components_number-input_variants_states_disabled_properties_colors_background
+  ) !important;
+  color: var(
+    --recursica_ui-kit_components_number-input_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_number-input_variants_states_disabled_properties_colors_leading-icon
+  ) !important;
+}
+
+.root[data-disabled] .section[data-position="right"] :global(svg),
+.root[data-disabled] .control {
+  color: var(
+    --recursica_ui-kit_components_number-input_variants_states_disabled_properties_colors_trailing-icon
+  ) !important;
+}

package/src/components/NumberInput/NumberInput.stories.tsx

@@ -1,12 +1,34 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { NumberInput } from "./NumberInput";
-import { ComingSoon } from "@recursica/storybook-template";
 
 const meta: Meta<typeof NumberInput> = {
-  title: "UI-Kit/🚧 NumberInput",
+  title: "UI-Kit/NumberInput",
   component: NumberInput,
   tags: ["autodocs"],
-  argTypes: {},
+  argTypes: {
+    label: { control: "text" },
+    assistiveText: { control: "text" },
+    disabled: { control: "boolean" },
+    error: { control: "boolean" },
+    readOnly: { control: "boolean" },
+    required: { control: "boolean" },
+    hideControls: { control: "boolean" },
+    formLayout: {
+      control: "select",
+      options: ["stacked", "side-by-side"],
+    },
+    labelSize: {
+      control: "select",
+      options: ["small", "default", "large"],
+    },
+    checked: { table: { disable: true } },
+    defaultChecked: { table: { disable: true } },
+    assistiveWithIcon: { table: { disable: true } },
+    labelOptionalText: { table: { disable: true } },
+    labelWithEditIcon: { table: { disable: true } },
+    onLabelEditClick: { table: { disable: true } },
+    emptyValueComponent: { table: { disable: true } },
+  },
 };
 
 export default meta;
@@ -14,5 +36,63 @@ export default meta;
 type Story = StoryObj<typeof NumberInput>;
 
 export const Default: Story = {
-  render: () => <ComingSoon componentName="NumberInput" />,
+  args: {
+    label: "Amount",
+    placeholder: "Enter an amount",
+    assistiveText: "Must be greater than 0",
+    defaultValue: 10,
+    min: 0,
+    max: 100,
+  },
+};
+
+export const SideBySideLayout: Story = {
+  args: {
+    ...Default.args,
+    formLayout: "side-by-side",
+  },
+};
+
+export const States: Story = {
+  render: () => (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "1rem",
+        maxWidth: 400,
+      }}
+    >
+      <NumberInput label="Default" placeholder="Enter a number" />
+      <NumberInput label="Disabled" placeholder="Disabled input" disabled />
+      <NumberInput label="Error" placeholder="Error state" error />
+      <NumberInput label="Read Only" value={42} readOnly />
+      <NumberInput label="Required" required />
+    </div>
+  ),
+};
+
+export const WithLeftIcon: Story = {
+  args: {
+    label: "Price",
+    placeholder: "0.00",
+    leftSection: <span>$</span>,
+  },
+};
+
+export const WithRightIcon: Story = {
+  args: {
+    label: "Percentage",
+    placeholder: "0",
+    rightSection: <span>%</span>,
+    hideControls: true, // Typically hiding controls if rightSection is occupied
+  },
+};
+
+export const HiddenControls: Story = {
+  args: {
+    label: "Zip Code",
+    placeholder: "Enter zip code",
+    hideControls: true,
+  },
 };