timeline.tsx

Overview

timeline.tsx is a React component module designed to create flexible, customizable timeline UI components. It provides both a basic Timeline component with context management for active steps and a more advanced CustomTimeline component that supports rich timeline nodes with icons, dates, titles, content, and customizable styles.

The file exports a set of reusable subcomponents (TimelineItem, TimelineIndicator, TimelineSeparator, etc.) that compose the timeline structure, along with context and hooks to manage active states and interactions.

This module is intended for use in React applications that require horizontal or vertical timelines with step progression and visual indicators.

Detailed Explanation

Context and Hook

TimelineContext

• Purpose: Holds the state of the current active step and a function to update it.

• Type: React Context with value type:

  {
    activeStep: number;
    setActiveStep: (step: number) => void;
  }
  

• Usage: Provides active step state to timeline child components.

useTimeline

• Description: Custom hook to consume TimelineContext.

• Throws: Error if used outside a Timeline provider.

• Returns: { activeStep, setActiveStep }.

Components

Timeline

• Props:

  • defaultValue?: number — initial active step (default: 1).

  • value?: number — controlled active step.

  • onValueChange?: (value: number) => void — callback when active step changes.

  • orientation?: 'horizontal' | 'vertical' — layout direction (default: 'vertical').

  • className?: string and other standard div HTML attributes.

• Functionality:

  • Manages active step state internally or controlled via props.

  • Provides context for child components.

  • Renders a div with orientation-based styling.

• Example:

  <Timeline defaultValue={1} orientation="horizontal" onValueChange={(step) => console.log(step)}>
    {/* TimelineItems here */}
  </Timeline>
  

TimelineContent

• Props: Standard div attributes plus optional className.

• Purpose: Container for timeline item content, styled with muted foreground and small text.

• Usage:

  <TimelineContent>
    Details or description about the timeline event.
  </TimelineContent>
  

TimelineDate

• Props:

  • asChild?: boolean — if true, renders using Radix UI Slot to pass props to child element.

  • Standard time element attributes.

• Purpose: Displays the date/time associated with a timeline event.

• Example:

  <TimelineDate>2023-06-15</TimelineDate>
  

TimelineHeader

• Props: Standard div attributes.

• Purpose: Container for timeline item header elements such as date and title.

• Usage:

  <TimelineHeader>
    <TimelineDate>June 15</TimelineDate>
    <TimelineTitle>Project Kickoff</TimelineTitle>
  </TimelineHeader>
  

TimelineIndicator

• Props:

  • asChild?: boolean (commented out, not used currently)

  • className?: string

  • children?: React.ReactNode

• Purpose: Visual indicator (circle) for each timeline step.

• Styling: Changes border and background color depending on completion and active state.

• Example:

  <TimelineIndicator>
    <Icon />
  </TimelineIndicator>
  

TimelineItem

• Props:

  • step: number — The step number of this item.

  • Standard div attributes.

• Functionality:

  • Uses useTimeline to determine if this step is active or completed.

  • Sets data-completed attribute if step is completed.

  • Applies layout and spacing styles according to orientation.

• Example:

  <TimelineItem step={2}>
    {/* Contents */}
  </TimelineItem>
  

TimelineSeparator

• Props: Standard div attributes.

• Purpose: Visual line separator between timeline items.

• Styling: Adjusts length and orientation based on timeline orientation.

• Example:

  <TimelineSeparator />
  

TimelineTitle

• Props: Standard h3 element attributes.

• Purpose: Displays the title text of a timeline item.

• Example:

  <TimelineTitle>Design Phase</TimelineTitle>
  

Advanced Component: CustomTimeline

• Props:

  • nodes: TimelineNode[] — Array of timeline node data.

  • activeStep?: number — Controlled active step.

  • nodeSize?: string | number — Size of the node indicator circle.

  • onStepChange?: (step: number, id: string | number) => void — Callback on step change.

  • orientation?: 'horizontal' | 'vertical' (default: 'horizontal').

  • lineStyle?: 'solid' | 'dashed' (default: 'solid').

  • lineColor?: string (default: CSS var).

  • indicatorColor?: string (default: CSS var).

  • defaultValue?: number (default: 1).

  • activeStyle?: TimelineIndicatorNodeProps — Styling overrides for active node.

  • Additional div attributes.

• TimelineNode interface:

  interface TimelineNode {
    id: string | number;
    title?: React.ReactNode;
    content?: React.ReactNode;
    date?: React.ReactNode;
    icon?: React.ReactNode;
    completed?: boolean;
    clickable?: boolean;
    activeStyle?: TimelineIndicatorNodeProps;
    nodeSize?: string | number;
    className?: string;
    // plus standard HTML div attributes except id/title/content keys
  }
  

