@zentauri-ui/zentauri-components 1.7.9 → 1.8.1

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

@@ -0,0 +1,120 @@
+"use client";
+import { animate, motion, useInView, useReducedMotion, type UseInViewOptions } from "framer-motion";
+import { animatedNumberAppearance } from "./variants";
+import { AnimatedNumberCounterProps, AnimatedNumberProps } from "./types";
+import { cn } from "../../lib/utils";
+import { zuiAnimatedNumberBase } from "../../design-system/animated-number";
+import { animationFinalType, animationInitialType } from "./animations";
+import { useEffect, useRef, useState } from "react";
+
+const DEFAULT_VIEWPORT = { once: true, amount: 0.2 } as const;
+
+export const AnimatedNumber = ({
+  number,
+  wrapperClassName,
+  className,
+  ref,
+  appearance,
+  size,
+  type = "up",
+  delayInSecond = 0.1,
+  transition,
+  initial,
+  whileInView,
+  viewport,
+  ...rest
+}: AnimatedNumberProps) => {
+  const numbersList = [...number.toString()];
+  const reducedMotion = useReducedMotion();
+  const motionless = Boolean(reducedMotion);
+
+  const digitVariants = {
+    hidden: animationInitialType[type],
+    visible: animationFinalType[type],
+  };
+
+  return (
+    <motion.div
+      ref={ref}
+      initial={motionless ? false : "hidden"}
+      whileInView={motionless ? undefined : "visible"}
+      viewport={viewport ?? DEFAULT_VIEWPORT}
+      transition={{
+        staggerChildren: delayInSecond,
+      }}
+      className={cn(wrapperClassName, zuiAnimatedNumberBase)}
+    >
+      {numbersList.map((digit, index) => (
+        <motion.span
+          key={index + "-" + digit}
+          className={cn(
+            "inline-block",
+            animatedNumberAppearance({ appearance, size }),
+            className,
+          )}
+          variants={digitVariants}
+          transition={transition}
+          {...rest}
+        >
+          {digit}
+        </motion.span>
+      ))}
+    </motion.div>
+  );
+};
+
+export const AnimatedNumberCounter = ({
+  number,
+  className,
+  ref: externalRef,
+  appearance,
+  size,
+  duration = 2,
+  viewport,
+  ...rest
+}: AnimatedNumberCounterProps) => {
+  const [currentNumber, setCurrentNumber] = useState(0);
+  const reducedMotion = useReducedMotion();
+  const internalRef = useRef<HTMLParagraphElement>(null);
+  // once: false gives real two-way tracking so isInView flips false when scrolled away,
+  // preventing offscreen animations when the number prop changes later.
+  const isInView = useInView(internalRef, {
+    once: false,
+    amount: 0.2,
+    ...viewport,
+  } as UseInViewOptions);
+
+  useEffect(() => {
+    if (!isInView) return;
+
+    if (reducedMotion) {
+      setCurrentNumber(number);
+      return;
+    }
+
+    const controls = animate(currentNumber, number, {
+      duration,
+      ease: "circOut",
+      onUpdate: (latest) => setCurrentNumber(Math.round(latest)),
+    });
+
+    return () => controls.stop();
+    // currentNumber intentionally omitted — captured value gives smooth from→to on prop changes
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [isInView, number, duration, reducedMotion]);
+
+  return (
+    <motion.p
+      className={cn(animatedNumberAppearance({ appearance, size }), className)}
+      ref={(node: HTMLParagraphElement) => {
+        internalRef.current = node;
+        if (externalRef) {
+          externalRef.current = node;
+        }
+      }}
+      {...rest}
+    >
+      {currentNumber}
+    </motion.p>
+  );
+};

package/src/ui/animated-number/animations.ts

@@ -0,0 +1,22 @@
+export const animationInitialType = {
+  up: { y: "-100%" },
+  down: { y: "100%" },
+  scaleUp: { scale: 0 },
+  scaleDown: { scale: 1.25 },
+  rotateX: { rotateX: "0" },
+  rotateY: { rotateY: "0" },
+  skewX: { skewX: 20 },
+  skewY: { skewY: 20 },
+  fade: { opacity: 0 },
+};
+export const animationFinalType = {
+  up: { y: 0 },
+  down: { y: 0 },
+  scaleUp: { scale: 1 },
+  scaleDown: { scale: 1 },
+  rotateX: { rotateX: "360deg" },
+  rotateY: { rotateY: "360deg" },
+  skewX: { skewX: 0 },
+  skewY: { skewY: 0 },
+  fade: { opacity: 1 },
+};

package/src/ui/animated-number/index.ts

@@ -0,0 +1,4 @@
+"use client";
+export { AnimatedNumber, AnimatedNumberCounter } from "./animated-number";
+export type { AnimatedNumberProps, AnimatedNumberCounterProps } from "./types";
+export { animatedNumberAppearance } from "./variants";

package/src/ui/animated-number/types.ts

@@ -0,0 +1,39 @@
+import { VariantProps } from "class-variance-authority";
+import { MotionProps } from "framer-motion";
+import { RefObject } from "react";
+import { animatedNumberAppearance } from "./variants";
+
+type MotionTransitionWithoutDelay = Omit<
+  NonNullable<MotionProps["transition"]>,
+  "delay"
+> & {
+  delay?: never;
+};
+
+export type MotionPropsWithoutTransitionDelay = Omit<
+  MotionProps,
+  "transition"
+> & {
+  transition?: MotionTransitionWithoutDelay;
+};
+
+export type AnimatedNumberProps = MotionPropsWithoutTransitionDelay & {
+  number: number;
+  wrapperClassName?: string;
+  className?: string;
+  ref?: RefObject<HTMLDivElement>;
+  appearance?: VariantProps<typeof animatedNumberAppearance>["appearance"];
+  size?: VariantProps<typeof animatedNumberAppearance>["size"];
+  type?: "up" | "down" | "scaleUp" | "scaleDown" | "rotateX" | "rotateY" | "skewX" | "skewY" | "fade";
+  delayInSecond?: number;
+  transition?: MotionProps["transition"];
+};
+
+export type AnimatedNumberCounterProps = MotionProps & {
+  number: number;
+  className?: string;
+  ref?: RefObject<HTMLParagraphElement>;
+  appearance?: VariantProps<typeof animatedNumberAppearance>["appearance"];
+  size?: VariantProps<typeof animatedNumberAppearance>["size"];
+  duration?: number;
+};

package/src/ui/animated-number/variants.ts

@@ -0,0 +1,14 @@
+import { cva } from "class-variance-authority";
+
+import { zuiAnimatedNumberAppearance, zuiAnimatedNumberSize } from "../../design-system/animated-number";
+
+export const animatedNumberAppearance = cva("inline-flex",{
+  variants: {
+    appearance: zuiAnimatedNumberAppearance,
+    size: zuiAnimatedNumberSize
+  },
+  defaultVariants: {
+    appearance: "default",
+    size: "md",
+  },
+});

package/src/ui/copy-button/animated/animations.ts

@@ -0,0 +1,22 @@
+import type { CopyButtonAnimationPresets } from "./types";
+
+export const copyButtonAnimationPresets: CopyButtonAnimationPresets = {
+  swap: {
+    initial: { opacity: 0, scale: 0.6, rotate: -45 },
+    animate: { opacity: 1, scale: 1, rotate: 0 },
+    exit: { opacity: 0, scale: 0.6, rotate: 45 },
+    transition: { type: "spring", stiffness: 520, damping: 24 },
+  },
+  pop: {
+    initial: { opacity: 0, scale: 0.4, rotate: 0 },
+    animate: { opacity: 1, scale: 1, rotate: 0 },
+    exit: { opacity: 0, scale: 0.4, rotate: 0 },
+    transition: { type: "spring", stiffness: 600, damping: 20 },
+  },
+  fade: {
+    initial: { opacity: 0, scale: 1, rotate: 0 },
+    animate: { opacity: 1, scale: 1, rotate: 0 },
+    exit: { opacity: 0, scale: 1, rotate: 0 },
+    transition: { duration: 0.16 },
+  },
+};

package/src/ui/copy-button/animated/copy-button-animated.tsx

@@ -0,0 +1,39 @@
+"use client";
+
+import { AnimatePresence, motion } from "framer-motion";
+
+import { CopyButtonBase } from "../copy-button-base";
+import type { CopyButtonIconRenderer } from "../types";
+
+import { copyButtonAnimationPresets } from "./animations";
+import type { CopyButtonAnimatedProps } from "./types";
+
+export function CopyButtonAnimated({
+  animation = "swap",
+  ...props
+}: CopyButtonAnimatedProps) {
+  const preset = copyButtonAnimationPresets[animation];
+
+  const renderIcon: CopyButtonIconRenderer = ({
+    copied,
+    copyIcon,
+    copiedIcon,
+  }) => (
+    <AnimatePresence initial={false} mode="wait">
+      <motion.span
+        key={copied ? "copied" : "idle"}
+        className="inline-flex items-center justify-center"
+        initial={preset.initial}
+        animate={preset.animate}
+        exit={preset.exit}
+        transition={preset.transition}
+      >
+        {copied ? copiedIcon : copyIcon}
+      </motion.span>
+    </AnimatePresence>
+  );
+
+  return <CopyButtonBase {...props} renderIcon={renderIcon} />;
+}
+
+CopyButtonAnimated.displayName = "CopyButtonAnimated";

package/src/ui/copy-button/animated/index.ts

@@ -0,0 +1,10 @@
+"use client";
+
+export { CopyButtonAnimated } from "./copy-button-animated";
+export { copyButtonAnimationPresets } from "./animations";
+export type {
+  CopyButtonAnimatedProps,
+  CopyButtonAnimation,
+  CopyButtonAnimationPreset,
+  CopyButtonAnimationPresets,
+} from "./types";

package/src/ui/copy-button/animated/types.ts

@@ -0,0 +1,21 @@
+import type { Transition } from "framer-motion";
+
+import type { CopyButtonProps } from "../types";
+
+export type CopyButtonAnimation = "swap" | "pop" | "fade";
+
+export type CopyButtonAnimatedProps = CopyButtonProps & {
+  animation?: CopyButtonAnimation;
+};
+
+export type CopyButtonAnimationPreset = {
+  initial: { opacity: number; scale: number; rotate: number };
+  animate: { opacity: number; scale: number; rotate: number };
+  exit: { opacity: number; scale: number; rotate: number };
+  transition: Transition;
+};
+
+export type CopyButtonAnimationPresets = Record<
+  CopyButtonAnimation,
+  CopyButtonAnimationPreset
+>;

package/src/ui/copy-button/copy-button-base.tsx

@@ -0,0 +1,88 @@
+"use client";
+
+import { FiCheck, FiCopy } from "react-icons/fi";
+
+import { useClipboard } from "../../hooks/useClipboard/useClipboard";
+import { cn } from "../../lib/utils";
+
+import type { CopyButtonBaseProps, CopyButtonIconRenderer } from "./types";
+import { copyButtonVariants } from "./variants";
+
+const defaultRenderIcon: CopyButtonIconRenderer = ({
+  copied,
+  copyIcon,
+  copiedIcon,
+}) => (copied ? copiedIcon : copyIcon);
+
+export function CopyButtonBase({
+  value,
+  timeout = 2000,
+  appearance,
+  size,
+  iconOnly = true,
+  label = "Copy",
+  copiedLabel = "Copied",
+  copyIcon = <FiCopy aria-hidden />,
+  copiedIcon = <FiCheck aria-hidden />,
+  onCopy,
+  renderIcon = defaultRenderIcon,
+  className,
+  type = "button",
+  disabled,
+  onClick,
+  "aria-label": ariaLabel,
+  ref,
+  ...rest
+}: CopyButtonBaseProps) {
+  const { copied, copy } = useClipboard(timeout);
+
+  const handleClick: NonNullable<CopyButtonBaseProps["onClick"]> = async (
+    event,
+  ) => {
+    onClick?.(event);
+    if (event.defaultPrevented) {
+      return;
+    }
+    const ok = await copy(value);
+    if (ok) {
+      onCopy?.(value);
+    }
+  };
+
+  const text = copied ? copiedLabel : label;
+
+  return (
+    <button
+      ref={ref}
+      type={type}
+      data-slot="copy-button"
+      data-copied={copied ? "true" : undefined}
+      disabled={disabled}
+      aria-label={ariaLabel ?? (iconOnly ? text : undefined)}
+      onClick={handleClick}
+      className={cn(
+        copyButtonVariants({ appearance, size, iconOnly }),
+        className,
+      )}
+      {...rest}
+    >
+      <span
+        data-slot="copy-button-icon"
+        className="relative inline-flex items-center justify-center"
+      >
+        {renderIcon({ copied, copyIcon, copiedIcon })}
+      </span>
+      {!iconOnly ? (
+        <span data-slot="copy-button-label" aria-live="polite">
+          {text}
+        </span>
+      ) : (
+        <span className="sr-only" aria-live="polite">
+          {text}
+        </span>
+      )}
+    </button>
+  );
+}
+
+CopyButtonBase.displayName = "CopyButton";

package/src/ui/copy-button/copy-button.test.tsx

@@ -0,0 +1,82 @@
+import { createRef } from "react";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { CopyButton } from "./copy-button";
+
+describe("CopyButton", () => {
+  const originalClipboard = navigator.clipboard;
+
+  beforeEach(() => {
+    Object.defineProperty(navigator, "clipboard", {
+      configurable: true,
+      writable: true,
+      value: { writeText: vi.fn().mockResolvedValue(undefined) },
+    });
+  });
+
+  afterEach(() => {
+    Object.defineProperty(navigator, "clipboard", {
+      configurable: true,
+      writable: true,
+      value: originalClipboard,
+    });
+  });
+
+  it("should expose displayName", () => {
+    expect(CopyButton.displayName).toBe("CopyButton");
+  });
+
+  it("should stamp data-slot", () => {
+    render(<CopyButton value="npm i zentauri" />);
+    expect(
+      document.querySelector('[data-slot="copy-button"]'),
+    ).toBeInTheDocument();
+  });
+
+  it("should write the value to the clipboard on click", async () => {
+    render(<CopyButton value="copy me" />);
+    fireEvent.click(screen.getByRole("button"));
+    await waitFor(() =>
+      expect(navigator.clipboard.writeText).toHaveBeenCalledWith("copy me"),
+    );
+  });
+
+  it("should call onCopy after a successful copy", async () => {
+    const user = userEvent.setup();
+    const onCopy = vi.fn();
+    render(<CopyButton value="token-123" onCopy={onCopy} />);
+    await user.click(screen.getByRole("button"));
+    await waitFor(() => expect(onCopy).toHaveBeenCalledWith("token-123"));
+  });
+
+  it("should flip to the copied state and mark data-copied", async () => {
+    const user = userEvent.setup();
+    render(<CopyButton value="x" timeout={0} copiedLabel="Copied!" />);
+    const button = screen.getByRole("button");
+    await user.click(button);
+    await waitFor(() =>
+      expect(button.getAttribute("data-copied")).toBe("true"),
+    );
+  });
+
+  it("should render the label when iconOnly is false", () => {
+    render(<CopyButton value="x" iconOnly={false} label="Copy code" />);
+    expect(screen.getByText("Copy code")).toBeInTheDocument();
+  });
+
+  it("should apply the secondary appearance token", () => {
+    render(<CopyButton value="x" appearance="secondary" />);
+    const button = document.querySelector(
+      '[data-slot="copy-button"]',
+    ) as HTMLElement;
+    expect(button.className).toMatch(/--zui-copy-button-secondary-bg/);
+  });
+
+  it("should forward ref", () => {
+    const ref = createRef<HTMLButtonElement>();
+    render(<CopyButton ref={ref} value="x" />);
+    expect(ref.current?.getAttribute("data-slot")).toBe("copy-button");
+  });
+});

package/src/ui/copy-button/copy-button.tsx

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

package/src/ui/copy-button/index.ts

@@ -0,0 +1,10 @@
+"use client";
+
+export { CopyButton } from "./copy-button";
+export type {
+  CopyButtonBaseProps,
+  CopyButtonIconRenderer,
+  CopyButtonProps,
+  CopyButtonVariantProps,
+} from "./types";
+export { copyButtonVariants } from "./variants";

package/src/ui/copy-button/types.ts

@@ -0,0 +1,37 @@
+import type { VariantProps } from "class-variance-authority";
+import type { ComponentPropsWithRef, ReactNode } from "react";
+
+import type { copyButtonVariants } from "./variants";
+
+export type CopyButtonVariantProps = VariantProps<typeof copyButtonVariants>;
+
+/** Renders the icon region for a given copied state. Lets the animated entry swap the static icons for motion ones. */
+export type CopyButtonIconRenderer = (state: {
+  copied: boolean;
+  copyIcon: ReactNode;
+  copiedIcon: ReactNode;
+}) => ReactNode;
+
+export interface CopyButtonBaseProps
+  extends Omit<ComponentPropsWithRef<"button">, "value" | "onCopy"> {
+  /** Text written to the clipboard when the button is pressed. */
+  value: string;
+  /** Milliseconds the copied state stays active before resetting. `0` keeps it until re-copied. */
+  timeout?: number;
+  appearance?: CopyButtonVariantProps["appearance"];
+  size?: CopyButtonVariantProps["size"];
+  /** Render only the icon (default). Pass `false` to show the label text alongside the icon. */
+  iconOnly?: boolean;
+  /** Label shown (and used for `aria-label`) in the idle state. */
+  label?: string;
+  /** Label shown (and used for `aria-label`) after a successful copy. */
+  copiedLabel?: string;
+  copyIcon?: ReactNode;
+  copiedIcon?: ReactNode;
+  /** Called with `value` after the clipboard write succeeds. */
+  onCopy?: (value: string) => void;
+  /** Overrides how the icon region renders; the animated entry uses this for motion. */
+  renderIcon?: CopyButtonIconRenderer;
+}
+
+export type CopyButtonProps = Omit<CopyButtonBaseProps, "renderIcon">;

package/src/ui/copy-button/variants.ts

@@ -0,0 +1,29 @@
+import { cva } from "class-variance-authority";
+
+import {
+  zuiCopyButtonAppearances,
+  zuiCopyButtonBase,
+  zuiCopyButtonIconOnlySizes,
+  zuiCopyButtonSizes,
+} from "../../design-system/copy-button";
+
+export const copyButtonVariants = cva(zuiCopyButtonBase, {
+  variants: {
+    appearance: zuiCopyButtonAppearances,
+    size: zuiCopyButtonSizes,
+    iconOnly: {
+      true: "",
+      false: "",
+    },
+  },
+  compoundVariants: [
+    { iconOnly: true, size: "sm", class: zuiCopyButtonIconOnlySizes.sm },
+    { iconOnly: true, size: "md", class: zuiCopyButtonIconOnlySizes.md },
+    { iconOnly: true, size: "lg", class: zuiCopyButtonIconOnlySizes.lg },
+  ],
+  defaultVariants: {
+    appearance: "default",
+    size: "md",
+    iconOnly: true,
+  },
+});

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

@@ -0,0 +1,15 @@
+import type { KbdAnimationPresets } from "./types";
+
+export const kbdAnimationPresets: KbdAnimationPresets = {
+  none: {},
+  press: {
+    whileHover: { y: -1 },
+    whileTap: { y: 1, scale: 0.96 },
+    transition: { type: "spring", stiffness: 600, damping: 22 },
+  },
+  pop: {
+    initial: { scale: 0.85, opacity: 0 },
+    animate: { scale: 1, opacity: 1 },
+    transition: { type: "spring", stiffness: 520, damping: 26 },
+  },
+};

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

@@ -0,0 +1,9 @@
+"use client";
+
+export { KbdAnimated } from "./kbd-animated";
+export { kbdAnimationPresets } from "./animations";
+export type {
+  KbdAnimatedProps,
+  KbdAnimation,
+  KbdAnimationPresets,
+} from "./types";

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

@@ -0,0 +1,26 @@
+"use client";
+
+import { motion } from "framer-motion";
+
+import { KbdBase } from "../kbd-base";
+import type { KbdBaseProps } from "../types";
+
+import { kbdAnimationPresets } from "./animations";
+import type { KbdAnimatedProps } from "./types";
+
+export function KbdAnimated({ animation = "none", ...props }: KbdAnimatedProps) {
+  const motionProps = kbdAnimationPresets[animation];
+
+  return (
+    <KbdBase
+      {...({
+        as: motion.span,
+        initial: animation === "none" ? false : undefined,
+        ...motionProps,
+        ...props,
+      } as KbdBaseProps)}
+    />
+  );
+}
+
+KbdAnimated.displayName = "KbdAnimated";

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

@@ -0,0 +1,16 @@
+import type { HTMLMotionProps } from "framer-motion";
+
+import type { KbdBaseProps } from "../types";
+
+export type KbdAnimation = "none" | "press" | "pop";
+
+export type KbdAnimatedProps = Omit<KbdBaseProps, "as"> & {
+  animation?: KbdAnimation;
+};
+
+type KbdPresetMotionProps = Pick<
+  HTMLMotionProps<"span">,
+  "transition" | "whileHover" | "whileTap" | "animate" | "initial"
+>;
+
+export type KbdAnimationPresets = Record<KbdAnimation, KbdPresetMotionProps>;

package/src/ui/kbd/index.ts

@@ -0,0 +1,5 @@
+"use client";
+
+export { Kbd } from "./kbd";
+export type { KbdBaseProps, KbdProps, KbdVariantProps } from "./types";
+export { kbdKeyVariants, kbdSeparatorVariants } from "./variants";