viewdoc 0.1.0

package/README.md

@@ -0,0 +1,151 @@
+# viewdoc
+
+Universal React document viewer — images, PDFs, Word documents and Excel spreadsheets, all with zoom, pan, fullscreen and a consistent toolbar.
+
+```tsx
+import { DocViewer } from 'viewdoc'
+import 'viewdoc/styles.css'
+
+<DocViewer uri="https://example.com/report.pdf" />
+```
+
+That's it — `DocViewer` detects the file type from the URL and renders the right viewer.
+
+## Install
+
+```bash
+npm install viewdoc
+```
+
+`react` and `react-dom` (17+) are peer dependencies — install them if your project doesn't already have them.
+
+Don't forget the stylesheet:
+
+```tsx
+import 'viewdoc/styles.css'
+```
+
+## Supported file types
+
+| Type | Extensions | Powered by |
+|---|---|---|
+| Images | `.png` `.jpg/.jpeg` `.gif` `.webp` `.svg` `.bmp` `.ico` `.avif` | native `<img>` |
+| PDF | `.pdf` | `pdfjs-dist` |
+| Word | `.docx` | `mammoth` |
+| Excel | `.xlsx` `.xls` (legacy binary) `.xlsm` `.csv` | `xlsx` (SheetJS) |
+
+**Not supported:** old binary `.doc` (pre-2007 Word) — there's no reliable way to parse it in the browser. TIFF/HEIC/RAW images also aren't supported since browsers can't decode them natively.
+
+## Components
+
+### `DocViewer` (recommended)
+
+Auto-detects the file type and renders the matching viewer.
+
+```tsx
+<DocViewer uri="https://example.com/invoice.xlsx" fileName="invoice.xlsx" />
+```
+
+Detection reads the URL's path (ignoring query strings, so presigned S3/CloudFront URLs work correctly). If your URL has no reliable extension (e.g. an opaque storage key), force it:
+
+```tsx
+<DocViewer uri="https://example.com/blob/9f8a2b" type="pdf" />
+```
+
+`type` also accepts a MIME type (`"application/pdf"`, `"image/png"`, etc.) if that's what you have on hand.
+
+If detection fails and no `type` is given, `DocViewer` renders a `fallback` node (or a small default message):
+
+```tsx
+<DocViewer uri={file.url} fallback={<p>Can't preview this file type.</p>} />
+```
+
+### Individual viewers
+
+Use these directly if you already know the file type, or want a smaller bundle (each one is independently tree-shakeable):
+
+```tsx
+import { ImageViewer, PdfViewer, DocxViewer, XlsxViewer } from 'viewdoc'
+
+<ImageViewer uri="https://example.com/photo.jpg" />
+<PdfViewer uri="https://example.com/report.pdf" />
+<DocxViewer uri="https://example.com/letter.docx" />
+<XlsxViewer uri="https://example.com/budget.xlsx" />
+```
+
+## Props
+
+`DocViewer` and all four viewers share the same prop shape (`DocViewer` just adds `type` and `fallback` on top):
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `uri` | `string` | *required* | URL or data URI of the file |
+| `fileName` | `string` | — | Alt text / suggested download filename |
+| `className` / `style` | — | — | Applied to the outer wrapper |
+| `width` / `height` | `number \| string` | `1200` / `700` | Viewer size (px number or any CSS size) |
+| `minScale` / `maxScale` / `zoomStep` | `number` | varies by viewer | Zoom range and increment |
+| `enableZoomControls` | `boolean` | `true` | Show zoom out/in/reset buttons |
+| `enableWheelZoom` | `boolean` | `true` | Ctrl/Cmd + scroll wheel to zoom |
+| `enablePan` *(ImageViewer only)* | `boolean` | `true` | Click-drag-release panning of the image |
+| `enableFullscreen` | `boolean` | `true` | Show fullscreen toggle |
+| `enableDownload` | `boolean` | `true` | Show download button |
+| `onDownload` | `() => void` | — | Custom download handler; defaults to downloading `uri` |
+| `theme` | `ViewerTheme` | — | Override colors/radii (see below) |
+| `floating` | `boolean` | `true` | Render as a centered, draggable floating window vs. an embedded block that fills the parent |
+| `windowDraggable` | `boolean` | `true` | When floating, allow dragging via the toolbar's grip icon |
+| `defaultPosition` | `{ x: number; y: number }` | centered in viewport | Initial position when floating |
+
+Every boolean defaults to `true` — pass `false` to turn a feature off. Nothing needs to be configured to get a fully working viewer.
+
+## Theming
+
+Pass a `theme` object to override the default dark look. Any field you omit keeps its default:
+
+```tsx
+<DocViewer
+  uri={file.url}
+  theme={{
+    background: '#0b1220',
+    toolbarBackground: '#111827',
+    toolbarBorderColor: '#1f2937',
+    toolbarButtonHoverBackground: '#1f2937',
+    textColor: '#93c5fd',
+    borderRadius: '16px',
+  }}
+/>
+```
+
+Available fields: `background`, `toolbarBackground`, `toolbarBorderColor`, `toolbarButtonHoverBackground`, `textColor`, `borderRadius`, `toolbarButtonRadius`.
+
+## Embedded vs. floating mode
+
+By default every viewer opens as a **floating window**: centered on screen, draggable by its toolbar grip icon, sized 1200×700. This is meant for "preview this file" use cases (e.g. clicking a file in a list).
+
+If you want the viewer to sit inline in your layout instead — filling whatever container you put it in — set `floating={false}`:
+
+```tsx
+<div style={{ width: 600, height: 400 }}>
+  <DocViewer uri={file.url} floating={false} />
+</div>
+```
+
+In non-floating mode, the viewer still renders at its `width`/`height` (default 1200×700) and centers itself inside the parent container.
+
+## Interaction reference
+
+- **Zoom**: `+`/`−` buttons, click the `%` label or the reset icon to return to 100%, or hold Ctrl/Cmd and scroll
+- **Pan**: click-drag the content directly (images), or click-drag/scroll anywhere on the canvas (PDF, DOCX, XLSX — these use native scrolling under the hood, so the mouse wheel always works too)
+- **Move the window**: click-drag the small grip icon (⊹) at the left of the toolbar (only shown when `floating` is `true`)
+- **Fullscreen**: toggle button on the right of the toolbar
+- **Download**: button next to fullscreen; downloads `uri` unless you pass `onDownload`
+
+## Known limitations
+
+- Old binary `.doc`/legacy Word formats before 2007 aren't supported (only `.docx`)
+- The Excel table view is read-only — no cell editing or selection
+- `DocxViewer` and `XlsxViewer` render content via `dangerouslySetInnerHTML` using HTML generated from the file itself (by `mammoth`/`xlsx`) — treat untrusted files with the same caution you'd apply to any HTML you didn't author
+- PDF rendering resolves its worker script via `import.meta.url`, which requires an ESM-aware bundler (Vite, Webpack 5+, esbuild). CommonJS (`require`) consumers may need extra worker configuration
+
+## License
+
+MIT