Format-specific source viewers

Use Source to choose the viewer automatically. The components below provide format-specific controls and require Sea context. They accept the same step bindings.

Source viewers display original documents and highlight the locations behind extracted values.

At a glance
Type	Building block
Elements	`sea-pdf-viewer`, `sea-image-viewer`, `sea-xlsx-viewer`
React	`SeaPdfViewer` from `@sea-dev/widget-lit/react/pdf-viewer`; `SeaImageViewer` from `@sea-dev/widget-lit/react`
Without React	`@sea-dev/widget-lit/pdf-viewer`, `@sea-dev/widget-lit/image-viewer`, `@sea-dev/widget-lit/xlsx-viewer`
Connection	Required Sea context. A PDF viewer can use an explicit document URL
Configure	The attributes under each viewer below

Usage

Source	Element	Input
PDF	`sea-pdf-viewer`	`pdfUrl` or a bound source
Image	`sea-image-viewer`	`documentExtractionId`
Excel or CSV	`sea-xlsx-viewer`	`documentExtractionId`

Import the registration modules through your host's bundler:

import "@sea-dev/widget-lit/context";
import type { SeaContext } from "@sea-dev/widget-lit/context";
import { SeaPdfViewer } from "@sea-dev/widget-lit/pdf-viewer";
import { SeaImageViewer } from "@sea-dev/widget-lit/image-viewer";
import { SeaXlsxViewer } from "@sea-dev/widget-lit/xlsx-viewer";

PDF

Web components

export function showPdf(provider: SeaContext, url: string) {
  const viewer = new SeaPdfViewer();
  viewer.pdfUrl = url;
  viewer.style.cssText = "display:block;height:640px";
  provider.append(viewer);
  return viewer;
}

React

The React wrapper is SeaPdfViewer from @sea-dev/widget-lit/react/pdf-viewer.

It requires Context provider, including when pdfUrl supplies the document. It reads documents and active citations from the provider. An explicit pdfUrl takes precedence. activePage selects a page when a citation is unset.

PDF attributes and properties

Property	Attribute	Type	Default	Description
`pdfUrl`	`pdf-url`	`string`	`""`	Loads this PDF URL instead of the document selected by context.
`documentExtractionId`	`document-extraction-id`	`string`	`""`	Selects one source document from the provider's loaded extractions.
`contentType`	`content-type`	`string`	`""`	Identifies the document format when the URL lacks an extension.
`workerUrl`	`worker-url`	`string`	`""`	Sets the shared PDF.js worker URL.
`documentUrl`	—	`DocumentUrlResolver or undefined`	—	Rewrites the source document URL before retrieval.
`documentProxy`	`document-proxy`	`string`	`""`	Fetches the source document through a host proxy endpoint.
`annotations`	—	`SourceAnnotation[]`	`[]`	Supplies source highlight regions for an explicit document.
`activeAnnotationKey`	`active-annotation-key`	`string or undefined`	—	Selects a highlighted region by annotation key.
`activeCitationId`	`active-citation-id`	`string or undefined`	—	Selects the active citation.
`activePage`	`active-page`	`number or undefined`	—	Selects a page, starting at 1, when no active citation or annotation is set.
`tabs`	—	`PdfTab[] or undefined`	—	Groups PDF pages into named tabs using each tab's `pageNumbers` list.
`citationPopoverPlacement`	`citation-popover-placement`	`string`	`""`	Places citation details at `gutter`, `rail`, `below`, `above`, `beside` or `edge`, inheriting the context when unset.
`stepLabel`	`step-label`	`string or undefined`	—	Selects one step by its unique pipeline label within the enclosing process.
`stepRole`	`step-role`	`PipelineStepRoleWire or undefined`	—	Constrains the selected step to this execution role.
`stepId`	`step-id`	`string or undefined`	—	Selects a pipeline step definition within the enclosing process.
`runStepId`	`run-step-id`	`string or undefined`	—	Selects one executable step instance within the enclosing process.
`outputFormId`	`output-form-id`	`string or undefined`	—	Narrows the selected step's outputs to this form.
`outputSubmissionId`	`output-submission-id`	`string or undefined`	—	Selects an exact output submission from the enclosing process.
`workerSrc`	—	`string or null`	`null`	Sets the shared PDF.js worker URL before the first viewer mounts.

