@arbidocs/blocks 0.4.68 → 0.4.70

package/README.md

@@ -19,7 +19,7 @@ Optional peers, only needed for the entry that uses them:
 
 | Peer | Needed by |
 | --- | --- |
-| `@tanstack/react-query` | `@arbidocs/blocks/connect`, `@arbidocs/blocks/studio` |
+| `@tanstack/react-query` | `@arbidocs/blocks/connect`, `@arbidocs/blocks/studio`, `@arbidocs/blocks/document-tools` |
 | `react-router-dom` | `@arbidocs/blocks/studio` |
 | `@measured/puck` | `@arbidocs/blocks/studio` |
 | `@playwright/test` | types of `@arbidocs/blocks/record` (no runtime import) |
@@ -67,6 +67,8 @@ Every capability is its own entry, so a bundler only loads what you use:
 | `/files`, `/facts` | document grid, facts table | `ag-grid-*` |
 | `/artifacts` | artifact editor, version bar, track changes | none |
 | `/artifacts/editor` | rich-text (markdown) editing surface | `@mdxeditor/editor` (optional peer) |
+| `/document-tools` | PDF markup, signing and version parts (see below) | `@tanstack/react-query` |
+| `/document-tools/viewer` | annotated PDF viewer, signature placement | `pdf-lib`, `react-pdf` (optional peers of `@arbidocs/react`) |
 | `/home`, `/workspaces` | dashboard, workspace cards and forms | `@dnd-kit/*` |
 | `/settings` | settings, billing, modals | `cmdk` |
 | `/connect` | demo/live connection layer | `@tanstack/react-query` |
@@ -157,6 +159,88 @@ draft is stored and parsed, then the editor on the stored version (the presentat
 <StreamedArtifact artifacts={task.artifacts} workspaceId={workspaceId} busy={task.status === 'running'} error={task.error} />
 ```
 
+## Using the document tools in another frontend
+
+The PDF document tools are what ARBI's document page uses: annotate (highlight, comment, stamp,
+redact) with the marks saved as the version's markup on the server (autosave, colleagues' edits
+merged in), "Show original", "Download with markup", the notes about markup on an older version
+("Copy open comments here") and about marks left in this browser, Freeze (a separate annotated or
+redacted copy, with a redaction log), e-signing (choose where the signature goes, sign with the
+password; only the signature and optionally the date are drawn), the signature details with "View
+certificate", the public certificate page, and the read-only version bar.
+
+| Import | What |
+| --- | --- |
+| `@arbidocs/react/document-tools` | `DocumentToolsProvider`, `useDocumentMarkup`, `createMarkupStore`, `fetchMarkupPdf`, `canAnnotate`, `useDocumentSignatures`, `useSignDocument`, `useSignatureVerification` |
+| `@arbidocs/blocks/document-tools` | `AnnotateButton`, `ShowOriginalButton`, `DownloadMarkupButton`, `SignButton`, `MarkupNotices`, `MarkupViewNote`, `SignDocumentDialog`, `SignatureStatus`, `SignatureCertificate`, `VersionSnapshotBar` |
+| `@arbidocs/blocks/document-tools/viewer` | `AnnotatedPdfViewer`, `SignaturePlacementViewer` (load lazily: pdf-lib) |
+
+What the host provides, once, around the viewer (the tools import no store, router or toast
+library of their own):
+
+- an ARBI API client signed in as the user: `arbi.getClient().fetch` from an `@arbidocs/sdk`
+  `Arbi`, or `createArbiClient(...).fetch` from `@arbidocs/client`;
+- `deploymentDomain` (the one the user's keys are derived for) and `user: { name, email }`, for
+  signing; without a user marks are authored as "You";
+- callbacks, all optional: `notify(message, kind, { description, action })`, `openDocument(ref)`
+  (the copy just frozen, the signed copy), `onDocumentsChanged(ids, 'markup' | 'copy' | 'signed')`
+  to refresh your lists, `emailDocument(ref)` (adds "Email it" after signing), `uploadDocument`,
+  `saveFile` and `certificateUrl` (defaults: the API client, a download link, `/verify/{ref}`);
+- a React Query `QueryClientProvider`, the blocks styles (see Styles), and the pdf.js assets the
+  kit `PdfViewer` loads (`/pdf.worker.min.mjs`, `/cmaps/`, `/standard_fonts/` by default) plus the
+  optional peers `react-pdf`, `pdfjs-dist` and `pdf-lib`.
+
+```tsx
+import { lazy, Suspense, useState } from 'react'
+import { DocumentToolsProvider, useDocumentMarkup, useDocumentSignatures } from '@arbidocs/react/document-tools'
+import { AnnotateButton, MarkupNotices, SignatureStatus } from '@arbidocs/blocks/document-tools'
+const AnnotatedPdfViewer = lazy(() =>
+  import('@arbidocs/blocks/document-tools/viewer').then((m) => ({ default: m.AnnotatedPdfViewer })))
+
+<DocumentToolsProvider
+  client={arbi.getClient().fetch}
+  deploymentDomain={deploymentDomain}
+  user={{ name: 'Ana Lopez', email: 'ana@firm.example' }}
+  notify={(message, kind) => toast[kind](message)}
+  openDocument={(ref) => navigate(`/documents/${ref}`)}
+  onDocumentsChanged={() => queryClient.invalidateQueries({ queryKey: ['documents'] })}
+>
+  <DocumentPage doc={doc} pdf={pdfBlob} />
+</DocumentToolsProvider>
+
+function DocumentPage({ doc, pdf }) {
+  // `doc` is the document record (DocResponse): external_id, shared, folder, current_version, versions.
+  const [editing, setEditing] = useState(false)
+  const markup = useDocumentMarkup(doc, undefined)
+  const { data: signatures } = useDocumentSignatures(doc.external_id)
+  return (
+    <>
+      <AnnotateButton active={editing} onClick={() => setEditing((on) => !on)} />
+      {signatures?.signed && <SignatureStatus status={signatures} />}
+      <MarkupNotices legacyPrompt={markup.legacyPrompt} olderNote={markup.olderNote}
+        onOpenVersion={(n) => navigate(`/documents/${doc.external_id}@v${n}`)} />
+      <Suspense fallback={null}>
+        <AnnotatedPdfViewer file={pdf} documentId={doc.external_id} fileName={doc.file_name}
+          shared={!!doc.shared} folder={doc.folder} editing={editing}
+          onMarkupChange={markup.onMarkupChange} />
+      </Suspense>
+    </>
+  )
+}
+```
+
+A signed version is locked: only a further signature changes it. Pass `signed` to
+`AnnotatedPdfViewer` and a `disabledReason` (`SIGNED_LOCKED_REASON`, from `isSignedVersion(doc)` or
+the signature status) to `DownloadMarkupButton`: marks stay in the markup layer and are never
+written into its PDF, and the plain download is the signed file. Show `SignedEditNote` above any
+editor of a signed version ("Editing creates a new unsigned version").
+
+`AnnotatedPdfViewer` and `SignaturePlacementViewer` take your own binding of the kit viewer as
+`viewer` (for example one that reports the visible page); `SignaturePlacementViewer`'s
+`onContinue(appearance)` hands the box to `SignDocumentDialog`. Serve `SignatureCertificate` on a
+route that needs no sign-in (ARBI uses `/verify/:reference`), inside a `DocumentToolsProvider` with
+an unauthenticated client: it is the page the signature on a signed PDF links to.
+
 ## Editorial site parts
 
 `@arbidocs/blocks/site` (and the root) carry the layout parts for static marketing pages: