@refraktor/core 0.0.1

package/src/components/tooltip/tooltip.tsx

@@ -0,0 +1,158 @@
+import { useId } from "@refraktor/utils";
+import { useTheme } from "../../theme";
+import {
+    createClassNamesConfig,
+    createComponentConfig,
+    factory,
+    useClassNames,
+    useProps
+} from "../../utils";
+import {
+    TooltipClassNames,
+    TooltipFactoryPayload,
+    TooltipProps
+} from "./tooltip.types";
+import { useTooltip } from "./use-tooltip";
+import { cloneElement, ComponentProps, isValidElement } from "react";
+import { Transition } from "../transition";
+import { FloatingArrow, FloatingPortal } from "@floating-ui/react";
+
+const defaultProps = {
+    positioning: {
+        placement: "top",
+        offset: 8
+    },
+    middlewares: { flip: true, shift: true, inline: true },
+    trigger: "hover",
+    openDelay: 0,
+    closeDelay: 0,
+    showArrow: false,
+    radius: "default",
+    withinPortal: true
+} satisfies Partial<TooltipProps>;
+
+const Tooltip = factory<TooltipFactoryPayload>((_props, ref) => {
+    const { cx, getRadius } = useTheme();
+    const {
+        id,
+        children,
+        content,
+        opened,
+        defaultOpened,
+        onOpenedChange,
+        positioning,
+        middlewares,
+        disabled,
+        trigger,
+        openDelay,
+        closeDelay,
+        showArrow,
+        transitionProps,
+        radius,
+        withinPortal,
+        className,
+        classNames,
+        ...props
+    } = useProps("Tooltip", defaultProps, _props);
+    const classes = useClassNames("Tooltip", classNames);
+
+    const _id = useId(id);
+
+    const {
+        opened: isOpened,
+        context,
+        refs,
+        floatingStyles,
+        getReferenceProps,
+        getFloatingProps,
+        placement,
+        arrowRef
+    } = useTooltip({
+        opened,
+        defaultOpened,
+        onOpenedChange,
+        positioning,
+        middlewares,
+        disabled,
+        trigger,
+        openDelay,
+        closeDelay,
+        showArrow
+    });
+
+    const triggerElement = isValidElement(children)
+        ? cloneElement(children as any, {
+              ref: refs.setReference,
+              ...getReferenceProps({
+                  ...(children.props as ComponentProps<any>)
+              })
+          })
+        : null;
+
+    const tooltipContent = (
+        <Transition
+            transition="fade"
+            duration={200}
+            mounted={isOpened}
+            {...transitionProps}
+        >
+            <div
+                ref={(node) => {
+                    refs.setFloating(node);
+
+                    if (typeof ref === "function") {
+                        ref(node);
+                    } else if (ref) {
+                        ref.current = node;
+                    }
+                }}
+                id={_id}
+                role="tooltip"
+                style={floatingStyles}
+                className={cx(
+                    "z-50 px-1.5 py-0.5 text-sm bg-[var(--refraktor-bg)] text-[var(--refraktor-text)] shadow-md",
+                    getRadius(radius),
+                    classes.content,
+                    className
+                )}
+                {...getFloatingProps()}
+                {...props}
+            >
+                {content}
+
+                {showArrow && (
+                    <FloatingArrow
+                        ref={arrowRef}
+                        context={context}
+                        width={10}
+                        height={5}
+                        className={cx(
+                            "fill-[var(--refraktor-bg)]",
+                            classes.arrow
+                        )}
+                    />
+                )}
+            </div>
+        </Transition>
+    );
+
+    return (
+        <div className={cx("inline-block", classes.root)}>
+            <span className={cx("inline-block", classes.trigger)}>
+                {triggerElement}
+            </span>
+
+            {withinPortal ? (
+                <FloatingPortal>{tooltipContent}</FloatingPortal>
+            ) : (
+                tooltipContent
+            )}
+        </div>
+    );
+});
+
+Tooltip.displayName = "@refraktor/core/Tooltip";
+Tooltip.configure = createComponentConfig<TooltipProps>();
+Tooltip.classNames = createClassNamesConfig<TooltipClassNames>();
+
+export default Tooltip;

package/src/components/tooltip/tooltip.types.ts

