react-miui 0.33.0 → 0.34.0

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

@@ -0,0 +1,285 @@
+/* eslint-disable max-lines */
+import React, { useCallback, useState } from "react";
+
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import { Gap } from "../../utils/Gap";
+import { Button } from "../button/Button";
+import { Drawer } from "../drawer/Drawer";
+import { Modal } from "../modal/Modal";
+import { ModalButtons } from "../modal/ModalButtons";
+import { Tooltip, TooltipProvider } from "./Tooltip";
+
+const meta: Meta<typeof Tooltip> = {
+    title: "Components/UI/Tooltip",
+    component: Tooltip,
+    tags: ["autodocs", "ui"],
+    argTypes: {
+        side: {
+            control: "inline-radio",
+            options: ["top", "right", "bottom", "left"],
+        },
+        align: {
+            control: "inline-radio",
+            options: ["start", "center", "end"],
+        },
+        sideOffset: { control: { type: "number", min: 0, max: 40 } },
+        alignOffset: { control: { type: "number", min: -40, max: 40 } },
+        delayDuration: { control: { type: "number", min: 0, max: 2000, step: 100 } },
+        avoidCollisions: { type: "boolean" },
+        arrow: { type: "boolean" },
+        content: { control: "text" },
+        children: { table: { disable: true } },
+        open: { table: { disable: true } },
+        defaultOpen: { table: { disable: true } },
+        onOpenChange: { table: { disable: true } },
+    },
+};
+
+type Story = StoryObj<typeof Tooltip>;
+
+/**
+ * Playground. Tweak `side`, `align`, `sideOffset`, `delayDuration`, `arrow`,
+ * and `avoidCollisions` from the controls panel.
+ */
+const Primary: Story = {
+    args: {
+        content: "Save your changes",
+        side: "top",
+        align: "center",
+        sideOffset: 6,
+        alignOffset: 0,
+        delayDuration: 500,
+        avoidCollisions: true,
+        arrow: true,
+    },
+    render: (args) => (
+        <div style={{ padding: 80, display: "flex", justifyContent: "center" }}>
+            <Tooltip {...args}>
+                <Button>Hover me</Button>
+            </Tooltip>
+        </div>
+    ),
+};
+
+/**
+ * All four sides shown at once.
+ */
+const AllSides: Story = {
+    render: () => (
+        <div
+            style={{
+                padding: 120,
+                display: "grid",
+                gridTemplateColumns: "repeat(2, max-content)",
+                gap: 40,
+                justifyContent: "center",
+            }}
+        >
+            <Tooltip content={"Top"} side={"top"} arrow={true}>
+                <Button>Top</Button>
+            </Tooltip>
+            <Tooltip content={"Right"} side={"right"} arrow={true}>
+                <Button>Right</Button>
+            </Tooltip>
+            <Tooltip content={"Bottom"} side={"bottom"} arrow={true}>
+                <Button>Bottom</Button>
+            </Tooltip>
+            <Tooltip content={"Left"} side={"left"} arrow={true}>
+                <Button>Left</Button>
+            </Tooltip>
+        </div>
+    ),
+};
+
+/**
+ * `TooltipProvider` enables group-delay behavior: once any tooltip is open, the next ones
+ * appear without waiting for `delayDuration` (until `skipDelayDuration` elapses with all
+ * tooltips closed). Hover one button slowly, then sweep across the rest — they pop instantly.
+ */
+const GroupDelay: Story = {
+    render: () => (
+        <TooltipProvider delayDuration={500} skipDelayDuration={400}>
+            <div style={{ padding: 80, display: "flex", gap: 12, justifyContent: "center" }}>
+                <Tooltip content={"First"}>
+                    <Button>One</Button>
+                </Tooltip>
+                <Tooltip content={"Second"}>
+                    <Button>Two</Button>
+                </Tooltip>
+                <Tooltip content={"Third"}>
+                    <Button>Three</Button>
+                </Tooltip>
+                <Tooltip content={"Fourth"}>
+                    <Button>Four</Button>
+                </Tooltip>
+            </div>
+        </TooltipProvider>
+    ),
+};
+
+/**
+ * Triggers placed near viewport edges. With `avoidCollisions` (default) the tooltip
+ * flips to fit; toggle the arg in the playground story to see the difference.
+ */
+const NearViewportEdge: Story = {
+    render: () => (
+        <div style={{ height: "90vh", position: "relative" }}>
+            <div style={{ position: "absolute", top: 4, left: 4 }}>
+                <Tooltip content={"I would overflow up-left, so I flip"} side={"top"} arrow={true}>
+                    <Button>Top-left corner</Button>
+                </Tooltip>
+            </div>
+            <div style={{ position: "absolute", top: 4, right: 4 }}>
+                <Tooltip content={"I would overflow up-right, so I flip"} side={"top"} arrow={true}>
+                    <Button>Top-right corner</Button>
+                </Tooltip>
+            </div>
+            <div style={{ position: "absolute", bottom: 4, left: 4 }}>
+                <Tooltip content={"I would overflow down-left"} side={"bottom"} arrow={true}>
+                    <Button>Bottom-left corner</Button>
+                </Tooltip>
+            </div>
+            <div style={{ position: "absolute", bottom: 4, right: 4 }}>
+                <Tooltip content={"I would overflow down-right"} side={"bottom"} arrow={true}>
+                    <Button>Bottom-right corner</Button>
+                </Tooltip>
+            </div>
+        </div>
+    ),
+};
+
+/**
+ * Long content wraps to the configured `maxWidth`.
+ */
+const LongContent: Story = {
+    render: () => (
+        <div style={{ padding: 80, display: "flex", justifyContent: "center" }}>
+            <Tooltip
+                content={"This tooltip has a longer description that wraps onto multiple lines once it "
+                    + "exceeds the maximum content width set in the styles."}
+                side={"bottom"}
+            >
+                <Button>Long description</Button>
+            </Tooltip>
+        </div>
+    ),
+};
+
+/**
+ * Edge case: tooltip rendered from inside a `Modal`. Because the content is portalled to
+ * `document.body`, it escapes the modal's stacking context and renders above it.
+ */
+const InModal: Story = {
+    render: () => {
+        const [open, setOpen] = useState(false);
+
+        const handleOpen = useCallback(() => { setOpen(true); }, []);
+        const handleClose = useCallback(() => { setOpen(false); }, []);
+
+        return (
+            <div>
+                <Button onClick={handleOpen}>Open modal</Button>
+                <Modal isOpen={open} onClose={handleClose} title={"Tooltip in a modal"}>
+                    <Gap>
+                        <div>Hover the buttons below — the tooltip should appear above the modal.</div>
+                        <div style={{ display: "flex", gap: 12 }}>
+                            <Tooltip content={"Above modal, side=top"} side={"top"} arrow={true}>
+                                <Button>Top</Button>
+                            </Tooltip>
+                            <Tooltip content={"Above modal, side=right"} side={"right"} arrow={true}>
+                                <Button>Right</Button>
+                            </Tooltip>
+                            <Tooltip content={"Above modal, side=bottom"} side={"bottom"} arrow={true}>
+                                <Button>Bottom</Button>
+                            </Tooltip>
+                        </div>
+                    </Gap>
+                    <ModalButtons>
+                        <ModalButtons.Button variant={"main"} onClick={handleClose}>Close</ModalButtons.Button>
+                    </ModalButtons>
+                </Modal>
+            </div>
+        );
+    },
+};
+
+/**
+ * Edge case: tooltip rendered from inside a `Drawer`. Same portal behavior — content
+ * floats above the drawer regardless of the drawer's stacking context.
+ */
+const InDrawer: Story = {
+    render: () => {
+        const [open, setOpen] = useState(false);
+
+        const handleOpen = useCallback(() => { setOpen(true); }, []);
+        const handleClose = useCallback(() => { setOpen(false); }, []);
+
+        return (
+            <div>
+                <Button onClick={handleOpen}>Open drawer</Button>
+                <Drawer isOpen={open} onClose={handleClose}>
+                    <div style={{ padding: 24, display: "flex", flexDirection: "column", gap: 16 }}>
+                        <div>Tooltips work from inside a drawer.</div>
+                        <Tooltip content={"Hello from inside the drawer"} side={"bottom"} arrow={true}>
+                            <Button>Hover me</Button>
+                        </Tooltip>
+                        <Button onClick={handleClose}>Close drawer</Button>
+                    </div>
+                </Drawer>
+            </div>
+        );
+    },
+};
+
+/**
+ * Controlled tooltip — open state is driven by parent. Useful for tutorials,
+ * onboarding tours, or pinning a tooltip open while a user interacts elsewhere.
+ */
+const Controlled: Story = {
+    render: () => {
+        const [open, setOpen] = useState(false);
+
+        const handleToggle = useCallback(() => { setOpen(p => !p); }, []);
+
+        return (
+            <div style={{ padding: 80, display: "flex", gap: 16, justifyContent: "center" }}>
+                <Button onClick={handleToggle}>{open ? "Hide" : "Show"} tooltip</Button>
+                <Tooltip content={"I'm controlled"} open={open} side={"right"}>
+                    <Button>Target</Button>
+                </Tooltip>
+            </div>
+        );
+    },
+};
+
+/**
+ * Tooltip wrapping a non-button trigger. Any element that can receive a ref works
+ * — here, an inline word with a dotted underline.
+ */
+const InlineTrigger: Story = {
+    render: () => (
+        <div style={{ padding: 80, fontSize: 18, lineHeight: 1.6, maxWidth: 500, margin: "0 auto" }}>
+            This sentence contains a{" "}
+            <Tooltip content={"A short, contextual explanation."}>
+                <span style={{ borderBottom: "1px dotted currentColor", cursor: "help" }}>
+                    glossed term
+                </span>
+            </Tooltip>
+            {" "}that reveals more on hover or focus.
+        </div>
+    ),
+};
+
+export default meta;
+export {
+    Primary,
+    AllSides,
+    GroupDelay,
+    NearViewportEdge,
+    LongContent,
+    InModal,
+    InDrawer,
+    Controlled,
+    InlineTrigger,
+};

