@zentauri-ui/zentauri-components 1.3.1 → 1.4.0

package/src/ui/alert/alert.test.tsx

@@ -0,0 +1,150 @@
+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 {
+  AlertClose,
+  AlertDefaultIcon,
+  AlertDescription,
+  AlertIcon,
+  AlertTitle,
+} from "./alert-base";
+import { Alert } from "./alert";
+
+describe("Alert", () => {
+  describe("public contract and metadata", () => {
+    it("should expose displayName on compound parts", () => {
+      expect(Alert.displayName).toBe("Alert");
+      expect(AlertIcon.displayName).toBe("AlertIcon");
+      expect(AlertTitle.displayName).toBe("AlertTitle");
+      expect(AlertDescription.displayName).toBe("AlertDescription");
+      expect(AlertClose.displayName).toBe("AlertClose");
+    });
+
+    it("should stamp data-slot on the root element", () => {
+      render(
+        <Alert>
+          <AlertTitle>Heads up</AlertTitle>
+        </Alert>,
+      );
+      const root = document.querySelector('[data-slot="alert"]');
+      expect(root).toBeTruthy();
+      expect(root?.getAttribute("data-slot")).toBe("alert");
+    });
+  });
+
+  describe("semantics and live region", () => {
+    it("should use role alert and polite live region for non-error appearances", () => {
+      render(
+        <Alert appearance="info">
+          <AlertTitle>Info</AlertTitle>
+        </Alert>,
+      );
+      const live = screen.getByRole("alert");
+      expect(live.getAttribute("aria-live")).toBe("polite");
+    });
+
+    it("should use assertive live region for error appearance", () => {
+      render(
+        <Alert appearance="error">
+          <AlertTitle>Error</AlertTitle>
+        </Alert>,
+      );
+      expect(screen.getByRole("alert").getAttribute("aria-live")).toBe(
+        "assertive",
+      );
+    });
+  });
+
+  describe("closable behavior", () => {
+    it("should render a dismiss control when closable is true", () => {
+      render(
+        <Alert closable closeLabel="Remove warning">
+          <AlertTitle>Warning</AlertTitle>
+        </Alert>,
+      );
+      expect(
+        screen.getByRole("button", { name: "Remove warning" }),
+      ).toHaveAttribute("data-slot", "alert-close");
+    });
+
+    it("should invoke onClose when the built-in dismiss button is activated", async () => {
+      const user = userEvent.setup();
+      const handleClose = vi.fn();
+      render(
+        <Alert closable onClose={handleClose}>
+          <AlertTitle>Dismissible</AlertTitle>
+        </Alert>,
+      );
+      await user.click(screen.getByRole("button", { name: /dismiss alert/i }));
+      expect(handleClose).toHaveBeenCalledTimes(1);
+    });
+
+    it("should allow AlertClose to run a custom handler", async () => {
+      const user = userEvent.setup();
+      const handleClose = vi.fn();
+      render(
+        <Alert>
+          <AlertTitle>Manual close</AlertTitle>
+          <AlertClose aria-label="Close" onClick={handleClose}>
+            ×
+          </AlertClose>
+        </Alert>,
+      );
+      await user.click(screen.getByRole("button", { name: "Close" }));
+      expect(handleClose).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("composition", () => {
+    it("should render compound slots for icon, title, and description", () => {
+      render(
+        <Alert>
+          <AlertIcon>
+            <span data-testid="custom-icon">!</span>
+          </AlertIcon>
+          <AlertTitle>Title</AlertTitle>
+          <AlertDescription>Description body</AlertDescription>
+        </Alert>,
+      );
+      expect(screen.getByTestId("custom-icon")).toBeInTheDocument();
+      expect(
+        document.querySelector('[data-slot="alert-title"]'),
+      ).toHaveTextContent("Title");
+      expect(
+        document.querySelector('[data-slot="alert-description"]'),
+      ).toHaveTextContent("Description body");
+    });
+
+    it("should apply appearance classes from the variant recipe", () => {
+      render(
+        <Alert appearance="success">
+          <AlertTitle>Done</AlertTitle>
+        </Alert>,
+      );
+      const root = document.querySelector('[data-slot="alert"]') as HTMLElement;
+      expect(root.className).toMatch(/border-emerald-500/);
+    });
+  });
+
+  describe("ref forwarding", () => {
+    it("should forward ref to the motion root", () => {
+      const ref = createRef<HTMLDivElement>();
+      render(
+        <Alert ref={ref}>
+          <AlertTitle>Ref</AlertTitle>
+        </Alert>,
+      );
+      expect(ref.current).toBeInstanceOf(HTMLDivElement);
+      expect(ref.current?.getAttribute("data-slot")).toBe("alert");
+    });
+  });
+
+  describe("AlertDefaultIcon", () => {
+    it("should render error icon markup when appearance is error", () => {
+      const { container } = render(<AlertDefaultIcon appearance="error" />);
+      expect(container.querySelector("svg")).toBeTruthy();
+    });
+  });
+});

package/src/ui/alert/alert.tsx

@@ -0,0 +1,9 @@
+// alert.tsx  ← users import this by default
+import { AlertBase } from "./alert-base";
+import type { AlertProps } from "./types";
+
+export const Alert = (props: AlertProps) => {
+  return <AlertBase {...props} />;
+}
+
+Alert.displayName = "Alert";

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

@@ -0,0 +1,20 @@
+import { motion } from "framer-motion";
+import { AlertBase } from "../alert-base";
+import { alertAnimationPresets } from "./animations";
+import type { AlertAnimatedProps } from "./types";
+
+export const AlertAnimated = ({
+  animation = "none",
+  ...props
+}: AlertAnimatedProps) => {
+  const motionProps = alertAnimationPresets[animation];
+
+  return (
+    <AlertBase
+      as={motion.div}
+      initial={animation === "none" ? false : undefined}
+      {...motionProps}
+      {...props}
+    />
+  );
+};

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

@@ -0,0 +1,20 @@
+import { AlertAnimationPresets } from "./types";
+
+export const alertAnimationPresets: AlertAnimationPresets = {
+  none: {},
+  "slide-down": {
+    initial: { y: -8, opacity: 0 },
+    animate: { y: 0, opacity: 1 },
+    transition: { type: "spring", stiffness: 420, damping: 30 },
+  },
+  fade: {
+    initial: { opacity: 0 },
+    animate: { opacity: 1 },
+    transition: { duration: 0.2 },
+  },
+  pop: {
+    initial: { scale: 0.96, opacity: 0 },
+    animate: { scale: 1, opacity: 1 },
+    transition: { type: "spring", stiffness: 520, damping: 28 },
+  },
+};

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

@@ -0,0 +1,3 @@
+export { AlertAnimated } from "./alert-animated";
+export type { AlertAnimatedProps} from "./types";
+export { alertAnimationPresets } from "./animations";

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

@@ -0,0 +1,16 @@
+import { HTMLMotionProps } from "framer-motion";
+import type { AlertBaseProps, AlertAnimation } from "../types";
+
+export type AlertAnimatedProps = Omit<AlertBaseProps, "as"> & {
+  animation?: AlertAnimation;
+};
+
+export type AlertPresetMotionProps = Pick<
+  HTMLMotionProps<"div">,
+  "initial" | "animate" | "transition"
+>;
+
+export type AlertAnimationPresets = Record<
+  AlertAnimation,
+  AlertPresetMotionProps
+>;

package/src/ui/alert/index.ts

@@ -0,0 +1,22 @@
+"use client";
+
+export {
+  AlertClose,
+  AlertDefaultIcon,
+  AlertDescription,
+  AlertIcon,
+  AlertTitle,
+} from "./alert-base";
+export { Alert } from "./alert";
+
+export type {
+  AlertAnimation,
+  AlertProps,
+  AlertSectionProps,
+  AlertSize,
+} from "./types";
+export {
+  alertVariants,
+  alertTitleVariants,
+  alertDescriptionVariants,
+} from "./variants";

package/src/ui/alert/types.ts

@@ -0,0 +1,28 @@
+import type { VariantProps } from "class-variance-authority";
+import type { ComponentPropsWithRef, ElementType, ReactNode } from "react";
+
+import type { alertVariants } from "./variants";
+
+export type AlertAnimation = "none" | "slide-down" | "fade" | "pop";
+export type AlertAppearance = VariantProps<typeof alertVariants>["appearance"]; 
+export type AlertSize = VariantProps<typeof alertVariants>["size"];
+
+export interface AlertBaseProps extends ComponentPropsWithRef<"div"> {
+  appearance?: AlertAppearance;
+  size?: AlertSize;
+  closable?: boolean;
+  onClose?: () => void;
+  closeLabel?: string;
+  triggerClassName?: string;
+  // Accept the wrapper element/component as a prop — defaults to "div"
+  as?: ElementType;
+}
+
+
+export type AlertSectionProps = {
+  className?: string;
+  children?: ReactNode;
+};
+
+export type AlertProps = Omit<AlertBaseProps, "as">;
+

package/src/ui/alert/variants.ts

@@ -0,0 +1,74 @@
+import { cva } from "class-variance-authority";
+
+export const alertVariants = cva(
+  "relative flex w-full gap-3 border text-sm ring-offset-slate-950 transition-colors",
+  {
+    variants: {
+      appearance: {
+        default: "border-white/10 bg-white/5 text-slate-50",
+        success: "border-emerald-500/40 bg-emerald-500/10 text-emerald-50",
+        warning: "border-amber-500/40 bg-amber-500/10 text-amber-50",
+        error: "border-rose-500/50 bg-rose-500/10 text-rose-50",
+        info: "border-sky-500/40 bg-sky-500/10 text-sky-50",
+        ghost: "border-transparent bg-transparent text-slate-200",
+        purple: "border-purple-600 bg-purple-950/70 backdrop-blur-xl",
+        pink: "border-pink-600 bg-pink-950/70 backdrop-blur-xl",
+        orange: "border-orange-600 bg-orange-950/70 backdrop-blur-xl",
+        yellow: "border-yellow-600 bg-yellow-950/70 backdrop-blur-xl",
+        teal: "border-teal-600 bg-teal-950/70 backdrop-blur-xl",
+        indigo: "border-indigo-600 bg-indigo-950/70 backdrop-blur-xl",
+        gray: "border-gray-600 bg-gray-950/70 backdrop-blur-xl",
+        violet: "border-violet-600 bg-violet-950/70 backdrop-blur-xl",
+        "gradient-blue":
+          "border-gradient-to-r from-blue-600 to-purple-600 bg-gradient-to-r from-blue-950/70 to-purple-950/70 backdrop-blur-xl",
+        "gradient-green":
+          "border-gradient-to-r from-green-600 to-lime-600 bg-gradient-to-r from-green-950/70 to-lime-950/70 backdrop-blur-xl",
+        "gradient-red":
+          "border-gradient-to-r from-red-600 to-pink-600 bg-gradient-to-r from-red-950/70 to-pink-950/70 backdrop-blur-xl",
+        "gradient-yellow":
+          "border-gradient-to-r from-yellow-600 to-orange-600 bg-gradient-to-r from-yellow-950/70 to-orange-950/70 backdrop-blur-xl",
+        "gradient-purple":
+          "border-gradient-to-r from-purple-600 to-pink-600 bg-gradient-to-r from-purple-950/70 to-pink-950/70 backdrop-blur-xl",
+        "gradient-teal":
+          "border-gradient-to-r from-teal-600 to-cyan-600 bg-gradient-to-r from-teal-950/70 to-cyan-950/70 backdrop-blur-xl",
+        "gradient-indigo":
+          "border-gradient-to-r from-indigo-600 to-purple-600 bg-gradient-to-r from-indigo-950/70 to-purple-950/70 backdrop-blur-xl",
+        "gradient-pink":
+          "border-gradient-to-r from-pink-600 to-rose-600 bg-gradient-to-r from-pink-950/70 to-rose-950/70 backdrop-blur-xl",
+        "gradient-orange":
+          "border-gradient-to-r from-orange-600 to-red-600 bg-gradient-to-r from-orange-950/70 to-red-950/70 backdrop-blur-xl",
+      },
+      size: {
+        sm: "rounded-lg p-3",
+        md: "rounded-xl p-4",
+        lg: "rounded-2xl p-5 text-base",
+      },
+    },
+    defaultVariants: {
+      appearance: "default",
+      size: "md",
+    },
+  },
+);
+
+export const alertTitleVariants = cva("font-semibold leading-tight", {
+  variants: {
+    size: {
+      sm: "text-xs md:text-sm",
+      md: "text-xs md:text-sm",
+      lg: "text-xs md:text-sm",
+    },
+  },
+  defaultVariants: { size: "md" },
+});
+
+export const alertDescriptionVariants = cva("text-slate-300", {
+  variants: {
+    size: {
+      sm: "text-xs md:text-sm",
+      md: "text-xs md:text-sm",
+      lg: "text-xs md:text-sm",
+    },
+  },
+  defaultVariants: { size: "md" },
+});

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

@@ -0,0 +1,11 @@
+import { AvatarAnimationPresets } from "./types";
+
+export const avatarAnimationPresets: AvatarAnimationPresets = {
+  none: { initial: false },
+  subtle: {
+    initial: false,
+    whileHover: { scale: 1.03 },
+    whileTap: { scale: 0.98 },
+    transition: { type: "spring", stiffness: 420, damping: 28 },
+  },
+};

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

@@ -0,0 +1,25 @@
+"use client";
+
+import { motion } from "framer-motion";
+
+import { avatarAnimationPresets } from "./animations";
+import { AvatarBase } from "../avatar-base";
+import type { AvatarAnimatedProps } from "./types";
+
+export function AvatarAnimated({
+  animation = "none",
+  ...props
+}: AvatarAnimatedProps) {
+  const motionProps = avatarAnimationPresets[animation];
+
+  return (
+    <AvatarBase
+      as={motion.span}
+      initial={animation === "none" ? false : undefined}
+      {...motionProps}
+      {...props}
+    />
+  );
+}
+
+AvatarAnimated.displayName = "AvatarAnimated";

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

@@ -0,0 +1,6 @@
+"use client";
+
+export { AvatarAnimated } from "./avatar-animated";
+export { AvatarFallback, AvatarGroup, AvatarImage } from "../avatar-base";
+export type { AvatarAnimatedProps, AvatarAnimation, AvatarAnimationPresets } from "./types";
+export { avatarAnimationPresets } from "./animations";

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

@@ -0,0 +1,16 @@
+import type { AvatarBaseProps } from "../types";
+import { HTMLMotionProps } from "framer-motion";
+
+export type AvatarAnimatedProps = Omit<AvatarBaseProps, "as"> & {
+  animation?: AvatarAnimation;
+};
+
+export type AvatarAnimationPresets = Record<
+  AvatarAnimation,
+  Pick<
+    HTMLMotionProps<"span">,
+    "whileHover" | "whileTap" | "transition" | "initial"
+  >
+>;
+
+export type AvatarAnimation = "none" | "subtle";

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

@@ -0,0 +1,184 @@
+"use client";
+
+import {
+  Children,
+  createContext,
+  isValidElement,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type Ref,
+} from "react";
+
+import { cn } from "../../lib/utils";
+
+import type {
+  AvatarBaseProps,
+  AvatarCtx,
+  AvatarFallbackProps,
+  AvatarGroupProps,
+  AvatarImageProps,
+  ImageStatus,
+} from "./types";
+import {
+  avatarFallbackVariants,
+  avatarGroupVariants,
+  avatarImageVariants,
+  avatarVariants,
+} from "./variants";
+
+const AvatarContext = createContext<AvatarCtx | null>(null);
+
+function useAvatarContext(component: string): AvatarCtx {
+  const ctx = useContext(AvatarContext);
+  if (!ctx) {
+    throw new Error(`${component} must be used within <Avatar>`);
+  }
+  return ctx;
+}
+
+export function AvatarBase({
+  className,
+  size,
+  appearance,
+  children,
+  ref,
+  as: Wrapper = "span",
+  ...rest
+}: AvatarBaseProps) {
+  const [imageStatus, setImageStatus] = useState<ImageStatus>("idle");
+  const ctx = useMemo(
+    () => ({ imageStatus, setImageStatus }),
+    [imageStatus],
+  );
+
+  return (
+    <AvatarContext.Provider value={ctx}>
+      <Wrapper
+        ref={ref}
+        data-slot="avatar"
+        className={cn(avatarVariants({ size, appearance }), className)}
+        {...rest}
+      >
+        {children}
+      </Wrapper>
+    </AvatarContext.Provider>
+  );
+}
+
+AvatarBase.displayName = "Avatar";
+
+export function AvatarImage({
+  className,
+  onLoad,
+  onError,
+  ref,
+  ...rest
+}: AvatarImageProps & { ref?: Ref<HTMLImageElement> }) {
+  const { setImageStatus } = useAvatarContext("AvatarImage");
+
+  return (
+    <img
+      ref={ref}
+      data-slot="avatar-image"
+      className={cn(avatarImageVariants(), className)}
+      onLoad={(e) => {
+        setImageStatus("loaded");
+        onLoad?.(e);
+      }}
+      onError={(e) => {
+        setImageStatus("error");
+        onError?.(e);
+      }}
+      {...rest}
+    />
+  );
+}
+
+AvatarImage.displayName = "AvatarImage";
+
+export function AvatarFallback({
+  className,
+  delayMs = 0,
+  ref,
+  ...rest
+}: AvatarFallbackProps & { ref?: Ref<HTMLSpanElement> }) {
+  const { imageStatus } = useAvatarContext("AvatarFallback");
+  const [show, setShow] = useState(delayMs === 0);
+
+  useEffect(() => {
+    if (imageStatus === "loaded") {
+      setShow(false);
+      return;
+    }
+    if (imageStatus === "error") {
+      setShow(true);
+      return;
+    }
+    if (delayMs <= 0) {
+      setShow(true);
+      return;
+    }
+    const t = window.setTimeout(() => setShow(true), delayMs);
+    return () => window.clearTimeout(t);
+  }, [delayMs, imageStatus]);
+
+  if (!show) {
+    return null;
+  }
+
+  return (
+    <span
+      ref={ref}
+      data-slot="avatar-fallback"
+      className={cn(avatarFallbackVariants(), className)}
+      {...rest}
+    />
+  );
+}
+
+AvatarFallback.displayName = "AvatarFallback";
+
+export function AvatarGroup({
+  className,
+  max,
+  children,
+  ref,
+  ...rest
+}: AvatarGroupProps & { ref?: Ref<HTMLDivElement> }) {
+  const childArray = useMemo(
+    () => Children.toArray(children).filter(isValidElement),
+    [children],
+  );
+  const visible = max !== undefined ? childArray.slice(0, max) : childArray;
+  const overflow =
+    max !== undefined && childArray.length > max
+      ? childArray.length - max
+      : 0;
+
+  return (
+    <div
+      ref={ref}
+      data-slot="avatar-group"
+      className={cn(avatarGroupVariants(), className)}
+      {...rest}
+    >
+      {visible}
+      {overflow > 0 ? (
+        <span
+          data-slot="avatar-group-overflow"
+          className={cn(
+            avatarVariants({ size: "md" }),
+            "z-10 grid place-items-center bg-slate-800 text-xs font-semibold text-white",
+          )}
+          aria-label={`${overflow} more`}
+        >
+          +{overflow}
+        </span>
+      ) : null}
+    </div>
+  );
+}
+
+AvatarGroup.displayName = "AvatarGroup";

package/src/ui/avatar/avatar.test.tsx

@@ -0,0 +1,51 @@
+import { createRef } from "react";
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { Avatar, AvatarFallback, AvatarGroup, AvatarImage } from "./avatar";
+
+describe("Avatar", () => {
+  it("should expose displayName", () => {
+    expect(Avatar.displayName).toBe("Avatar");
+    expect(AvatarImage.displayName).toBe("AvatarImage");
+    expect(AvatarFallback.displayName).toBe("AvatarFallback");
+    expect(AvatarGroup.displayName).toBe("AvatarGroup");
+  });
+
+  it("should stamp data-slot on avatar root", () => {
+    render(
+      <Avatar>
+        <AvatarFallback>AB</AvatarFallback>
+      </Avatar>,
+    );
+    expect(document.querySelector('[data-slot="avatar"]')).toBeTruthy();
+  });
+
+  it("should forward ref on Avatar", () => {
+    const ref = createRef<HTMLSpanElement>();
+    render(
+      <Avatar ref={ref}>
+        <AvatarFallback>Z</AvatarFallback>
+      </Avatar>,
+    );
+    expect(ref.current?.getAttribute("data-slot")).toBe("avatar");
+  });
+
+  it("should render overflow count in AvatarGroup", () => {
+    render(
+      <AvatarGroup max={2}>
+        <Avatar>
+          <AvatarFallback>A</AvatarFallback>
+        </Avatar>
+        <Avatar>
+          <AvatarFallback>B</AvatarFallback>
+        </Avatar>
+        <Avatar>
+          <AvatarFallback>C</AvatarFallback>
+        </Avatar>
+      </AvatarGroup>,
+    );
+    expect(screen.getByLabelText("1 more")).toBeInTheDocument();
+    expect(screen.getByText("+1")).toBeInTheDocument();
+  });
+});

package/src/ui/avatar/avatar.tsx

@@ -0,0 +1,11 @@
+// avatar.tsx — default static entry (no framer-motion)
+import { AvatarBase, AvatarFallback, AvatarGroup, AvatarImage } from "./avatar-base";
+import type { AvatarProps } from "./types";
+
+export function Avatar(props: AvatarProps) {
+  return <AvatarBase {...props} />;
+}
+
+Avatar.displayName = "Avatar";
+
+export { AvatarFallback, AvatarGroup, AvatarImage };

package/src/ui/avatar/index.ts

@@ -0,0 +1,16 @@
+"use client";
+
+export { Avatar, AvatarFallback, AvatarGroup, AvatarImage } from "./avatar";
+export type { AvatarBaseProps } from "./types";
+export type {
+  AvatarFallbackProps,
+  AvatarGroupProps,
+  AvatarImageProps,
+  AvatarProps,
+} from "./types";
+export {
+  avatarFallbackVariants,
+  avatarGroupVariants,
+  avatarImageVariants,
+  avatarVariants,
+} from "./variants";