@zentauri-ui/zentauri-components 1.8.0 → 1.8.2

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/divider/divider.test.tsx

@@ -0,0 +1,55 @@
+import { createRef } from "react";
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { Divider } from "./divider";
+
+const DIVIDER_SLOT = '[data-slot="divider"]';
+
+function getDividerRoot(container: HTMLElement = document.body) {
+  const elements = container.querySelectorAll(DIVIDER_SLOT);
+  expect(elements.length).toBe(1);
+  return elements[0] as HTMLElement;
+}
+
+describe("Divider", () => {
+  it("should expose a stable displayName", () => {
+    expect(Divider.displayName).toBe("Divider");
+  });
+
+  it("should render a horizontal separator by default", () => {
+    render(<Divider />);
+    const root = screen.getByRole("separator");
+    expect(root).toHaveAttribute("data-slot", "divider");
+    expect(root).toHaveAttribute("aria-orientation", "horizontal");
+  });
+
+  it("should render a vertical separator when requested", () => {
+    render(<Divider orientation="vertical" />);
+    expect(screen.getByRole("separator")).toHaveAttribute(
+      "aria-orientation",
+      "vertical",
+    );
+  });
+
+  it("should render label content between two divider lines", () => {
+    render(<Divider label="Or continue with" />);
+    expect(screen.getByText("Or continue with")).toHaveAttribute(
+      "data-slot",
+      "divider-label",
+    );
+    expect(document.querySelectorAll("[aria-hidden]").length).toBe(2);
+  });
+
+  it("should apply appearance token classes", () => {
+    render(<Divider appearance="emerald" />);
+    expect(getDividerRoot().className).toMatch(/--zui-divider-emerald-fg/);
+  });
+
+  it("should forward refs to the separator element", () => {
+    const ref = createRef<HTMLDivElement>();
+    render(<Divider ref={ref} />);
+    expect(ref.current).toBeInstanceOf(HTMLElement);
+    expect(ref.current?.getAttribute("data-slot")).toBe("divider");
+  });
+});

package/src/ui/empty-state/empty-state.test.tsx

@@ -0,0 +1,88 @@
+import { createRef } from "react";
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { EmptyState } from "./empty-state";
+import {
+  EmptyStateAction,
+  EmptyStateDescription,
+  EmptyStateIcon,
+  EmptyStateTitle,
+} from "./empty-state-base";
+
+const EMPTY_STATE_SLOT = '[data-slot="empty-state"]';
+
+function getEmptyStateRoot(container: HTMLElement = document.body) {
+  const elements = container.querySelectorAll(EMPTY_STATE_SLOT);
+  expect(elements.length).toBe(1);
+  return elements[0] as HTMLElement;
+}
+
+describe("EmptyState", () => {
+  it("should set displayName on compound parts", () => {
+    expect(EmptyState.displayName).toBe("EmptyState");
+    expect(EmptyStateIcon.displayName).toBe("EmptyStateIcon");
+    expect(EmptyStateTitle.displayName).toBe("EmptyStateTitle");
+    expect(EmptyStateDescription.displayName).toBe("EmptyStateDescription");
+    expect(EmptyStateAction.displayName).toBe("EmptyStateAction");
+  });
+
+  it("should stamp data-slot on the root section", () => {
+    render(<EmptyState>Nothing here</EmptyState>);
+    const root = getEmptyStateRoot();
+    expect(root.tagName).toBe("SECTION");
+    expect(root).toHaveAttribute("data-slot", "empty-state");
+  });
+
+  it("should render title, description, icon, and action slots", () => {
+    render(
+      <EmptyState>
+        <EmptyStateIcon>!</EmptyStateIcon>
+        <EmptyStateTitle>No results</EmptyStateTitle>
+        <EmptyStateDescription>Try another filter.</EmptyStateDescription>
+        <EmptyStateAction>
+          <button type="button">Reset</button>
+        </EmptyStateAction>
+      </EmptyState>,
+    );
+
+    expect(
+      screen.getByRole("heading", { level: 2, name: "No results" }),
+    ).toHaveAttribute("data-slot", "empty-state-title");
+    expect(screen.getByText("Try another filter.")).toHaveAttribute(
+      "data-slot",
+      "empty-state-description",
+    );
+    expect(screen.getByText("!")).toHaveAttribute(
+      "data-slot",
+      "empty-state-icon",
+    );
+    expect(screen.getByRole("button", { name: "Reset" })).toBeVisible();
+  });
+
+  it("should apply live region state when requested", () => {
+    render(<EmptyState liveRegion="assertive">Updated</EmptyState>);
+    expect(getEmptyStateRoot()).toHaveAttribute("aria-live", "assertive");
+  });
+
+  it("should apply size classes to nested text slots through context", () => {
+    render(
+      <EmptyState size="lg">
+        <EmptyStateTitle>Large title</EmptyStateTitle>
+        <EmptyStateDescription>Large description</EmptyStateDescription>
+      </EmptyState>,
+    );
+
+    expect(screen.getByText("Large title").className).toMatch(/text-xl/);
+    expect(screen.getByText("Large description").className).toMatch(
+      /text-base/,
+    );
+  });
+
+  it("should forward refs to the root element", () => {
+    const ref = createRef<HTMLElement>();
+    render(<EmptyState ref={ref}>Empty</EmptyState>);
+    expect(ref.current).toBeInstanceOf(HTMLElement);
+    expect(ref.current?.getAttribute("data-slot")).toBe("empty-state");
+  });
+});

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";

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