• Functionality:

  • Manages internal or controlled active step state.

  • Renders a Timeline component with mapped TimelineItems representing each node.

  • Styles each node's indicator and separator based on completion and active state.

  • Supports click interaction to change active step.

  • Supports custom styles for active nodes (colors, sizes).

• Usage Example:

  const nodes = [
    { id: 1, title: 'Start', date: '2023-01-01', icon: <StartIcon />, completed: true },
    { id: 2, title: 'Middle', date: '2023-02-01', icon: <MiddleIcon /> },
    { id: 3, title: 'End', date: '2023-03-01', icon: <EndIcon />, clickable: false },
  ];
  
  <CustomTimeline
    nodes={nodes}
    activeStep={2}
    onStepChange={(step, id) => console.log('Step changed', step, id)}
    orientation="vertical"
    lineStyle="dashed"
  />
  

Important Implementation Details

• Context Usage: The Timeline component provides a React context TimelineContext to share active step state with timeline items and related components.

• Controlled vs Uncontrolled: Both Timeline and CustomTimeline support controlled (value / activeStep) and uncontrolled (defaultValue) usage.

• Orientation Styling: CSS classes and data-orientation attributes are used to switch between horizontal and vertical layouts dynamically.

• Dynamic Styling: The color and size of indicators and separators change based on whether nodes are active, completed, or inactive.

• Use of parseColorToRGBA: Converts CSS color strings to RGBA arrays for inline style manipulation, enabling transparency control and custom coloring.

• Radix UI Slot: TimelineDate optionally uses Radix UI's Slot component to allow rendering as a child element with inherited props.

• Accessibility: Aria attributes like aria-hidden="true" are applied to purely decorative elements (indicators, separators).

Interaction with Other Parts of the System

• Utility Imports:

  • cn from @/lib/utils: Utility for conditional classNames.

  • parseColorToRGBA from @/utils/common-util: Converts color strings to rgba arrays.

• Radix UI:

  • Uses @radix-ui/react-slot for flexible component composition.

• Styling:

  • Relies on TailwindCSS utility classes and custom data attributes for styling.

• Exported API:

  • This module exports the main timeline components and subcomponents for use in UI screens or other components requiring timeline visualizations.

Visual Diagram

componentDiagram
    component Timeline {
      +defaultValue?: number
      +value?: number
      +onValueChange?: (value: number) => void
      +orientation?: 'horizontal' | 'vertical'
    }
    component CustomTimeline {
      +nodes: TimelineNode[]
      +activeStep?: number
      +onStepChange?: (step: number, id: string|number) => void
      +orientation?: 'horizontal' | 'vertical'
      +lineStyle?: 'solid' | 'dashed'
      +lineColor?: string
      +indicatorColor?: string
    }
    component TimelineItem {
      +step: number
    }
    component TimelineIndicator
    component TimelineSeparator
    component TimelineHeader
    component TimelineDate
    component TimelineTitle
    component TimelineContent

    Timeline <|-- CustomTimeline
    Timeline o-- TimelineItem
    TimelineItem o-- TimelineIndicator
    TimelineItem o-- TimelineSeparator
    TimelineItem o-- TimelineHeader
    TimelineHeader o-- TimelineDate
    TimelineHeader o-- TimelineTitle
    TimelineItem o-- TimelineContent

Summary

The timeline.tsx file provides a comprehensive, flexible React timeline component suite that supports:

• Context-driven step activation.

• Horizontal or vertical orientation.

• Customizable indicators and separators.

• Rich timeline nodes with icons, titles, dates, and content.

• Controlled and uncontrolled usage patterns.

• Interactive step changes with callbacks.

It is designed for integration in React applications needing visual representation of sequential events or processes.

Exports

Example Usage Snippet

import { CustomTimeline } from './timeline';

const milestones = [
  { id: 'a', title: 'Start', date: 'Jan 1', icon: <StartIcon />, completed: true },
  { id: 'b', title: 'Middle', date: 'Feb 1', icon: <MiddleIcon /> },
  { id: 'c', title: 'End', date: 'Mar 1', icon: <EndIcon />, clickable: false },
];

function App() {
  const [active, setActive] = React.useState(2);

  return (
    <CustomTimeline
      nodes={milestones}
      activeStep={active}
      onStepChange={(step, id) => setActive(step)}
      orientation="vertical"
      lineStyle="dashed"
      indicatorColor="#4f46e5"
    />
  );
}

This completes the documentation for timeline.tsx.