[muhammad-ali-e]

What

• DocumentViewer (components/patterns/document-viewer/) is the component page tasks will import. It combines the loader, the status screens, the toolbar and the page list.
• ViewerToolbar: page navigation and zoom controls.
• lib/pdf/zoom.ts: zoom steps and fit-to-width / fit-to-page maths.
• lib/pdf/keyboard.ts: maps keys to viewer actions.
• hooks/useElementSize.ts: tracks an element's size.
• PdfPageList gains a ref handle, current-page reporting, zoom anchoring and a keyboard target.

Part of the v1 DocumentViewer (P1-T21, UN-4390).

Why

Six page tasks need one viewer with paging, zoom and programmatic scrolling. v0's viewers used setTimeout before jumping to a page. Here every scroll target is exact, because every page has its real size before it renders.

How

• API: <DocumentViewer source highlights activeHighlightId onHighlightClick initialZoom ref />. The ref exposes scrollToPage(index) and scrollToHighlight(id).
  • A scroll requested while the document is loading is queued, and runs once the pages are laid out.
  • When activeHighlightId changes, that highlight is centred in view. This replaces v0's jump-to-highlight on change.
• Scrolling: uses the pages' offsetTop / offsetHeight / offsetWidth, so it needs no timers and no waiting for a render.
  • A page lands at the top of the viewer.
  • A highlight is centred vertically. Word-level boxes are centred horizontally too.
• Toolbar: role="toolbar", and every control is a labelled button reachable with Tab, in reading order.
  • Previous / next.
  • A page box showing n / N. Enter jumps to the typed page; an out-of-range value reverts.
  • Zoom out / in, with a live zoom-level readout.
  • Fit width / fit page, shown as pressed while active.
  • Icons are Lucide: ZoomIn/ZoomOut/ChevronLeft/ChevronRight match the Prompt Studio viewer frames in the P1-T22 inventory. Figma has no glyph for fit width or fit page, so I picked MoveHorizontal and Scan. Easy to swap.
• Zoom:
  • Fit width is the default. The fit is computed from the viewer body's size via ResizeObserver, so it refits on resize.
  • Fit width uses the widest page; fit page fits every page (the smallest zoom that fits each one), so scrolling into a page of another size never rescales the document. Both leave room for the list padding and the platform scrollbar, measured once, not guessed. In a fit mode the pages wait for the viewer's size before laying out.
  • −/+ steps through 25 %–400 %, starting from wherever a fit left the zoom (e.g. 112 % → 125 %).
  • A zoom change keeps the same spot of the same page at the top. The anchor is recorded on scroll and restored in a layout effect after the pages resize.
• Keyboard: works while the pages region has focus. The region is focusable, as scrollable regions should be.
  • PageUp / PageDown move to the previous / next page.
  • Home / End go to the first / last page.
  • + / = zoom in, and - zooms out.
  • Keys pressed with Ctrl, Meta or Alt are left to the browser, so browser zoom still works.
• Current page: the page with the largest visible share, read from the layout on scroll and resize. A tie goes to the lower page. A page jumped to stays current while the view stays where the jump landed.
• New document: the page list is keyed per document, so opening another document starts fresh at the top.

Can this PR break any existing features. If yes, please list possible items. If no, please explain why. (PS: Admins do not merge the PR without this section filled)

• No. All the code is new and lives under src/v1/. Nothing in v0 or the v1 entry imports it yet, and lucide-react is already a dependency.

Database Migrations

• None

Env Config

• None

Relevant Docs

• P1-T21 implementation plan; P1-T22 icon inventory.

Related Issues or PRs

• Jira: UN-4505 (parent UN-4390)
• Stacked on UN-4504 [DEV] Add v1 PDF highlight layer and highlight normalisers #2407 (UN-4504) → UN-4503 [DEV] Render v1 PDF pages in a windowed, scrolling list #2405 → UN-4502 [DEV] Add the v1 PDF loader, document hook and viewer states #2404 → UN-4299 [FEAT] v1 design tokens, themes and style isolation (P0-T04) #2399 → UN-4270 [FEAT] v1 scaffold, strict TypeScript and import boundary #2380

