@zentauri-ui/zentauri-components 1.7.4 → 1.7.6

package/src/ui/scroll-area/scroll-area.test.tsx

@@ -0,0 +1,116 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { ScrollArea } from "./scroll-area";
+
+describe("ScrollArea", () => {
+  it("exposes a display name", () => {
+    expect(ScrollArea.displayName).toBe("ScrollArea");
+  });
+
+  it("renders children in the viewport slot", () => {
+    render(
+      <ScrollArea>
+        <p>Scrollable content</p>
+      </ScrollArea>,
+    );
+
+    expect(document.querySelector('[data-slot="scroll-area"]')).toBeTruthy();
+    expect(
+      document.querySelector('[data-slot="scroll-area-viewport"]'),
+    ).toBeTruthy();
+    expect(screen.getByText("Scrollable content")).toBeInTheDocument();
+  });
+
+  it("applies horizontal orientation metadata and overflow classes", () => {
+    render(
+      <ScrollArea orientation="horizontal" data-testid="scroll-area">
+        Wide content
+      </ScrollArea>,
+    );
+
+    const area = screen.getByTestId("scroll-area");
+    expect(area).toHaveAttribute("data-orientation", "horizontal");
+    expect(area.className).toContain("overflow-x-auto");
+    expect(area.className).toContain("overflow-y-hidden");
+  });
+
+  it("applies both-axis orientation metadata and overflow classes", () => {
+    render(
+      <ScrollArea orientation="both" data-testid="scroll-area">
+        Wide and tall content
+      </ScrollArea>,
+    );
+
+    const area = screen.getByTestId("scroll-area");
+    expect(area).toHaveAttribute("data-orientation", "both");
+    expect(area.className).toContain("overflow-auto");
+  });
+
+  it("uses named regions as keyboard-focusable scroll containers", () => {
+    render(
+      <ScrollArea aria-label="Notifications" data-testid="scroll-area">
+        Notifications
+      </ScrollArea>,
+    );
+
+    const area = screen.getByTestId("scroll-area");
+    expect(area).toHaveAttribute("role", "region");
+    expect(area).toHaveAttribute("tabindex", "0");
+  });
+
+  it("respects explicit role and tabIndex values", () => {
+    render(
+      <ScrollArea
+        aria-label="Activity"
+        data-testid="scroll-area"
+        role="group"
+        tabIndex={-1}
+      >
+        Activity
+      </ScrollArea>,
+    );
+
+    const area = screen.getByTestId("scroll-area");
+    expect(area).toHaveAttribute("role", "group");
+    expect(area).toHaveAttribute("tabindex", "-1");
+  });
+
+  it("applies viewport class names", () => {
+    render(
+      <ScrollArea viewportClassName="min-w-max" data-testid="scroll-area">
+        Content
+      </ScrollArea>,
+    );
+
+    expect(
+      document.querySelector('[data-slot="scroll-area-viewport"]'),
+    ).toHaveClass("min-w-max");
+  });
+
+  it("applies appearance, size, scrollbar, shadow, and className variants", () => {
+    render(
+      <ScrollArea
+        appearance="sky"
+        className="h-32"
+        data-testid="scroll-area"
+        scrollbar="hover"
+        shadow
+        size="lg"
+      >
+        Content
+      </ScrollArea>,
+    );
+
+    const area = screen.getByTestId("scroll-area");
+    expect(area).toHaveAttribute("data-scrollbar", "hover");
+    expect(area.className).toContain("h-32");
+    expect(area.className).toContain("[--zui-scroll-area-size:0.875rem]");
+    expect(area.className).toContain(
+      "[box-shadow:inset_0_2px_12px_rgb(15_23_42_/_0.08)]",
+    );
+    expect(area.className).toContain(
+      "[--zui-scroll-area-thumb:oklch(54.6%_0.245_262.881)]",
+    );
+  });
+});

package/src/ui/scroll-area/scroll-area.tsx

