@syscore/ui-library 1.27.3 → 2.0.0

package/client/components/ui/timeline.tsx

@@ -0,0 +1,181 @@
+import * as React from "react";
+import { cn } from "@/lib/utils";
+
+// ─── Context ──────────────────────────────────────────────────────────────────
+
+interface TimelineContextValue {
+  direction: "vertical" | "horizontal";
+  side: "start" | "end" | "alternate";
+  align: "center" | "start";
+  density: "default" | "compact";
+}
+
+const TimelineContext = React.createContext<TimelineContextValue>({
+  direction: "vertical",
+  side: "alternate",
+  align: "center",
+  density: "default",
+});
+
+// ─── Timeline Root ────────────────────────────────────────────────────────────
+
+export interface TimelineProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * Layout direction.
+   * - "vertical"   → items stack top-to-bottom (default)
+   * - "horizontal" → items flow left-to-right
+   */
+  direction?: "vertical" | "horizontal";
+  /**
+   * Which side content renders on relative to the stem.
+   * - "alternate" → alternates left / right (default)
+   * - "end"       → all content on the right (vertical) or below (horizontal)
+   * - "start"     → all content on the left (vertical) or above (horizontal)
+   */
+  side?: "start" | "end" | "alternate";
+  /**
+   * Vertical alignment of content inside each item.
+   * - "center" → content is centered on the dot (default)
+   * - "start"  → content aligns to the top of the dot
+   */
+  align?: "center" | "start";
+  /**
+   * Reduces spacing between items.
+   */
+  density?: "default" | "compact";
+}
+
+const Timeline = React.forwardRef<HTMLDivElement, TimelineProps>(
+  (
+    {
+      className,
+      children,
+      direction = "vertical",
+      side = "alternate",
+      align = "center",
+      density = "default",
+      ...props
+    },
+    ref
+  ) => (
+    <TimelineContext.Provider value={{ direction, side, align, density }}>
+      <div
+        ref={ref}
+        className={cn(
+          "timeline",
+          direction === "horizontal" && "timeline--horizontal",
+          `timeline--side-${side}`,
+          `timeline--align-${align}`,
+          density === "compact" && "timeline--compact",
+          className
+        )}
+        {...props}
+      >
+        {children}
+      </div>
+    </TimelineContext.Provider>
+  )
+);
+Timeline.displayName = "Timeline";
+
+// ─── TimelineItem ─────────────────────────────────────────────────────────────
+
+export interface TimelineItemProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * Background color of the dot — any CSS color or var() token.
+   */
+  dotColor?: string;
+  /**
+   * Size of the dot.
+   * - "x-small" → 12px
+   * - "small"   → 16px  (default)
+   * - "default" → 24px
+   * - "large"   → 32px
+   * - "x-large" → 40px
+   */
+  size?: "x-small" | "small" | "default" | "large" | "x-large";
+  /**
+   * When true the dot background is filled with `dotColor`
+   * (instead of just a border ring).
+   */
+  fillDot?: boolean;
+  /**
+   * Completely hides the dot and stem connector.
+   */
+  hideDot?: boolean;
+  /**
+   * Icon rendered inside the dot. Pass any React node.
+   * For best results use with size="large" or size="x-large".
+   */
+  icon?: React.ReactNode;
+  /**
+   * Content rendered on the opposite side of the stem from the main content.
+   * Equivalent to Vuetify's v-slot:opposite.
+   */
+  opposite?: React.ReactNode;
+}
+
+const TimelineItem = React.forwardRef<HTMLDivElement, TimelineItemProps>(
+  (
+    {
+      className,
+      children,
+      dotColor,
+      size = "small",
+      fillDot = false,
+      hideDot = false,
+      icon,
+      opposite,
+      ...props
+    },
+    ref
+  ) => {
+    const { align } = React.useContext(TimelineContext);
+
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          "timeline-item",
+          `timeline-item--size-${size}`,
+          fillDot && "timeline-item--fill-dot",
+          hideDot && "timeline-item--hide-dot",
+          align === "start" && "timeline-item--align-start",
+          className
+        )}
+        {...props}
+      >
+        {/* Opposite slot */}
+        <div className="timeline-item-opposite">
+          {opposite}
+        </div>
+
+        {/* Stem + dot column */}
+        <div className="timeline-item-stem">
+          <div className="timeline-item-stem-line timeline-item-stem-line--before" />
+          {!hideDot && (
+            <div
+              className="timeline-item-dot"
+              style={dotColor ? { backgroundColor: dotColor, borderColor: dotColor } : undefined}
+            >
+              {icon && (
+                <span className="timeline-item-dot-icon">{icon}</span>
+              )}
+            </div>
+          )}
+          <div className="timeline-item-stem-line timeline-item-stem-line--after" />
+        </div>
+
+        {/* Main content */}
+        <div className="timeline-item-body">
+          {children}
+        </div>
+      </div>
+    );
+  }
+);
+TimelineItem.displayName = "TimelineItem";
+
+// ─── Exports ──────────────────────────────────────────────────────────────────
+
+export { Timeline, TimelineItem };