npm package: @jaydixit/transitpaths
Description: A flexible timeline component for Astro projects with itinerary parsing, chronological sequencing, and location tracking
Author: Jay Dixit
Latest version: 1.0.2

# @jaydixit/transitpaths

A flexible timeline component for Astro projects with itinerary parsing, chronological sequencing, and location tracking.

## Features

- 📅 **MDX/Markdown Parsing**: Parse itinerary files with dates, locations, and activities
- 🗓️ **Chronological Sequencing**: Automatic chronological ordering of events
- 📍 **Location Tracking**: Track current location based on date
- ✈️ **Transit Visualization**: Beautiful transit event displays (flights, trains, driving)
- ✅ **Todo Management**: Support for todo items with completion tracking
- 🎨 **Customizable Themes**: Multiple built-in themes and custom styling
- 📱 **Responsive Design**: Mobile-optimized layout
- 🔧 **Flexible Configuration**: Extensive customization options

## Installation

```bash
npm install @jaydixit/transitpaths
# or
yarn add @jaydixit/transitpaths
# or
pnpm add @jaydixit/transitpaths
```

## Basic Usage

### Using the Timeline Component

```astro
---
// pages/itinerary.astro
import Timeline from '@jaydixit/transitpaths/src/components/Timeline.astro';
import itineraryContent from './my-itinerary.mdx?raw';

const config = {
  theme: 'default',
  features: {
    calendar: true,
    currentLocation: true,
    navigation: true,
    todoItems: true,
    autoScrollToToday: true
  }
};
---

<Timeline mdxContent={itineraryContent} config={config} />
```

### MDX File Format

Create your itinerary in MDX format:

```mdx
---
title: Summer Travel 2025
excerpt: My travel plans for summer
---

# Summer European Adventure

## July 26

- fly Brooklyn ➔ Edinburgh

## July 27

Arrive Edinburgh

## August 1

- Edinburgh Fringe Festival opening
- [ ] Buy tickets for shows
- [x] Book accommodation

## August 5

- train Edinburgh ➔ Milan

## August 6 -- August 10

Milan Fashion Week activities
```

## Advanced Usage

### Using with Custom Data

```astro
---
import Timeline from '@jaydixit/transitpaths/src/components/Timeline.astro';
import { buildChronoEvents } from '@jaydixit/transitpaths';

// Build your own event data
const myEvents = buildChronoEvents(timelineData, locationConfig);

const config = {
  theme: 'minimal'
};
---

<Timeline data={myEvents} config={config} />
```

### Custom Location Configuration

```astro
---
import Timeline from '@jaydixit/transitpaths/src/components/Timeline.astro';
import type { LocationConfig } from '@jaydixit/transitpaths';

const customLocations: LocationConfig = {
  tokyo: {
    name: 'Tokyo',
    theme: 'japan',
    emoji: '🗼',
    icon: '⛩️',
    iconName: 'tabler:torii',
    keywords: ['tokyo', 'japan'],
    title: 'Tokyo',
    country: 'Japan'
  },
  kyoto: {
    name: 'Kyoto',
    theme: 'japan',
    emoji: '🏯',
    icon: '⛩️',
    iconName: 'tabler:temple',
    keywords: ['kyoto'],
    title: 'Kyoto',
    country: 'Japan'
  }
};

const config = {
  locations: customLocations
};
---

<Timeline mdxContent={content} config={config} />
```

### Programmatic Parsing

```javascript
import { parseItinerary, buildChronoEvents } from '@jaydixit/transitpaths';

// Parse MDX content
const { timelineData, metadata } = parseItinerary(mdxContent, {
  locationConfig: myLocations,
  smartQuotes: customSmartQuotesFunction
});

// Build chronological events
const events = buildChronoEvents(timelineData, myLocations);

// Use events in your application
console.log(events);
```

## Configuration Options

### TimelineConfig