@@ -0,0 +1,62 @@
+"use client";
+
+import { cn } from "../../lib/utils";
+
+import type { ScrollAreaProps } from "./types";
+import { scrollAreaVariants } from "./variants";
+
+export function ScrollArea(props: ScrollAreaProps) {
+  const {
+    appearance,
+    children,
+    className,
+    orientation,
+    ref,
+    role,
+    scrollbar,
+    shadow,
+    size,
+    tabIndex,
+    viewportClassName,
+    ...rest
+  } = props;
+  const ariaLabel = rest["aria-label"];
+  const ariaLabelledBy = rest["aria-labelledby"];
+  const isNamedRegion =
+    role === "region" ||
+    ariaLabel !== undefined ||
+    ariaLabelledBy !== undefined;
+
+  return (
+    <div
+      ref={ref}
+      data-orientation={orientation ?? "vertical"}
+      data-scrollbar={scrollbar ?? "auto"}
+      data-slot="scroll-area"
+      role={
+        role ??
+        (ariaLabel !== undefined || ariaLabelledBy !== undefined
+          ? "region"
+          : undefined)
+      }
+      tabIndex={tabIndex ?? (isNamedRegion ? 0 : undefined)}
+      className={cn(
+        scrollAreaVariants({
+          appearance,
+          orientation,
+          scrollbar,
+          shadow,
+          size,
+        }),
+        className,
+      )}
+      {...rest}
+    >
+      <div data-slot="scroll-area-viewport" className={viewportClassName}>
+        {children}
+      </div>
+    </div>
+  );
+}
+
+ScrollArea.displayName = "ScrollArea";

package/src/ui/scroll-area/types.ts

@@ -0,0 +1,11 @@
+import type { VariantProps } from "class-variance-authority";
+import type { ComponentPropsWithRef } from "react";
+
+import type { scrollAreaVariants } from "./variants";
+
+export type ScrollAreaVariantProps = VariantProps<typeof scrollAreaVariants>;
+
+export type ScrollAreaProps = ScrollAreaVariantProps &
+  ComponentPropsWithRef<"div"> & {
+    viewportClassName?: string;
+  };

package/src/ui/scroll-area/variants.ts

@@ -0,0 +1,44 @@
+import { cva } from "class-variance-authority";
+
+import {
+  zuiScrollAreaAppearances,
+  zuiScrollAreaBase,
+  zuiScrollAreaOrientations,
+  zuiScrollAreaShadows,
+  zuiScrollAreaSizes,
+  zuiScrollAreaVisibility,
+} from "../../design-system/scroll-area";
+
+export const scrollAreaVariants = cva(zuiScrollAreaBase, {
+  variants: {
+    appearance: zuiScrollAreaAppearances,
+    orientation: zuiScrollAreaOrientations,
+    scrollbar: zuiScrollAreaVisibility,
+    shadow: zuiScrollAreaShadows,
+    size: zuiScrollAreaSizes,
+  },
+  compoundVariants: [
+    {
+      scrollbar: "always",
+      orientation: "vertical",
+      class: "overflow-x-hidden overflow-y-scroll",
+    },
+    {
+      scrollbar: "always",
+      orientation: "horizontal",
+      class: "overflow-x-scroll overflow-y-hidden",
+    },
+    {
+      scrollbar: "always",
+      orientation: "both",
+      class: "overflow-scroll",
+    },
+  ],
+  defaultVariants: {
+    appearance: "default",
+    orientation: "vertical",
+    scrollbar: "auto",
+    shadow: false,
+    size: "md",
+  },
+});

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

