npm package: @opusx/pdf
Description: A production-ready, type-safe PDF viewer component for Vue 3 applications, built with PDF.js. Designed for both Single-SPA micro-frontends and standalone Vue applications.
Latest version: 1.0.0

# @opusx/pdf

A production-ready, type-safe PDF viewer component for Vue 3 applications, built with PDF.js. Designed for both Single-SPA micro-frontends and standalone Vue applications.

## Features

- 100% Type-Safe - Strict TypeScript with zero `any` types
- Beautiful UI - Modern, accessible design with dark mode support
- Responsive - Works seamlessly on desktop and mobile
- View Modes - Single page and continuous scrolling
- Performance - Lazy loading, virtual scrolling, and optimized rendering
- Accessibility - Full keyboard navigation and screen reader support
- Well Tested - Comprehensive unit and integration tests
- Tree Shakeable - ES modules with minimal bundle size

## Installation

```bash
npm install @opusx/pdf
```

### Peer Dependencies

```bash
npm install vue pdfjs-dist
```

## Quick Start

### Basic Usage

```vue
<script setup lang="ts">
import { PdfViewer } from '@opusx/pdf'
import '@opusx/pdf/dist/opusx-pdf.css'

const pdfUrl = '/path/to/document.pdf'
</script>

<template>
  <PdfViewer :src="pdfUrl" />
</template>
```

### With Options

```vue
<template>
  <PdfViewer 
    :src="pdfUrl"
    :initial-page="1"
    :initial-scale="1.5"
    view-mode="continuous"
    :show-toolbar="true"
    :debug="false"
  />
</template>
```

## API Reference

### PdfViewer Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `src` | `string` | **required** | URL or path to the PDF file |
| `initialPage` | `number` | `1` | Page number to display on load |
| `initialScale` | `number` | `1.0` | Initial zoom level (0.5 - 3.0) |
| `viewMode` | `'single' \| 'continuous'` | `'single'` | Display mode |
| `showToolbar` | `boolean` | `true` | Show/hide the toolbar |
| `debug` | `boolean` | `false` | Enable debug logging |

### Events

```vue
<PdfViewer 
  @page-change="onPageChange"
  @scale-change="onScaleChange"
  @loading="onLoading"
  @error="onError"
/>
```

## Advanced Usage

### Programmatic Control

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { PdfViewer } from '@opusx/pdf'

const viewerRef = ref()

function goToPage(page: number) {
  viewerRef.value?.goToPage(page)
}

function zoomIn() {
  viewerRef.value?.zoomIn()
}
</script>

<template>
  <PdfViewer ref="viewerRef" :src="pdfUrl" />
</template>
```

### Custom Styling

```css
/* Override CSS variables */
:root {
  --pdf-background: #1a1a1a;
  --pdf-toolbar-bg: #2d2d2d;
  --pdf-text: #ffffff;
  --pdf-border: #404040;
}
```

## Development

### Setup

1. Clone the repository
   ```bash
   git clone <repository-url>
   cd packages/pdf
   ```

2. Install dependencies
   ```bash
   npm install
   ```

3. Start development server
   ```bash
   npm run dev
   ```

### Project Structure

```
packages/pdf/
├── src/
│   ├── components/     # Vue components
│   ├── composables/    # Vue composables
│   ├── utils/          # Utility functions
│   ├── types/          # TypeScript types
│   └── index.ts        # Main entry point
├── dist/               # Build output
├── __tests__/          # Test files
└── vite.config.ts      # Vite configuration
```

## Building

### Production Build

```bash
npm run build
```

This generates:
- `dist/opusx-pdf.mjs` - ES module (tree-shakeable)
- `dist/opusx-pdf.umd.js` - UMD bundle (browser compatible)
- `dist/opusx-pdf.css` - Styles
- `dist/` - TypeScript declarations

### Build Configuration

The build is configured for both library and application use:
- Library mode: Tree-shakeable ES modules
- Type declarations: Full TypeScript support
- Externalized dependencies: `vue` and `pdfjs-dist` are peer dependencies

## Testing

### Run All Tests

```bash
npm test
```

### Run Tests in Watch Mode

```bash
npm run test:watch
```

### Run Tests with Coverage

```bash
npm run test:coverage
```

### Test Structure

- **Unit tests**: `src/__tests__/unit/` - Individual functions and composables
- **Component tests**: `src/__tests__/components/` - Vue component behavior
- **Integration tests**: `src/__tests__/integration/` - End-to-end scenarios

## Upgrading

### From 0.x to 1.x

#### Breaking Changes

- Minimum Vue version: 3.3+
- Minimum TypeScript version: 5.0+

#### Migration Steps

1. Update dependencies
   ```bash
   npm install @opusx/pdf@latest vue@latest
   ```

2. Update imports
   ```typescript
   // Before
   import PdfViewer from '@opusx/pdf'
   
   // After
   import { PdfViewer } from '@opusx/pdf'
   ```

3. Update CSS imports
   ```typescript
   // Before
   import '@opusx/pdf/style.css'
   
   // After
   import '@opusx/pdf/dist/opusx-pdf.css'
   ```

### Checking Your Version

```bash
npm list @opusx/pdf
```

## Troubleshooting

### PDF.js Worker Issues

If you encounter worker-related errors:

```typescript
import { GlobalWorkerOptions } from 'pdfjs-dist'
import workerUrl from 'pdfjs-dist/build/pdf.worker.min.mjs?url'

GlobalWorkerOptions.workerSrc = workerUrl
```

### Build Errors

**Issue**: `Cannot resolve '@/...'`

**Solution**: Ensure Vite is configured with path aliases:

```typescript
// vite.config.ts
import { resolve } from 'path'

export default defineConfig({
  resolve: {
    alias: {
      '@': resolve(__dirname, './src')
    }
  }
})
```

### Type Errors

**Issue**: `Cannot find module '@opusx/pdf'`

**Solution**: Ensure TypeScript can find the types:

```json
{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "types": ["@opusx/pdf"]
  }
}
```

## Performance Recommendations

1. **Lazy Load PDFs**: Load PDFs on demand, not on initial render
2. **Use Continuous Mode**: For long documents, continuous scrolling provides better user experience
3. **Optimize Scale**: Start with `scale={1.0}` and let users zoom as needed
4. **Enable Caching**: PDF.js caches rendered pages automatically

## Browser Support

- Chrome/Edge: Latest 2 versions
- Firefox: Latest 2 versions
- Safari: Latest 2 versions

## Contributing

### Code Standards

- **TypeScript**: Strict mode enabled, no `any` types
- **Formatting**: Prettier with 2-space indentation
- **Linting**: ESLint with Vue and TypeScript rules

### Pull Request Process

1. Create a feature branch: `git checkout -b feature/my-feature`
2. Make your changes with tests
3. Run tests: `npm test`
4. Build: `npm run build`
5. Submit pull request with detailed description

## License

MIT

## References

- [PDF.js Documentation](https://mozilla.github.io/pdf.js/)
- [Vue 3 Documentation](https://vuejs.org/)
- [Single-SPA Documentation](https://single-spa.js.org/)

## Support

For issues and feature requests, please use the GitHub issue tracker.