File Preview

https://github.com/wh131462/file-preview
Admin
A modern, feature-rich file preview component library with first-class support for both React and...
Tokens:21,441
Snippets:276
Trust Score:7.9
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Verify Setup and Run Demos

Source: https://github.com/wh131462/file-preview/blob/master/CONTRIBUTING.md

Start the React demo, Vue demo, or documentation site to verify your setup.

```bash
# Start React demo
pnpm dev
```

```bash
# Start Vue demo
pnpm dev:vue
```

```bash
# Start documentation site
pnpm dev:docs
```

--------------------------------

### Development Commands for Vue File Preview

Source: https://github.com/wh131462/file-preview/blob/master/packages/vue-file-preview/README.md

Commands to clone the repository, install dependencies, start the development server, and build the library.

```bash
# Clone repository
git clone https://github.com/wh131462/file-preview.git

# Install dependencies
pnpm install

# Start dev server (Vue demo app)
pnpm dev:vue-example

# Build library
pnpm build:vue
```

--------------------------------

### Install Vue File Preview

Source: https://github.com/wh131462/file-preview/blob/master/README.md

Install the Vue package via npm.

```bash
npm install @eternalheart/vue-file-preview
```

--------------------------------

### Install React File Preview

Source: https://github.com/wh131462/file-preview/blob/master/README.md

Install the React package via npm.

```bash
npm install @eternalheart/react-file-preview
```

--------------------------------

### Install React File Preview

Source: https://github.com/wh131462/file-preview/blob/master/packages/react-file-preview/README.md

Commands to install the package using npm, yarn, or pnpm.

```bash
# Using npm
npm install @eternalheart/react-file-preview

# Using yarn
yarn add @eternalheart/react-file-preview

# Using pnpm
pnpm add @eternalheart/react-file-preview
```

--------------------------------

### Install the package

Source: https://github.com/wh131462/file-preview/blob/master/packages/vue-file-preview/README.md

Use your preferred package manager to add the library to your project.

```bash
# Using npm
npm install @eternalheart/vue-file-preview

# Using yarn
yarn add @eternalheart/vue-file-preview

# Using pnpm
pnpm add @eternalheart/vue-file-preview
```

--------------------------------

### Install Dependencies

Source: https://github.com/wh131462/file-preview/blob/master/CONTRIBUTING.md

Install project dependencies using pnpm.

```bash
pnpm install
```

--------------------------------

### Install Angular File Preview

Source: https://github.com/wh131462/file-preview/blob/master/README.md

Install the Angular package via npm.

```bash
npm install @eternalheart/angular-file-preview
```

--------------------------------

### Install angular-file-preview

Source: https://github.com/wh131462/file-preview/blob/master/packages/angular-file-preview/README.md

Commands to install the package using npm, yarn, or pnpm.

```bash
# Using npm
npm install @eternalheart/angular-file-preview

# Using yarn
yarn add @eternalheart/angular-file-preview

# Using pnpm
pnpm add @eternalheart/angular-file-preview
```

--------------------------------

### Execute Development and Build Commands

Source: https://github.com/wh131462/file-preview/blob/master/README.md

Collection of pnpm scripts for starting development servers, building packages, and managing deployment.

```bash
# Start dev servers
pnpm dev              # React demo
pnpm dev:vue          # Vue demo
pnpm dev:angular      # Angular demo
pnpm dev:all          # React + Vue + Angular demos
pnpm dev:docs         # Documentation site
pnpm kill:dev         # Stop demo servers on ports 4800–4803

# Build
pnpm build            # Build all packages
pnpm build:lib        # Build library only
pnpm build:example    # Build examples only

# Preview builds
pnpm preview:example  # Preview example build
pnpm preview:docs     # Preview docs build

# Deploy and publish
pnpm gh               # Build and deploy examples and docs to GitHub Pages
pnpm pub:react        # Publish the React package to npm
pnpm pub:vue          # Publish the Vue package to npm
pnpm pub:angular      # Publish the Angular package to npm
```

--------------------------------

### Conventional Commit Message Examples

Source: https://github.com/wh131462/file-preview/blob/master/CONTRIBUTING.zh-CN.md

Examples demonstrating the conventional commit message format for various types of changes, including features, fixes, documentation, and chores.

```bash
feat(react): 添加 HEIC 图片格式支持
fix(core): 修正 AVIF 文件的 MIME 类型检测
docs: 更新快速开始指南
refactor(vue): 简化 FilePreviewEmbed 组件 props
perf(react): 优化图片渲染性能
chore(deps): 升级 pdfjs-dist 到 4.0.0
```

--------------------------------

### Implement FilePreviewModal in Angular

Source: https://github.com/wh131462/file-preview/blob/master/packages/angular-file-preview/README.md

Basic setup for a file preview modal using Angular signals to manage file state and visibility.

```ts
import { Component, signal } from '@angular/core';
import { FilePreviewModal } from '@eternalheart/angular-file-preview';
import '@eternalheart/angular-file-preview/style.css';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [FilePreviewModal],
  template: `
    <input type="file" (change)="handleFileSelect($event)" />
    <FilePreviewModal
      [files]="files()"
      [currentIndex]="currentIndex()"
      [isOpen]="isOpen()"
      (close)="isOpen.set(false)"
      (navigate)="currentIndex.set($event)"
    />
  `,
})
export class AppComponent {
  files = signal<File[]>([]);
  currentIndex = signal(0);
  isOpen = signal(false);

  handleFileSelect(e: Event) {
    const file = (e.target as HTMLInputElement).files?.[0];
    if (file) {
      this.files.set([file]);
      this.currentIndex.set(0);
      this.isOpen.set(true);
    }
  }
}
```

--------------------------------

### Use Vue FilePreviewModal

Source: https://github.com/wh131462/file-preview/blob/master/README.md

Import the component and styles within a script setup block, then use the component in the template.

```vue
<script setup>
import { FilePreviewModal } from '@eternalheart/vue-file-preview';
import '@eternalheart/vue-file-preview/style.css';
</script>

<template>
  <FilePreviewModal
    :files="[file]"
    :current-index="0"
    :is-open="true"
    @close="isOpen = false"
  />
</template>
```

--------------------------------

### Configure File Input Arrays

Source: https://github.com/wh131462/file-preview/blob/master/packages/react-file-preview/README.md

Examples of different ways to structure the files array, including mixed usage of native objects, URLs, and custom file objects.

```typescript
// Method 1: Using native File objects
const files = [file1, file2]; // Array of File objects

// Method 2: Using HTTP URL strings
const files = [
  'https://example.com/image.jpg',
  'https://example.com/document.pdf',
];

// Method 3: Using file objects
const files = [
  {
    name: 'presentation.pptx',
    type: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
    url: '/path/to/presentation.pptx',
  },
];

// Method 4: Mixed usage
const files = [
  file1,  // File object
  'https://example.com/image.jpg',  // URL string
  { name: 'doc.pdf', type: 'application/pdf', url: '/doc.pdf' },  // File object
];
```

--------------------------------

### Conventional Commits Examples

Source: https://github.com/wh131462/file-preview/blob/master/CONTRIBUTING.md

Examples of commit messages following the Conventional Commits specification. Use these formats for different types of changes to maintain a clear commit history.

```bash
feat(react): add support for HEIC image format
```

```bash
fix(core): correct MIME type detection for AVIF files
```

```bash
docs: update quick start guide
```

```bash
refactor(vue): simplify FilePreviewEmbed props
```

```bash
perf(react): optimize image rendering performance
```

```bash
chore(deps): upgrade pdfjs-dist to 4.0.0
```

--------------------------------

### Lint Code with pnpm

Source: https://github.com/wh131462/file-preview/blob/master/CONTRIBUTING.md

Run the ESLint configuration to check code style before committing. Ensure all new code adheres to the project's established style guide.

```bash
pnpm lint
```

--------------------------------

### Vite build error message

Source: https://github.com/wh131462/file-preview/blob/master/packages/angular-file-preview/README.md

Example of the error message encountered when using @jsquash/avif with Vite.

```text
[commonjs--resolver] Invalid value "iife" for option "worker.format"
- UMD and IIFE output formats are not supported for code-splitting builds.
file: .../@jsquash/avif/codec/enc/avif_enc_mt.js
```

--------------------------------

### Example Commit/PR Title Format

Source: https://github.com/wh131462/file-preview/blob/master/CONTRIBUTING.md

Use this format for commit messages and pull request titles to clearly indicate the type and scope of changes.

```text
feat(react): add zoom controls to image viewer
```

--------------------------------

### Parameterized Translations

Source: https://github.com/wh131462/file-preview/blob/master/packages/vue-file-preview/README.md

Example of passing dynamic data to translation keys using an object argument.

```vue
<template>
  <!-- Dictionary: 'custom.file_size': 'File size: {size} KB' -->
  <span>{{ t('custom.file_size', { size: 1024 }) }}</span>
  <!-- → "File size: 1024 KB" -->
</template>
```

--------------------------------

### Development Commands

Source: https://github.com/wh131462/file-preview/blob/master/packages/react-file-preview/README.md

Standard commands for setting up the development environment and building the library or demo application.

```bash
# Clone repository
git clone https://github.com/wh131462/file-preview.git

# Install dependencies
pnpm install

# Start dev server (demo app)
pnpm dev

# Build library (for npm)
pnpm build:lib

# Build demo app (for GitHub Pages)
pnpm build:demo
```

--------------------------------

### Build and Test Commands

Source: https://github.com/wh131462/file-preview/blob/master/CONTRIBUTING.md

Commands for building all packages, the library only, running the linter, and type checking.

```bash
# Build all packages
pnpm build

# Build library only
pnpm build:lib

# Run linter
pnpm lint

# Run type checking
pnpm type-check
```

--------------------------------

### View Project Directory Structure

Source: https://github.com/wh131462/file-preview/blob/master/README.md

