laif-ds/dist/agent-docs/components/FilePreviewer.md

Design System di Laif con componenti React basati su principi di Atomic Design

 # 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.