@@ -0,0 +1,104 @@
+import { ComponentPropsWithoutRef, ReactNode } from "react";
+import type {
+    FlipOptions,
+    InlineOptions,
+    Placement,
+    ShiftOptions
+} from "@floating-ui/react";
+import {
+    createClassNamesConfig,
+    createComponentConfig,
+    FactoryPayload
+} from "../../utils";
+import { TransitionProps } from "../transition";
+import { RefraktorRadius } from "../../theme";
+
+export type TooltipClassNames = {
+    root?: string;
+    trigger?: string;
+    content?: string;
+    arrow?: string;
+};
+
+export type TooltipPositioning = {
+    /** The placement of the tooltip relative to the trigger element @default `top` */
+    placement?: Placement;
+
+    /** Offset distance from the trigger element in pixels @default `8` */
+    offset?: number;
+};
+
+export type TooltipMiddlewares = {
+    shift?: boolean | ShiftOptions;
+    flip?: boolean | FlipOptions;
+    inline?: boolean | InlineOptions;
+};
+
+export type TooltipTrigger = "hover" | "focus";
+
+export interface TooltipProps extends Omit<
+    ComponentPropsWithoutRef<"div">,
+    "content"
+> {
+    /** The trigger element that activates the tooltip */
+    children: ReactNode;
+
+    /** Content to display inside the tooltip */
+    content: ReactNode;
+
+    /** State of the tooltip (controlled) */
+    opened?: boolean;
+
+    /** Initial state of the tooltip (uncontrolled) */
+    defaultOpened?: boolean;
+
+    /** Callback called when the tooltip state changes */
+    onOpenedChange?: (opened: boolean) => void;
+
+    /** Positioning settings for the tooltip */
+    positioning?: TooltipPositioning;
+
+    /** Middlewares settings for the tooltip */
+    middlewares?: TooltipMiddlewares;
+
+    /** Whether the tooltip is disabled @default `false` */
+    disabled?: boolean;
+
+    /** Trigger type for the tooltip @default `hover` */
+    trigger?: TooltipTrigger;
+
+    /** Delay in milliseconds before the tooltip opens @default `0` */
+    openDelay?: number;
+
+    /** Delay in milliseconds before the tooltip closes @default `0` */
+    closeDelay?: number;
+
+    /** Whether to show the arrow for the tooltip @default `false` */
+    showArrow?: boolean;
+
+    /** Transition props for the tooltip content, uses Transition component internally */
+    transitionProps?: Omit<TransitionProps, "children" | "mounted">;
+
+    /** Radius for the tooltip content @default `default` */
+    radius?: RefraktorRadius;
+
+    /** Whether to render the tooltip within a portal @default `true` */
+    withinPortal?: boolean;
+
+    /** Used for editing root class name */
+    className?: string;
+
+    /** Used for styling different parts of the component */
+    classNames?: TooltipClassNames;
+}
+
+export interface TooltipFactoryPayload extends FactoryPayload {
+    props: TooltipProps;
+    ref: HTMLDivElement;
+    compound: {
+        configure: ReturnType<typeof createComponentConfig<TooltipProps>>;
+        classNames: ReturnType<
+            typeof createClassNamesConfig<TooltipClassNames>
+        >;
+    };
+}

package/src/components/tooltip/use-tooltip.ts

