React API

@imposia/react binds one Core controller and one canonical iframe into the React lifecycle. It also re-exports the Core and Viewer API surface, so a React application usually needs no other Imposia import. Import @imposia/react/styles.css once.

ImposiaPageViewer and ImposiaDocument

ImposiaPageViewer mounts a Core page document, then binds the page Viewer after the first commit. ImposiaDocument is a compatibility wrapper with the same public props and handle types: ImposiaDocumentProps = ImposiaPageViewerProps and ImposiaDocumentHandle = ImposiaPageViewerHandle.

const viewer = useRef<ImposiaPageViewerHandle>(null);

<ImposiaPageViewer
  ref={viewer}
  source={{ html: "<main><h1>Report</h1></main>" }}
  documentOptions={{ page: { size: "A4", margin: "18mm" } }}
  viewerOptions={{ mode: "single", inspector: true }}
  onError={console.error}
/>;

ImposiaPageViewerHandle

Handle methods act on the latest committed generation. Methods that need the Viewer or a commit throw (or reject) before the first commit and after unmount.

Deferred preparation and retry (0.7.0)

preparation is available on ImposiaPageViewer, its ImposiaDocument wrapper, and useImposiaDocument. "immediate" (default) starts on mount; "idle" uses requestIdleCallback with a 1500 ms timeout, or a 200 ms timer when unavailable; "manual" waits for prepare() or retry(). Changing the policy does not pause an already started controller. Subsequent source/revision changes update normally after preparation has started.

The hook result and component handle both expose prepare(): void and retry(): void. prepare() starts once; repeated calls do nothing. retry() starts if needed, remounts after a synchronous mount failure, or calls update with the latest source on the existing controller. Options are captured at mount; increment documentOptionsRevision to apply changed options. Retry does not replace an already-aborted documentOptions.signal; provide a fresh signal and option revision for that case.

In ready, state.source identifies the source used for that committed document. In loading, error, or aborted, a previous committed state.document may remain, but state.source is absent. All five statuses are idle, loading, ready, aborted, and error. Abortion is terminal and does not call onError.

const { hostRef, state, prepare, retry } = useImposiaDocument({
  source: { html }, preparation: "manual",
});
return <>
  <button onClick={prepare}>Prepare preview</button>
  {state.status === "error" && <button onClick={retry}>Retry</button>}
  <div ref={hostRef} aria-busy={state.status === "loading"} />
</>;

Viewer fit, zoomable, and keyboard changes remount the presentation binding while preserving the current page, uncontrolled mode/zoom, and Core iframe. The deferred preparation API is for a single document; useImposiaPublication does not expose these methods.

ImposiaPublicationViewer

const publication = useRef<ImposiaPublicationViewerHandle>(null);

<ImposiaPublicationViewer
  ref={publication}
  snapshot={{
    metadata: { title: "Guide", language: "en" },
    entries: [{ id: "intro", title: "Introduction", html: "<h1>Introduction</h1>" }],
  }}
/>;

Its required snapshot prop accepts PublicationSnapshot. Optional props are snapshotRevision, publicationOptions, publicationOptionsRevision, viewerOptions (without reader), readerOptions (without controller), className, style, onReady, onError, and onStateChange. Revision props force updates/remounts as their names indicate. The component supplies the reader/controller binding itself, which is why reader and controller are excluded from its option props.

ImposiaPublicationViewerHandle

All actions except current and resolveDestination throw after unmount. Reader actions also throw before the Publication reader is ready.

useImposiaDocument and useImposiaPublication

useImposiaDocument(props: UseImposiaDocumentProps): UseImposiaDocumentResult;
useImposiaPublication(props: UseImposiaPublicationProps): UseImposiaPublicationResult;

Both hooks return a hostRef, lifecycle state, and a controller that is undefined until the mount effect creates it. Attach hostRef to one div. A loading or error state can retain the last committed document/publication.

useImposiaDocument accepts the page component's source, revision, options, and callbacks. HTML sources update when HTML/base URL changes; light-DOM sources update when node identity changes. sourceRevision forces an update, and documentOptionsRevision remounts the controller.

useImposiaPublication accepts the publication component's snapshot, revision, options, and callbacks. It updates when the snapshot reference or snapshotRevision changes; publicationOptionsRevision remounts the controller. Both hooks destroy their controller on cleanup and treat AbortError as lifecycle cancellation.

function Article({ html }: { html: string }) {
  const { hostRef, state } = useImposiaDocument({ source: { html } });
  return <div ref={hostRef} aria-busy={state.status === "loading"} />;
}