@zentauri-ui/zentauri-components 1.3.0 → 1.4.0

package/src/ui/toggle/animated/toggle-animated.tsx

@@ -0,0 +1,76 @@
+"use client";
+
+import { motion } from "framer-motion";
+import { useCallback, useState } from "react";
+
+import { cn } from "../../../lib/utils";
+
+import { toggleThumbAnimationPresets } from "./animations";
+import type { ToggleAnimatedProps } from "./types";
+import { toggleThumbVariants, toggleTrackVariants } from "../variants";
+
+export function ToggleAnimated(props: ToggleAnimatedProps) {
+  const {
+    className,
+    size,
+    appearance,
+    animation = "spring",
+    checked,
+    defaultChecked = false,
+    onCheckedChange,
+    disabled,
+    ref,
+    "aria-label": ariaLabel = "Toggle",
+    children,
+    ...rest
+  } = props;
+  const isControlled = checked !== undefined;
+  const [uncontrolled, setUncontrolled] = useState(defaultChecked);
+  const resolved = isControlled ? Boolean(checked) : uncontrolled;
+  const thumbMotion = toggleThumbAnimationPresets[animation];
+
+  const setChecked = useCallback(
+    (next: boolean) => {
+      if (!isControlled) {
+        setUncontrolled(next);
+      }
+      onCheckedChange?.(next);
+    },
+    [isControlled, onCheckedChange],
+  );
+
+  const thumbShiftPx = size === "sm" ? 14 : size === "lg" ? 26 : 20;
+
+  return (
+    <button
+      ref={ref}
+      type="button"
+      role="switch"
+      data-slot="toggle"
+      aria-checked={resolved}
+      aria-label={ariaLabel}
+      data-state={resolved ? "checked" : "unchecked"}
+      disabled={disabled}
+      className={cn(toggleTrackVariants({ size, appearance }), className)}
+      onClick={() => {
+        if (!disabled) {
+          setChecked(!resolved);
+        }
+      }}
+      {...rest}
+    >
+      <span className="sr-only">{children}</span>
+      <motion.span
+        className={cn(
+          toggleThumbVariants({ size }),
+          "absolute left-1 top-1/2 -translate-y-1/2",
+        )}
+        animate={{ x: resolved ? thumbShiftPx : 0 }}
+        transition={thumbMotion.transition}
+        layout={thumbMotion.layout}
+      />
+    </button>
+  );
+}
+
+ToggleAnimated.displayName = "Toggle";

package/src/ui/toggle/animated/types.ts

@@ -0,0 +1,13 @@
+import type { HTMLMotionProps } from "framer-motion";
+import type { ToggleProps } from "../types";
+
+export type ToggleAnimation = "none" | "spring";
+
+export type ToggleThumbPreset = Pick<HTMLMotionProps<"span">, "transition" | "layout">;
+
+export type ToggleAnimationPresets = Record<ToggleAnimation, ToggleThumbPreset>;
+
+
+export type ToggleAnimatedProps = ToggleProps & {
+  animation?: ToggleAnimation;
+};

package/src/ui/toggle/index.ts

@@ -0,0 +1,5 @@
+"use client";
+
+export { Toggle } from "./toggle";
+export type { ToggleProps, ToggleTrackVariantProps, ToggleThumbVariantProps } from "./types";
+export { toggleThumbVariants, toggleTrackVariants } from "./variants";

package/src/ui/toggle/toggle-base.tsx