Displays the monorepo layout including core packages, framework bindings, and documentation.

```text
file-preview/
├── packages/
│   ├── file-preview-core/     # Framework-agnostic core (types, detection, parsers)
│   ├── react-file-preview/    # React bindings → @eternalheart/react-file-preview
│   ├── vue-file-preview/      # Vue bindings → @eternalheart/vue-file-preview
│   ├── angular-file-preview/  # Angular bindings → @eternalheart/angular-file-preview
│   ├── example/               # React demo app (deployed to GitHub Pages)
│   ├── vue-example/           # Vue demo app (deployed to GitHub Pages /vue)
│   ├── angular-example/       # Angular demo app (deployed to GitHub Pages /angular)
│   └── docs/                  # VitePress documentation site
└── openspec/                  # OpenSpec change records
```

--------------------------------

### Custom Renderer Implementation

Source: https://github.com/wh131462/file-preview/blob/master/packages/react-file-preview/README.md

How to create a custom renderer for handling unsupported file types and integrating with the toolbar.

```APIDOC
## Custom Renderer

### Description
Custom renderers allow handling file types not supported by default. They can implement `getToolbarGroups` to provide custom toolbar actions.

### Implementation
Use `forwardRef` and `useImperativeHandle` to expose `getToolbarGroups` to the `FilePreviewModal`.

### Renderer Interface
- **test** (Function) - Required - Predicate function `(file) => boolean` to determine if the renderer should handle the file.
- **render** (Function) - Required - Function returning the React component to render the file.
```

--------------------------------

### Preview Multiple Files with Navigation

Source: https://github.com/wh131462/file-preview/blob/master/packages/react-file-preview/README.md

Shows how to configure the FilePreviewModal to handle an array of files with navigation controls.

```tsx
const files = [
  { name: 'image.jpg', type: 'image/jpeg', url: '/path/to/image.jpg' },
  { name: 'document.pdf', type: 'application/pdf', url: '/path/to/document.pdf' },
  { name: 'presentation.pptx', type: 'application/vnd.openxmlformats-officedocument.presentationml.presentation', url: '/path/to/presentation.pptx' },
  { name: 'spreadsheet.xlsx', type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', url: '/path/to/spreadsheet.xlsx' },
];

<FilePreviewModal
  files={files}
  currentIndex={0}
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  onNavigate={setCurrentIndex}
/>
```

--------------------------------

### Project Directory Structure

Source: https://github.com/wh131462/file-preview/blob/master/packages/react-file-preview/README.md

Overview of the file organization within the react-file-preview repository.

```text
react-file-preview/
├── src/
│   ├── index.ts              # Library entry point
│   ├── FilePreviewModal.tsx  # Main component
│   ├── types.ts              # Type definitions
│   ├── utils/                # Utility functions
│   ├── renderers/            # File type renderers
│   ├── App.tsx               # Demo app
│   └── main.tsx              # Demo app entry
├── lib/                      # Built library (npm package)
├── dist/                     # Built demo app (GitHub Pages)
└── vite.config.lib.ts        # Library build config
```

--------------------------------

### Clone Repository

Source: https://github.com/wh131462/file-preview/blob/master/CONTRIBUTING.md

Clone your forked repository locally and navigate into the project directory.

```bash
git clone https://github.com/YOUR_USERNAME/file-preview.git
cd file-preview
```

--------------------------------

### Implement Basic FilePreviewModal

Source: https://github.com/wh131462/file-preview/blob/master/packages/react-file-preview/README.md

Use FilePreviewModal to display a file selection modal. Requires importing the component and its associated CSS.

```tsx
import { FilePreviewModal } from '@eternalheart/react-file-preview';
import '@eternalheart/react-file-preview/style.css';
import { useState } from 'react';

function App() {
  const [files, setFiles] = useState([]);
  const [currentIndex, setCurrentIndex] = useState(0);
  const [isOpen, setIsOpen] = useState(false);

  const handleFileSelect = (file: File) => {
    // Method 1: Directly pass File object (recommended)
    setFiles([file]);
    setCurrentIndex(0);
    setIsOpen(true);
  };

  return (
    <>
      <input
        type="file"
        onChange={(e) => e.target.files?.[0] && handleFileSelect(e.target.files[0])}
      />

      <FilePreviewModal
        files={files}
        currentIndex={currentIndex}
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
        onNavigate={setCurrentIndex}
      />
    </>
  );
}
```

--------------------------------

### Configure PDF.js

Source: https://github.com/wh131462/file-preview/blob/master/packages/react-file-preview/README.md

Configure the library to use local static files for PDF previewing.

```tsx
import { configurePdfjs } from '@eternalheart/react-file-preview';

// Configure to use local static files
configurePdfjs({
  workerSrc: '/pdfjs/pdf.worker.min.mjs',
  cMapUrl: '/pdfjs/cmaps/',
  cMapPacked: true
});
```

--------------------------------

### Run All Tests

Source: https://github.com/wh131462/file-preview/blob/master/CONTRIBUTING.md