@@ -0,0 +1,16 @@
+import type { Transition } from "framer-motion";
+
+/** Entrance presets for animated timeline items (fade + slide, connector draw). */
+export type TimelineTransition = "none" | "default" | "smooth" | "slow";
+
+export type TimelineTransitionPresets = Record<TimelineTransition, Transition>;
+
+export const timelineItemTransitionPresets: TimelineTransitionPresets = {
+  none: { duration: 0 },
+  default: { duration: 0.4, ease: [0.22, 1, 0.36, 1] },
+  smooth: { duration: 0.55, ease: [0.22, 1, 0.36, 1] },
+  slow: { duration: 0.8, ease: [0.4, 0, 0.2, 1] },
+};
+
+/** Default per-item entrance delay multiplier (seconds) for staggered reveals. */
+export const TIMELINE_DEFAULT_STAGGER = 0.08;

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

@@ -0,0 +1,22 @@
+"use client";
+
+export {
+  Timeline,
+  TimelineContent,
+  TimelineDescription,
+  TimelineIndicator,
+  TimelineTitle,
+} from "../timeline-base";
+export { TimelineItem } from "./timeline-item-animated";
+export type {
+  TimelineAnimatedProps,
+  TimelineItemAnimatedProps,
+} from "./types";
+export {
+  TIMELINE_DEFAULT_STAGGER,
+  timelineItemTransitionPresets,
+} from "./animations";
+export type {
+  TimelineTransition,
+  TimelineTransitionPresets,
+} from "./animations";

package/src/ui/timeline/animated/timeline-item-animated.tsx

@@ -0,0 +1,76 @@
+"use client";
+
+import { useMemo } from "react";
+import { motion, useReducedMotion } from "framer-motion";
+
+import { cn } from "../../../lib/utils";
+
+import {
+  TimelineItemContext,
+  useTimelineContext,
+  useTimelineIndex,
+} from "../timeline-base";
+import type { TimelineItemCtx } from "../types";
+import {
+  timelineConnectorVariants,
+  timelineItemVariants,
+} from "../variants";
+import {
+  TIMELINE_DEFAULT_STAGGER,
+  timelineItemTransitionPresets,
+} from "./animations";
+import type { TimelineItemAnimatedProps } from "./types";
+
+export function TimelineItem({
+  className,
+  children,
+  transitionVariant = "default",
+  stagger = TIMELINE_DEFAULT_STAGGER,
+  ref,
+  ...rest
+}: TimelineItemAnimatedProps & { ref?: React.Ref<HTMLLIElement> }) {
+  const { size, total } = useTimelineContext("TimelineItem");
+  const index = useTimelineIndex("TimelineItem");
+  const isLast = index === total - 1;
+  const itemCtx = useMemo<TimelineItemCtx>(
+    () => ({ index, isLast }),
+    [index, isLast],
+  );
+
+  const reducedMotion = useReducedMotion();
+  const motionless = transitionVariant === "none" || Boolean(reducedMotion);
+  const transition = timelineItemTransitionPresets[transitionVariant];
+  const delay = index * stagger;
+
+  return (
+    <TimelineItemContext.Provider value={itemCtx}>
+      <motion.li
+        ref={ref}
+        data-slot="timeline-item"
+        data-last={isLast ? "" : undefined}
+        className={cn(timelineItemVariants(), className)}
+        initial={motionless ? false : { opacity: 0, y: 12 }}
+        whileInView={motionless ? undefined : { opacity: 1, y: 0 }}
+        viewport={{ once: true, amount: 0.35 }}
+        transition={{ ...transition, delay }}
+        {...rest}
+      >
+        {!isLast ? (
+          <motion.span
+            aria-hidden="true"
+            data-slot="timeline-connector"
+            className={timelineConnectorVariants({ size })}
+            style={{ originY: 0 }}
+            initial={motionless ? false : { scaleY: 0, x: "-50%" }}
+            whileInView={motionless ? undefined : { scaleY: 1, x: "-50%" }}
+            viewport={{ once: true, amount: 0.35 }}
+            transition={{ ...transition, delay: delay + 0.12 }}
+          />
+        ) : null}
+        {children}
+      </motion.li>
+    </TimelineItemContext.Provider>
+  );
+}
+
+TimelineItem.displayName = "TimelineItem";

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