@@ -0,0 +1,70 @@
+"use client";
+
+import { useCallback, useState } from "react";
+
+import { cn } from "../../lib/utils";
+
+import type { ToggleProps } from "./types";
+import { toggleThumbVariants, toggleTrackVariants } from "./variants";
+
+export function ToggleBase(props: ToggleProps) {
+  const {
+    className,
+    size,
+    appearance,
+    checked,
+    defaultChecked = false,
+    onCheckedChange,
+    disabled,
+    ref,
+    "aria-label": ariaLabel = "Toggle",
+    children,
+    ...rest
+  } = props;
+  const isControlled = checked !== undefined;
+  const [uncontrolled, setUncontrolled] = useState(defaultChecked);
+  const resolved = isControlled ? Boolean(checked) : uncontrolled;
+
+  const setChecked = useCallback(
+    (next: boolean) => {
+      if (!isControlled) {
+        setUncontrolled(next);
+      }
+      onCheckedChange?.(next);
+    },
+    [isControlled, onCheckedChange],
+  );
+
+  const thumbShiftPx = size === "sm" ? 14 : size === "lg" ? 26 : 20;
+
+  return (
+    <button
+      ref={ref}
+      type="button"
+      role="switch"
+      data-slot="toggle"
+      aria-checked={resolved}
+      aria-label={ariaLabel}
+      data-state={resolved ? "checked" : "unchecked"}
+      disabled={disabled}
+      className={cn(toggleTrackVariants({ size, appearance }), className)}
+      onClick={() => {
+        if (!disabled) {
+          setChecked(!resolved);
+        }
+      }}
+      {...rest}
+    >
+      <span className="sr-only">{children}</span>
+      <span
+        className={cn(
+          toggleThumbVariants({ size }),
+          "absolute left-1 top-1/2 -translate-y-1/2 transition-[transform] duration-200 ease-out",
+        )}
+        style={{ transform: `translateX(${resolved ? thumbShiftPx : 0}px)` }}
+      />
+    </button>
+  );
+}
+
+ToggleBase.displayName = "Toggle";

package/src/ui/toggle/toggle.test.tsx

@@ -0,0 +1,44 @@
+import { createRef } from "react";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+
+import { Toggle } from "./toggle";
+
+describe("Toggle", () => {
+  it("should expose displayName", () => {
+    expect(Toggle.displayName).toBe("Toggle");
+  });
+
+  it("should stamp data-slot", () => {
+    render(<Toggle defaultChecked={false} />);
+    expect(document.querySelector('[data-slot="toggle"]')).toBeTruthy();
+  });
+
+  it("should use role switch", () => {
+    render(<Toggle aria-label="Notifications" />);
+    expect(
+      screen.getByRole("switch", { name: "Notifications" }),
+    ).toBeInTheDocument();
+  });
+
+  it("should call onCheckedChange when toggled", async () => {
+    const user = userEvent.setup();
+    const onCheckedChange = vi.fn();
+    render(
+      <Toggle
+        defaultChecked={false}
+        onCheckedChange={onCheckedChange}
+        aria-label="Airplane mode"
+      />,
+    );
+    await user.click(screen.getByRole("switch"));
+    expect(onCheckedChange).toHaveBeenLastCalledWith(true);
+  });
+
+  it("should forward ref", () => {
+    const ref = createRef<HTMLButtonElement>();
+    render(<Toggle ref={ref} defaultChecked aria-label="On" />);
+    expect(ref.current?.getAttribute("data-slot")).toBe("toggle");
+  });
+});

package/src/ui/toggle/toggle.tsx

@@ -0,0 +1,9 @@
+// toggle.tsx — default static entry (no framer-motion)
+import { ToggleBase } from "./toggle-base";
+import type { ToggleProps } from "./types";
+
+export function Toggle(props: ToggleProps) {
+  return <ToggleBase {...props} />;
+}
+
+Toggle.displayName = "Toggle";

package/src/ui/toggle/types.ts

@@ -0,0 +1,18 @@
+import type { VariantProps } from "class-variance-authority";
+import type { ButtonHTMLAttributes, ReactNode, Ref } from "react";
+
+import type { toggleThumbVariants, toggleTrackVariants } from "./variants";
+
+export type ToggleTrackVariantProps = VariantProps<typeof toggleTrackVariants>;
+export type ToggleThumbVariantProps = VariantProps<typeof toggleThumbVariants>;
+
+export type ToggleProps = ToggleTrackVariantProps &
+  ToggleThumbVariantProps &
+  Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type" | "role" | "ref"> & {
+    checked?: boolean;
+    defaultChecked?: boolean;
+    onCheckedChange?: (checked: boolean) => void;
+    "aria-label"?: string;
+    children?: ReactNode;
+    ref?: Ref<HTMLButtonElement>;
+  };

