Feature request: 2-D grid layout for the thumbnail plugin (multi-column + horizontal)

Aperta
#701 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
12/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Tranquilla
Stack tecnologico
typescript
Ambito
frontend

Direzione di ricerca

The relevant code is in the @embedpdf/plugin-thumbnail package: start from the public types ThumbMeta and WindowState, updateWindow(scrollY, viewportH) and ThumbnailDocumentState, then the reducer that stacks thumbnails by top and the ThumbnailsPane that places them. This is a design proposal still waiting on the maintainers' answers to its three questions, so the first step is agreeing the API shape (additive layout mode versus a breaking change to those types) rather than editing files. Done means a settled orientation/cross-axis-count model plus a prototype PR.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Feature request: 2-D grid layout for the thumbnail plugin (multi-column + horizontal)

Plugin: @embedpdf/plugin-thumbnail (observed on 2.14.4)

Summary

Today the thumbnail plugin lays thumbnails out as a single vertical column and virtualizes them along one axis (vertical). I'd like to propose making the layout model 2-dimensional by default — a grid where the current single column is simply the 1-column case — which would unlock:

  • Multi-column rails that reflow into 2/3/… columns as the pane gets wider.
  • Horizontal strips (a filmstrip) that flow into 2/3/… rows as they get taller and scroll sideways.

Curious whether this direction aligns with how you'd want the plugin to evolve before anyone invests in it.

Current behavior

The layout and windowing are modelled on a single vertical axis. From the public types:

  • ThumbMeta positions each thumbnail with only a vertical top offset (no x / column / left).
  • WindowState is { start, end, items, totalHeight }, and updateWindow(scrollY, viewportH) only receives the vertical scroll position and viewport height.
  • ThumbnailDocumentState tracks scrollY / viewportH — no cross-axis extent.
  • The reducer stacks thumbnails by top and picks the visible window by comparing top against scrollY.

So there's no representation for "which column" or "how far across," which is what a grid or a horizontal strip needs.

Motivation

We're building thumbnail UIs on top of the plugin and keep hitting the same wall: a fixed-width sidebar wastes space when the user widens it (it can't add columns), and there's no first-class horizontal/filmstrip mode. Users increasingly expect thumbnail panels to behave like a responsive grid.

We currently work around this by reusing ThumbImg for the actual bitmap rendering (which is great) and reimplementing the layout + windowing ourselves outside the plugin. That works, but it means the plugin's own windowing/state is unused, and every consumer who wants a grid has to rebuild the same thing. It'd be much nicer if the plugin owned it.

Proposed direction (open to your take)

Treat the layout as a grid by default, with orientation:

  • An orientation (vertical | horizontal) picking the scroll axis.
  • A cross-axis count — either a fixed column/row count or derived from the pane's measured cross-axis size and the thumbnail size (so it can reflow responsively).
  • Per-thumbnail metadata carrying both a main-axis and cross-axis position, so ThumbnailsPane can place items in a grid.
  • Windowing that accounts for the cross-axis count (N items per line), while still only rendering the lines near the viewport.

The nice property here is that 2-D is a superset of 1-D: the existing single-column behavior is just orientation: vertical with a cross-axis count of 1. So supporting a grid doesn't cost anyone the current layout — it stays available as the default, and callers who only want a column keep getting exactly that.

Questions for maintainers

  1. Is a 2-D/grid + orientation model something you'd want in the core plugin, or do you see thumbnail layout as intentionally the consumer's job (plugin = rendering only)?
  2. If in-core: would you prefer it as a breaking evolution of the current types (ThumbMeta / WindowState / updateWindow), or an additive opt-in layout mode alongside the existing 1-D path?
  3. Any constraints I should know about (SSR, the framework adapters, existing consumers) that would shape the API?

Happy to help — including a prototype PR — if there's appetite and rough agreement on the shape. Wanted to check direction first rather than drop a large change cold.

Lingua principale
TypeScript
Stelle
4.5k
Fork
317
Merge medio
10h 16m
PR unite (30g)
174

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di embedpdf/embed-pdf-viewer

Tutte le issue di embedpdf/embed-pdf-viewer

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.