@boxcustodia/library 2.0.0-alpha.2 → 2.0.0-alpha.20

package/src/components/timeline/timeline.stories.tsx

@@ -0,0 +1,364 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import {
+  GitCompareArrowsIcon,
+  GitForkIcon,
+  GitMergeIcon,
+  GitPullRequestArrowIcon,
+} from "lucide-react";
+import { useState } from "react";
+import { Tag } from "../tag/tag";
+import {
+  Timeline,
+  TimelineContent,
+  TimelineDate,
+  TimelineHeader,
+  TimelineIndicator,
+  TimelineItem,
+  TimelineRoot,
+  TimelineSeparator,
+  TimelineTitle,
+} from "./timeline";
+
+/**
+ * Vertical or horizontal timeline that highlights progress up to an active step.
+ * Use the composite `Timeline` for simple item lists, or compose primitives
+ * (`TimelineRoot`, `TimelineItem`, `TimelineHeader`, `TimelineTitle`, `TimelineDate`,
+ * `TimelineIndicator`, `TimelineSeparator`, `TimelineContent`) for full control.
+ * The `value` / `defaultValue` prop marks the active step — every item with
+ * `step <= value` renders as completed.
+ */
+const meta: Meta<typeof Timeline> = {
+  title: "Components/Timeline",
+  component: Timeline,
+  args: {
+    defaultValue: 2,
+    items: [
+      {
+        date: "Mar 15, 2024",
+        title: "Project kickoff",
+        content: "Initial planning and team alignment session.",
+      },
+      {
+        date: "Mar 22, 2024",
+        title: "Design review",
+        content: "First round of feedback on wireframes.",
+      },
+      {
+        date: "Apr 02, 2024",
+        title: "Development",
+        content: "Implementation of core features begins.",
+      },
+      {
+        date: "Apr 18, 2024",
+        title: "Launch",
+        content: "Public release and marketing rollout.",
+      },
+    ],
+  },
+  parameters: {
+    layout: "centered",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Timeline>;
+
+export const Default: Story = {
+  render: (args) => (
+    <div className="w-[400px]">
+      <Timeline {...args} />
+    </div>
+  ),
+};
+
+export const Horizontal: Story = {
+  args: {
+    orientation: "horizontal",
+  },
+  render: (args) => (
+    <div className="w-full">
+      <Timeline {...args} />
+    </div>
+  ),
+};
+
+/**
+ * Controlled timeline — external state drives which step is active.
+ */
+export const Controlled: Story = {
+  render: (args) => {
+    const [value, setValue] = useState(1);
+    return (
+      <div className="flex w-[400px] flex-col gap-4">
+        <Timeline {...args} value={value} onValueChange={setValue} />
+        <div className="flex gap-2">
+          {args.items?.map((_, i) => (
+            <button
+              key={i}
+              type="button"
+              onClick={() => setValue(i + 1)}
+              className="rounded border px-3 py-1 text-sm"
+            >
+              Step {i + 1}
+            </button>
+          ))}
+        </div>
+      </div>
+    );
+  },
+};
+
+/**
+ * Custom indicators with icons inside larger dots, and the date moved below
+ * the description via primitives composed in `description`. Override the
+ * `indicator`, `separator`, `item` and `title` slots in `classNames` to
+ * retune offsets when the dot size changes.
+ */
+export const WithIndicator: Story = {
+  args: {
+    defaultValue: 3,
+    className: "w-full max-w-md",
+    classNames: {
+      item: "group-data-[orientation=vertical]/timeline:ms-10",
+      title: "mt-0.5",
+      indicator:
+        "bg-primary/10 group-data-completed/timeline-item:bg-primary group-data-completed/timeline-item:text-primary-foreground flex size-6 items-center justify-center border-none group-data-[orientation=vertical]/timeline:-left-7",
+      separator:
+        "group-data-[orientation=vertical]/timeline:-left-7 group-data-[orientation=vertical]/timeline:h-[calc(100%-1.5rem-0.25rem)] group-data-[orientation=vertical]/timeline:translate-y-6.5",
+    },
+    items: [
+      {
+        title: "Forked Repository",
+        content: (
+          <>
+            Forked the repository to create a new branch for development.
+            <TimelineDate className="mt-2 mb-0">15 minutes ago</TimelineDate>
+          </>
+        ),
+        indicator: <GitForkIcon className="size-4" />,
+      },
+      {
+        title: "Pull Request Submitted",
+        content: (
+          <>
+            Submitted PR #342 with new feature implementation. Waiting for code
+            review.
+            <TimelineDate className="mt-2 mb-0">10 minutes ago</TimelineDate>
+          </>
+        ),
+        indicator: <GitPullRequestArrowIcon className="size-3.5" />,
+      },
+      {
+        title: (
+          <span className="inline-flex items-center gap-2">
+            Comparing Branches
+            <Tag variant="error">Build failed</Tag>
+          </span>
+        ),
+        content: (
+          <>
+            CI build failed on the feature branch. Tests are red — review
+            required before merge.
+            <TimelineDate className="mt-2 mb-0">5 minutes ago</TimelineDate>
+          </>
+        ),
+        indicator: <GitCompareArrowsIcon className="size-3.5" />,
+      },
+      {
+        title: "Merged Branch",
+        content: (
+          <>
+            Merged the feature branch into the main branch. Ready for
+            deployment.
+            <TimelineDate className="mt-2 mb-0">Just now</TimelineDate>
+          </>
+        ),
+        indicator: <GitMergeIcon className="size-3.5" />,
+      },
+    ],
+  },
+};
+
+/**
+ * Custom content in `description` — pass any ReactNode to render rich layouts
+ * (links, lists, badges, avatars) inside each item.
+ */
+export const CustomContent: Story = {
+  args: {
+    defaultValue: 2,
+    items: [
+      {
+        date: "Mar 15, 2024",
+        title: "Pull request merged",
+        content: (
+          <div className="flex flex-col gap-2">
+            <p>
+              <a
+                href="#"
+                className="font-medium text-foreground underline underline-offset-2"
+              >
+                #482 — Add Timeline component
+              </a>{" "}
+              merged into <code className="text-xs">main</code>.
+            </p>
+            <div className="flex flex-wrap gap-1">
+              <span className="rounded-md bg-success/10 px-2 py-0.5 text-xs font-medium text-success">
+                +1.2k
+              </span>
+              <span className="rounded-md bg-error/10 px-2 py-0.5 text-xs font-medium text-error">
+                -34
+              </span>
+              <span className="rounded-md bg-muted px-2 py-0.5 text-xs font-medium">
+                6 files
+              </span>
+            </div>
+          </div>
+        ),
+      },
+      {
+        date: "Mar 22, 2024",
+        title: "Review requested",
+        content: (
+          <ul className="list-disc space-y-1 pl-4">
+            <li>Add stories covering horizontal orientation</li>
+            <li>Document the controlled API in the meta JSDoc</li>
+            <li>Verify line alignment in RTL mode</li>
+          </ul>
+        ),
+      },
+      {
+        date: "Apr 02, 2024",
+        title: "Released",
+        content: (
+          <p>
+            Shipped in{" "}
+            <code className="rounded bg-muted px-1 py-0.5 text-xs">
+              v2.0.0-alpha.15
+            </code>
+            . See the{" "}
+            <a
+              href="#"
+              className="font-medium text-foreground underline underline-offset-2"
+            >
+              changelog
+            </a>
+            .
+          </p>
+        ),
+      },
+    ],
+  },
+};
+
+const roadmap = [
+  {
+    date: "Jan 2025",
+    title: "AI Engine Integration",
+    content:
+      "Deep integration of advanced LLMs for real-time code generation and context-aware suggestions.",
+  },
+  {
+    date: "Feb 2025",
+    title: "Collaborative Editing",
+    content:
+      "Multi-user real-time collaboration with shared cursors and instant synchronization across workspaces.",
+  },
+  {
+    date: "Mar 2025",
+    title: "Visual Theme Builder",
+    content:
+      "Interactive interface for creating and managing custom design systems with automated CSS variable generation.",
+  },
+  {
+    date: "Apr 2025",
+    title: "Enterprise Security",
+    content:
+      "Role-based access control, SOC2 compliance audit, and enhanced data encryption protocols.",
+  },
+];
+
+const milestones = [
+  {
+    date: "Jan 2024",
+    title: "Seed Funding",
+    content: "$2M raised to kick off product development.",
+  },
+  {
+    date: "Mar 2024",
+    title: "Product MVP",
+    content: "First working version shipped to beta testers.",
+  },
+  {
+    date: "May 2024",
+    title: "First Client",
+    content: "Signed first enterprise deal with a Fortune 500.",
+  },
+  {
+    date: "Jul 2024",
+    title: "Series A",
+    content: "$18M round led by Accel Partners.",
+  },
+  {
+    date: "Sep 2024",
+    title: "Global Expansion",
+    content: "Opened offices in London and Singapore.",
+  },
+];
+
+export const DateLeft: Story = {
+  args: {
+    variant: "date-left",
+    defaultValue: 2,
+    className: "w-full max-w-md",
+    items: roadmap,
+  },
+};
+
+export const Alternate: Story = {
+  args: {
+    variant: "alternate",
+    defaultValue: 3,
+    className: "w-[24rem]",
+    items: milestones,
+  },
+};
+
+/**
+ * Build the timeline manually with primitives when you need custom slots,
+ * extra markup, or conditional content per step.
+ */
+export const Primitive: Story = {
+  render: () => (
+    <div className="w-[400px]">
+      <TimelineRoot defaultValue={2}>
+        <TimelineItem step={1}>
+          <TimelineHeader>
+            <TimelineDate>Mar 15, 2024</TimelineDate>
+            <TimelineTitle>Kickoff</TimelineTitle>
+          </TimelineHeader>
+          <TimelineIndicator />
+          <TimelineSeparator />
+          <TimelineContent>Project planning starts.</TimelineContent>
+        </TimelineItem>
+        <TimelineItem step={2}>
+          <TimelineHeader>
+            <TimelineDate>Apr 02, 2024</TimelineDate>
+            <TimelineTitle>Development</TimelineTitle>
+          </TimelineHeader>
+          <TimelineIndicator />
+          <TimelineSeparator />
+          <TimelineContent>Feature implementation in progress.</TimelineContent>
+        </TimelineItem>
+        <TimelineItem step={3}>
+          <TimelineHeader>
+            <TimelineDate>Apr 18, 2024</TimelineDate>
+            <TimelineTitle>Launch</TimelineTitle>
+          </TimelineHeader>
+          <TimelineIndicator />
+          <TimelineSeparator />
+          <TimelineContent>Public release.</TimelineContent>
+        </TimelineItem>
+      </TimelineRoot>
+    </div>
+  ),
+};

package/src/components/timeline/timeline.test.tsx

@@ -0,0 +1,207 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import {
+  Timeline,
+  TimelineContent,
+  TimelineDate,
+  TimelineHeader,
+  TimelineIndicator,
+  TimelineItem,
+  TimelineRoot,
+  TimelineSeparator,
+  TimelineTitle,
+} from "../../components";
+
+const defaultItems = [
+  { title: "Step 1", content: "Content 1", date: "Jan 1" },
+  { title: "Step 2", content: "Content 2", date: "Jan 2" },
+  { title: "Step 3", content: "Content 3", date: "Jan 3" },
+];
+
+describe("TimelineRoot", () => {
+  it("renders with data-slot='timeline'", () => {
+    render(<TimelineRoot />);
+    expect(
+      document.querySelector('[data-slot="timeline"]'),
+    ).toBeInTheDocument();
+  });
+
+  it("defaults to vertical orientation", () => {
+    render(<TimelineRoot />);
+    expect(document.querySelector('[data-slot="timeline"]')).toHaveAttribute(
+      "data-orientation",
+      "vertical",
+    );
+  });
+
+  it("sets data-orientation='horizontal'", () => {
+    render(<TimelineRoot orientation="horizontal" />);
+    expect(document.querySelector('[data-slot="timeline"]')).toHaveAttribute(
+      "data-orientation",
+      "horizontal",
+    );
+  });
+
+  it("applies className", () => {
+    render(<TimelineRoot className="custom-timeline" />);
+    expect(document.querySelector('[data-slot="timeline"]')).toHaveClass(
+      "custom-timeline",
+    );
+  });
+});
+
+describe("TimelineItem", () => {
+  it("renders with data-slot='timeline-item'", () => {
+    render(
+      <TimelineRoot>
+        <TimelineItem step={1} />
+      </TimelineRoot>,
+    );
+    expect(
+      document.querySelector('[data-slot="timeline-item"]'),
+    ).toBeInTheDocument();
+  });
+
+  it("sets data-completed on items where step <= activeStep", () => {
+    render(
+      <TimelineRoot defaultValue={2}>
+        <TimelineItem step={1} />
+        <TimelineItem step={2} />
+        <TimelineItem step={3} />
+      </TimelineRoot>,
+    );
+    const completed = document.querySelectorAll("[data-completed]");
+    expect(completed).toHaveLength(2);
+  });
+
+  it("does not set data-completed when step > activeStep", () => {
+    render(
+      <TimelineRoot defaultValue={1}>
+        <TimelineItem step={2} />
+      </TimelineRoot>,
+    );
+    expect(
+      document.querySelector('[data-slot="timeline-item"]'),
+    ).not.toHaveAttribute("data-completed");
+  });
+});
+
+describe("Timeline sub-primitive data-slots", () => {
+  function renderFull() {
+    return render(
+      <TimelineRoot>
+        <TimelineItem step={1}>
+          <TimelineHeader>
+            <TimelineTitle>Title</TimelineTitle>
+            <TimelineDate>Jan 1</TimelineDate>
+          </TimelineHeader>
+          <TimelineIndicator />
+          <TimelineSeparator />
+          <TimelineContent>Content</TimelineContent>
+        </TimelineItem>
+      </TimelineRoot>,
+    );
+  }
+
+  it("renders data-slot='timeline-header'", () => {
+    renderFull();
+    expect(
+      document.querySelector('[data-slot="timeline-header"]'),
+    ).toBeInTheDocument();
+  });
+
+  it("renders data-slot='timeline-title'", () => {
+    renderFull();
+    expect(
+      document.querySelector('[data-slot="timeline-title"]'),
+    ).toBeInTheDocument();
+  });
+
+  it("renders data-slot='timeline-date'", () => {
+    renderFull();
+    expect(
+      document.querySelector('[data-slot="timeline-date"]'),
+    ).toBeInTheDocument();
+  });
+
+  it("renders data-slot='timeline-content'", () => {
+    renderFull();
+    expect(
+      document.querySelector('[data-slot="timeline-content"]'),
+    ).toBeInTheDocument();
+  });
+
+  it("renders data-slot='timeline-indicator'", () => {
+    renderFull();
+    expect(
+      document.querySelector('[data-slot="timeline-indicator"]'),
+    ).toBeInTheDocument();
+  });
+
+  it("renders data-slot='timeline-separator'", () => {
+    renderFull();
+    expect(
+      document.querySelector('[data-slot="timeline-separator"]'),
+    ).toBeInTheDocument();
+  });
+});
+
+describe("Timeline composite", () => {
+  it("renders all item titles", () => {
+    render(<Timeline items={defaultItems} />);
+    expect(screen.getByText("Step 1")).toBeInTheDocument();
+    expect(screen.getByText("Step 2")).toBeInTheDocument();
+    expect(screen.getByText("Step 3")).toBeInTheDocument();
+  });
+
+  it("renders item content", () => {
+    render(<Timeline items={defaultItems} />);
+    expect(screen.getByText("Content 1")).toBeInTheDocument();
+  });
+
+  it("renders item dates", () => {
+    render(<Timeline items={defaultItems} />);
+    expect(screen.getByText("Jan 1")).toBeInTheDocument();
+  });
+
+  it("skips undefined title/content/date fields", () => {
+    render(<Timeline items={[{ title: undefined, content: undefined }]} />);
+    expect(
+      document.querySelector('[data-slot="timeline-item"]'),
+    ).toBeInTheDocument();
+  });
+
+  it("renders with variant='alternate'", () => {
+    render(<Timeline items={defaultItems} variant="alternate" />);
+    expect(screen.getByText("Step 1")).toBeInTheDocument();
+  });
+
+  it("renders with variant='date-left'", () => {
+    render(<Timeline items={defaultItems} variant="date-left" />);
+    expect(screen.getByText("Step 1")).toBeInTheDocument();
+  });
+
+  it("applies classNames.item to timeline items", () => {
+    render(
+      <Timeline
+        items={[{ title: "T1" }]}
+        classNames={{ item: "custom-item" }}
+      />,
+    );
+    expect(document.querySelector('[data-slot="timeline-item"]')).toHaveClass(
+      "custom-item",
+    );
+  });
+
+  it("applies classNames.content to content slots", () => {
+    render(
+      <Timeline
+        items={[{ content: "C1" }]}
+        classNames={{ content: "custom-content" }}
+      />,
+    );
+    expect(
+      document.querySelector('[data-slot="timeline-content"]'),
+    ).toHaveClass("custom-content");
+  });
+});