package/src/components/ui/tooltip/Tooltip.styled.ts

@@ -0,0 +1,36 @@
+import * as RadixTooltip from "@radix-ui/react-tooltip";
+
+import { dimensionsPxToRem, fontPxToRem, keyframes, pxToRem, styled } from "../../../theme";
+
+const fadeIn = keyframes({
+    from: { opacity: 0, transform: "scale(0.96)" },
+    to: { opacity: 1, transform: "scale(1)" },
+});
+
+const StyledContent = styled(RadixTooltip.Content, {
+    "zIndex": 10,
+    "background": "$text2",
+    "color": "$background",
+    "padding": `${dimensionsPxToRem(18)} ${dimensionsPxToRem(36)}`,
+    "borderRadius": dimensionsPxToRem(12),
+    "fontSize": fontPxToRem(24),
+    "lineHeight": 1.3,
+    "maxWidth": pxToRem(280),
+    "boxShadow": `0 ${pxToRem(2)} ${pxToRem(8)} rgba(0, 0, 0, 0.18)`,
+    "userSelect": "none",
+    "transformOrigin": "var(--radix-tooltip-content-transform-origin)",
+    "animation": `${fadeIn.toString()} 120ms ease-out`,
+
+    "&[data-state=\"closed\"]": {
+        animationDirection: "reverse",
+    },
+});
+
+const StyledArrow = styled(RadixTooltip.Arrow, {
+    fill: "$text2",
+});
+
+export {
+    StyledContent,
+    StyledArrow,
+};

