@recursica/mantine-adapter 0.13.1 → 0.15.0

package/src/components/Tooltip/Tooltip.stories.tsx

@@ -1,17 +1,165 @@
 import type { Meta, StoryObj } from "@storybook/react";
-import { Tooltip } from "./Tooltip";
-import { ComingSoon } from "@recursica/storybook-template";
+import { Tooltip, type TooltipProps } from "./Tooltip";
+import { Button } from "../Button";
 
-const meta: Meta<typeof Tooltip> = {
-  title: "UI-Kit/🚧 Tooltip",
+/**
+ * Tooltip story axes:
+ * - position: tooltip alignment relative to target
+ * - withBeak: beak (arrow) indicator on the tooltip
+ * - openDelay / closeDelay: hover timing controls
+ * - multiline: text wrapping behavior
+ * - disabled: suppress the tooltip entirely
+ * - layer: tested via the global Layer decorator (withLayer/layer args)
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type TooltipStoryArgs = Record<string, any>;
+
+const meta: Meta = {
+  title: "UI-Kit/Tooltip",
   component: Tooltip,
   tags: ["autodocs"],
+  argTypes: {
+    label: {
+      control: "text",
+      description: "Content displayed inside the tooltip.",
+    },
+    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 tooltip 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 tooltip and the target element.",
+    },
+    openDelay: {
+      control: "number",
+      description: "Delay in ms before the tooltip opens on hover.",
+    },
+    closeDelay: {
+      control: "number",
+      description: "Delay in ms before the tooltip closes when hover ends.",
+    },
+    disabled: {
+      control: "boolean",
+      description: "If set, the tooltip will not be rendered.",
+    },
+    opened: {
+      control: "boolean",
+      description:
+        "Force the tooltip to stay open. Useful for inspecting styling.",
+    },
+    // Hide auto-detected HTML attributes that leak from ElementProps<'div'>
+    defaultChecked: { table: { disable: true } },
+    defaultValue: { table: { disable: true } },
+    suppressContentEditableWarning: { table: { disable: true } },
+    suppressHydrationWarning: { table: { disable: true } },
+  },
+  parameters: {
+    layout: "centered",
+    docs: {
+      description: {
+        component: `
+The \`Tooltip\` component displays a floating label when the user hovers over or focuses a target element. It wraps Mantine's \`Tooltip\` while enforcing strict Recursica design token styling.
+
+### API
+
+Unlike \`HoverCard\`, Tooltip is a single component — content is passed via the \`label\` prop:
+\`\`\`tsx
+<Tooltip label="Helpful text" withBeak>
+  <Button>Hover me</Button>
+</Tooltip>
+\`\`\`
+
+### Static Sub-Components
+- \`Tooltip.Floating\` — A tooltip that follows the cursor position
+- \`Tooltip.Group\` — Groups multiple tooltips to share hover delay
+
+### Key Behaviors
+- The beak (arrow) is shown by default (\`withBeak={true}\`)
+- Supports \`openDelay\` and \`closeDelay\` for timing control
+- Set \`multiline\` to allow text wrapping within max-width
+        `,
+      },
+    },
+  },
 };
 
 export default meta;
 
-type Story = StoryObj<typeof Tooltip>;
+type Story = StoryObj<TooltipStoryArgs>;
 
 export const Default: Story = {
-  render: () => <ComingSoon componentName="Tooltip" />,
+  args: {
+    label: "This is a helpful tooltip",
+    position: "top",
+    withBeak: true,
+    offset: 5,
+    openDelay: 0,
+    closeDelay: 0,
+    disabled: false,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  render: ({ withLayer, layer, ...args }: TooltipStoryArgs) => {
+    return (
+      <Tooltip {...(args as TooltipProps)}>
+        <Button variant="solid">Hover me</Button>
+      </Tooltip>
+    );
+  },
+};
+
+export const WithoutBeak: Story = {
+  args: {
+    label: "Tooltip without a beak indicator",
+    position: "top",
+    withBeak: false,
+    offset: 5,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  render: ({ withLayer, layer, ...args }: TooltipStoryArgs) => {
+    return (
+      <Tooltip {...(args as TooltipProps)}>
+        <Button variant="outline">Without Beak</Button>
+      </Tooltip>
+    );
+  },
+};
+
+export const LongContent: Story = {
+  args: {
+    label:
+      "This is a longer tooltip message that demonstrates how text wraps within the maximum width defined by the design system.",
+    position: "top",
+    withBeak: true,
+    opened: true,
+    offset: 5,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  render: ({ withLayer, layer, ...args }: TooltipStoryArgs) => {
+    return (
+      <Tooltip {...(args as TooltipProps)}>
+        <Button variant="solid">Long Content</Button>
+      </Tooltip>
+    );
+  },
 };

package/src/components/Tooltip/Tooltip.tsx

@@ -1,7 +1,117 @@
-import React from "react";
+import {
+  Tooltip as MantineTooltip,
+  type TooltipProps as MantineTooltipProps,
+} from "@mantine/core";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Tooltip.module.css";
 
-export type TooltipProps = React.HTMLAttributes<HTMLDivElement>;
+// ============================================================
+// TOOLTIP
+// ============================================================
 
-export const Tooltip: React.FC<TooltipProps> = (props) => {
-  return <div {...props}>Tooltip</div>;
+/**
+ * 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
+>;
+
+const TooltipBase = function Tooltip({
+  overStyled = false,
+  withBeak = true,
+  ...rest
+}: TooltipProps) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+
+  // Bind CSS module classes to Mantine's internal classNames API
+  const mergedClassNames: Partial<Record<string, string>> = {
+    tooltip: styles.tooltip,
+    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 (
+    <MantineTooltip
+      position="top" /* Recursica default; Mantine defaults to "bottom" */
+      multiline /* Always allow text wrapping within max-width */
+      arrowSize={arrowSize}
+      withArrow={resolvedWithArrow}
+      classNames={mergedClassNames}
+      {...(sanitizedProps as unknown as MantineTooltipProps)}
+    />
+  );
 };
+TooltipBase.displayName = "Tooltip";
+
+// ============================================================
+// DOT NOTATION EXPORT
+// ============================================================
+
+type TooltipComponent = typeof TooltipBase & {
+  Floating: typeof MantineTooltip.Floating;
+  Group: typeof MantineTooltip.Group;
+};
+
+export const Tooltip = TooltipBase as TooltipComponent;
+Tooltip.Floating = MantineTooltip.Floating;
+Tooltip.Group = MantineTooltip.Group;