Execute all defined tests in the project using the pnpm test command.

```bash
# Run all tests
pnpm test
```

--------------------------------

### Project Structure Overview

Source: https://github.com/wh131462/file-preview/blob/master/CONTRIBUTING.md

Directory structure for the file-preview monorepo, including core, React, and Vue packages.

```tree
file-preview/
├── packages/
│   ├── file-preview-core/        # Framework-agnostic core
│   │   ├── src/
│   │   │   ├── types/            # TypeScript type definitions
│   │   │   ├── utils/            # Utility functions
│   │   │   └── loaders/          # File loaders and parsers
│   │   └── package.json
│   │
│   ├── react-file-preview/       # React bindings
│   │   ├── src/
│   │   │   ├── components/       # React components
│   │   │   ├── renderers/        # File type renderers
│   │   │   └── hooks/            # Custom React hooks
│   │   └── package.json
│   │
│   ├── vue-file-preview/         # Vue bindings
│   │   ├── src/
│   │   │   ├── components/       # Vue components
│   │   │   └── composables/      # Vue composables
│   │   └── package.json
│   │
│   ├── example/                  # React demo app
│   ├── vue-example/              # Vue demo app
│   └── docs/                     # VitePress documentation
│
├── openspec/                     # OpenSpec change records
└── pnpm-workspace.yaml
```

--------------------------------

### Preview PowerPoint Files with FilePreviewModal

Source: https://github.com/wh131462/file-preview/blob/master/packages/react-file-preview/README.md

Demonstrates how to trigger a file preview modal for a single PowerPoint file using state management.

```tsx
import { FilePreviewModal } from '@eternalheart/react-file-preview';
import { useState } from 'react';

function PptPreview() {
  const [isOpen, setIsOpen] = useState(false);

  const pptFile = {
    name: 'presentation.pptx',
    type: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
    url: '/path/to/your/presentation.pptx',
  };

  return (
    <>
      <button onClick={() => setIsOpen(true)}>
        Preview PPT
      </button>

      <FilePreviewModal
        files={[pptFile]}
        currentIndex={0}
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
      />
    </>
  );
}
```

--------------------------------

### Implement Basic FilePreviewModal

Source: https://github.com/wh131462/file-preview/blob/master/packages/vue-file-preview/README.md

Use FilePreviewModal to display a file selection triggered by an input element. Requires importing the component and its CSS.

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { FilePreviewModal } from '@eternalheart/vue-file-preview';
import '@eternalheart/vue-file-preview/style.css';

const files = ref<File[]>([]);
const currentIndex = ref(0);
const isOpen = ref(false);

const handleFileSelect = (e: Event) => {
  const file = (e.target as HTMLInputElement).files?.[0];
  if (file) {
    files.value = [file];
    currentIndex.value = 0;
    isOpen.value = true;
  }
};
</script>

<template>
  <input type="file" @change="handleFileSelect" />

  <FilePreviewModal
    :files="files"
    :current-index="currentIndex"
    :is-open="isOpen"
    @close="isOpen = false"
    @navigate="currentIndex = $event"
  />
</template>
```

--------------------------------

### Import CSS styles

Source: https://github.com/wh131462/file-preview/blob/master/packages/vue-file-preview/README.md

Include the required CSS file in your application entry point.

```ts
import '@eternalheart/vue-file-preview/style.css';
```

--------------------------------

### Run Tests with Coverage

Source: https://github.com/wh131462/file-preview/blob/master/CONTRIBUTING.md

Execute all tests and generate a code coverage report using the pnpm test:coverage command.

```bash
# Run tests with coverage
pnpm test:coverage
```

--------------------------------

### Define file as PreviewFileLink object

Source: https://github.com/wh131462/file-preview/blob/master/packages/docs/guide/basic-usage.md

Use an object with name, url, and type properties for more detailed file metadata.

```ts
const file = {
  name: 'document.pdf',
  url: 'https://example.com/file.pdf',
  type: 'application/pdf'
}
```

--------------------------------

### Configure Multiple Input Types in Vue

Source: https://github.com/wh131462/file-preview/blob/master/packages/angular-file-preview/README.md

Demonstrates passing various file input formats including native File objects, URLs, and metadata objects to the modal.

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { FilePreviewModal, type PreviewFileInput } from '@eternalheart/angular-file-preview';
import '@eternalheart/angular-file-preview/style.css';

// Assume file1 comes from a File API source: <input type="file">,
// drag & drop, clipboard paste, or fetch().then(r => r.blob())
const file1 = new File(['content'], 'example.txt', { type: 'text/plain' });

const files: PreviewFileInput[] = [
  // 1. Native File object (auto revoked when unmounted)
  file1,

  // 2. HTTP URL string (loaded on demand)
  'https://example.com/image.jpg',

  // 3. File object with metadata (recommended for remote resources)
  {
    name: 'document.pdf',
    type: 'application/pdf',
    url: '/path/to/document.pdf',
    size: 1024,
  },
];

// Memory note: If you generate URLs via URL.createObjectURL(),
// call URL.revokeObjectURL() when files are removed to avoid memory leaks.

const isOpen = ref(true);
</script>

<template>
  <FilePreviewModal
    :files="files"
    :current-index="0"
    :is-open="isOpen"
    @close="isOpen = false"
  />
</template>
```