package/src/components/ui/tooltip/Tooltip.tsx

@@ -0,0 +1,195 @@
+import React, { forwardRef } from "react";
+
+import * as RadixTooltip from "@radix-ui/react-tooltip";
+
+import { StyledArrow, StyledContent } from "./Tooltip.styled";
+
+type Side = "top" | "right" | "bottom" | "left";
+type Align = "start" | "center" | "end";
+
+interface TooltipProviderProps {
+    /**
+     * The duration from when the pointer enters the trigger until the tooltip opens, in milliseconds.
+     * Default: `500`.
+     */
+    delayDuration?: number;
+    /**
+     * If a tooltip has opened, the duration during which other tooltips open instantly
+     * (without waiting for `delayDuration`), in milliseconds.
+     * Default: `300`.
+     */
+    skipDelayDuration?: number;
+    /**
+     * When `true`, the tooltip content stays open while the pointer is over it.
+     * Set to `false` for stricter "hover the trigger only" behavior.
+     * Default: `true`.
+     */
+    disableHoverableContent?: boolean;
+    children: React.ReactNode;
+}
+
+/**
+ * Required wrapper for `<Tooltip>`. Render it once near the root of your app — usually
+ * around (or just inside) your top-level layout. It enables group-delay behavior via
+ * `skipDelayDuration`: once one tooltip in the subtree has been seen, the next ones
+ * open without waiting for `delayDuration`.
+ *
+ * A single `<Tooltip>` without a `<TooltipProvider>` ancestor will throw at runtime.
+ */
+const TooltipProvider = (props: TooltipProviderProps) => {
+    const radixProps: Omit<React.ComponentProps<typeof RadixTooltip.Provider>, "children"> = {};
+    if (props.delayDuration !== undefined) { radixProps.delayDuration = props.delayDuration; }
+    if (props.skipDelayDuration !== undefined) { radixProps.skipDelayDuration = props.skipDelayDuration; }
+    if (props.disableHoverableContent !== undefined) {
+        radixProps.disableHoverableContent = props.disableHoverableContent;
+    }
+
+    return (
+        <RadixTooltip.Provider {...radixProps}>
+            {props.children}
+        </RadixTooltip.Provider>
+    );
+};
+
+interface TooltipProps {
+    /**
+     * The content to render inside the tooltip.
+     */
+    content: React.ReactNode;
+    /**
+     * Preferred side of the trigger to render the tooltip against. Will be flipped
+     * automatically on collision unless `avoidCollisions` is `false`.
+     * Default: `"top"`.
+     */
+    side?: Side;
+    /**
+     * Distance in pixels between the trigger and the tooltip.
+     * Default: `6`.
+     */
+    sideOffset?: number;
+    /**
+     * Alignment along the chosen side.
+     * Default: `"center"`.
+     */
+    align?: Align;
+    /**
+     * Offset in pixels from the `align` edge.
+     * Default: `0`.
+     */
+    alignOffset?: number;
+    /**
+     * The duration from when the pointer enters the trigger until the tooltip opens.
+     * Overrides the provider's `delayDuration` for this tooltip only.
+     */
+    delayDuration?: number;
+    /**
+     * When `true`, the tooltip will not flip to the opposite side on collision.
+     * Default: `true` (collisions are avoided).
+     */
+    avoidCollisions?: boolean;
+    /**
+     * When `true`, renders an arrow pointing at the trigger.
+     * Default: `true`.
+     */
+    arrow?: boolean;
+    /**
+     * Controlled open state. If omitted, the tooltip is uncontrolled.
+     */
+    open?: boolean;
+    /**
+     * Initial open state for the uncontrolled mode.
+     */
+    defaultOpen?: boolean;
+    /**
+     * Called when the open state changes.
+     */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * Additional class name applied to the tooltip content.
+     */
+    className?: string;
+    /**
+     * The element that triggers the tooltip on hover/focus. Must be a single React element
+     * that can receive a ref and event handlers (a DOM element or a component using forwardRef).
+     */
+    children: React.ReactElement;
+}
+
+/**
+ * A tooltip that appears on hover or keyboard focus of its child trigger.
+ *
+ * Powered by Radix UI under the hood, so accessibility (ARIA, focus, escape, group delay)
+ * is handled. The content is portalled to `document.body`, so it escapes stacking contexts
+ * and renders above modals/drawers.
+ *
+ * Requires a `<TooltipProvider>` somewhere up the tree.
+ *
+ * @example
+ * ```tsx
+ * <TooltipProvider>
+ *     <Tooltip content="Save changes" side="bottom">
+ *         <Button>Save</Button>
+ *     </Tooltip>
+ * </TooltipProvider>
+ * ```
+ */
+// eslint-disable-next-line react/no-multi-comp
+const Tooltip = forwardRef<HTMLDivElement, TooltipProps>((props, ref) => {
+    const {
+        content,
+        side = "top",
+        // eslint-disable-next-line @typescript-eslint/no-magic-numbers
+        sideOffset = 6,
+        align = "center",
+        alignOffset = 0,
+        delayDuration,
+        avoidCollisions = true,
+        arrow = true,
+        open,
+        defaultOpen,
+        onOpenChange,
+        className,
+        children,
+    } = props;
+
+    const rootProps: React.ComponentProps<typeof RadixTooltip.Root> = {};
+    if (open !== undefined) { rootProps.open = open; }
+    if (defaultOpen !== undefined) { rootProps.defaultOpen = defaultOpen; }
+    if (onOpenChange !== undefined) { rootProps.onOpenChange = onOpenChange; }
+    if (delayDuration !== undefined) { rootProps.delayDuration = delayDuration; }
+
+    return (
+        <RadixTooltip.Root {...rootProps}>
+            <RadixTooltip.Trigger asChild={true}>
+                {children}
+            </RadixTooltip.Trigger>
+            <RadixTooltip.Portal>
+                <StyledContent
+                    ref={ref}
+                    side={side}
+                    sideOffset={sideOffset}
+                    align={align}
+                    alignOffset={alignOffset}
+                    avoidCollisions={avoidCollisions}
+                    className={className}
+                >
+                    {content}
+                    {/* eslint-disable-next-line react/jsx-no-leaked-render */}
+                    {arrow && <StyledArrow width={10} height={5} />}
+                </StyledContent>
+            </RadixTooltip.Portal>
+        </RadixTooltip.Root>
+    );
+});
+
+Tooltip.displayName = "Tooltip";
+Tooltip.toString = () => StyledContent.toString();
+
+const TooltipContentSelector = StyledContent.toString();
+
+export {
+    Tooltip,
+    TooltipProvider,
+    TooltipContentSelector,
+};
+export type { TooltipProps, TooltipProviderProps };

package/src/index.ts

@@ -42,6 +42,7 @@ export * from "./components/ui/stats/Stats";
 export * from "./components/ui/tabs/Selector";
 export * from "./components/ui/toaster/Toaster";
 export * from "./components/ui/toolButton/ToolButton";
+export * from "./components/ui/tooltip/Tooltip";
 
 export * from "./components/utils/Gap";
 export * from "./components/utils/HandleEsc";