@@ -0,0 +1,21 @@
+import type { TimelineItemProps, TimelineProps } from "../types";
+import type { TimelineTransition } from "./animations";
+
+export type TimelineAnimatedProps = TimelineProps;
+
+/** Motion `li` uses different handler types than some React DOM events. */
+export type TimelineItemMotionConflictProps =
+  | "onAnimationStart"
+  | "onDrag"
+  | "onDragEnd"
+  | "onDragStart";
+
+export type TimelineItemAnimatedProps = Omit<
+  TimelineItemProps,
+  TimelineItemMotionConflictProps
+> & {
+  /** Entrance easing/duration preset. `none` renders without motion. */
+  transitionVariant?: TimelineTransition;
+  /** Per-item entrance delay multiplier in seconds (index × stagger). */
+  stagger?: number;
+};

package/src/ui/timeline/index.ts

@@ -0,0 +1,30 @@
+"use client";
+
+export {
+  Timeline,
+  TimelineContent,
+  TimelineDescription,
+  TimelineIndicator,
+  TimelineItem,
+  TimelineTitle,
+} from "./timeline";
+export type {
+  TimelineAppearance,
+  TimelineContentProps,
+  TimelineDescriptionProps,
+  TimelineIndicatorProps,
+  TimelineItemProps,
+  TimelineProps,
+  TimelineSize,
+  TimelineTitleProps,
+  TimelineTransition,
+} from "./types";
+export {
+  timelineConnectorVariants,
+  timelineContentVariants,
+  timelineDescriptionVariants,
+  timelineIndicatorVariants,
+  timelineItemVariants,
+  timelineTitleVariants,
+  timelineVariants,
+} from "./variants";

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

