React API

@imposia/react는 Core 컨트롤러 하나와 canonical iframe 하나를 React 수명 주기에 연결합니다. Core와 Viewer의 API 표면도 다시 내보내므로, React 앱에는 대개 다른 Imposia import가 필요 없습니다. @imposia/react/styles.css는 한 번만 불러오세요.

ImposiaPageViewer와 ImposiaDocument

ImposiaPageViewer는 Core 페이지 문서를 마운트한 뒤, 첫 확정 이후에 Page Viewer를 연결합니다. ImposiaDocument는 공개 prop과 핸들 타입이 같은 호환 래퍼입니다. ImposiaDocumentProps = ImposiaPageViewerProps, ImposiaDocumentHandle = ImposiaPageViewerHandle입니다.

const viewer = useRef<ImposiaPageViewerHandle>(null);

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

ImposiaPageViewerHandle

핸들 메서드는 마지막 확정 세대에 작용합니다. Viewer나 확정된 문서가 필요한 메서드는 첫 확정 전과 언마운트 후에 예외를 발생시키거나 Promise를 거부합니다.

ImposiaPublicationViewer

const publication = useRef<ImposiaPublicationViewerHandle>(null);

<ImposiaPublicationViewer
  ref={publication}
  snapshot={{
    metadata: { title: "안내서", language: "ko" },
    entries: [{ id: "intro", title: "소개", html: "<h1>소개</h1>" }],
  }}
/>;

필수 prop인 snapshot은 PublicationSnapshot을 받습니다. 선택 prop은 snapshotRevision, publicationOptions, publicationOptionsRevision, viewerOptions(reader 제외), readerOptions(controller 제외), className, style, onReady, onError, onStateChange입니다. revision prop은 이름 그대로 갱신과 재마운트를 강제합니다. Reader와 컨트롤러 연결은 컴포넌트가 직접 제공하며, reader와 controller가 옵션 prop에서 제외된 이유입니다.

ImposiaPublicationViewerHandle

current와 resolveDestination을 제외한 모든 동작은 언마운트 후 호출하면 예외가 발생합니다. Reader 동작은 Publication Reader가 준비되기 전에 호출해도 예외가 발생합니다.

useImposiaDocument와 useImposiaPublication

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

두 훅은 hostRef, 수명 주기 state, 그리고 마운트 effect가 만들기 전까지 undefined인 컨트롤러를 반환합니다. hostRef는 div 하나에 연결하세요. loading이나 error 상태에서도 마지막으로 확정된 문서 또는 Publication이 남아 있을 수 있습니다.

useImposiaDocument는 페이지 컴포넌트의 source, revision, 옵션, 콜백을 받습니다. HTML 원본은 HTML이나 기준 URL이 바뀔 때 갱신되고, light DOM 원본은 노드 정체성이 바뀔 때 갱신됩니다. sourceRevision은 갱신을 강제하고, documentOptionsRevision은 컨트롤러를 다시 마운트합니다.

useImposiaPublication은 Publication 컴포넌트의 snapshot, revision, 옵션, 콜백을 받습니다. 스냅샷 참조나 snapshotRevision이 바뀔 때 갱신되고, publicationOptionsRevision은 컨트롤러를 다시 마운트합니다. 두 훅 모두 정리 단계에서 컨트롤러를 제거하고 AbortError를 수명 주기 취소로 봅니다.

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