--------------------------------

### Test custom renderers with theme props

Source: https://github.com/wh131462/file-preview/blob/master/packages/react-file-preview/README.md

Verify renderer appearance by manually switching the theme prop in the FilePreviewModal.

```tsx
<FilePreviewModal
  files={files}
  theme="light"  // Switch between 'light', 'dark', 'auto'
  customRenderers={[...]}
/>
```

--------------------------------

### Apply Lazy Loading to Custom Renderers

Source: https://github.com/wh131462/file-preview/blob/master/packages/vue-file-preview/README.md

Demonstrates how to apply the lazy loading pattern to custom renderer registration.

```vue
<script setup>
import { defineAsyncComponent } from 'vue';

const MyCustomRenderer = defineAsyncComponent(() => import('./MyCustomRenderer.vue'));

const files = [...];
</script>

<template>
  <FilePreviewModal
    :files="files"
    :custom-renderers="[
      {
        test: (file) => file.type === 'application/custom',
        render: () => MyCustomRenderer
      }
    ]"
  />
</template>
```

--------------------------------

### Implement Custom Renderer with Toolbar Updates

Source: https://github.com/wh131462/file-preview/blob/master/packages/react-file-preview/README.md

Create a custom renderer using forwardRef and ToolbarEventEmitter to manage real-time toolbar state updates.

```tsx
import { forwardRef, useImperativeHandle, useState, useEffect, useMemo, useCallback } from 'react';
import { ToolbarEventEmitter } from '@eternalheart/react-file-preview';
import type { RendererHandle, ToolbarGroup } from '@eternalheart/react-file-preview';

interface CustomRendererProps {
  url: string;
  onPageChange?: (current: number, total: number) => void;
}

export const CustomRenderer = forwardRef<RendererHandle, CustomRendererProps>((props, ref) => {
  const [currentPage, setCurrentPage] = useState(1);
  const [totalPages, setTotalPages] = useState(10);
  const emitter = useMemo(() => new ToolbarEventEmitter(), []);
  
  // Notify toolbar when state changes
  useEffect(() => {
    emitter.notify();
    props.onPageChange?.(currentPage, totalPages);
  }, [currentPage, totalPages, emitter, props]);
  
  const getToolbarGroups = useCallback((): ToolbarGroup[] => [
    {
      items: [
        {
          type: 'button',
          icon: <ChevronLeft className="w-4 h-4" />,
          tooltip: 'Previous Page',
          action: () => setCurrentPage(p => Math.max(1, p - 1)),
          disabled: currentPage <= 1
        },
        {
          type: 'text',
          content: `${currentPage} / ${totalPages}`,
          minWidth: '4rem'
        },
        {
          type: 'button',
          icon: <ChevronRight className="w-4 h-4" />,
          tooltip: 'Next Page',
          action: () => setCurrentPage(p => Math.min(totalPages, p + 1)),
          disabled: currentPage >= totalPages
        }
      ]
    }
  ], [currentPage, totalPages]);
  
  useImperativeHandle(ref, () => ({
    getToolbarGroups,
    onToolbarChange: (listener) => emitter.subscribe(listener)
  }), [getToolbarGroups, emitter]);
  
  return <div>Your custom renderer UI</div>;
});
```

--------------------------------

### Implement FilePreviewEmbed

Source: https://github.com/wh131462/file-preview/blob/master/packages/react-file-preview/README.md

Renders an inline preview component. The component fills its parent container by default.

```tsx
import { FilePreviewEmbed } from '@eternalheart/react-file-preview';
import '@eternalheart/react-file-preview/style.css';
import { useState } from 'react';

function InlinePreview() {
  const [index, setIndex] = useState(0);

  const files = [
    'https://example.com/image.jpg',
    { name: 'document.pdf', type: 'application/pdf', url: '/doc.pdf' },
  ];

  return (
    // The embedded preview fills its parent container by default.
    <div style={{ width: '100%', height: 520 }}>
      <FilePreviewEmbed
        files={files}
        currentIndex={index}
        onNavigate={setIndex}
      />
    </div>
  );
}
```

--------------------------------

### Configure PDF.js worker

Source: https://github.com/wh131462/file-preview/blob/master/packages/vue-file-preview/README.md

Initialize the PDF worker in your application entry point to use local static files.

```ts
import * as pdfjsLib from 'pdfjs-dist/build/pdf.mjs';
import { configurePdfWorker } from '@eternalheart/vue-file-preview';

configurePdfWorker(pdfjsLib, {
  workerSrc: '/pdfjs/pdf.worker.min.mjs',
  cMapUrl: '/pdfjs/cmaps/',
  cMapPacked: true,
});
```

--------------------------------

