@zentauri-ui/zentauri-components 1.7.5 → 1.7.7

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

package/src/ui/timeline/timeline.test.tsx

@@ -0,0 +1,262 @@
+import { createRef } from "react";
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import {
+  Timeline,
+  TimelineContent,
+  TimelineDescription,
+  TimelineIndicator,
+  TimelineItem,
+  TimelineTitle,
+} from "./timeline";
+
+describe("Timeline", () => {
+  it("should expose displayName", () => {
+    expect(Timeline.displayName).toBe("Timeline");
+    expect(TimelineItem.displayName).toBe("TimelineItem");
+    expect(TimelineIndicator.displayName).toBe("TimelineIndicator");
+    expect(TimelineContent.displayName).toBe("TimelineContent");
+    expect(TimelineTitle.displayName).toBe("TimelineTitle");
+    expect(TimelineDescription.displayName).toBe("TimelineDescription");
+  });
+
+  it("should stamp data-slot on timeline root and use ordered list markup", () => {
+    render(
+      <Timeline>
+        <TimelineItem>
+          <TimelineIndicator />
+          <TimelineContent>
+            <TimelineTitle>One</TimelineTitle>
+          </TimelineContent>
+        </TimelineItem>
+      </Timeline>,
+    );
+    const root = document.querySelector('[data-slot="timeline"]');
+    expect(root).toBeTruthy();
+    expect(root?.tagName).toBe("OL");
+    expect(document.querySelector('[data-slot="timeline-item"]')?.tagName).toBe(
+      "LI",
+    );
+  });
+
+  it("should apply default indicator appearance from the root", () => {
+    render(
+      <Timeline>
+        <TimelineItem>
+          <TimelineIndicator />
+          <TimelineContent>
+            <TimelineTitle>Cart</TimelineTitle>
+          </TimelineContent>
+        </TimelineItem>
+      </Timeline>,
+    );
+    const indicator = document.querySelector(
+      '[data-slot="timeline-indicator"]',
+    );
+    expect(indicator?.className).toContain(
+      "--zui-timeline-indicator-default-border",
+    );
+  });
+
+  it("should inherit appearance from the Timeline root", () => {
+    render(
+      <Timeline appearance="sky">
+        <TimelineItem>
+          <TimelineIndicator />
+          <TimelineContent>
+            <TimelineTitle>Sky</TimelineTitle>
+          </TimelineContent>
+        </TimelineItem>
+      </Timeline>,
+    );
+    const indicator = document.querySelector(
+      '[data-slot="timeline-indicator"]',
+    );
+    expect(indicator?.className).toContain(
+      "--zui-timeline-indicator-sky-border",
+    );
+  });
+
+  it("should let an indicator override the root appearance", () => {
+    render(
+      <Timeline appearance="sky">
+        <TimelineItem>
+          <TimelineIndicator />
+          <TimelineContent>
+            <TimelineTitle>Default sky</TimelineTitle>
+          </TimelineContent>
+        </TimelineItem>
+        <TimelineItem>
+          <TimelineIndicator appearance="rose" />
+          <TimelineContent>
+            <TimelineTitle>Override rose</TimelineTitle>
+          </TimelineContent>
+        </TimelineItem>
+      </Timeline>,
+    );
+    const indicators = document.querySelectorAll(
+      '[data-slot="timeline-indicator"]',
+    );
+    expect(indicators[0]?.className).toContain(
+      "--zui-timeline-indicator-sky-border",
+    );
+    expect(indicators[1]?.className).toContain(
+      "--zui-timeline-indicator-rose-border",
+    );
+  });
+
+  it("should pass size from Timeline context to indicators", () => {
+    render(
+      <Timeline size="sm">
+        <TimelineItem>
+          <TimelineIndicator />
+          <TimelineContent>
+            <TimelineTitle>Small</TimelineTitle>
+          </TimelineContent>
+        </TimelineItem>
+      </Timeline>,
+    );
+    const indicator = document.querySelector(
+      '[data-slot="timeline-indicator"]',
+    );
+    expect(indicator?.className).toMatch(/size-5/);
+  });
+
+  it("should render a connector on every item except the last", () => {
+    render(
+      <Timeline>
+        <TimelineItem>
+          <TimelineIndicator />
+          <TimelineContent>
+            <TimelineTitle>First</TimelineTitle>
+          </TimelineContent>
+        </TimelineItem>
+        <TimelineItem>
+          <TimelineIndicator />
+          <TimelineContent>
+            <TimelineTitle>Second</TimelineTitle>
+          </TimelineContent>
+        </TimelineItem>
+        <TimelineItem>
+          <TimelineIndicator />
+          <TimelineContent>
+            <TimelineTitle>Third</TimelineTitle>
+          </TimelineContent>
+        </TimelineItem>
+      </Timeline>,
+    );
+    const connectors = document.querySelectorAll(
+      '[data-slot="timeline-connector"]',
+    );
+    expect(connectors).toHaveLength(2);
+    const items = document.querySelectorAll('[data-slot="timeline-item"]');
+    expect(items[2]?.hasAttribute("data-last")).toBe(true);
+    expect(items[0]?.hasAttribute("data-last")).toBe(false);
+  });
+
+  it("should drop bottom padding on the last item's content", () => {
+    render(
+      <Timeline>
+        <TimelineItem>
+          <TimelineIndicator />
+          <TimelineContent data-testid="first">
+            <TimelineTitle>First</TimelineTitle>
+          </TimelineContent>
+        </TimelineItem>
+        <TimelineItem>
+          <TimelineIndicator />
+          <TimelineContent data-testid="last">
+            <TimelineTitle>Last</TimelineTitle>
+          </TimelineContent>
+        </TimelineItem>
+      </Timeline>,
+    );
+    expect(screen.getByTestId("first").className).toMatch(/pb-6/);
+    expect(screen.getByTestId("last").className).toMatch(/pb-0/);
+    expect(screen.getByTestId("last").className).not.toMatch(/pb-6/);
+  });
+
+  it("should render custom indicator children", () => {
+    render(
+      <Timeline>
+        <TimelineItem>
+          <TimelineIndicator>✓</TimelineIndicator>
+          <TimelineContent>
+            <TimelineTitle>Check</TimelineTitle>
+          </TimelineContent>
+        </TimelineItem>
+      </Timeline>,
+    );
+    expect(screen.getByText("✓")).toBeInTheDocument();
+  });
+
+  it("should stamp data-slot on content, title and description", () => {
+    render(
+      <Timeline>
+        <TimelineItem>
+          <TimelineIndicator />
+          <TimelineContent data-testid="c">
+            <TimelineTitle data-testid="t">T</TimelineTitle>
+            <TimelineDescription data-testid="d">D</TimelineDescription>
+          </TimelineContent>
+        </TimelineItem>
+      </Timeline>,
+    );
+    expect(document.querySelector('[data-slot="timeline-content"]')).toBe(
+      screen.getByTestId("c"),
+    );
+    expect(document.querySelector('[data-slot="timeline-title"]')).toBe(
+      screen.getByTestId("t"),
+    );
+    expect(document.querySelector('[data-slot="timeline-description"]')).toBe(
+      screen.getByTestId("d"),
+    );
+  });
+
+  it("should forward ref on Timeline", () => {
+    const ref = createRef<HTMLOListElement>();
+    render(
+      <Timeline ref={ref}>
+        <TimelineItem>
+          <TimelineIndicator />
+          <TimelineContent>
+            <TimelineTitle>A</TimelineTitle>
+          </TimelineContent>
+        </TimelineItem>
+      </Timeline>,
+    );
+    expect(ref.current?.getAttribute("data-slot")).toBe("timeline");
+  });
+
+  it("should forward ref on TimelineItem", () => {
+    const ref = createRef<HTMLLIElement>();
+    render(
+      <Timeline>
+        <TimelineItem ref={ref}>
+          <TimelineIndicator />
+          <TimelineContent>
+            <TimelineTitle>A</TimelineTitle>
+          </TimelineContent>
+        </TimelineItem>
+      </Timeline>,
+    );
+    expect(ref.current?.getAttribute("data-slot")).toBe("timeline-item");
+  });
+
+  it("should throw when TimelineItem is used outside Timeline", () => {
+    expect(() =>
+      render(
+        <TimelineItem>
+          <TimelineIndicator />
+        </TimelineItem>,
+      ),
+    ).toThrow(/must be used within <Timeline>/);
+  });
+
+  it("should throw when TimelineIndicator is used outside Timeline", () => {
+    expect(() => render(<TimelineIndicator />)).toThrow(
+      /must be used within <Timeline>/,
+    );
+  });
+});

package/src/ui/timeline/timeline.tsx

@@ -0,0 +1,24 @@
+// timeline.tsx — default static entry (no framer-motion)
+import {
+  Timeline as TimelineBase,
+  TimelineContent,
+  TimelineDescription,
+  TimelineIndicator,
+  TimelineItem,
+  TimelineTitle,
+} from "./timeline-base";
+import type { TimelineProps } from "./types";
+
+export function Timeline(props: TimelineProps) {
+  return <TimelineBase {...props} />;
+}
+
+Timeline.displayName = "Timeline";
+
+export {
+  TimelineContent,
+  TimelineDescription,
+  TimelineIndicator,
+  TimelineItem,
+  TimelineTitle,
+};