@quario/viewer

The embeddable viewer. It lays a compiled report out on your page geometry, paints the pages, and wires the export menu. It compiles nothing and never touches the event stream. It sits on @quario/landing, the package the two surface elements share, which a host never imports.

Registering the element

const TAG: 'quario-viewer'

Import @quario/viewer/register to define the element, or import QuarioViewer and define it yourself.

QuarioViewer

A LitElement. Set properties as element properties, not attributes.

Children with slot="bar" sit in the bar. They follow the page controls and come before the search, view, and export controls.

get renderComplete(): Promise<boolean>

It resolves once a pending render settles.

get pageNumber(): number
set pageNumber(value: number)
get pageCount(): number
get query(): string
set query(value: string)

pageNumber counts from 1, and pageCount is the length. Both read 0 until a render lands. A page number past the end goes to the last page, and one written before a render lands waits for it. query searches the whole report, and "" searches for nothing. A value of the wrong shape for either is a host-option error and goes nowhere.

The viewer hides each page’s canvas from assistive technology. It lays the page’s text over the canvas as a group named “Page n of N”. A screen reader reads that text, and a reader selects and copies it. A run’s href is a link in that layer, .qv-link as before, and the layer itself is .qv-mirror, formerly .qv-links. A table reads as a table, and restates its headings on each page it continues onto. --qv-focus also tints selected text, and --qv-match colours the current search match.

Types

type ViewableReport = CompiledReport
type ViewerPage = LayoutPage
type ViewerFonts = LayoutFonts
type ViewerParams = Readonly<Record<string, JsonValue>>

ViewerStrings

Every key is optional, and a key left out stays English. A function’s result goes through String(). A function that throws draws the English text, and the viewer reports it once per record as a host-option error. The marking and an error’s own message aren’t the viewer’s wording, so neither is here.

The other keys take a string.

Pass the same fonts record here and to pdf({ fonts }), and hold it across renders. It’s the identity the viewer remembers a face by.

Events

interface QuarioViewerEventMap {
  rendered: CustomEvent<undefined>
  error: CustomEvent<ViewerErrorDetail>
  pagechange: CustomEvent<ViewerPageChangeDetail>
  searchchange: CustomEvent<ViewerSearchChangeDetail>
  link: CustomEvent<ViewerLinkDetail>
}

interface ViewerPageChangeDetail {
  pageNumber: number
  pageCount: number
}

interface ViewerSearchChangeDetail {
  query: string
  match: number
  matches: number
}

interface ViewerLinkDetail {
  href: string
}

interface ViewerErrorDetail {
  error: unknown
  kind: 'mount-render' | 'update-render' | 'export' | 'host-option'
}

host-option names a property the viewer rejected, which reached no render at all. mount-render covers a failure before any render lands on the sheet, and update-render covers one after. export covers a download or a print the viewer couldn’t produce.

pagechange and searchchange fire only when their values change, the first render included. link fires before a click or a middle click opens a URL link, and preventDefault() keeps the tab from opening. A #label link never fires it.

addEventListener and removeEventListener take their types from that map.

An unlicensed report carries the marking on the sheet the viewer paints, just as it does in an export.