package/src/ui/toggle/variants.ts

@@ -0,0 +1,84 @@
+import { cva } from "class-variance-authority";
+
+export const toggleTrackVariants = cva(
+  "relative inline-flex shrink-0 cursor-pointer rounded-full border border-white/10 transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-slate-300 focus-visible:ring-offset-2 focus-visible:ring-offset-slate-950 data-[state=checked]:border-cyan-500/40 disabled:cursor-not-allowed disabled:opacity-50",
+  {
+    variants: {
+      size: {
+        sm: "h-5 w-9",
+        md: "h-6 w-11",
+        lg: "h-7 w-[3.25rem]",
+      },
+      appearance: {
+        default: "data-[state=checked]:bg-cyan-600/80",
+        success:
+          "data-[state=checked]:border-emerald-500/40 data-[state=checked]:bg-emerald-600/80",
+        destructive:
+          "data-[state=checked]:border-rose-500/40 data-[state=checked]:bg-rose-600/80",
+        neutral:
+          "data-[state=checked]:border-slate-400/40 data-[state=checked]:bg-slate-600/90",
+        indigo:
+          "data-[state=checked]:border-indigo-500/40 data-[state=checked]:bg-indigo-600/80",
+        purple:
+          "data-[state=checked]:border-purple-500/40 data-[state=checked]:bg-purple-600/80",
+        pink: "data-[state=checked]:border-pink-500/40 data-[state=checked]:bg-pink-600/80",
+        orange:
+          "data-[state=checked]:border-orange-500/40 data-[state=checked]:bg-orange-600/80",
+        yellow:
+          "data-[state=checked]:border-yellow-500/40 data-[state=checked]:bg-yellow-600/80",
+        green:
+          "data-[state=checked]:border-green-500/40 data-[state=checked]:bg-green-600/80",
+        teal: "data-[state=checked]:border-teal-500/40 data-[state=checked]:bg-teal-600/80",
+        cyan: "data-[state=checked]:border-cyan-500/40 data-[state=checked]:bg-cyan-600/80",
+        lime: "data-[state=checked]:border-lime-500/40 data-[state=checked]:bg-lime-600/80",
+        emerald:
+          "data-[state=checked]:border-emerald-500/40 data-[state=checked]:bg-emerald-600/80",
+        rose: "data-[state=checked]:border-rose-500/40 data-[state=checked]:bg-rose-600/80",
+        slate:
+          "data-[state=checked]:border-slate-400/40 data-[state=checked]:bg-slate-600/90",
+        zinc: "data-[state=checked]:border-zinc-400/40 data-[state=checked]:bg-zinc-600/90",
+        gray: "data-[state=checked]:border-gray-400/40 data-[state=checked]:bg-gray-600/90",
+        stone:
+          "data-[state=checked]:border-stone-400/40 data-[state=checked]:bg-stone-600/90",
+        "gradient-blue":
+          "data-[state=checked]:bg-linear-to-r from-blue-600 to-purple-600",
+        "gradient-green":
+          "data-[state=checked]:bg-linear-to-r from-green-600 to-lime-600",
+        "gradient-red":
+          "data-[state=checked]:bg-linear-to-r from-red-600 to-pink-600",
+        "gradient-yellow":
+          "data-[state=checked]:bg-linear-to-r from-yellow-600 to-orange-600",
+        "gradient-purple":
+          "data-[state=checked]:bg-linear-to-r from-purple-600 to-pink-600",
+        "gradient-teal":
+          "data-[state=checked]:bg-linear-to-r from-teal-600 to-cyan-600",
+        "gradient-indigo":
+          "data-[state=checked]:bg-linear-to-r from-indigo-600 to-purple-600",
+        "gradient-pink":
+          "data-[state=checked]:bg-linear-to-r from-pink-600 to-rose-600",
+        "gradient-orange":
+          "data-[state=checked]:bg-linear-to-r from-orange-600 to-red-600",
+      },
+    },
+    defaultVariants: {
+      size: "md",
+      appearance: "default",
+    },
+  },
+);
+
+export const toggleThumbVariants = cva(
+  "pointer-events-none block rounded-full bg-white shadow-[0_1px_2px_rgba(15,23,42,0.35)] ring-0",
+  {
+    variants: {
+      size: {
+        sm: "size-4",
+        md: "size-5",
+        lg: "size-6",
+      },
+    },
+    defaultVariants: {
+      size: "md",
+    },
+  },
+);