@@ -0,0 +1,50 @@
+"use client";
+
+import { Fragment } from "react";
+
+import { zuiKbdBase } from "../../design-system/kbd";
+import { cn } from "../../lib/utils";
+
+import type { KbdBaseProps } from "./types";
+import { kbdKeyVariants, kbdSeparatorVariants } from "./variants";
+
+export function KbdBase({
+  keys,
+  separator,
+  appearance,
+  size,
+  children,
+  className,
+  as: Wrapper = "span",
+  ref,
+  ...rest
+}: KbdBaseProps) {
+  const items = keys ?? (children != null ? [children] : []);
+
+  return (
+    <Wrapper
+      ref={ref}
+      data-slot="kbd"
+      className={cn(zuiKbdBase, className)}
+      {...rest}
+    >
+      {items.map((key, index) => (
+        <Fragment key={index}>
+          {index > 0 && separator != null ? (
+            <span data-slot="kbd-separator" className={kbdSeparatorVariants({ size })}>
+              {separator}
+            </span>
+          ) : null}
+          <kbd
+            data-slot="kbd-key"
+            className={kbdKeyVariants({ appearance, size })}
+          >
+            {key}
+          </kbd>
+        </Fragment>
+      ))}
+    </Wrapper>
+  );
+}
+
+KbdBase.displayName = "Kbd";

package/src/ui/kbd/kbd.test.tsx

@@ -0,0 +1,48 @@
+import { createRef } from "react";
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { Kbd } from "./kbd";
+
+describe("Kbd", () => {
+  it("should expose displayName", () => {
+    expect(Kbd.displayName).toBe("Kbd");
+  });
+
+  it("should stamp data-slot on the wrapper", () => {
+    render(<Kbd keys={["⌘", "K"]} />);
+    expect(document.querySelector('[data-slot="kbd"]')).toBeInTheDocument();
+  });
+
+  it("should render one keycap per key", () => {
+    render(<Kbd keys={["Ctrl", "Shift", "P"]} />);
+    expect(document.querySelectorAll('[data-slot="kbd-key"]')).toHaveLength(3);
+  });
+
+  it("should render children as a single keycap", () => {
+    render(<Kbd>Esc</Kbd>);
+    expect(document.querySelectorAll('[data-slot="kbd-key"]')).toHaveLength(1);
+    expect(screen.getByText("Esc")).toBeInTheDocument();
+  });
+
+  it("should render separators between keys", () => {
+    render(<Kbd keys={["⌘", "K"]} separator="+" />);
+    expect(
+      document.querySelectorAll('[data-slot="kbd-separator"]'),
+    ).toHaveLength(1);
+  });
+
+  it("should apply the appearance token", () => {
+    render(<Kbd keys={["A"]} appearance="emerald" />);
+    const key = document.querySelector(
+      '[data-slot="kbd-key"]',
+    ) as HTMLElement;
+    expect(key.className).toMatch(/--zui-kbd-emerald-bg/);
+  });
+
+  it("should forward ref", () => {
+    const ref = createRef<HTMLSpanElement>();
+    render(<Kbd ref={ref} keys={["A"]} />);
+    expect(ref.current?.getAttribute("data-slot")).toBe("kbd");
+  });
+});

package/src/ui/kbd/kbd.tsx

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

package/src/ui/kbd/types.ts

@@ -0,0 +1,21 @@
+import type { VariantProps } from "class-variance-authority";
+import type { ComponentPropsWithRef, ElementType, ReactNode } from "react";
+
+import type { kbdKeyVariants } from "./variants";
+
+export type KbdVariantProps = VariantProps<typeof kbdKeyVariants>;
+
+export interface KbdBaseProps
+  extends Omit<ComponentPropsWithRef<"span">, "children"> {
+  /** Keys to render as individual keycaps, e.g. `["⌘", "K"]`. Takes precedence over `children`. */
+  keys?: ReactNode[];
+  /** Optional node rendered between keycaps (e.g. "+" or "then"). */
+  separator?: ReactNode;
+  appearance?: KbdVariantProps["appearance"];
+  size?: KbdVariantProps["size"];
+  /** Single keycap content when `keys` is not provided. */
+  children?: ReactNode;
+  as?: ElementType;
+}
+
+export type KbdProps = Omit<KbdBaseProps, "as">;

package/src/ui/kbd/variants.ts

@@ -0,0 +1,31 @@
+import { cva } from "class-variance-authority";
+
+import {
+  zuiKbdKeyAppearances,
+  zuiKbdKeyBase,
+  zuiKbdKeySizes,
+  zuiKbdSeparatorSizes,
+} from "../../design-system/kbd";
+
+export const kbdKeyVariants = cva(zuiKbdKeyBase, {
+  variants: {
+    appearance: zuiKbdKeyAppearances,
+    size: zuiKbdKeySizes,
+  },
+  defaultVariants: {
+    appearance: "outline",
+    size: "md",
+  },
+});
+
+export const kbdSeparatorVariants = cva(
+  "text-[color:var(--zui-kbd-separator-fg,#94a3b8)] dark:text-[color:var(--zui-kbd-separator-fg-dark,#64748b)]",
+  {
+    variants: {
+      size: zuiKbdSeparatorSizes,
+    },
+    defaultVariants: {
+      size: "md",
+    },
+  },
+);