PDF events

Event	Type	Description
`pdf-loaded`	`CustomEvent`	`{ numPages }` after a PDF loads.
`pdf-load-error`	`CustomEvent`	`{ error }` when PDF loading fails.
`citation-clicked`	`CustomEvent`	`{ annotationKey, citationId, citationIds }` when a highlighted source is selected.

PDF styling parts

Part	Description
`root`	The source viewer container.
`toolbar`	The page, zoom and source controls.
`content`	The scrollable document area.
`status`	Loading, empty and error messages.

Images

Web components

Pass an already configured <sea-context> element to showImage.

export function showImage(provider: SeaContext, documentExtractionId: string) {
  const viewer = new SeaImageViewer();
  viewer.documentExtractionId = documentExtractionId;
  viewer.style.cssText = "display:block;height:640px";
  provider.append(viewer);
  return viewer;
}

React

The React wrapper is SeaImageViewer from @sea-dev/widget-lit/react and accepts the same extraction identity.

Mount the image viewer inside Context provider for a known submission. Set documentExtractionId to a document in the submission or its referenced upstream sources. Read results describes the returned document identities.

Without an explicit identity, the viewer follows the provider's selected document or opens its only loaded source. Several unselected sources show a selection prompt. An unavailable extraction shows Retry. A loaded source retries its owning submission. If an explicit or provider-selected extraction is missing in the current round, Retry reloads the current submission and its referenced sources, plus the loaded current document request. The viewer opens only an exact extraction match. An explicit or provider-selected extraction can keep showing the current document request's source while another submission is inspected. Historic rounds use their own sources.

The viewer reads file metadata and citations from Sea. Configure documentUrl or document-proxy on the provider.

Image attributes and properties

Property	Attribute	Type	Default	Description
`documentExtractionId`	`document-extraction-id`	`string`	`""`	Selects an image extraction from the provider's loaded document sources.
`stepLabel`	`step-label`	`string or undefined`	—	Selects one step by its unique pipeline label within the enclosing process.
`stepRole`	`step-role`	`PipelineStepRoleWire or undefined`	—	Constrains the selected step to this execution role.
`stepId`	`step-id`	`string or undefined`	—	Selects a pipeline step definition within the enclosing process.
`runStepId`	`run-step-id`	`string or undefined`	—	Selects one executable step instance within the enclosing process.
`outputFormId`	`output-form-id`	`string or undefined`	—	Narrows the selected step's outputs to this form.
`outputSubmissionId`	`output-submission-id`	`string or undefined`	—	Selects an exact output submission from the enclosing process.

Image events

Event	Type	Description
`citation-selected`	`CustomEvent`	`{ citationId, documentExtractionId }` selects the bound document before its highlight is activated.
`citation-clicked`	`CustomEvent`	`{ annotationKey, citationId, citationIds }` when a highlighted source is selected.

Image styling parts

Part	Description
`root`	The source viewer container.
`toolbar`	The zoom or sheet controls.
`content`	The scrollable source document.
`status`	Loading, empty and error messages.

Spreadsheets

Web components

export function showSpreadsheet(
  provider: SeaContext,
  documentExtractionId: string,
) {
  const viewer = new SeaXlsxViewer();
  viewer.documentExtractionId = documentExtractionId;
  viewer.style.cssText = "display:block;height:640px";
  provider.append(viewer);
  return viewer;
}

React

The React wrapper is SeaXlsxViewer from @sea-dev/widget-lit/react and accepts the same extraction identity.

Mount the spreadsheet viewer inside Context provider and select a backend extraction with documentExtractionId. It follows the same selection and Retry rules as images. Filename, MIME type, URL and citations come from the provider. Configure source URL handling on the provider.

The preview displays up to 1,000 rows and 100 columns, moving to the selected backend citation. Stored sheet IDs and cell coordinates select the matching worksheet and cells.

Spreadsheet attributes and properties