package/src/ui/tooltip/animated/animations.ts

@@ -0,0 +1,16 @@
+import type { TooltipAnimationPresets } from "./types";
+
+
+export const tooltipAnimationPresets: TooltipAnimationPresets = {
+  none: {},
+  fade: {
+    initial: { opacity: 0 },
+    animate: { opacity: 1 },
+    transition: { duration: 0.15, ease: "easeOut" },
+  },
+  scale: {
+    initial: { opacity: 0, scale: 0.96 },
+    animate: { opacity: 1, scale: 1 },
+    transition: { duration: 0.15, ease: "easeIn" },
+  },
+};

package/src/ui/tooltip/animated/index.ts

@@ -0,0 +1,10 @@
+"use client";
+
+export { TooltipContentAnimated } from "./tooltip-content-animated";
+export type {
+  TooltipContentAnimatedProps,
+  TooltipAnimation,
+  TooltipAnimationPresets,
+  TooltipPresetMotionProps,
+} from "./types";
+export { tooltipAnimationPresets } from "./animations";

package/src/ui/tooltip/animated/tooltip-content-animated.tsx

@@ -0,0 +1,47 @@
+"use client";
+
+import { motion } from "framer-motion";
+
+import { cn } from "../../../lib/utils";
+
+import { tooltipAnimationPresets } from "./animations";
+import type { TooltipContentAnimatedProps } from "./types";
+import { tooltipVariants } from "../variants";
+import { useTooltip } from "../tooltip-base";
+
+export const TooltipContentAnimated = ({
+  children,
+  className,
+  variant,
+  size,
+  width,
+  animation = "none",
+}: TooltipContentAnimatedProps) => {
+  const { open, position } = useTooltip();
+
+  if (!open) return null;
+
+  const positionStyles = {
+    top: "bottom-full mb-2",
+    bottom: "top-full mt-2",
+    left: "right-full top-1/2 -translate-y-1/2 mr-2",
+    right: "left-full top-1/2 -translate-y-1/2 ml-2",
+  };
+
+  const motionProps = tooltipAnimationPresets[animation];
+
+  return (
+    <motion.div
+      data-open={open}
+      role="tooltip"
+      {...motionProps}
+      className={cn(
+        tooltipVariants({ variant, size, width }),
+        positionStyles[position],
+        className,
+      )}
+    >
+      {children}
+    </motion.div>
+  );
+};

package/src/ui/tooltip/animated/types.ts

@@ -0,0 +1,19 @@
+import { HTMLMotionProps } from "framer-motion";
+import type { TooltipContentProps } from "../types";
+
+export type TooltipAnimation = "none" | "fade" | "scale";
+
+export type TooltipPresetMotionProps = Pick<
+  HTMLMotionProps<"div">,
+  "initial" | "animate" | "style" | "transition"
+>;
+
+export type TooltipAnimationPresets = Record<
+  TooltipAnimation,
+  TooltipPresetMotionProps
+>;
+
+
+export type TooltipContentAnimatedProps = TooltipContentProps & {
+  animation?: TooltipAnimation;
+};