@@ -0,0 +1,199 @@
+import { useUncontrolled } from "@refraktor/utils";
+import {
+    TooltipMiddlewares,
+    TooltipPositioning,
+    TooltipTrigger
+} from "./tooltip.types";
+import {
+    arrow,
+    autoUpdate,
+    flip,
+    FloatingContext,
+    inline,
+    Middleware,
+    offset,
+    Placement,
+    shift,
+    useDismiss,
+    useFloating,
+    useFocus,
+    useHover,
+    useInteractions,
+    useRole
+} from "@floating-ui/react";
+import { useCallback, useMemo, useRef } from "react";
+
+interface UseTooltipProps {
+    opened?: boolean;
+    defaultOpened?: boolean;
+    onOpenedChange?: (opened: boolean) => void;
+    positioning?: TooltipPositioning;
+    middlewares?: TooltipMiddlewares;
+    disabled?: boolean;
+    trigger?: TooltipTrigger;
+    showArrow?: boolean;
+    openDelay?: number;
+    closeDelay?: number;
+}
+
+export interface UseTooltipReturn {
+    opened: boolean;
+    open: () => void;
+    close: () => void;
+    toggle: () => void;
+    context: FloatingContext;
+    refs: {
+        setReference: (node: HTMLElement | null) => void;
+        setFloating: (node: HTMLElement | null) => void;
+        reference: React.MutableRefObject<HTMLElement | null>;
+        floating: React.MutableRefObject<HTMLElement | null>;
+    };
+    floatingStyles: React.CSSProperties;
+    getReferenceProps: (
+        userProps?: React.HTMLAttributes<HTMLElement>
+    ) => Record<string, unknown>;
+    getFloatingProps: (
+        userProps?: React.HTMLAttributes<HTMLElement>
+    ) => Record<string, unknown>;
+    arrowRef: React.RefObject<SVGSVGElement | null>;
+    placement: Placement;
+}
+
+export function useTooltip(options: UseTooltipProps = {}): UseTooltipReturn {
+    const {
+        opened,
+        defaultOpened,
+        onOpenedChange,
+        positioning = {
+            placement: "top",
+            offset: 8
+        },
+        middlewares = { flip: true, shift: true, inline: true },
+        disabled = false,
+        trigger = "hover",
+        showArrow = false,
+        openDelay = 0,
+        closeDelay = 0
+    } = options;
+
+    const arrowRef = useRef<SVGSVGElement>(null);
+
+    const [isOpen, setIsOpen] = useUncontrolled({
+        value: opened,
+        defaultValue: defaultOpened,
+        finalValue: false,
+        onChange: onOpenedChange
+    });
+
+    const middleware = useMemo(() => {
+        const middleware: Middleware[] = [];
+
+        middleware.push(offset(positioning.offset ?? 8));
+
+        if (middlewares.flip) {
+            middleware.push(
+                flip(
+                    typeof middlewares.flip === "boolean"
+                        ? undefined
+                        : middlewares.flip
+                )
+            );
+        }
+
+        if (middlewares.shift) {
+            middleware.push(
+                shift(
+                    typeof middlewares.shift === "boolean"
+                        ? undefined
+                        : middlewares.shift
+                )
+            );
+        }
+
+        if (middlewares.inline) {
+            middleware.push(
+                inline(
+                    typeof middlewares.inline === "boolean"
+                        ? undefined
+                        : middlewares.inline
+                )
+            );
+        }
+
+        if (arrowRef.current && showArrow) {
+            middleware.push(
+                arrow({
+                    element: arrowRef.current
+                })
+            );
+        }
+
+        return middleware;
+    }, [positioning.offset, middlewares, showArrow, arrowRef]);
+
+    const floating = useFloating({
+        placement: positioning.placement,
+        open: isOpen,
+        onOpenChange: setIsOpen,
+        middleware: middleware,
+        whileElementsMounted: autoUpdate
+    });
+
+    const hover = useHover(floating.context, {
+        enabled: trigger === "hover" && !disabled,
+        delay: {
+            open: openDelay,
+            close: closeDelay
+        }
+    });
+
+    const focus = useFocus(floating.context, {
+        enabled: trigger === "focus" && !disabled
+    });
+
+    const dismiss = useDismiss(floating.context);
+
+    const role = useRole(floating.context, {
+        role: "tooltip"
+    });
+
+    const { getReferenceProps, getFloatingProps } = useInteractions([
+        hover,
+        focus,
+        dismiss,
+        role
+    ]);
+
+    const open = useCallback(() => {
+        setIsOpen(true);
+    }, [setIsOpen]);
+
+    const close = useCallback(() => {
+        setIsOpen(false);
+    }, [setIsOpen]);
+
+    const toggle = useCallback(() => {
+        setIsOpen(!isOpen);
+    }, [setIsOpen, isOpen]);
+
+    return {
+        opened: isOpen,
+        open,
+        close,
+        toggle,
+        context: floating.context,
+        refs: {
+            setReference: floating.refs.setReference,
+            setFloating: floating.refs.setFloating,
+            reference: floating.refs
+                .reference as React.MutableRefObject<HTMLElement | null>,
+            floating: floating.refs
+                .floating as React.MutableRefObject<HTMLElement | null>
+        },
+        floatingStyles: floating.floatingStyles,
+        getReferenceProps,
+        getFloatingProps,
+        placement: floating.placement,
+        arrowRef
+    };
+}