@@ -0,0 +1,232 @@
+"use client";
+
+import {
+  Children,
+  createContext,
+  isValidElement,
+  useContext,
+  useMemo,
+} from "react";
+
+import { cn } from "../../lib/utils";
+
+import type {
+  TimelineContentProps,
+  TimelineCtx,
+  TimelineDescriptionProps,
+  TimelineIndicatorProps,
+  TimelineItemCtx,
+  TimelineItemProps,
+  TimelineProps,
+  TimelineSize,
+  TimelineTitleProps,
+} from "./types";
+import {
+  timelineConnectorVariants,
+  timelineContentVariants,
+  timelineDescriptionVariants,
+  timelineIndicatorVariants,
+  timelineItemVariants,
+  timelineTitleVariants,
+  timelineVariants,
+} from "./variants";
+
+const TimelineContext = createContext<TimelineCtx | null>(null);
+
+const TimelineIndexContext = createContext<number | null>(null);
+
+export const TimelineItemContext = createContext<TimelineItemCtx | null>(null);
+
+export function useTimelineContext(component: string): TimelineCtx {
+  const ctx = useContext(TimelineContext);
+  if (!ctx) {
+    throw new Error(`${component} must be used within <Timeline>`);
+  }
+  return ctx;
+}
+
+export function useTimelineIndex(component: string): number {
+  const index = useContext(TimelineIndexContext);
+  if (index === null) {
+    throw new Error(`${component} must be used within <Timeline>`);
+  }
+  return index;
+}
+
+function useTimelineSize(): TimelineSize {
+  return useContext(TimelineContext)?.size ?? "md";
+}
+
+function useTimelineIsLast(): boolean {
+  return useContext(TimelineItemContext)?.isLast ?? false;
+}
+
+export function Timeline({
+  appearance = "default",
+  size = "md",
+  className,
+  children,
+  ref,
+  ...rest
+}: TimelineProps) {
+  const items = useMemo(
+    () => Children.toArray(children).filter(isValidElement),
+    [children],
+  );
+  const ctx = useMemo<TimelineCtx>(
+    () => ({
+      appearance: appearance ?? "default",
+      size: size ?? "md",
+      total: items.length,
+    }),
+    [appearance, size, items.length],
+  );
+
+  return (
+    <TimelineContext.Provider value={ctx}>
+      <ol
+        ref={ref}
+        data-slot="timeline"
+        className={cn(timelineVariants(), "m-0 list-none p-0", className)}
+        {...rest}
+      >
+        {items.map((child, index) => (
+          <TimelineIndexContext.Provider key={child.key} value={index}>
+            {child}
+          </TimelineIndexContext.Provider>
+        ))}
+      </ol>
+    </TimelineContext.Provider>
+  );
+}
+
+Timeline.displayName = "Timeline";
+
+export function TimelineItem({
+  className,
+  children,
+  ref,
+  ...rest
+}: TimelineItemProps) {
+  const { size, total } = useTimelineContext("TimelineItem");
+  const index = useTimelineIndex("TimelineItem");
+  const isLast = index === total - 1;
+  const itemCtx = useMemo<TimelineItemCtx>(
+    () => ({ index, isLast }),
+    [index, isLast],
+  );
+
+  return (
+    <TimelineItemContext.Provider value={itemCtx}>
+      <li
+        ref={ref}
+        data-slot="timeline-item"
+        data-last={isLast ? "" : undefined}
+        className={cn(timelineItemVariants(), className)}
+        {...rest}
+      >
+        {!isLast ? (
+          <span
+            aria-hidden="true"
+            data-slot="timeline-connector"
+            className={timelineConnectorVariants({ size })}
+          />
+        ) : null}
+        {children}
+      </li>
+    </TimelineItemContext.Provider>
+  );
+}
+
+TimelineItem.displayName = "TimelineItem";
+
+export function TimelineIndicator({
+  className,
+  appearance,
+  children,
+  ref,
+  ...rest
+}: TimelineIndicatorProps & { ref?: React.Ref<HTMLDivElement> }) {
+  const { appearance: rootAppearance, size } =
+    useTimelineContext("TimelineIndicator");
+  return (
+    <div
+      ref={ref}
+      data-slot="timeline-indicator"
+      className={cn(
+        timelineIndicatorVariants({
+          appearance: appearance ?? rootAppearance,
+          size,
+        }),
+        className,
+      )}
+      {...rest}
+    >
+      {children}
+    </div>
+  );
+}
+
+TimelineIndicator.displayName = "TimelineIndicator";
+
+export function TimelineContent({
+  className,
+  children,
+  ref,
+  ...rest
+}: TimelineContentProps & { ref?: React.Ref<HTMLDivElement> }) {
+  const size = useTimelineSize();
+  const isLast = useTimelineIsLast();
+  return (
+    <div
+      ref={ref}
+      data-slot="timeline-content"
+      className={cn(
+        timelineContentVariants({ size }),
+        isLast && "pb-0",
+        className,
+      )}
+      {...rest}
+    >
+      {children}
+    </div>
+  );
+}
+
+TimelineContent.displayName = "TimelineContent";
+
+export function TimelineTitle({
+  className,
+  ref,
+  ...rest
+}: TimelineTitleProps & { ref?: React.Ref<HTMLDivElement> }) {
+  const size = useTimelineSize();
+  return (
+    <div
+      ref={ref}
+      data-slot="timeline-title"
+      className={cn(timelineTitleVariants({ size }), className)}
+      {...rest}
+    />
+  );
+}
+
+TimelineTitle.displayName = "TimelineTitle";
+
+export function TimelineDescription({
+  className,
+  ref,
+  ...rest
+}: TimelineDescriptionProps & { ref?: React.Ref<HTMLParagraphElement> }) {
+  const size = useTimelineSize();
+  return (
+    <p
+      ref={ref}
+      data-slot="timeline-description"
+      className={cn(timelineDescriptionVariants({ size }), className)}
+      {...rest}
+    />
+  );
+}
+
+TimelineDescription.displayName = "TimelineDescription";