@recursica/mantine-adapter 0.13.0 → 0.14.0

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

@@ -1,3 +1,55 @@
-import { default as React } from 'react';
-export type HoverCardProps = React.HTMLAttributes<HTMLDivElement>;
-export declare const HoverCard: React.FC<HoverCardProps>;
+import { HoverCardProps as MantineHoverCardProps, HoverCardTargetProps as MantineHoverCardTargetProps, HoverCardDropdownProps as MantineHoverCardDropdownProps } from '@mantine/core';
+import { RecursicaOverStyled } from '../../utils/filterStylingProps';
+/**
+ * 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>;
+declare const HoverCardBase: {
+    ({ overStyled, withBeak, ...rest }: HoverCardProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+/**
+ * Wrapper for the element that triggers the hover card.
+ * Requires a single child element that supports ref forwarding.
+ */
+export type HoverCardTargetProps = MantineHoverCardTargetProps;
+declare const HoverCardTarget: {
+    (props: HoverCardTargetProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+/** The dropdown panel displayed when hovering over the target. */
+export type HoverCardDropdownProps = RecursicaOverStyled<MantineHoverCardDropdownProps>;
+declare const HoverCardDropdown: {
+    ({ overStyled, ...rest }: HoverCardDropdownProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+type HoverCardComponent = typeof HoverCardBase & {
+    Target: typeof HoverCardTarget;
+    Dropdown: typeof HoverCardDropdown;
+};
+export declare const HoverCard: HoverCardComponent;
+export {};

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

@@ -1,3 +1,11 @@
 import { default as React } from 'react';
-export type NumberInputProps = React.HTMLAttributes<HTMLDivElement>;
-export declare const NumberInput: React.FC<NumberInputProps>;
+import { NumberInputProps as MantineNumberInputProps } from '@mantine/core';
+import { ReadOnlyControlProps } from '@recursica/adapter-common';
+import { RecursicaOverStyled } from '../../utils/filterStylingProps';
+import { RecursicaFormControlWrapperProps } from '../FormControlWrapper/FormControlWrapper';
+export interface RecursicaNumberInputProps extends Omit<MantineNumberInputProps, "size" | "variant" | "radius" | "wrapperProps" | "classNames" | "styles">, Pick<RecursicaFormControlWrapperProps, "assistiveText" | "assistiveWithIcon" | "formLayout" | "labelSize" | "labelAlignment" | "labelOptionalText" | "labelWithEditIcon" | "onLabelEditClick">, ReadOnlyControlProps {
+    /** Enables/disables the controls to increment and decrement the value */
+    hideControls?: boolean;
+}
+export type NumberInputProps = RecursicaOverStyled<RecursicaNumberInputProps>;
+export declare const NumberInput: React.ForwardRefExoticComponent<NumberInputProps & React.RefAttributes<HTMLInputElement>>;

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

@@ -1,3 +1,57 @@
-import { default as React } from 'react';
-export type PanelProps = React.HTMLAttributes<HTMLDivElement>;
-export declare const Panel: React.FC<PanelProps>;
+import { Drawer as MantineDrawer, DrawerProps as MantineDrawerProps } from '@mantine/core';
+import { RecursicaOverStyled } from '../../utils/filterStylingProps';
+/**
+ * Recursica Panel root props. Extends Mantine Drawer.
+ */
+export type PanelProps = RecursicaOverStyled<MantineDrawerProps>;
+/**
+ * Recursica Panel component wrapping Mantine's Drawer.
+ *
+ * Panels slide in or expand from the edge of the screen to reveal
+ * additional content or functionality. They are commonly used to provide
+ * supplementary information, navigation options, or toolsets without
+ * cluttering the main interface.
+ *
+ * ```tsx
+ * <Panel opened={opened} onClose={close} title="Panel Title" position="right">
+ *   <Panel.Body>
+ *     Content goes here
+ *   </Panel.Body>
+ * </Panel>
+ * ```
+ *
+ * Mantine Drawer sub-components available via dot-notation:
+ * - `Panel.Header` — Top section with title and close button
+ * - `Panel.Title` — Title text within the header
+ * - `Panel.CloseButton` — Close button within the header
+ * - `Panel.Body` — Scrollable body content area
+ * - `Panel.Content` — Outer content container
+ * - `Panel.Overlay` — Background overlay
+ * - `Panel.Root` — Root element for advanced composition
+ * - `Panel.Stack` — Stacked drawer context
+ */
+declare const PanelBase: {
+    ({ overStyled, position, keepMounted, ...rest }: PanelProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+export type PanelFooterProps = RecursicaOverStyled<React.HTMLAttributes<HTMLDivElement>>;
+/**
+ * Panel footer section with action buttons.
+ * Separated from the body by a divider. Remains fixed at the bottom.
+ * This is a Recursica-specific sub-component; Mantine Drawer does not
+ * natively provide a footer.
+ */
+export declare const PanelFooter: import('react').ForwardRefExoticComponent<PanelFooterProps & import('react').RefAttributes<HTMLDivElement>>;
+type PanelComponent = typeof PanelBase & {
+    Root: typeof MantineDrawer.Root;
+    Overlay: typeof MantineDrawer.Overlay;
+    Content: typeof MantineDrawer.Content;
+    Header: typeof MantineDrawer.Header;
+    Title: typeof MantineDrawer.Title;
+    CloseButton: typeof MantineDrawer.CloseButton;
+    Body: typeof MantineDrawer.Body;
+    Stack: typeof MantineDrawer.Stack;
+    Footer: typeof PanelFooter;
+};
+export declare const Panel: PanelComponent;
+export {};

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

@@ -1,3 +1,42 @@
-import { default as React } from 'react';
-export type TooltipProps = React.HTMLAttributes<HTMLDivElement>;
-export declare const Tooltip: React.FC<TooltipProps>;
+import { Tooltip as MantineTooltip, TooltipProps as MantineTooltipProps } from '@mantine/core';
+import { RecursicaOverStyled } from '../../utils/filterStylingProps';
+/**
+ * Recursica-specific props for Tooltip.
+ */
+export interface RecursicaTooltipProps {
+    /**
+     * Whether to display a beak (arrow) pointing from the tooltip to the target.
+     * This is the Recursica equivalent of Mantine's `withArrow`.
+     * When both `withBeak` and `withArrow` are provided, `withBeak` takes precedence.
+     * @default true
+     */
+    withBeak?: boolean;
+}
+/**
+ * Recursica Tooltip component wrapping Mantine's Tooltip.
+ *
+ * Displays a floating label when the user hovers over or focuses a target element.
+ * Unlike HoverCard, Tooltip is a single component (not composable) — content is
+ * passed via the `label` prop, and the trigger is passed as `children`.
+ *
+ * ```tsx
+ * <Tooltip label="Helpful information" withBeak>
+ *   <Button>Hover me</Button>
+ * </Tooltip>
+ * ```
+ *
+ * Static sub-components available via dot-notation:
+ * - `Tooltip.Floating` — Tooltip that follows the cursor
+ * - `Tooltip.Group` — Shared hover delay group for multiple tooltips
+ */
+export type TooltipProps = RecursicaOverStyled<MantineTooltipProps & RecursicaTooltipProps>;
+declare const TooltipBase: {
+    ({ overStyled, withBeak, ...rest }: TooltipProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+type TooltipComponent = typeof TooltipBase & {
+    Floating: typeof MantineTooltip.Floating;
+    Group: typeof MantineTooltip.Group;
+};
+export declare const Tooltip: TooltipComponent;
+export {};

package/package.json

@@ -11,7 +11,7 @@
     "type": "git",
     "url": "git+https://github.com/borderux/recursica.git"
   },
-  "version": "0.13.0",
+  "version": "0.14.0",
   "type": "module",
   "main": "./dist/mantine-adapter.cjs",
   "module": "./dist/mantine-adapter.js",

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

@@ -97,9 +97,6 @@
   );
 
   outline: none;
-  transition:
-    border-color 0.15s ease,
-    background-color 0.15s ease;
 }
 
 .input::placeholder {

package/src/components/HoverCard/HOVERCARD_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,77 @@
+# HoverCard – Implementation Notes
+
+Decisions and design tweaks strictly tailored for the UI Kit's HoverCard wrapped against `@mantine/core`. This is a living document that tracks _why_ specific logic decisions exist.
+
+---
+
+## 1. Composable API Preservation (1:1 Mapping)
+
+**Decision:** We maintain the exact library composition API structure (`<HoverCard>`, `<HoverCard.Target>`, `<HoverCard.Dropdown>`) as a 1:1 React component mapping.
+
+**Implementation:** Mantine's HoverCard internally manages hover detection, open/close delays, Floating UI positioning, and portal rendering. By preserving the exact sub-component tree, Recursica safely inherits all of these behaviors without reimplementation.
+
+---
+
+## 2. HoverCard.Target Pass-Through
+
+**Decision:** `HoverCard.Target` is a transparent pass-through with no styling applied.
+
+**Implementation:** The target wrapper exists solely to manage Mantine's ref forwarding and hover event binding for the trigger element. No `filterStylingProps` or CSS module classes are applied — the trigger's appearance is entirely controlled by whatever component the integrator places inside it (e.g., `<Button>`). This is identical to the `Menu.Target` pattern.
+
+---
+
+## 3. Token Namespace: `hover-card-popover`
+
+**Decision:** The CSS module exclusively uses variables from the `--recursica_ui-kit_components_hover-card-popover_*` namespace.
+
+**Implementation:** The Recursica token system defines a single shared namespace (`hover-card-popover`) for this component covering geometry (border-radius, border-size, padding, min/max-width), typography (content-text\_\*), elevation, and layer-aware colors (background, border-color, content). No tokens from other component namespaces are referenced.
+
+---
+
+## 4. Hardcoded Values
+
+**Decision:** Two hardcoded values exist in the component.
+
+### `border-style: solid` (CSS module)
+
+Mantine renders the dropdown using its `Paper` component, which does not set `border-style` natively. Without this hardcoded value, the border-width and border-color tokens would have no visible effect. This is the same pattern used in the Menu component's dropdown.
+
+### `arrowSize` defaulted to `16` (HoverCard.tsx)
+
+Mantine's `arrowSize` prop is a JavaScript number used for inline style calculations: it sets `width`, `height`, and a positioning offset (`-arrowSize/2`) directly on the arrow `<div>` element. These inline styles **cannot** be overridden via CSS without `!important`, and the positioning offset has no CSS equivalent. This means the beak size cannot be fully CSS-driven — it is one of the rare cases where a design token value must be mirrored as a JS prop.
+
+The default value `16` matches the Recursica `beak-size` token (`--recursica_ui-kit_components_hover-card-popover_properties_beak-size: 16px`). Developers can override `arrowSize` if needed, but should be aware this is a design system concern. If the token value changes, the default in `HoverCard.tsx` must also be updated.
+
+This is documented as an open issue in `docs/COMPONENT_ISSUES.md`.
+
+**Note:** Mantine calls this the "arrow"; Recursica calls it the "beak". The Recursica prop `withBeak` (defaulting to `true`) maps to Mantine's `withArrow`. Both `withBeak` and `withArrow` are accepted; `withBeak` takes precedence.
+
+---
+
+## 5. Minimal CSS Override Philosophy
+
+**Decision:** The CSS module only overrides visual design tokens (colors, typography, spacing, borders, shadows). All structural layout properties are deferred to Mantine's native behavior.
+
+**Implementation:** HoverCard is an overlay component where Mantine's native Floating UI positioning and Paper layout are already correct. We avoid setting:
+
+- `overflow` on the dropdown (Mantine handles scroll behavior natively)
+- `display`, `position`, `z-index` (Floating UI controls these)
+- `pointer-events` (Mantine manages hover detection across target and dropdown)
+
+**Rationale:** The Menu implementation demonstrated that aggressive structural resets (overflow, box-sizing) on overlay components cause layout breakage. Default to Mantine's native behavior and only override what the Recursica token system explicitly needs to control.
+
+---
+
+## 6. ClassNames Merging on Root
+
+**Decision:** The root `HoverCard` component binds CSS module classes via `classNames` on the Mantine root, identical to the Menu pattern.
+
+**Implementation:** The root component receives `classNames={{ dropdown: styles.dropdown }}` and merges any consumer-provided `classNames` when `overStyled` is true. This ensures our token-driven styles are applied to the dropdown panel without wrapper divs, and the consumer's classes are additive.
+
+---
+
+## 7. Default Position Override
+
+**Decision:** Recursica defaults `position` to `"top"`. Mantine defaults to `"bottom"`.
+
+**Implementation:** The `position="top"` default is set on the Mantine root element before the prop spread, so developer-provided `position` values still take precedence. This aligns with Recursica's design intent for overlay components to appear above their trigger by default.

package/src/components/HoverCard/HoverCard.module.css

@@ -0,0 +1,84 @@
+/* HARDCODED VALUES:
+   - border-style: solid. Structural rendering rule for the dropdown border (Mantine uses Paper
+     which may not set border-style natively). Same pattern as Menu.
+   - arrowSize defaults to 16 in HoverCard.tsx. Mantine uses arrowSize for inline width/height
+     and positioning (-arrowSize/2) calculations that cannot be CSS-driven. The default matches
+     the Recursica beak-size token (16px). See COMPONENT_ISSUES.md for details.
+   - All structural layout (display, position, overflow) is deferred to Mantine's native
+     behavior. We only override visual design tokens (colors, typography, spacing, borders).
+*/
+
+/* ======================================
+   DROPDOWN CONTAINER
+   ====================================== */
+
+.dropdown {
+  background-color: var(
+    --recursica_ui-kit_components_hover-card-popover_colors_background
+  );
+  border-style: solid; /* HARDCODE: Mantine Paper does not set border-style natively */
+  border-width: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_border-size
+  );
+  border-color: var(
+    --recursica_ui-kit_components_hover-card-popover_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
+  );
+
+  min-width: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_min-width
+  );
+  max-width: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_max-width
+  );
+
+  padding: var(
+      --recursica_ui-kit_components_hover-card-popover_properties_vertical-padding
+    )
+    var(
+      --recursica_ui-kit_components_hover-card-popover_properties_horizontal-padding
+    );
+
+  /* Typography */
+  font-family: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_content-text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_content-text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_content-text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_content-text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_content-text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_content-text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_content-text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_content-text_text-transform
+  );
+
+  color: var(--recursica_ui-kit_components_hover-card-popover_colors_content);
+}
+
+/* ======================================
+   ARROW / BEAK
+   ====================================== */
+
+.arrow {
+  border-color: var(
+    --recursica_ui-kit_components_hover-card-popover_colors_border-color
+  );
+}

package/src/components/HoverCard/HoverCard.stories.tsx

@@ -1,17 +1,172 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { HoverCard } from "./HoverCard";
-import { ComingSoon } from "@recursica/storybook-template";
+import { Button } from "../Button";
+import { Text } from "../Text/Text";
+import { Group } from "../Group/Group";
+import { Stack } from "../Stack/Stack";
+import { Avatar } from "../Avatar";
 
-const meta: Meta<typeof HoverCard> = {
-  title: "UI-Kit/🚧 HoverCard",
+/**
+ * HoverCard story axes:
+ * - position: dropdown alignment relative to target
+ * - withArrow: arrow indicator on the dropdown
+ * - openDelay / closeDelay: hover timing controls
+ * - content variations: plain text, rich content (avatar + text + actions)
+ * - layer: tested via the global Layer decorator (withLayer/layer args)
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type HoverCardStoryArgs = Record<string, any>;
+
+const meta: Meta = {
+  title: "UI-Kit/HoverCard",
   component: HoverCard,
   tags: ["autodocs"],
+  argTypes: {
+    position: {
+      control: "select",
+      options: [
+        "bottom",
+        "bottom-start",
+        "bottom-end",
+        "top",
+        "top-start",
+        "top-end",
+        "left",
+        "left-start",
+        "left-end",
+        "right",
+        "right-start",
+        "right-end",
+      ],
+      description: "The position of the dropdown relative to the target.",
+    },
+    withBeak: {
+      control: "boolean",
+      description:
+        "Whether to display a beak (arrow) pointing to the target. Recursica equivalent of Mantine's withArrow.",
+    },
+    offset: {
+      control: "number",
+      description:
+        "Distance in px between the dropdown and the target element.",
+    },
+    openDelay: {
+      control: "number",
+      description: "Delay in ms before the dropdown opens on hover.",
+    },
+    closeDelay: {
+      control: "number",
+      description: "Delay in ms before the dropdown closes when hover ends.",
+    },
+    disabled: {
+      control: "boolean",
+      description: "If set, the hover card dropdown will not be rendered.",
+    },
+  },
+  parameters: {
+    layout: "centered",
+    docs: {
+      description: {
+        component: `
+The \`HoverCard\` component displays a popover-style dropdown when the user hovers over a target element. It wraps Mantine's composable \`HoverCard\` while enforcing strict Recursica design token styling.
+
+### Composable API
+
+HoverCard uses a dot-notation composition pattern:
+- \`<HoverCard>\` — Root container managing open/close state on hover
+- \`<HoverCard.Target>\` — Wrapper for the trigger element (must be a single element supporting ref)
+- \`<HoverCard.Dropdown>\` — The popup panel displaying content on hover
+
+### Key Behaviors
+- The dropdown opens when the user hovers over the target and closes when they move away
+- \`openDelay\` and \`closeDelay\` control the timing of open/close transitions
+- The dropdown stays open while the user hovers over it, allowing interaction with its content
+        `,
+      },
+    },
+  },
 };
 
 export default meta;
 
-type Story = StoryObj<typeof HoverCard>;
+type Story = StoryObj<HoverCardStoryArgs>;
 
 export const Default: Story = {
-  render: () => <ComingSoon componentName="HoverCard" />,
+  args: {
+    position: "top",
+    withBeak: true,
+    offset: 5,
+    openDelay: 0,
+    closeDelay: 150,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  render: ({ withLayer, layer, ...args }: HoverCardStoryArgs) => {
+    return (
+      <HoverCard {...args}>
+        <HoverCard.Target>
+          <Button variant="solid">Hover me</Button>
+        </HoverCard.Target>
+
+        <HoverCard.Dropdown>
+          <Text>
+            This is a hover card with informational content that appears when
+            you hover over the target element.
+          </Text>
+        </HoverCard.Dropdown>
+      </HoverCard>
+    );
+  },
+};
+
+export const WithoutBeak: Story = {
+  args: {
+    position: "top",
+    withBeak: false,
+    offset: 5,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  render: ({ withLayer, layer, ...args }: HoverCardStoryArgs) => {
+    return (
+      <HoverCard {...args}>
+        <HoverCard.Target>
+          <Button variant="outline">Without Beak</Button>
+        </HoverCard.Target>
+
+        <HoverCard.Dropdown>
+          <Text>
+            This hover card has the beak disabled, showing a clean dropdown
+            without the pointing indicator.
+          </Text>
+        </HoverCard.Dropdown>
+      </HoverCard>
+    );
+  },
+};
+
+export const RichContent: Story = {
+  args: {
+    position: "top",
+    offset: 5,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  render: ({ withLayer, layer, ...args }: HoverCardStoryArgs) => {
+    return (
+      <HoverCard {...args}>
+        <HoverCard.Target>
+          <Button variant="solid">User Profile</Button>
+        </HoverCard.Target>
+
+        <HoverCard.Dropdown>
+          <Group>
+            <Avatar src={null} alt="User avatar" />
+            <Stack>
+              <Text>Jane Doe</Text>
+              <Text>Software Engineer at Recursica</Text>
+            </Stack>
+          </Group>
+        </HoverCard.Dropdown>
+      </HoverCard>
+    );
+  },
 };