# Record PDF Export
URL: /docs/web/docyrus/record-pdf-export

A three-step wizard (Select a Template → Preview → PDF) that renders a Docyrus data source record to PDF using its saved HTML templates, with an optional editable-template mode.

**Record PDF Export** turns a single Docyrus data source record into a PDF through a guided
three-step wizard:

1. **Select a Template** — lists the data source's saved HTML/PDF templates (`tenant_html_template`).
2. **Preview** — renders the chosen template compiled against the record, using the
   [`HtmlTemplateEditor`](/docs/web/components/html-template-editor) in **preview-only** mode.
3. **PDF** — generates the final PDF server-side and shows it in an inline viewer with a download button.
4. **Email** *(optional, when `sendEmail` is set)* — mounts an email composer
   ([`useDocyrusEmailComposer`](/docs/web/hooks/use-docyrus-email-composer)) with the generated PDF
   pre-attached, so the user can send the record straight from the wizard.

The headless [`useDocyrusRecordPdfExport`](#hook--usedocyrusrecordpdfexport) hook owns all data
fetching, step state, and PDF generation. `DocyrusRecordPdfExportWizard` is the batteries-included
UI built on top of it. The hook accepts a **`dataSourceId`** and **`recordId`** — the app / data
source slugs needed by the render endpoints are resolved automatically (or supplied explicitly).

**Demo:**

```tsx
'use client';

import { FileTextIcon } from 'lucide-react';

import { Step, Stepper } from '@docyrus/ui/components/stepper';
import { Button } from '@docyrus/ui/primitives/ui/button';

export function RecordPdfExportDemo() {
  return (
    <div className="flex w-full flex-col gap-4 rounded-lg border border-dashed border-border p-6 text-sm text-muted-foreground">
      

      <p>
        <code>{''}</code> requires an authenticated{' '}
        <code>RestApiClient</code> plus a <code>dataSourceId</code> and{' '}
        <code>recordId</code>. It lists the data source&apos;s saved HTML
        templates, previews the selected template compiled against the record
        (via the <code>HtmlTemplateEditor</code> in preview-only mode), and
        renders a server-side PDF — wire it to your tenant (or the playground)
        to see it live.
      </p>

      <div className="flex items-center gap-2">
        
      </div>
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-record-pdf-export
```

**Dependencies:**
- [@tanstack/react-query](https://www.npmjs.com/package/@tanstack/react-query)
- [lucide-react](https://www.npmjs.com/package/lucide-react)
- [@docyrus/api-client](https://www.npmjs.com/package/@docyrus/api-client)

## Usage

### Wizard inside a dialog

```tsx
import { useState } from 'react';

import { useDocyrusAuth } from '@docyrus/signin';
import { DocyrusRecordPdfExportWizard } from '@docyrus/ui/components/record-pdf-export';
import {
  Dialog,
  DialogContent,
  DialogHeader,
  DialogTitle,
  DialogTrigger
} from '@docyrus/ui/primitives/ui/dialog';
import { Button } from '@docyrus/ui/primitives/ui/button';

function ExportRecordButton({ dataSourceId, recordId }: { dataSourceId: string; recordId: string }) {
  const { client } = useDocyrusAuth();
  const [open, setOpen] = useState(false);

  if (!client) return null;

  return (
    
      
      
        
        
    
  );
}
```

### Editable-template mode

Pass `templateEditable` to let the user tweak the rendered document before exporting. The preview
step then exposes the **Code**, **Data** (read-only reference), and **Preview** tabs — the Code tab
holds the server-compiled document HTML for this record. When it is edited, the PDF step renders the
edited HTML through the custom-body endpoint instead of the saved template.

```tsx

```

### Email step

Pass `sendEmail` to append an **Email** step. After the PDF is generated, the wizard mounts an email
composer (via [`useDocyrusEmailComposer`](/docs/web/hooks/use-docyrus-email-composer)) with the
rendered PDF pre-attached (sent through its storage path) and the user's email accounts loaded into
the From selector. Sending requires the `Messaging.Email.Send` OAuth scope.

```tsx

```

### Headless — drive your own UI

```tsx
import { HtmlTemplateEditor } from '@docyrus/ui/components/html-template-editor';
import { useDocyrusRecordPdfExport } from '@docyrus/ui/components/record-pdf-export';

function CustomExport({ client, dataSourceId, recordId }) {
  const {
    step, goNext, goBack, canGoNext,
    templates, selectedTemplateId, setSelectedTemplateId,
    previewEditorProps,
    pdfUrl, isGeneratingPdf
  } = useDocyrusRecordPdfExport({ client, dataSourceId, recordId });

  // Step 1 — render `templates` and call `setSelectedTemplateId(id)`.
  // Step 2 — 
  // Step 3 — <iframe src={pdfUrl} /> (auto-generated on entering the step).
}
```

## How it works

| Step | Endpoint(s) | Notes |
|------|-------------|-------|
| Resolve slugs | `GET /v1/dev/data-sources/:dataSourceId` | Maps `dataSourceId` → `app_slug` + `slug`. Skipped when `appSlug` + `dataSourceSlug` are supplied. |
| List templates | `GET /v1/dev/html-templates?tenantDataSourceId=:dataSourceId` | Drives the "Select a Template" step. The default template (`is_default`) is auto-selected. |
| Compiled preview | `GET /v1/apps/:appSlug/data-sources/:dataSourceSlug/items/:recordId/templates/:templateId/html` | Returns the **server-compiled** document `body` (+ `styles`) for this record — the same `templateCompiler` the PDF uses. This is the preview source, so the preview matches the PDF exactly. |
| Record data (editable only) | `GET /v1/apps/:appSlug/data-sources/:dataSourceSlug/items/:recordId?columns=*` | Read-only reference shown in the editable-mode Data tab. |
| Render PDF (saved) | `GET /v1/apps/:appSlug/data-sources/:dataSourceSlug/items/:recordId/templates/:templateId/pdf` | Default path. The server compiles the saved template against the record. |
| Render PDF (edited) | `PUT /v1/apps/:appSlug/data-sources/:dataSourceSlug/items/:recordId/renderPdfTemplate/:templateId` | Used in `templateEditable` mode when the compiled HTML was edited. Sends the edited HTML as a `multipart/form-data` `body` file (`data={}` so the server loads the record for header/footer). |

## Preview uses the HTML Template Editor

The preview step mounts [`HtmlTemplateEditor`](/docs/web/components/html-template-editor) with the
**server-compiled** document HTML as `value`, then restricts the visible tabs. Compiling on the
server (rather than client-compiling the raw template against the raw record) is what makes the
preview faithful — the record's fields are mapped/expanded exactly as they are for the PDF. Three
editor props power this:

| Prop | Type | Purpose |
|------|------|---------|
| `visibleTabs` | `HtmlTemplateEditorTab[]` | Restricts which tabs render (and their order). The wizard passes `['preview']` (read-only) or `['code', 'data', 'preview']` (editable). The tab strip auto-hides when a single tab remains, and the Visual/Plate tab is intentionally omitted (its round-trip is lossy for complex nested-block table templates). |
| `dataReadOnly` | `boolean` | Makes only the **Data** tab read-only while keeping the Code editor editable — the record data is a reference, not editable. |
| `previewStyles` | `string` | Extra CSS injected into the Preview iframe (the template's `styles`), without baking a `<style>` block into the Plate document tree. |

In **editable** mode the user tweaks the *compiled* document HTML (the final output for this record)
in the Code tab — the custom-body PDF endpoint takes final HTML as-is, so this is the only
round-trip-faithful editing surface the API supports.

## Hook — `useDocyrusRecordPdfExport`

```tsx
const wizard = useDocyrusRecordPdfExport(options);
```

### Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `client` | `RestApiClient` | — | Authenticated REST client. |
| `dataSourceId` | `string` | — | `tenant_data_source.id` of the record's data source. |
| `recordId` | `string` | — | `tenant_data_source_item.id` of the record to render. |
| `appSlug` | `string` | — | App slug. When omitted, resolved from `dataSourceId`. |
| `dataSourceSlug` | `string` | — | Data source slug. When omitted, resolved from `dataSourceId`. |
| `enabled` | `boolean` | `true` | Toggles all network activity. |
| `templateEditable` | `boolean` | `false` | Exposes template + read-only Data tabs in the preview; edited bodies render via the custom-body endpoint. |
| `sendEmail` | `boolean` | `false` | Appends an **Email** step that mounts a composer with the generated PDF pre-attached. Sending needs the `Messaging.Email.Send` scope. |
| `initialTemplateId` | `string` | — | Pre-select a template by id. |
| `autoSelectDefaultTemplate` | `boolean` | `true` | Auto-select the default (or first) template once the list resolves. |
| `resolveDataSourceEndpoint` | `string` | `/v1/dev/data-sources/{id}` | Endpoint override for slug resolution. |
| `listTemplatesEndpoint` | `string` | `/v1/dev/html-templates` | Endpoint override for the templates list. |
| `templateDetailEndpoint` | `string` | `/v1/dev/html-templates/{templateId}` | Endpoint override for a template's body. |

### Returns

| Field | Type | Description |
|-------|------|-------------|
| `steps` | `RecordPdfExportStep[]` | Ordered steps for this wizard — includes `'email'` when `sendEmail` is set. |
| `step` / `setStep` / `stepIndex` | `RecordPdfExportStep` … | Current step (`'select' \| 'preview' \| 'pdf' \| 'email'`) and controls. |
| `goNext` / `goBack` / `canGoNext` / `canGoBack` / `isLastStep` | — | Step navigation. |
| `appSlug` / `dataSourceSlug` / `isResolving` / `resolveError` | — | Resolved slugs + resolution state. |
| `templates` / `isLoadingTemplates` / `templatesError` / `refetchTemplates` | — | Templates list state. |
| `selectedTemplateId` / `setSelectedTemplateId` / `selectedTemplate` | — | Selected template. |
| `templateDetail` / `isLoadingTemplateDetail` / `templateDetailError` | `DocyrusHtmlTemplateDetail` … | Selected template's body / styles. |
| `record` / `recordJson` / `isLoadingRecord` / `recordError` | — | The target record (object + pretty JSON string). |
| `templateEditable` / `editedHtml` / `setEditedHtml` / `isDirty` / `resetEdits` | — | Editable body state. |
| `generatePdf` / `isGeneratingPdf` / `pdfResult` / `pdfUrl` / `pdfError` | — | PDF generation. Auto-fires on entering the PDF step. |
| `previewEditorProps` | `RecordPdfExportPreviewEditorProps` | Ready to spread onto `<HtmlTemplateEditor>` for the preview step. |
| `reset` | `() => void` | Reset the wizard back to the first step. |

## API Reference — `DocyrusRecordPdfExportWizard`

Extends every [hook option](#options) plus:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `className` | `string` | — | Wrapper class. |
| `bodyHeight` | `string` | `'70vh'` | Height of the wizard body region. |
| `onClose` | `() => void` | — | Fired by the footer **Done** button on the PDF step. |
| `hideClose` | `boolean` | `false` | Hide the footer **Done** button. |

## Type Exports

| Type | Description |
|------|-------------|
| `UseDocyrusRecordPdfExportOptions` | Options for the hook. |
| `UseDocyrusRecordPdfExportResult` | Return shape of the hook. |
| `RecordPdfExportPreviewEditorProps` | Props spread onto `HtmlTemplateEditor` for the preview. |
| `DocyrusRecordPdfExportWizardProps` | Props for the wizard component. |
| `DocyrusHtmlTemplateSummary` | Template list row. |
| `DocyrusHtmlTemplateDetail` | Template detail row (adds `body` / `styles`). |
| `DocyrusRecordPdfResult` | The upstream html-to-pdf result (`url`, `filename`, …). |
| `RecordPdfExportStep` | `'select' \| 'preview' \| 'pdf'`. |