package/src/components/transition/index.ts

@@ -0,0 +1,11 @@
+export { default as Transition } from "./transition";
+export type {
+    TransitionDefinition,
+    TransitionDirection,
+    TransitionMotionPreference,
+    TransitionPreset,
+    TransitionProps,
+    TransitionState,
+    TransitionTimingValue
+} from "./transition.types";
+export { default as transitions, defineTransition } from "./transitions";

package/src/components/transition/transition.test.tsx

@@ -0,0 +1,126 @@
+import { describe, expect, it, vi } from "vitest";
+import { render, screen, waitFor } from "../../vitest";
+import Transition from "./transition";
+
+describe("@refraktor/core/Transition", () => {
+    it("unmounts content after exit by default", async () => {
+        const { rerender } = await render(
+            <Transition mounted transition="fade" immediate>
+                <div data-testid="content">Content</div>
+            </Transition>
+        );
+
+        expect(screen.getByTestId("content")).toBeInTheDocument();
+
+        rerender(
+            <Transition mounted={false} transition="fade" immediate>
+                <div data-testid="content">Content</div>
+            </Transition>
+        );
+
+        await waitFor(() => {
+            expect(screen.queryByTestId("content")).not.toBeInTheDocument();
+        });
+    });
+
+    it("keeps content mounted when keepMounted is true", async () => {
+        const { rerender } = await render(
+            <Transition
+                mounted
+                keepMounted
+                transition="fade"
+                immediate
+                data-testid="transition"
+            >
+                Content
+            </Transition>
+        );
+
+        rerender(
+            <Transition
+                mounted={false}
+                keepMounted
+                transition="fade"
+                immediate
+                data-testid="transition"
+            >
+                Content
+            </Transition>
+        );
+
+        const node = screen.getByTestId("transition");
+        expect(node).toBeInTheDocument();
+        await waitFor(() => {
+            expect(node).toHaveAttribute("data-transition-state", "exited");
+        });
+    });
+
+    it("fires lifecycle callbacks and forwards root props", async () => {
+        const onEnterStart = vi.fn();
+        const onEnterEnd = vi.fn();
+        const onExitStart = vi.fn();
+        const onExitEnd = vi.fn();
+        const onStateChange = vi.fn();
+
+        const { rerender } = await render(
+            <Transition
+                mounted={false}
+                keepMounted
+                immediate
+                id="custom-id"
+                className="custom-class"
+                data-testid="transition"
+                onEnterStart={onEnterStart}
+                onEnterEnd={onEnterEnd}
+                onExitStart={onExitStart}
+                onExitEnd={onExitEnd}
+                onStateChange={onStateChange}
+            >
+                {(state) => <span>{state}</span>}
+            </Transition>
+        );
+
+        rerender(
+            <Transition
+                mounted
+                keepMounted
+                immediate
+                id="custom-id"
+                className="custom-class"
+                data-testid="transition"
+                onEnterStart={onEnterStart}
+                onEnterEnd={onEnterEnd}
+                onExitStart={onExitStart}
+                onExitEnd={onExitEnd}
+                onStateChange={onStateChange}
+            >
+                {(state) => <span>{state}</span>}
+            </Transition>
+        );
+
+        rerender(
+            <Transition
+                mounted={false}
+                keepMounted
+                immediate
+                id="custom-id"
+                className="custom-class"
+                data-testid="transition"
+                onEnterStart={onEnterStart}
+                onEnterEnd={onEnterEnd}
+                onExitStart={onExitStart}
+                onExitEnd={onExitEnd}
+                onStateChange={onStateChange}
+            >
+                {(state) => <span>{state}</span>}
+            </Transition>
+        );
+
+        const node = screen.getByTestId("transition");
+
+        expect(node).toHaveAttribute("id", "custom-id");
+        expect(node).toHaveClass("custom-class");
+        expect(node).toHaveAttribute("data-transition-state", "exited");
+        expect(node).toHaveTextContent("exited");
+    });
+});