package/src/ui/tooltip/index.ts

@@ -0,0 +1,17 @@
+"use client";
+
+export {
+  Tooltip,
+  TooltipTrigger,
+  TooltipContent,
+  TooltipContext,
+  useTooltip,
+} from "./tooltip";
+export type {
+  TooltipProps,
+  TooltipTriggerProps,
+  TooltipContentProps,
+  TooltipContextType,
+  TooltipPosition,
+} from "./types";
+export { tooltipVariants } from "./variants";

package/src/ui/tooltip/tooltip-base.tsx

@@ -0,0 +1,152 @@
+"use client";
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
+
+import { cn } from "../../lib/utils";
+
+import type {
+  TooltipProps,
+  TooltipContextType,
+  TooltipTriggerProps,
+  TooltipContentProps,
+} from "./types";
+import { tooltipVariants } from "./variants";
+
+export const TooltipContext = createContext<TooltipContextType | null>(null);
+
+export const useTooltip = () => {
+  const context = useContext(TooltipContext);
+  if (!context) {
+    throw new Error("Tooltip components must be used within Tooltip");
+  }
+  return context;
+};
+
+export const Tooltip = ({
+  children,
+  defaultOpen = false,
+  open: controlledOpen,
+  onOpenChange,
+  position = "top",
+  delay = 100,
+}: TooltipProps) => {
+  const [uncontrolledOpen, setUncontrolledOpen] = useState(defaultOpen);
+
+  const isControlled = controlledOpen !== undefined;
+  const open = isControlled ? controlledOpen : uncontrolledOpen;
+
+  const setOpen = useCallback(
+    (value: boolean) => {
+      if (!isControlled) setUncontrolledOpen(value);
+      onOpenChange?.(value);
+    },
+    [isControlled, onOpenChange],
+  );
+
+  const showTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const cancelDelayedOpen = useCallback(() => {
+    if (showTimeoutRef.current !== null) {
+      clearTimeout(showTimeoutRef.current);
+      showTimeoutRef.current = null;
+    }
+  }, []);
+
+  const scheduleDelayedOpen = useCallback(() => {
+    cancelDelayedOpen();
+    showTimeoutRef.current = setTimeout(() => {
+      showTimeoutRef.current = null;
+      setOpen(true);
+    }, delay);
+  }, [cancelDelayedOpen, delay, setOpen]);
+
+  useEffect(() => () => cancelDelayedOpen(), [cancelDelayedOpen]);
+
+  return (
+    <TooltipContext.Provider
+      value={{
+        open,
+        setOpen,
+        position,
+        delay,
+        scheduleDelayedOpen,
+        cancelDelayedOpen,
+      }}
+    >
+      <div className="relative inline-block">{children}</div>
+    </TooltipContext.Provider>
+  );
+};
+
+export const TooltipTrigger = ({
+  children,
+  className,
+}: TooltipTriggerProps) => {
+  const { setOpen, scheduleDelayedOpen, cancelDelayedOpen } = useTooltip();
+
+  const triggerProps = {
+    onMouseEnter: () => scheduleDelayedOpen(),
+    onMouseLeave: () => {
+      cancelDelayedOpen();
+      setOpen(false);
+    },
+    onFocus: () => {
+      cancelDelayedOpen();
+      setOpen(true);
+    },
+    onBlur: () => {
+      cancelDelayedOpen();
+      setOpen(false);
+    },
+    onKeyDown: (e: React.KeyboardEvent) => {
+      if (e.key === "Escape") {
+        cancelDelayedOpen();
+        setOpen(false);
+      }
+    },
+    className,
+    tabIndex: 0,
+  };
+
+  return <span {...triggerProps}>{children}</span>;
+};
+
+export const TooltipContent = ({
+  children,
+  className,
+  variant,
+  size,
+  width,
+}: TooltipContentProps) => {
+  const { open, position } = useTooltip();
+
+  if (!open) return null;
+
+  const positionStyles = {
+    top: "bottom-full mb-2",
+    bottom: "top-full mt-2",
+    left: "right-full top-1/2 -translate-y-1/2 mr-2",
+    right: "left-full top-1/2 -translate-y-1/2 ml-2",
+  };
+
+  return (
+    <div
+      data-open={open}
+      role="tooltip"
+      className={cn(
+        tooltipVariants({ variant, size, width }),
+        positionStyles[position],
+        className,
+      )}
+    >
+      {children}
+    </div>
+  );
+};

