Timeline Rail

1'use client';
2 
3import * as React from 'react';
4import { cn } from '@/lib/utils';
5 
6type AnchorOrButton =
7  | ({
8      href: string;
9      onClick?: never;
10    } & React.AnchorHTMLAttributes<HTMLAnchorElement>)
11  | ({
12      href?: undefined;
13      onClick?: React.MouseEventHandler<HTMLButtonElement>;
14    } & React.ButtonHTMLAttributes<HTMLButtonElement>);
15 
16export type TimelineItem = {
17  /** Main small label shown near the dot (e.g., “headset”) */
18  label?: string;
19  /** Secondary label shown under the rail (e.g., “1910”) */
20  caption?: string;
21  /** Is this item emphasized (darker dot/rail before it) */
22  active?: boolean;
23} & AnchorOrButton;
24 
25export type TimelineRailProps = {
26  /** Items in left→right order */
27  items: TimelineItem[];
28 
29  /** Size density (dot size + vertical offsets) */
30  size?: 'sm' | 'md';
31 
32  /** Visually emphasize the rail up to the last `active` item */
33  emphasizeActiveTrail?: boolean;
34 
35  /** Angle for the top labels (deg). use 0 for straight text. */
36  labelAngle?: number;
37 
38  /** Layout spacing between dots (Tailwind gap classes allowed). */
39  gapClassName?: string;
40 
41  /** Visual customization */
42  lineColorClass?: string; // rail color
43  lineThickness?: number; // pixels
44  dotClass?: string; // dot color/class
45  dotActiveClass?: string; // active dot color/class
46 
47  /** Slots for precise control */
48  className?: string; // root
49  railClassName?: string; // the line element
50  itemClassName?: string; // <li>
51  labelClassName?: string; // top tiny label
52  captionClassName?: string; // bottom caption
53 
54  /** Optional renderers to fully control content */
55  renderLabel?: (item: TimelineItem, index: number) => React.ReactNode;
56  renderCaption?: (item: TimelineItem, index: number) => React.ReactNode;
57};
58 
59/** SRP: purely visual timeline rail. No data fetching or state kept here. */
60export default function TimelineRail({
61  items,
62  size = 'md',
63  emphasizeActiveTrail = true,
64  labelAngle = 45,
65  gapClassName = 'gap-14',
66  lineColorClass = 'bg-zinc-300 dark:bg-zinc-700',
67  lineThickness = 6,
68  dotClass = 'bg-zinc-400 dark:bg-zinc-600',
69  dotActiveClass = 'bg-zinc-900 dark:bg-zinc-100',
70  className,
71  railClassName,
72  itemClassName,
73  labelClassName,
74  captionClassName,
75  renderLabel,
76  renderCaption,
77}: TimelineRailProps) {
78  // compute last active index (for emphasized rail)
79  const lastActive = React.useMemo(() => {
80    let idx = -1;
81    items.forEach((it, i) => {
82      if (it.active) idx = i;
83    });
84    return idx;
85  }, [items]);
86 
87// … truncated