### Implement FilePreviewContent Component

Source: https://github.com/wh131462/file-preview/blob/master/packages/vue-file-preview/README.md

Use the lower-level FilePreviewContent component for building custom wrappers.

```vue
<FilePreviewContent
  mode="embed"
  :files="files"
  :current-index="index"
  @navigate="index = $event"
/>
```

--------------------------------

### Use React FilePreviewModal

Source: https://github.com/wh131462/file-preview/blob/master/README.md

Import the component and styles, then render the modal with file data and state handlers.

```tsx
import { FilePreviewModal } from '@eternalheart/react-file-preview';
import '@eternalheart/react-file-preview/style.css';

<FilePreviewModal
  files={[file]}
  currentIndex={0}
  isOpen={true}
  onClose={() => setIsOpen(false)}
/>
```

--------------------------------

### Automate static file copying with Vite

Source: https://github.com/wh131462/file-preview/blob/master/packages/vue-file-preview/README.md

Use vite-plugin-static-copy to automatically move PDF.js assets during the build process.

```ts
import { defineConfig } from 'vite';
import { viteStaticCopy } from 'vite-plugin-static-copy';

export default defineConfig({
  plugins: [
    viteStaticCopy({
      targets: [
        {
          src: 'node_modules/pdfjs-dist/build/pdf.worker.min.mjs',
          dest: 'pdfjs'
        },
        {
          src: 'node_modules/pdfjs-dist/cmaps',
          dest: 'pdfjs'
        }
      ]
    })
  ]
});
```

--------------------------------

### Implement a theme-aware custom renderer

Source: https://github.com/wh131462/file-preview/blob/master/packages/react-file-preview/README.md

Use semantic Tailwind classes with the rfp- prefix to ensure components adapt to the library's theme system.

```tsx
export const CustomRenderer = forwardRef<RendererHandle, Props>((props, ref) => {
  return (
    <div className="rfp-bg-surface-1 rfp-border rfp-border-line-weak rfp-rounded">
      <h2 className="rfp-text-fg-primary rfp-text-lg">Title</h2>
      <p className="rfp-text-fg-secondary">Body text</p>
      <button className="rfp-bg-surface-2 hover:rfp-bg-surface-3 rfp-text-fg-primary">
        Click me
      </button>
      <pre className="rfp-bg-code-bg rfp-text-code-fg">
        {code}
      </pre>
    </div>
  );
});
```

--------------------------------

### Implement FilePreviewContent

Source: https://github.com/wh131462/file-preview/blob/master/packages/react-file-preview/README.md

Use the lower-level FilePreviewContent component to build custom wrappers for modal or embed modes.

```tsx
import { FilePreviewContent } from '@eternalheart/react-file-preview';

<FilePreviewContent
  mode="embed"       // or "modal"
  files={files}
  currentIndex={index}
  onNavigate={setIndex}
/>
```

--------------------------------

### Implement file upload modal

Source: https://github.com/wh131462/file-preview/blob/master/packages/docs/guide/basic-usage.md

Handle file input changes and trigger the preview modal in React and Vue 3 environments.

```tsx
function FileUploadExample() {
  const [files, setFiles] = useState<PreviewFileInput[]>([])
  const [isOpen, setIsOpen] = useState(false)

  const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    const selectedFiles = Array.from(e.target.files || [])
    setFiles(selectedFiles)
    setIsOpen(true)
  }

  return (
    <>
      <input type="file" multiple onChange={handleFileChange} />
      <FilePreviewModal
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
        files={files}
        currentIndex={0}
      />
    </>
  )
}
```

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { FilePreviewModal, type PreviewFileInput } from '@eternalheart/vue-file-preview'

const files = ref<PreviewFileInput[]>([])
const isOpen = ref(false)

const handleFileChange = (e: Event) => {
  const target = e.target as HTMLInputElement
  files.value = Array.from(target.files || [])
  isOpen.value = true
}
</script>

<template>
  <input type="file" multiple @change="handleFileChange" />
  <FilePreviewModal
    :is-open="isOpen"
    :files="files"
    :current-index="0"
    @close="isOpen = false"
  />
</template>
```

--------------------------------

### Test Custom Renderers

Source: https://github.com/wh131462/file-preview/blob/master/packages/vue-file-preview/README.md

Verify custom renderers by manually switching themes during development.

```vue
<FilePreviewModal
  :files="files"
  theme="light"  // Switch between 'light', 'dark', 'auto'
  :custom-renderers="[...]"
/>
```

--------------------------------

### Use Angular FilePreviewModal

Source: https://github.com/wh131462/file-preview/blob/master/README.md

Import the component and styles in the module or component, then use the selector in the HTML template.

```ts
import { FilePreviewModal } from '@eternalheart/angular-file-preview';
import '@eternalheart/angular-file-preview/style.css';
```

```html
<FilePreviewModal
  [files]="[file]"
  [currentIndex]="0"
  [isOpen]="true"
  (close)="isOpen = false"
