# FilePreviewer

## Overview

Modal file preview component with support for images, PDFs (including secure read-only mode), audio, video, text, and Office documents (via online viewers). Use helper functions to open the modal from anywhere; mount the component once.

---

## API

### Functions

| Function               | Signature     | Description                       |
| ---------------------- | ------------- | --------------------------------- | ---------------------------------------------- | ---------------------------------------- |
| `previewFileModal`     | `(arg: string | PreviewOptions) => Promise<void>` | Opens the preview modal. Resolves when closed. |
| `safePreviewFileModal` | `(arg: string | PreviewOptions) => Promise<void   | undefined>`                                    | Safe variant that never throws on close. |

```ts
export type PreviewOptions = {
  url?: string;
  filename?: string;
  mimeType?: string;
  title?: React.ReactNode;
  readOnly?: boolean; // Enables SecurePdfViewer for PDFs
  page?: number; // Initial page for PDFs (1-based)
};
```

### Component

- `FilePreviewer`: Mount once near the app root. Controls the dialog UI and renders the appropriate preview body.

---

## Behavior

- **Kind detection**: Determines preview type from `mimeType`, `filename` or `url`.
- **Image**: Responsive `<img>` with contain fit.
- **PDF**:
  - `readOnly=true` uses `SecurePdfViewer` with `page` support.
  - Otherwise embedded via `<iframe>` (supports `#page=` parameter).
- **Audio/Video**: Native `<audio>`/`<video>` players.
- **Text**: Rendered in an `<iframe>` for remote text URLs.
- **Office**: Uses an online viewer when `url` is HTTP(S); otherwise shows a fallback notice.
- **Dialog**: Uses `Dialog` with `size="xl"` and a heading showing `title` or `filename` with a file icon.

---

## Examples

### Preview an Image (URL)

```tsx
import { Button } from "laif-ds";
import { FilePreviewer, previewFileModal } from "laif-ds";

export function PreviewImageButton() {
  return (
    <>
      <Button
        onClick={() =>
          previewFileModal({
            url: "https://picsum.photos/id/1003/1200/800",
            filename: "image.jpg",
            title: "Random Image",
          })
        }
      >
        Preview Image
      </Button>
      <FilePreviewer />
    </>
  );
}
```

### PDF with Read-only Secure Viewer

```tsx
import { Button } from "laif-ds";
import { FilePreviewer, previewFileModal } from "laif-ds";

export function PreviewPdf() {
  return (
    <>
      <Button
        onClick={() =>
          previewFileModal({
            url: "https://mozilla.github.io/pdf.js/web/compressed.tracemonkey-pldi-09.pdf",
            filename: "dummy.pdf",
            title: "PDF Document",
            readOnly: true,
            page: 1,
          })
        }
      >
        Preview PDF
      </Button>
      <FilePreviewer />
    </>
  );
}
```

### Office Document (XLSX)

```tsx
import { Button } from "laif-ds";
import { FilePreviewer, previewFileModal } from "laif-ds";

export function PreviewSpreadsheet() {
  return (
    <>
      <Button
        onClick={() =>
          previewFileModal({
            url: "https://filesamples.com/samples/document/xlsx/sample3.xlsx",
            filename: "spreadsheet.xlsx",
            title: "Excel Spreadsheet",
            readOnly: true,
          })
        }
      >
        Preview XLSX
      </Button>
      <FilePreviewer />
    </>
  );
}
```

---

## Notes

- **Mount**: Add a single `<FilePreviewer />` near app root or in Storybook decorators.
- **Filenames**: If `filename` is omitted, it is inferred from `url`.
- **Security**: For local files, prefer read-only mode for PDFs when appropriate.