50 lines
2.0 KiB
Markdown
50 lines
2.0 KiB
Markdown
# Proposal — `@suaveplan/react-pdf-preview` (deferred)
|
||
|
||
- **Status**: STUB (deferred from `enterprise-pdf` Chunk E)
|
||
- **Spec delta**: not yet authored — see Why / What below.
|
||
- **Depends on**: `@suaveplan/pdf@0.1.0` (Chunks A–E, shipped).
|
||
|
||
## Why
|
||
|
||
The upstream `@suaveplan/pdf` ships a `pdf-preview` React 19 component
|
||
(`/mnt/s/web/suaveplan/packages/server/pdf/src/components/pdf-preview/`)
|
||
that renders a `Document` AST as a live HTML preview, scaled to a
|
||
configurable viewport, with synchronised scrolling and printable
|
||
hard-page boundaries. The genesis `@suaveplan/pdf` package is
|
||
deliberately server-tier (no React/DOM peer deps) — the preview must
|
||
land in a sibling React-tier package so consumers can opt in without
|
||
inflating the server bundle.
|
||
|
||
## What
|
||
|
||
Create `@suaveplan/react-pdf-preview` at
|
||
`packages/devtools/docs/react-pdf-preview/` (React 19 peer-dep only,
|
||
consumes `@suaveplan/pdf` via `workspace:^`). Land:
|
||
|
||
- `PdfPreview` React component rendering a `Document<TData>` via the
|
||
layout engine into HTML primitives (no canvas — accessibility wins).
|
||
- `usePdfPreview` hook returning page-by-page render slots + scaling
|
||
helpers.
|
||
- Storybook stories: default + scaled + paginated + dark-mode +
|
||
printable-overlay variants.
|
||
- Playwright E2E spec exercising scroll-to-page, scale toggle, and
|
||
PDF download.
|
||
- 100 / 100 / 100 / 100 Istanbul coverage + 100% docs coverage.
|
||
|
||
## Out of scope
|
||
|
||
- Replacing the server-tier renderer — the React preview consumes the
|
||
same `Document` AST produced by `createDocument` / template factories.
|
||
- Browser-tier PDF.js binding — that's a separate adapter package
|
||
(`@suaveplan/pdf-viewer`) tracked elsewhere.
|
||
- Native (iOS / Android) preview — a future React Native package.
|
||
|
||
## Acceptance criteria
|
||
|
||
- Package builds, lints, typechecks, tests, and ships with 100/100/100/100
|
||
coverage.
|
||
- Every exported symbol carries a co-located `.md` and a story.
|
||
- E2E spec passes against a staging Storybook deployment.
|
||
- `@suaveplan/pdf` remains React-free — the preview consumes its public
|
||
surface only.
|