```typescript
interface TimelineConfig {
  // Custom location definitions
  locations?: LocationConfig;
  
  // Date formatting (future feature)
  dateFormat?: string;
  
  // Visual theme
  theme?: 'default' | 'minimal' | 'compact' | string;
  
  // Feature toggles
  features?: {
    calendar?: boolean;        // Show calendar navigation
    currentLocation?: boolean;  // Show current location box
    navigation?: boolean;       // Show navigation buttons
    todoItems?: boolean;       // Show todo checkboxes
    autoScrollToToday?: boolean; // Auto-scroll to current date
  };
  
  // Custom functions
  smartQuotes?: (text: string) => string;
  customIconResolver?: (cityName: string) => string;
}
```

### Location Configuration

```typescript
interface LocationDetail {
  name: string;          // Display name
  theme: string;         // Theme key
  emoji: string;         // Location emoji
  icon: string;          // Icon character
  iconName?: string;     // Icon library name (e.g., 'tabler:building')
  keywords: string[];    // Keywords for detection
  title: string;         // Section title
  country: string;       // Country name
  region?: string;       // State/Province (for US/Canada)
}
```

## Styling

### Using Built-in Themes

```astro
<Timeline mdxContent={content} config={{ theme: 'minimal' }} />
```

Available themes:
- `default`: Full-featured with colors
- `minimal`: Grayscale, reduced visual elements
- `compact`: Smaller spacing for dense timelines

### Custom CSS

Override CSS variables for custom styling:

```css
.transitpaths-timeline {
  --timeline-primary: #3b82f6;
  --timeline-secondary: #fb923c;
  --timeline-background: #ffffff;
  --timeline-text: #1f2937;
  --timeline-border: #e5e7eb;
}
```

## Transit Event Syntax

The parser recognizes several transit patterns:

```mdx
## August 15
- fly New York ➔ London
- train London → Paris
- drive Paris -> Lyon
- car Lyon ➔ Nice
- road trip Nice ➔ Monaco
```

Supported transit modes:
- `fly`: Airplane (✈️)
- `train`: Train (🚆)
- `drive`, `car`, `road trip`: Car (🚗)

## Todo Item Syntax

```mdx
## August 20
- [ ] Book hotel
- [ ] Reserve restaurant
- [x] Buy tickets
- Regular activity (no checkbox)
```

## API Reference

### Functions

#### `parseItinerary(mdxContent, config)`
Parses MDX content into structured timeline data.

**Parameters:**
- `mdxContent`: String containing MDX content
- `config`: ParserConfig object

**Returns:** `{ timelineData, metadata }`

#### `buildChronoEvents(timelineData, locationConfig)`
Builds chronologically ordered events from timeline data.

**Parameters:**
- `timelineData`: Array of TimelineEntry objects
- `locationConfig`: Location configuration object

**Returns:** Array of ChronoEvent objects

#### `getCityLocation(cityName, locationConfig)`
Gets location information for a city.

**Parameters:**
- `cityName`: Name of the city
- `locationConfig`: Location configuration object

**Returns:** Location string or null

## Examples

### Travel Blog

```astro
---
import Timeline from '@jaydixit/transitpaths/src/components/Timeline.astro';
import { getEntry } from 'astro:content';

const trip = await getEntry('trips', 'europe-2025');
---

<article>
  <h1>{trip.data.title}</h1>
  <Timeline mdxContent={trip.body} config={{
    theme: 'default',
    features: { 
      currentLocation: true,
      autoScrollToToday: true 
    }
  }} />
</article>
```

### Conference Schedule

```astro
---
import Timeline from '@jaydixit/transitpaths/src/components/Timeline.astro';

const conferenceSchedule = `
# Tech Conference 2025

## March 15
- fly San Francisco ➔ Austin
- [ ] Check in to hotel

## March 16
- Keynote: Future of AI
- Workshop: Building with LLMs
- [ ] Networking dinner

## March 17
- Panel: Ethics in Technology
- fly Austin ➔ San Francisco
`;

---

<Timeline mdxContent={conferenceSchedule} config={{
  theme: 'compact'
}} />
```

## Browser Support

- Modern browsers (Chrome, Firefox, Safari, Edge)
- ES2022+ JavaScript features required
- CSS Grid and Flexbox support required

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT License - see LICENSE file for details

## Author

Jay Dixit

## Changelog

### 1.0.0
- Initial release
- MDX parsing support
- Timeline component
- Location tracking
- Todo items
- Multiple themes