/>
```

--------------------------------

### Define File Input Types

Source: https://github.com/wh131462/file-preview/blob/master/packages/vue-file-preview/README.md

Supported file input formats include native File objects, custom PreviewFileLink objects, and direct HTTP URL strings.

```typescript
// Supports three types of file input
type PreviewFileInput = File | PreviewFileLink | string;

// 1. Native File object (Browser File API)
const file: File = ...;

// 2. File object
interface PreviewFileLink {
  id?: string;       // Optional unique identifier
  name: string;      // File name
  type: string;      // MIME type
  url: string;       // File URL (supports blob URLs and HTTP URLs)
  size?: number;     // File size in bytes
}

// 3. HTTP URL string
const url: string = 'https://example.com/file.pdf';
```

--------------------------------

### Git Contributing Workflow

Source: https://github.com/wh131462/file-preview/blob/master/README.md

Standard commands for creating and pushing feature branches.

```bash
git checkout -b feature/amazing-feature
git commit -m 'feat: add amazing feature'
git push origin feature/amazing-feature
```

--------------------------------

### Implement Custom Renderer in Vue

Source: https://github.com/wh131462/file-preview/blob/master/README.md

Define a component for the renderer and pass the configuration to the FilePreviewModal.

```vue
<script setup>
import { FilePreviewModal } from '@eternalheart/vue-file-preview';

const CustomRenderer = {
  props: ['url'],
  template: '<div>Custom render: {{ url }}</div>'
};

const customRenderers = [
  {
    test: (file) => file.type === 'application/custom',
    render: () => CustomRenderer
  }
];
</script>

<template>
  <FilePreviewModal
    :files="files"
    :current-index="0"
    :is-open="true"
    :custom-renderers="customRenderers"
    @close="isOpen = false"
  />
</template>
```

--------------------------------

### Create Feature Branch

Source: https://github.com/wh131462/file-preview/blob/master/CONTRIBUTING.md

Use these commands to create a new branch for feature development or bug fixes.

```bash
git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix
```

--------------------------------

### Define file as URL string

Source: https://github.com/wh131462/file-preview/blob/master/packages/docs/guide/basic-usage.md

Use a simple string array to represent files by their remote URL.

```ts
const files = ['https://example.com/file.pdf']
```

--------------------------------

### Define file as native File object

Source: https://github.com/wh131462/file-preview/blob/master/packages/docs/guide/basic-usage.md

Use the standard browser File API for local file handling.

```ts
const file = new File(['content'], 'document.txt', { type: 'text/plain' })
```

--------------------------------

### Translate Toolbar Items

Source: https://github.com/wh131462/file-preview/blob/master/packages/vue-file-preview/README.md

Shows how to use t.value() for imperative translation calls within script logic, such as toolbar configuration.

```typescript
const getToolbarGroups = (): ToolbarGroup[] => [
  {
    items: [
      {
        type: 'button',
        icon: Download,
        tooltip: t.value('common.download'),  // ✅ Translated (use .value in script)
        action: handleDownload
      }
    ]
  }
];
```

--------------------------------

### Configure Multiple Input Types

Source: https://github.com/wh131462/file-preview/blob/master/packages/react-file-preview/README.md

Supports native File objects, HTTP URL strings, and objects with metadata. Ensure URL.revokeObjectURL() is called if generating object URLs to prevent memory leaks.

```tsx
import { FilePreviewModal, PreviewFileInput } from '@eternalheart/react-file-preview';
import '@eternalheart/react-file-preview/style.css';

function App() {
  // Assume `file1` comes from a File API source: <input type="file">,
  // drag & drop, clipboard paste, or fetch().then(r => r.blob())
  const file1 = new File(['content'], 'example.txt', { type: 'text/plain' });

  const files: PreviewFileInput[] = [
    // 1. Native File object (auto revoked when unmounted)
    file1,

    // 2. HTTP URL string (loaded on demand)
    'https://example.com/image.jpg',

    // 3. File object with metadata (recommended for remote resources)
    {
      name: 'document.pdf',
      type: 'application/pdf',
      url: '/path/to/document.pdf',
      size: 1024,
    },
  ];

  // Memory note: If you generate URLs via URL.createObjectURL(),
  // call URL.revokeObjectURL() when files are removed to avoid memory leaks.

  return (
    <FilePreviewModal
      files={files}
      currentIndex={0}
      isOpen={true}
      onClose={() => {}}
    />
  );
}
```

--------------------------------

### Import CSS Styles

Source: https://github.com/wh131462/file-preview/blob/master/packages/react-file-preview/README.md

Required CSS import for the component to render correctly.

```tsx
import '@eternalheart/react-file-preview/style.css';
```

--------------------------------

### FilePreviewContent

Source: https://github.com/wh131462/file-preview/blob/master/packages/react-file-preview/README.md

A low-level component used as the base for FilePreviewModal and FilePreviewEmbed.

```APIDOC
## FilePreviewContent

### Description
A lower-level component for building fully custom file preview wrappers.