package/src/ui/tooltip/tooltip.test.tsx

@@ -0,0 +1,84 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it } from "vitest";
+
+import { Tooltip, TooltipContent, TooltipTrigger } from "./tooltip";
+
+describe("Tooltip", () => {
+  it("should show tooltip content after pointer hover with zero delay", async () => {
+    const user = userEvent.setup();
+    render(
+      <Tooltip delay={0}>
+        <TooltipTrigger>
+          <button type="button">Target</button>
+        </TooltipTrigger>
+        <TooltipContent>Helpful hint</TooltipContent>
+      </Tooltip>,
+    );
+    await user.hover(screen.getByRole("button", { name: "Target" }));
+    expect(await screen.findByRole("tooltip")).toHaveTextContent(
+      "Helpful hint",
+    );
+  });
+
+  it("should hide tooltip content when pointer leaves the trigger", async () => {
+    const user = userEvent.setup();
+    render(
+      <Tooltip delay={0}>
+        <TooltipTrigger>
+          <button type="button">Target</button>
+        </TooltipTrigger>
+        <TooltipContent>Hint</TooltipContent>
+      </Tooltip>,
+    );
+    const trigger = screen.getByRole("button", { name: "Target" });
+    await user.hover(trigger);
+    expect(await screen.findByRole("tooltip")).toBeInTheDocument();
+    await user.unhover(trigger);
+    await waitFor(() => {
+      expect(screen.queryByRole("tooltip")).not.toBeInTheDocument();
+    });
+  });
+
+  it("should open on focus and close on blur", async () => {
+    const user = userEvent.setup();
+    render(
+      <Tooltip delay={0}>
+        <TooltipTrigger>
+          <button type="button">Focus me</button>
+        </TooltipTrigger>
+        <TooltipContent>Keyboard tip</TooltipContent>
+      </Tooltip>,
+    );
+    const trigger = screen.getByRole("button", { name: "Focus me" });
+    await user.click(trigger);
+    expect(await screen.findByRole("tooltip")).toHaveTextContent(
+      "Keyboard tip",
+    );
+    await user.tab();
+    await waitFor(() => {
+      expect(screen.queryByRole("tooltip")).not.toBeInTheDocument();
+    });
+  });
+
+  it("should close on Escape while the trigger is focused", async () => {
+    const user = userEvent.setup();
+    render(
+      <Tooltip delay={0}>
+        <TooltipTrigger>
+          <button type="button">Trap</button>
+        </TooltipTrigger>
+        <TooltipContent>Press Esc</TooltipContent>
+      </Tooltip>,
+    );
+    const trigger = screen.getByRole("button", { name: "Trap" });
+    trigger.focus();
+    await waitFor(() => {
+      expect(screen.getByRole("tooltip")).toBeInTheDocument();
+    });
+    await user.keyboard("{Escape}");
+    await waitFor(() => {
+      expect(screen.queryByRole("tooltip")).not.toBeInTheDocument();
+    });
+  });
+});

package/src/ui/tooltip/tooltip.tsx

@@ -0,0 +1,8 @@
+// tooltip.tsx — default static entry (no framer-motion)
+export {
+  Tooltip,
+  TooltipTrigger,
+  TooltipContent,
+  TooltipContext,
+  useTooltip,
+} from "./tooltip-base";