Property	Attribute	Type	Default	Description
`documentExtractionId`	`document-extraction-id`	`string`	`""`	Selects a spreadsheet extraction from the provider's loaded document sources.
`stepLabel`	`step-label`	`string or undefined`	—	Selects one step by its unique pipeline label within the enclosing process.
`stepRole`	`step-role`	`PipelineStepRoleWire or undefined`	—	Constrains the selected step to this execution role.
`stepId`	`step-id`	`string or undefined`	—	Selects a pipeline step definition within the enclosing process.
`runStepId`	`run-step-id`	`string or undefined`	—	Selects one executable step instance within the enclosing process.
`outputFormId`	`output-form-id`	`string or undefined`	—	Narrows the selected step's outputs to this form.
`outputSubmissionId`	`output-submission-id`	`string or undefined`	—	Selects an exact output submission from the enclosing process.

Spreadsheet events

Event	Type	Description

Spreadsheet styling parts

Part	Description
`root`	The source viewer container.
`toolbar`	The zoom or sheet controls.
`content`	The scrollable source document.
`status`	Loading, empty and error messages.

Document collection

The document list selects a source for sibling viewers.

What they need from the API

Read a signed URL from documents[].url in submission results, then let the browser load the file. The PDF viewer can obtain its document through Context provider. Image and spreadsheet viewers read their URL and citations from the bound extraction.

Set documentProxy to a host endpoint to fetch through your application, or supply a documentUrl function to rewrite the URL. A proxy receives ?url=<encoded-original-url> and returns document bytes. Configure these settings on Context provider for image and spreadsheet viewers. PDF viewers and Document intake also accept them directly.

Worker and highlights

Deploy the generated assets with the application. For a custom PDF worker URL, set SeaPdfViewer.workerSrc before mounting or workerUrl on a viewer. Use the same worker version for all PDF viewers.

Set --sea-highlight to change source highlight colour. The PDF viewer accepts annotations, activeAnnotationKey and activeCitationId as properties. Image and spreadsheet viewers read highlighting from Context provider.

This PDF highlight uses page 1 and normalised coordinates from 0 to 1:

import "@sea-dev/widget-lit/pdf-viewer";
import type { SeaPdfViewer } from "@sea-dev/widget-lit/pdf-viewer";

export function highlightTotal(viewer: SeaPdfViewer) {
  viewer.annotations = [
    {
      key: "total-assets",
      boundingRegions: [
        {
          pageNumber: 1,
          polygon: [0.1, 0.2, 0.6, 0.2, 0.6, 0.25, 0.1, 0.25],
        },
      ],
      linkedCitations: [
        {
          id: "citation-1",
          sourceRef: "document-1",
          path: "TotalAssets",
          value: 1250000,
        },
      ],
    },
  ];
  viewer.activeAnnotationKey = "total-assets";
  viewer.activeCitationId = "citation-1";
}

PDF tabs accepts { id, label, pageNumbers? } entries. Page numbers start at 1; omitting them shows all pages.

PDF method	Use
`scrollToPage(pageNumber)`	Scroll to a page numbered from 1
`scrollToAnnotation(key)`	Scroll to the named source highlight

Common problems

Symptom	Action
PDF fails to open	Check the document request and worker errors; see asset and CSP settings
Browser blocks a document	Allow the host origin in storage CORS or configure a document proxy
Signed URL expired	Read submission data again and assign the refreshed URL
Spreadsheet requests a fresh link	Select Refresh document to reload the bound source owner
Highlight is missing	Check the annotation identifiers and active selection

Format-specific source viewers ​

Usage ​

PDF ​

Web components ​

React ​

PDF attributes and properties ​

PDF events ​

PDF styling parts ​

Images ​

Web components ​

React ​

Image attributes and properties ​

Image events ​

Image styling parts ​

Spreadsheets ​

Web components ​

React ​

Spreadsheet attributes and properties ​

Spreadsheet events ​

Spreadsheet styling parts ​

Document collection ​

What they need from the API ​

Worker and highlights ​

Common problems ​

Format-specific source viewers

Usage

PDF

Web components

React

PDF attributes and properties

PDF events

PDF styling parts

Images

Web components

React

Image attributes and properties

Image events

Image styling parts

Spreadsheets

Web components

React

Spreadsheet attributes and properties

Spreadsheet events

Spreadsheet styling parts

Document collection

What they need from the API

Worker and highlights

Common problems