### Props
- **mode** ('modal' | 'embed') - Required - Determines the rendering mode
- **files** (PreviewFileInput[]) - Required - Array of files
- **currentIndex** (number) - Required - Current file index
- **onNavigate** ((index: number) => void) - Required - Navigation callback
```

--------------------------------

### Add Upstream Remote

Source: https://github.com/wh131462/file-preview/blob/master/CONTRIBUTING.md

Add the upstream remote repository to track changes from the original project.

```bash
git remote add upstream https://github.com/wh131462/file-preview.git
```

--------------------------------

### FilePreviewModal Component

Source: https://github.com/wh131462/file-preview/blob/master/packages/react-file-preview/README.md

The main component used to display file previews. It supports internationalization and custom renderers for specific file types.

```APIDOC
## <FilePreviewModal />

### Description
The primary component for rendering file previews. It supports locale configuration, custom message overrides, and custom renderers for unsupported file types.

### Props
- **files** (Array) - Required - List of files to preview.
- **locale** (string) - Optional - Locale code (e.g., 'en-US'). Defaults to Chinese.
- **messages** (Object) - Optional - Object to override specific translation keys.
- **customRenderers** (Array) - Optional - Array of renderer objects containing a `test` function and a `render` component.
```

--------------------------------

### Apply Semantic Tailwind Classes

Source: https://github.com/wh131462/file-preview/blob/master/packages/vue-file-preview/README.md

Use semantic utility classes to ensure components automatically adapt to the current theme.

```vue
<template>
  <div class="vfp-bg-surface-1 vfp-border vfp-border-line-weak vfp-rounded">
    <h2 class="vfp-text-fg-primary vfp-text-lg">Title</h2>
    <p class="vfp-text-fg-secondary">Body text</p>
    <button class="vfp-bg-surface-2 hover:vfp-bg-surface-3 vfp-text-fg-primary">
      Click me
    </button>
    <pre class="vfp-bg-code-bg vfp-text-code-fg">{{ code }}</pre>
  </div>
</template>
```

--------------------------------

### Embed File Preview Inline

Source: https://github.com/wh131462/file-preview/blob/master/packages/angular-file-preview/README.md

Renders the preview component inline within a container, suitable for dashboards or detail panels.

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { FilePreviewEmbed } from '@eternalheart/angular-file-preview';
import '@eternalheart/angular-file-preview/style.css';

const index = ref(0);

const files = [
  'https://example.com/image.jpg',
  { name: 'document.pdf', type: 'application/pdf', url: '/doc.pdf' },
];
</script>

<template>
  <div style="width: 100%; height: 520px">
    <FilePreviewEmbed
      :files="files"
      :current-index="index"
      @navigate="index = $event"
    />
  </div>
</template>
```

```vue
<!-- Explicit size -->
<FilePreviewEmbed :files="files" :width="800" :height="500" />
```

--------------------------------

### FilePreviewModal Component

Source: https://github.com/wh131462/file-preview/blob/master/packages/vue-file-preview/README.md

The FilePreviewModal component provides a modal interface for viewing files. It requires files, current index, and open state to be defined.

```APIDOC
## FilePreviewModal Props

- **files** (PreviewFileInput[]) - Required - Array of files (supports File objects, file objects, or URL strings)
- **currentIndex** (number) - Required - Current file index
- **isOpen** (boolean) - Required - Whether the modal is open
- **customRenderers** (CustomRenderer[]) - Optional - Custom renderers for specific file types
- **locale** (Locale) - Optional - UI language ('zh-CN' default, 'en-US' built-in)
- **messages** (Partial<Record<Locale, Partial<Messages>>>) - Optional - Custom translation overrides
- **headless** (boolean) - Optional - Headless mode — hides toolbar and navigation arrows
- **theme** (Theme) - Optional - Theme mode: 'auto' | 'dark' | 'light' (default 'dark')
- **showDownload** (boolean) - Optional - Whether to show the download button (default true)
- **showClose** (boolean) - Optional - Whether to show the close button (default true for modal)

## FilePreviewModal Events

- **close** - Emitted when the modal should close
- **navigate** (number) - Emitted when navigating to a different file index
```

--------------------------------

### Copy PDF.js static files

Source: https://github.com/wh131462/file-preview/blob/master/packages/vue-file-preview/README.md

Manually copy necessary PDF.js worker and cmap files to your public directory.

```bash
cp -r node_modules/pdfjs-dist/build/pdf.worker.min.mjs public/pdfjs/
cp -r node_modules/pdfjs-dist/cmaps public/pdfjs/
```

--------------------------------

### Register Custom Renderer

Source: https://github.com/wh131462/file-preview/blob/master/packages/react-file-preview/README.md

Integrate the custom renderer into the FilePreviewModal by providing a test function and render component.

```tsx
import { CustomRenderer } from './CustomRenderer';

<FilePreviewModal
  files={files}
  customRenderers={[
    {
      test: (file) => file.type === 'application/custom',
      render: () => <CustomRenderer />
    }
  ]}
/>
```
Tokens:
Raw