@zentauri-ui/zentauri-components 1.3.0 → 1.4.0

package/src/ui/buttons/button.test.tsx

@@ -0,0 +1,480 @@
+import { createRef } from "react";
+import { render, screen, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+
+import { ButtonAnimated } from "./animated";
+import { Button } from "./button";
+import type { ButtonAnimation } from "./animated/types";
+
+/** Stable selector contract for consumers of the design-system Button. */
+const BUTTON_SLOT_SELECTOR = '[data-slot="button"]';
+
+function getButtonSlot(container: HTMLElement = document.body) {
+  const elements = container.querySelectorAll(BUTTON_SLOT_SELECTOR);
+  expect(
+    elements.length,
+    `Expected exactly one element matching ${BUTTON_SLOT_SELECTOR} in the document, but found ${elements.length}`,
+  ).toBe(1);
+  return elements[0] as HTMLElement;
+}
+
+describe("Button (component library)", () => {
+  describe("public contract and metadata", () => {
+    it("should expose a stable displayName for devtools and documentation consumers", () => {
+      expect(
+        Button.displayName,
+        "Button.displayName must be set for library discoverability",
+      ).toBe("Button");
+    });
+
+    it("should stamp data-slot on the root element so apps can target the primitive without role ambiguity", () => {
+      render(<Button>Label</Button>);
+      const root = getButtonSlot();
+      expect(
+        root.getAttribute("data-slot"),
+        "data-slot must equal 'button' for the documented contract",
+      ).toBe("button");
+    });
+  });
+
+  describe("default rendering (button mode)", () => {
+    it("should render a native button element with implicit button role for assistive technologies", () => {
+      render(<Button>Save changes</Button>);
+      const control = screen.getByRole("button", { name: "Save changes" });
+      expect(
+        control.tagName,
+        "Default variant must render a BUTTON element",
+      ).toBe("BUTTON");
+    });
+
+    it("should default type to button so it does not accidentally submit parent forms", () => {
+      render(<Button>Neutral</Button>);
+      const control = screen.getByRole("button", { name: "Neutral" });
+      expect(
+        control.getAttribute("type"),
+        "type must default to 'button' inside forms",
+      ).toBe("button");
+    });
+
+    it("should render provided text children as the accessible name", () => {
+      render(<Button>Continue to checkout</Button>);
+      expect(
+        screen.getByRole("button", { name: "Continue to checkout" }),
+        "Visible label must map to the control's accessible name",
+      ).toBeVisible();
+    });
+
+    it("should support complex children while preserving a single root slot", () => {
+      render(
+        <Button>
+          <span data-testid="leading-icon" aria-hidden="true">
+            →
+          </span>
+          <span>Next</span>
+        </Button>,
+      );
+      const root = getButtonSlot();
+      expect(
+        within(root).getByTestId("leading-icon"),
+        "Leading decoration must stay inside the button root",
+      ).toBeInTheDocument();
+      expect(
+        screen.getByRole("button", { name: "Next" }),
+        "Name from text content must remain resolvable",
+      ).toBeInTheDocument();
+    });
+  });
+
+  describe("props: type (native button semantics)", () => {
+    it("should forward type='submit' for form submission controls", () => {
+      render(<Button type="submit">Send</Button>);
+      expect(
+        screen.getByRole("button", { name: "Send" }).getAttribute("type"),
+        "Consumers must be able to opt into submit behavior explicitly",
+      ).toBe("submit");
+    });
+
+    it("should forward type='reset' for form reset controls", () => {
+      render(<Button type="reset">Clear</Button>);
+      expect(
+        screen.getByRole("button", { name: "Clear" }).getAttribute("type"),
+        "Consumers must be able to opt into reset behavior explicitly",
+      ).toBe("reset");
+    });
+  });
+
+  describe("props: appearance (variant class application)", () => {
+    it("should apply default appearance styles from the variant recipe", () => {
+      render(<Button>Default</Button>);
+      const root = getButtonSlot();
+      expect(
+        root.className,
+        "Default appearance must include the default surface token classes",
+      ).toMatch(/bg-slate-50/);
+    });
+
+    it("should apply secondary appearance when appearance='secondary'", () => {
+      render(<Button appearance="secondary">Secondary</Button>);
+      const root = getButtonSlot();
+      expect(
+        root.className,
+        "Secondary appearance must switch to the slate surface recipe",
+      ).toMatch(/bg-slate-800/);
+    });
+
+    it("should apply destructive appearance when appearance='destructive'", () => {
+      render(<Button appearance="destructive">Delete</Button>);
+      const root = getButtonSlot();
+      expect(
+        root.className,
+        "Destructive appearance must surface danger styling",
+      ).toMatch(/bg-rose-600/);
+    });
+
+    it("should apply outline appearance when appearance='outline'", () => {
+      render(<Button appearance="outline">Outline</Button>);
+      const root = getButtonSlot();
+      expect(
+        root.className,
+        "Outline appearance must include border and translucent surface classes",
+      ).toMatch(/border-white\/10/);
+    });
+
+    it("should apply gradient appearance tokens for gradient presets", () => {
+      render(<Button appearance="gradient-blue">Gradient</Button>);
+      const root = getButtonSlot();
+      expect(
+        root.className,
+        "Gradient-blue appearance must include directional gradient utilities",
+      ).toMatch(/bg-gradient-to-r/);
+    });
+  });
+
+  describe("props: size", () => {
+    it("should apply medium size classes by default", () => {
+      render(<Button>MD</Button>);
+      const root = getButtonSlot();
+      expect(
+        root.className,
+        "Default size must map to the md recipe (responsive height utilities)",
+      ).toMatch(/h-9/);
+    });
+
+    it("should apply small size recipe when size='sm'", () => {
+      render(<Button size="sm">SM</Button>);
+      const root = getButtonSlot();
+      expect(root.className, "Small size must use the sm height scale").toMatch(
+        /h-7/,
+      );
+    });
+
+    it("should apply icon size recipe when size='icon'", () => {
+      render(
+        <Button size="icon" aria-label="Open menu">
+          ☰
+        </Button>,
+      );
+      const root = getButtonSlot();
+      expect(
+        root.className,
+        "Icon size must enforce square dimensions",
+      ).toMatch(/h-10/);
+      expect(
+        root.className,
+        "Icon size must enforce square dimensions",
+      ).toMatch(/w-10/);
+    });
+  });
+
+  describe("props: className composition", () => {
+    it("should merge consumer className with generated variant classes", () => {
+      render(
+        <Button className="my-custom-trigger" appearance="secondary">
+          Merge
+        </Button>,
+      );
+      const root = getButtonSlot();
+      expect(
+        root.className,
+        "Consumer class names must not replace variant output",
+      ).toMatch(/bg-slate-800/);
+      expect(
+        root.className,
+        "Consumer class names must be appended for Tailwind overrides",
+      ).toMatch(/my-custom-trigger/);
+    });
+  });
+
+  describe("props: disabled state", () => {
+    it("should mark the control disabled in the DOM and omit it from the tab order", () => {
+      render(<Button disabled>Unavailable</Button>);
+      const control = screen.getByRole("button", { name: "Unavailable" });
+      expect(
+        control,
+        "Disabled buttons must expose the disabled property to assistive tech",
+      ).toBeDisabled();
+      expect(
+        control.getAttribute("tabindex"),
+        "Unless overridden, disabled buttons should not be focused via tab",
+      ).not.toBe("0");
+    });
+
+    it("should not invoke onClick when the control is disabled", async () => {
+      const user = userEvent.setup();
+      const handleClick = vi.fn();
+      render(
+        <Button disabled onClick={handleClick}>
+          Blocked
+        </Button>,
+      );
+      await user.click(screen.getByRole("button", { name: "Blocked" }));
+      expect(
+        handleClick,
+        "Pointer interaction on disabled buttons must not run handlers",
+      ).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("event handlers", () => {
+    it("should call onClick once per activation with pointer input", async () => {
+      const user = userEvent.setup();
+      const handleClick = vi.fn();
+      render(<Button onClick={handleClick}>Click me</Button>);
+      await user.click(screen.getByRole("button", { name: "Click me" }));
+      expect(
+        handleClick,
+        "onClick must fire for enabled primary actions",
+      ).toHaveBeenCalledTimes(1);
+    });
+
+    it("should forward onKeyDown for keyboard-driven interactions", async () => {
+      const user = userEvent.setup();
+      const handleKeyDown = vi.fn();
+      render(<Button onKeyDown={handleKeyDown}>Keyboard</Button>);
+      const control = screen.getByRole("button", { name: "Keyboard" });
+      control.focus();
+      await user.keyboard("{Enter}");
+      expect(
+        handleKeyDown,
+        "onKeyDown must receive keyboard events on the button",
+      ).toHaveBeenCalled();
+    });
+
+    it("should forward onFocus and onBlur for focus management patterns", async () => {
+      const user = userEvent.setup();
+      const handleFocus = vi.fn();
+      const handleBlur = vi.fn();
+      render(
+        <div>
+          <Button onFocus={handleFocus} onBlur={handleBlur}>
+            Focus ring
+          </Button>
+          <button type="button">Other</button>
+        </div>,
+      );
+      const control = screen.getByRole("button", { name: "Focus ring" });
+      await user.click(control);
+      expect(
+        handleFocus,
+        "onFocus must run when the button receives focus",
+      ).toHaveBeenCalledTimes(1);
+      await user.click(screen.getByRole("button", { name: "Other" }));
+      expect(
+        handleBlur,
+        "onBlur must run when focus leaves the button",
+      ).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("ref forwarding", () => {
+    it("should attach ref to the underlying button element in button mode", () => {
+      const ref = createRef<HTMLButtonElement>();
+      render(
+        <Button ref={ref} type="button">
+          Ref target
+        </Button>,
+      );
+      expect(
+        ref.current,
+        "ref must point at the actual DOM node for imperative focus/measure APIs",
+      ).toBeInstanceOf(HTMLButtonElement);
+      expect(
+        ref.current?.textContent,
+        "ref node must be the rendered button instance",
+      ).toContain("Ref target");
+    });
+
+    it("should attach ref to the underlying anchor element in link mode", () => {
+      const ref = createRef<HTMLAnchorElement>();
+      render(
+        <Button as="link" ref={ref} href="/settings">
+          Settings
+        </Button>,
+      );
+      expect(
+        ref.current,
+        "ref must point at the anchor for link mode",
+      ).toBeInstanceOf(HTMLAnchorElement);
+      expect(
+        ref.current?.getAttribute("href"),
+        "ref node must include the consumer href",
+      ).toBe("/settings");
+    });
+  });
+
+  describe("passthrough DOM and ARIA attributes", () => {
+    it("should forward arbitrary data-* attributes for integration test hooks", () => {
+      render(<Button data-testid="primary-cta">Go</Button>);
+      expect(
+        screen.getByTestId("primary-cta"),
+        "data-testid must be preserved on the root element",
+      ).toBe(getButtonSlot());
+    });
+
+    it("should respect aria-label when the visible label is decorative or missing", () => {
+      render(
+        <Button aria-label="Close dialog" size="icon">
+          ×
+        </Button>,
+      );
+      expect(
+        screen.getByRole("button", { name: "Close dialog" }),
+        "Icon-only buttons must remain nameable via aria-label",
+      ).toBeInTheDocument();
+    });
+
+    it("should forward aria-expanded for toggle / menu button patterns", () => {
+      render(
+        <Button aria-expanded="true" aria-controls="menu-id">
+          Menu
+        </Button>,
+      );
+      const control = screen.getByRole("button", { name: "Menu" });
+      expect(
+        control.getAttribute("aria-expanded"),
+        "aria-expanded must pass through unchanged",
+      ).toBe("true");
+      expect(
+        control.getAttribute("aria-controls"),
+        "aria-controls must pass through unchanged",
+      ).toBe("menu-id");
+    });
+
+    it("should forward id for label association", () => {
+      render(
+        <>
+          <label htmlFor="agree">Agree</label>
+          <Button id="agree" type="button">
+            checkbox stand-in
+          </Button>
+        </>,
+      );
+      const control = document.getElementById("agree");
+      expect(control, "id must be applied to the interactive root").toBe(
+        getButtonSlot(),
+      );
+    });
+  });
+
+  describe("link mode (as='link')", () => {
+    it("should render an anchor with href and implicit link role", () => {
+      render(
+        <Button as="link" href="/docs/getting-started">
+          Read docs
+        </Button>,
+      );
+      const link = screen.getByRole("link", { name: "Read docs" });
+      expect(link.tagName, "Link mode must render an A element").toBe("A");
+      expect(
+        link.getAttribute("href"),
+        "href must be forwarded for navigation",
+      ).toBe("/docs/getting-started");
+    });
+
+    it("should add rel='noopener noreferrer' when target is _blank", () => {
+      render(
+        <Button as="link" href="https://example.com" target="_blank">
+          External
+        </Button>,
+      );
+      const link = screen.getByRole("link", { name: "External" });
+      expect(
+        link.getAttribute("rel"),
+        "External tabs must include noopener/noreferrer for tab safety",
+      ).toBe("noopener noreferrer");
+    });
+
+    it("should omit rel when target is not _blank", () => {
+      render(
+        <Button as="link" href="/internal" target="_self">
+          Internal
+        </Button>,
+      );
+      const link = screen.getByRole("link", { name: "Internal" });
+      expect(
+        link.getAttribute("rel"),
+        "rel should not be forced for same-context navigation",
+      ).toBeNull();
+    });
+
+    it("should still stamp data-slot on anchors for consistent styling hooks", () => {
+      render(
+        <Button as="link" href="/pricing">
+          Pricing
+        </Button>,
+      );
+      expect(
+        getButtonSlot().tagName,
+        "Link mode must keep the same data-slot contract",
+      ).toBe("A");
+    });
+  });
+
+  describe("props: animation presets (smoke)", () => {
+    const animations: ButtonAnimation[] = [
+      "none",
+      "lift",
+      "press",
+      "glow",
+      "tilt",
+      "bounce",
+    ];
+
+    it.each(animations)(
+      "should render without throwing when animation=%s",
+      (animation) => {
+        const { unmount } = render(
+          <ButtonAnimated animation={animation} appearance="secondary">
+            {animation}
+          </ButtonAnimated>,
+        );
+        expect(
+          getButtonSlot(),
+          `Animation preset '${animation}' must produce a mounted root`,
+        ).toBeVisible();
+        unmount();
+      },
+    );
+  });
+
+  describe("accessibility checklist", () => {
+    it("should expose focus styles via focus-visible classes in the class list", () => {
+      render(<Button>Focusable</Button>);
+      const root = getButtonSlot();
+      expect(
+        root.className,
+        "Library buttons must ship focus-visible ring utilities for keyboard users",
+      ).toMatch(/focus-visible:ring-2/);
+    });
+
+    it("should include disabled opacity utilities for visual vs AT state alignment", () => {
+      render(<Button disabled>Faded</Button>);
+      const root = getButtonSlot();
+      expect(
+        root.className,
+        "Disabled styling must include opacity treatment from the recipe",
+      ).toMatch(/disabled:opacity-50/);
+    });
+  });
+});

package/src/ui/buttons/button.tsx

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

package/src/ui/buttons/index.ts

@@ -0,0 +1,5 @@
+"use client";
+
+export { Button } from "./button";
+export type { ButtonProps, ButtonSharedStatic } from "./types";
+export { buttonVariants } from "./variants";

package/src/ui/buttons/types.ts

@@ -0,0 +1,14 @@
+import type { VariantProps } from "class-variance-authority";
+import type { ComponentPropsWithRef } from "react";
+
+import type { buttonVariants } from "./variants";
+
+export type ButtonSharedStatic = VariantProps<typeof buttonVariants>;
+
+export type ButtonProps =
+  | (ButtonSharedStatic & ComponentPropsWithRef<"button"> & {
+      as?: "button";
+    })
+  | (ButtonSharedStatic & ComponentPropsWithRef<"a"> & { as: "link" });
+
+

package/src/ui/buttons/variants.ts

@@ -0,0 +1,77 @@
+import { cva } from "class-variance-authority";
+
+export const buttonVariants = cva(
+  [
+    "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-xl",
+    "text-sm font-medium ring-offset-slate-950 transition-colors",
+    "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-slate-300 focus-visible:ring-offset-2",
+    "disabled:pointer-events-none disabled:opacity-50",
+    "select-none",
+  ],
+  {
+    variants: {
+      appearance: {
+        default:
+          "bg-slate-50 text-slate-950 shadow-[0_1px_2px_rgba(15,23,42,0.12)] hover:bg-white",
+        secondary: "bg-slate-800 text-slate-50 hover:bg-slate-700",
+        destructive: "bg-rose-600 text-white hover:bg-rose-600",
+        outline:
+          "border border-white/10 bg-white/5 text-slate-50 hover:bg-white/10",
+        ghost: "bg-transparent text-slate-200 hover:bg-white/5",
+        link: "bg-transparent text-cyan-300 underline-offset-4 hover:underline",
+        glass:
+          "border border-white/15 bg-white/10 text-white backdrop-blur-md hover:bg-white/15",
+        emerald: "bg-emerald-600 text-white hover:bg-emerald-600",
+        indigo: "bg-indigo-600 text-white hover:bg-indigo-600",
+        purple: "bg-purple-600 text-white hover:bg-purple-600",
+        pink: "bg-pink-600 text-white hover:bg-pink-600",
+        rose: "bg-rose-600 text-white hover:bg-rose-600",
+        sky: "bg-sky-600 text-white hover:bg-sky-600",
+        teal: "bg-teal-600 text-white hover:bg-teal-600",
+        yellow: "bg-yellow-600 text-white hover:bg-yellow-600",
+        orange: "bg-orange-600 text-white hover:bg-orange-600",
+        gray: "bg-gray-600 text-white hover:bg-gray-600",
+        amber: "bg-amber-600 text-white hover:bg-amber-600",
+        violet: "bg-violet-600 text-white hover:bg-violet-600",
+        "gradient-blue":
+          "bg-gradient-to-r from-blue-600 to-purple-600 text-white hover:from-blue-600 hover:to-purple-600",
+        "gradient-green":
+          "bg-gradient-to-r from-green-600 to-lime-600 text-white hover:from-green-600 hover:to-lime-600",
+        "gradient-red":
+          "bg-gradient-to-r from-red-600 to-pink-600 text-white hover:from-red-600 hover:to-pink-600",
+        "gradient-yellow":
+          "bg-gradient-to-r from-yellow-600 to-orange-600 text-white hover:from-yellow-600 hover:to-orange-600",
+        "gradient-purple":
+          "bg-gradient-to-r from-purple-600 to-pink-600 text-white hover:from-purple-600 hover:to-pink-600",
+        "gradient-teal":
+          "bg-gradient-to-r from-teal-600 to-cyan-600 text-white hover:from-teal-600 hover:to-cyan-600",
+        "gradient-indigo":
+          "bg-gradient-to-r from-indigo-600 to-purple-600 text-white hover:from-indigo-600 hover:to-purple-600",
+        "gradient-pink":
+          "bg-gradient-to-r from-pink-600 to-rose-600 text-white hover:from-pink-600 hover:to-rose-600",
+        "gradient-orange":
+          "bg-gradient-to-r from-orange-600 to-red-600 text-white hover:from-orange-600 hover:to-red-600",
+      },
+      size: {
+        sm: "h-7 md:h-9 px-3 text-xs",
+        md: "h-9 md:h-11 px-4",
+        lg: "h-10 md:h-12 px-5 text-base",
+        xl: "h-12 md:h-14 px-6 text-lg",
+        "2xl": "h-14 md:h-16 px-6 md:px-8 text-xl",
+        "3xl": "h-16 md:h-18 px-8 md:px-10 text-2xl",
+        "4xl": "h-18 md:h-20 px-10 md:px-12 text-2xl",
+        "5xl": "h-20 md:h-22 px-12 md:px-14 text-2xl",
+        "6xl": "h-22 md:h-24 px-14 md:px-16 text-2xl",
+        "7xl": "h-24 md:h-26 px-16 md:px-18 text-2xl",
+        "8xl": "h-26 md:h-28 px-20 text-2xl",
+        "9xl": "h-24 md:h-30 px-18 md:px-22 text-2xl",
+        "10xl": "h-26 md:h-32 px-20 md:px-24 text-2xl",
+        icon: "h-10 w-10",
+      },
+    },
+    defaultVariants: {
+      appearance: "default",
+      size: "md",
+    },
+  },
+);

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

@@ -0,0 +1,32 @@
+import type { HTMLMotionProps } from "framer-motion";
+
+import type { CardAnimation } from "./types";
+
+type CardPresetMotionProps = Pick<
+  HTMLMotionProps<"article">,
+  "style" | "transition" | "whileHover" | "whileTap"
+>;
+
+export type CardAnimationPresets = Record<CardAnimation, CardPresetMotionProps>;
+
+export const cardAnimationPresets: CardAnimationPresets = {
+  none: {},
+  lift: {
+    whileHover: { y: -4, scale: 1.01 },
+    whileTap: { y: 0, scale: 0.995 },
+    transition: { type: "spring", stiffness: 380, damping: 26 },
+  },
+  glow: {
+    whileHover: {
+      boxShadow:
+        "0 0 0 1px rgba(255,255,255,0.18), 0 22px 48px rgba(15,23,42,0.45)",
+    },
+    transition: { duration: 0.22, ease: "easeOut" },
+  },
+  tilt: {
+    whileHover: { rotateX: 4, rotateY: -4, scale: 1.01 },
+    whileTap: { rotateX: 0, rotateY: 0, scale: 0.99 },
+    transition: { type: "spring", stiffness: 280, damping: 22 },
+    style: { transformStyle: "preserve-3d" },
+  },
+};

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

@@ -0,0 +1,28 @@
+"use client";
+
+import { motion } from "framer-motion";
+
+import { cardAnimationPresets } from "./animations";
+import { CardBase } from "../card-base";
+import type { CardBaseProps } from "../types";
+import type { CardAnimatedProps } from "./types";
+
+export function CardAnimated({
+  animation = "none",
+  ...props
+}: CardAnimatedProps) {
+  const motionProps = cardAnimationPresets[animation];
+
+  return (
+    <CardBase
+      {...({
+        as: motion.article,
+        initial: false,
+        ...motionProps,
+        ...props,
+      } as CardBaseProps)}
+    />
+  );
+}
+
+CardAnimated.displayName = "CardAnimated";

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

@@ -0,0 +1,12 @@
+"use client";
+
+export { CardAnimated } from "./card-animated";
+export {
+  CardBody,
+  CardDescription,
+  CardFooter,
+  CardHeader,
+  CardTitle,
+} from "../card-base";
+export type { CardAnimatedProps } from "./types";
+export { cardAnimationPresets } from "./animations";

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

@@ -0,0 +1,8 @@
+import type { CardBaseProps } from "../types";
+
+export type CardAnimation = "none" | "lift" | "glow" | "tilt";
+
+export type CardAnimatedProps = Omit<CardBaseProps, "as"> & {
+  animation?: CardAnimation;
+};
+