vobi_document

Lib React (TypeScript estrito) para criação e renderização de documentos ricos — orçamentos, propostas, contratos — com editor drag-and-drop e saída pronta para impressão/PDF. Feita para ser consumida por outros projetos como camada completa de documentos: o host fornece dados, tema e variáveis; a lib entrega edição, preview e HTML paginado.

Por que existe

Montar documentos num app de gestão normalmente vira três implementações que divergem: a tela de edição, o preview e o PDF. Aqui as três superfícies renderizam exatamente o mesmo layout, porque todas partem da mesma config:

| Superfície | Componente | Base | |------------|-----------|------| | Editor (drag-and-drop) | <DocumentEditor> | <Puck> (@puckeditor/core) | | Preview / viewer | <DocumentRenderer> | <Render> | | PDF (server-side) | <DocumentRenderer resolvedVariables={...}> + buildDocumentHtml | <Render> + Paged.js |

buildConfig(registry, { theme }) gera uma única config de Puck que alimenta editor e renderer — qualquer divergência entre edição e saída final é eliminada por construção.

Principais recursos

• Editor visual — drag-and-drop de blocos, painel de estrutura (outline), bloqueio de blocos por permissão, header customizável via render-prop.
• Blocos prontos — 14 blocos genéricos em defaultBlocks: texto, título, lista, destaque, botão, divisor, espaço, imagem, grade de imagens, duas colunas, imagem + texto, ícone + texto, tabela e quebra de página. Todos com propsSchema e com as variáveis já resolvidas.
• Blocos customizados — o host cria os seus com defineBlock e registra no mesmo registry; entradas posteriores sobrescrevem por key.
• Tema — cores (brand/texto/fundo), fonte (allow-list Google Fonts), logo, formato e margens de página, tudo validado por Zod (themeSchema) e aplicado via CSS vars no PageFrame.
• Variáveis dinâmicas — chips no texto (<span class="dg-var" data-var-key="customer.name">) resolvidos a partir de um catálogo + resolver fornecidos pelo host; valores formatados em pt-BR; suporte a variáveis não resolvidas com placeholder ou label.
• Paginação para impressão — buildDocumentHtml (em vobi_document/print) gera HTML paginado com Paged.js embarcado: capa (coverBlockKey), header/footer com dados da empresa, repetição de cabeçalho de tabela entre páginas e blocos protegidos de corte (noCutBlockKeys).
• Schemas Zod — parseDocument / safeParseDocument validam o documento completo antes de persistir ou renderizar.
• Autosave — useDocumentAutosave com debounce para persistência incremental no host.

Instalação

pnpm add vobi_document

Peer dependencies (o host deve declarar as cinco — precisam ser instância única compartilhada com a lib):

pnpm add react react-dom styled-components @puckeditor/core zod

Duas cópias de @puckeditor/core, styled-components ou zod não geram erro de versão — falham silenciosamente (contexto errado no usePuck, estilos ausentes no HTML publicado, instanceof ZodError falso). Detalhes em docs/build-and-consume.md.

Uso básico

import {
  buildConfig,
  defaultBlocks,
  DocumentEditor,
  DocumentRenderer,
} from 'vobi_document';

const registry = [...defaultBlocks, meuBlocoCustomizado];

// Edição
<DocumentEditor
  registry={registry}
  theme={theme}
  data={data}
  onChange={setData}
  catalog={catalog}
  resolver={resolver}
  ctx={ctx}
/>

// Preview / PDF
<DocumentRenderer
  registry={registry}
  theme={theme}
  data={data}
  resolvedVariables={resolved}
/>

Entry points

O barrel principal traz tudo que roda no browser. As camadas também têm subpath próprio, para import granular:

| Subpath | Contém | |---------|--------| | vobi_document | core + reexport de blocks/editor/render/variables | | vobi_document/blocks | defineBlock, defaultBlocks, ContentIcon | | vobi_document/editor | DocumentEditor, settings, color picker, autosave | | vobi_document/render | DocumentRenderer, capa, header/footer | | vobi_document/print | buildDocumentHtml, buildPageCss — não sai do barrel | | vobi_document/variables | catálogo, resolver, chips | | vobi_document/puck | primitivas cruas do Puck |

import { buildDocumentHtml } from 'vobi_document/print';  // servidor / preview
import { Puck, Render, usePuck } from 'vobi_document/puck';

./print fica fora do barrel porque carrega o Paged.js embutido (~513kb) e react-dom/server — um host que só monta editor ou viewer não deve arriscar carregá-los. Isso derrubou o barrel de 631kb para 131kb e o index.d.ts de 387kb para 9,3kb. Migração de 1.0.x em docs/build-and-consume.md.

Desenvolvimento

Requer Node >= 20 e pnpm (nunca npm/yarn).

pnpm install
pnpm build          # tsup -> dist (ESM + CJS + .d.ts)
pnpm test           # jest
pnpm lint           # eslint 9 flat + airbnb + prettier
pnpm typecheck      # tsc --noEmit
pnpm deploy:local   # build + yalc push para os consumidores linkados

Gate obrigatório antes de finalizar qualquer branch:

pnpm typecheck && pnpm lint && pnpm test && pnpm build

Durante o desenvolvimento local, o consumo se dá via yalc (pnpm link:setup na primeira vez, pnpm deploy:local nas atualizações — reinicie o dev server do consumidor após cada push).

Documentação

Detalhe técnico mora em docs/:

| Assunto | Doc | |---------|-----| | Visão geral / arquitetura | docs/architecture.md | | Blocos / registry / criar bloco | docs/blocks.md | | Tema / cores / fonte / página / header | docs/theme.md | | Variáveis dinâmicas | docs/variables.md | | Autosave | docs/autosave.md | | Build / yalc / publicação | docs/build-and-consume.md | | API pública / exports | docs/api.md |