Dependencies Versions

• None

Notes on Testing

• bun run typecheck:v1, lint:v1 and test:v1 pass: 125 unit tests and 56 boundary fixtures. biome ci src/ reports no errors.
• Zoom and keyboard maths: stepping from fitted zoom values, both fit modes, clamping and formatting; key mapping, including modified keys.
• Toolbar: n / N, prev/next disabled at the ends, typed jump and revert, zoom and fit buttons, the pressed state, and the full Tab order.
• Page list, with a stubbed layout:
  • scrollToPage is exact and clamped.
  • scrollToHighlight centres both ways, and returns false for an unknown id.
  • The zoom anchor holds the same spot across 1× → 2×.
  • The current page is the most visible one.
• DocumentViewer:
  • Loading, then toolbar; failure, then Retry.
  • Fit width shows 100 % for a Letter page in an 864 px body, refits to 50 % on resize, and + steps to 125 % and unpresses the fit.
  • + / - keys work, and Ctrl + + is ignored.
  • End / Home move between pages.
  • A scroll requested while loading lands after the document opens. A mutation check confirms this test fails if the queued request is dropped.
• Browser-level checks come in UN-4507.

Screenshots

• None yet. The gallery comes in UN-4507.

Checklist

I have read and understood the Contribution Guidelines.

---

Generated by Claude Code

[muhammad-ali-e]

pre-commit.ci - pr is red because of the base branch, not this PR.

The failing hook is check-shebang-scripts-are-executable, on frontend/scripts/check-v1-styles.mjs. That file has a #! line but no executable bit. It comes from the tokens PR #2399 (UN-4299-design-tokens-themes); this PR doesn't touch it. The hook doesn't fail on #2399 itself only because pre-commit.ci doesn't run on that PR. Running pre-commit run --from-ref $(git merge-base origin/main HEAD) locally reproduces it, and this PR's own files pass every hook.

There's no fix to port yet. The fix is a one-line change on #2399: git add --chmod=+x frontend/scripts/check-v1-styles.mjs (or drop the shebang). Once #2399 has it, this check should go green here without any change to this PR.

---

Generated by Claude Code

[greptile-apps]

via Greptile

Confidence Score: 5/5

[Low impact] The PR appears safe to merge; no blocking issues remain.

Summary

Adds the v1 DocumentViewer with page controls, zoom, keyboard shortcuts, and scrolling to pages or highlights.

• One v1 viewer brings PDF pages, document states, and scroll requests together.
• The page list tracks the reader’s position and jumps to exact page or highlight targets.
• The viewer toolbar lets readers move between pages and choose zoom controls.
• Fit zoom scales PDF pages to the measured viewer size and available space.
• The focused page list responds to page and zoom keys.

_{Reviews (6) · Last reviewed commit: "UN-4505 Drop a waiting scroll as soon as..." · Reviewed by Greptile}

[praveen-formido]

DocumentViewer, toolbar, zoom and keys. Two items I would fix first: viewerKeyAction does not check for an editable target, so any input rendered in an overlay loses -, =, Home, End and the page keys; and fit-width assumes a 16px scrollbar, which gives a permanent horizontal scrollbar on 17px classic scrollbars. The rest are smaller.

Also: the PR body says fit page uses the current page, but the code (and its comment at DocumentViewer.tsx:158) deliberately fits every page. The code reads as the intended behaviour; the body should say so.

Dismissed because a newer commit was pushed; Greptile will re-review the current head.

Dismissed because a newer commit was pushed; Greptile will re-review the current head.

Dismissed because a newer commit was pushed; Greptile will re-review the current head.

[sonarqubecloud]

Quality Gate passed

Issues
8 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud