@masuidrive/ticket/README.md

Real-time ticket tracking viewer with Vite + Express

# @masuidrive/ticket

🎫 Real-time ticket tracking viewer for development workflow

A modern web-based ticket viewer that provides real-time updates for your markdown-based ticket system. Perfect for tracking development progress with live updates, mermaid diagrams, and HTML previews.

## Features

- 📝 **Markdown Ticket Support**: View and track tickets written in markdown
- 🔄 **Real-time Updates**: Automatic refresh when ticket files change
- 📊 **Mermaid Diagrams**: Render flowcharts, sequence diagrams, and more
- 🌐 **HTML Previews**: Preview HTML content with iframe sandboxing
- 🎨 **Dark/Light Theme**: Automatic theme switching support
- ⚡ **Fast Performance**: Built with Vite for lightning-fast development
- 🔗 **SSE Connection**: Server-Sent Events for live updates
- 📑 **Table of Contents**: Collapsible TOC with smooth scrolling navigation
- 🔝 **Scroll to Top**: Quick return button for easy navigation
- 🗺️ **Breadcrumb Navigation**: Sticky header showing current section hierarchy
- 🖱️ **Quick Navigation**: Double-click anywhere to jump to table of contents

## Quick Start

Run the ticket viewer in any directory:

```bash
npx @masuidrive/ticket
```

This will:
- Look for `current-ticket.md` in the current directory
- Start a web server at http://localhost:4932
- Open the ticket viewer in your browser

## Usage

### Basic Usage

```bash
# Start in current directory
npx @masuidrive/ticket

# Start in specific directory
npx @masuidrive/ticket ./my-project

# Start on custom port
npx @masuidrive/ticket -p 3000

# Combine options
npx @masuidrive/ticket -d ./my-project -p 3000
```

### Command Line Options

```
Options:
  -p, --port <number>    Server port (default: 4932)
  -h, --host <address>   Server host address (default: localhost)
  -d, --dir <path>       Project directory containing current-ticket.md
  --help                 Show help message

Examples:
  npx @masuidrive/ticket                           # Current directory, localhost:4932
  npx @masuidrive/ticket ./my-project             # Specific directory
  npx @masuidrive/ticket -p 3000                  # Custom port
  npx @masuidrive/ticket -h 0.0.0.0               # Listen on all interfaces
  npx @masuidrive/ticket -h 0.0.0.0 -p 3000       # External access on port 3000
  npx @masuidrive/ticket -h 0.0.0.0 -p 3000 -d ./my-project  # Full options
```

## Ticket Format

The viewer looks for `current-ticket.md` in your project directory. Here's an example ticket format:

~~~markdown
---
priority: 1
tags: ["frontend", "bug"]
description: "Fix navigation component styling"
created_at: "2025-01-15T10:30:00Z"
started_at: "2025-01-15T11:00:00Z"
closed_at: null
---

# Fix Navigation Component Styling

## Overview
The navigation component has styling issues in dark mode...

## Tasks
- [x] Identify CSS issues
- [ ] Fix dark mode colors
- [ ] Test responsive design

## Mermaid Diagram
```mermaid
flowchart TD
    A[Identify Issue] --> B[Fix Styles]
    B --> C[Test Changes]
    C --> D[Deploy]
```

## HTML Preview
```html-preview
<div class="nav-component">
  <h1>Navigation Preview</h1>
  <nav>...</nav>
</div>
```
~~~

## Features in Detail

### Real-time Updates
The viewer automatically refreshes when your ticket files change, providing instant feedback as you update your tickets.

### Mermaid Diagram Support
Render various diagram types:
- Flowcharts
- Sequence diagrams
- Class diagrams
- Gantt charts
- And more...

### HTML Preview
Preview HTML content safely with iframe sandboxing. Perfect for mockups and UI previews.

### Theme Support
Automatic dark/light theme switching based on system preferences, with manual toggle available.

### Enhanced Navigation
- **Table of Contents**: Automatically generated from markdown headers (H1-H6) with collapsible interface
- **Sticky Breadcrumb**: Shows current section hierarchy at the top of the page as you scroll
- **Scroll to Top**: Floating button appears after scrolling 100px for quick return to top
- **Quick Jump**: Double-click on empty space anywhere on the page to jump to table of contents
- **Header Return Links**: Hover over any heading to see a "↑" button that returns to table of contents
- **Japanese Support**: Full Unicode support with URL-safe encoding for smooth scrolling

## Requirements

- Node.js 18.0.0 or higher
- Modern web browser with ES2020 support

## Development

If you want to contribute or run from source:

```bash
git clone https://github.com/masuidrive/ticket-sh-viewer.git
cd ticket-sh-viewer
npm install
npm run build
npm start
```

## Architecture

- **Frontend**: Vite + React + TypeScript + Tailwind CSS
- **Backend**: Express.js with Server-Sent Events (SSE)
- **Real-time**: File watching with chokidar
- **Diagrams**: Mermaid.js integration
- **Previews**: Sandboxed iframe rendering

## License

MIT License - see LICENSE file for details

## Author

masuidrive

## Repository

https://github.com/masuidrive/ticket-sh-viewer

## Issues

Report issues at: https://github.com/masuidrive/ticket-sh-viewer/issues