vobi_document 1.0.0 → 1.0.1

package/README.md

@@ -1,66 +1,113 @@
-# document-generator
+# vobi_document
 
-Biblioteca do gerador de documentos. Build duplo (ESM + CJS) com tipos, schema em
-Zod e componentes React com styled-components.
+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.
 
-> Task A1 — scaffold. Entry point é placeholder; features entram a partir da A2.
+## Por que existe
 
-## Stack
+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:
 
-- **TypeScript** (strict)
-- **tsup** — build ESM + CJS + `.d.ts`
-- **Zod** — schema do documento
-- **styled-components** + **React** (peer dependencies)
-- **Jest** + ts-jest + Testing Library
-- **ESLint 9** (flat config) + airbnb (via FlatCompat) + Prettier
-- **pnpm** — gerenciador
-- **yalc** — link local para consumo na `homehero-app-bo`
+| 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 |
 
-## Setup
+`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** — texto, botão, divisor, quebra de página, imagem, grade de imagens, orçamento, tabela, ícone + texto, imagem + texto e duas colunas (`defaultBlocks`).
+- **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` 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
 
 ```bash
-pnpm install
+pnpm add vobi_document
+```
+
+Peer dependencies (o host deve declarar as quatro — precisam ser instância única compartilhada com a lib):
+
+```bash
+pnpm add react react-dom styled-components @puckeditor/core
+```
+
+> Duas cópias de `@puckeditor/core` ou `styled-components` não geram erro de versão — falham silenciosamente (contexto errado no `usePuck`, estilos ausentes no HTML publicado). Detalhes em `docs/build-and-consume.md`.
+
+## Uso básico
+
+```tsx
+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}
+/>
 ```
 
-## Scripts
+Primitivas do Puck ficam no subpath dedicado, fora do barrel principal:
 
-| Script | Ação |
-| --- | --- |
-| `pnpm build` | Build de produção (`dist/`, ESM + CJS + types) |
-| `pnpm dev` | Build em watch |
-| `pnpm typecheck` | `tsc --noEmit` |
-| `pnpm test` | Roda os testes (Jest) |
-| `pnpm test:watch` | Testes em watch |
-| `pnpm test:coverage` | Testes com cobertura |
-| `pnpm lint` | ESLint |
-| `pnpm lint:fix` | ESLint com autofix |
-| `pnpm format` | Prettier write |
-| `pnpm deploy:local` | Build + `yalc push` para os consumidores |
+```ts
+import { Puck, Render, usePuck } from 'vobi_document/puck';
+```
 
-## Consumo local na homehero-app-bo (yalc)
+## Desenvolvimento
 
-Na lib:
+Requer Node >= 20 e **pnpm** (nunca npm/yarn).
 
 ```bash
-pnpm build
-yalc publish
+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
 ```
 
-Na `homehero-app-bo`:
+Gate obrigatório antes de finalizar qualquer branch:
 
 ```bash
-yalc add document-generator
-npm install
+pnpm typecheck && pnpm lint && pnpm test && pnpm build
 ```
 
-Durante o desenvolvimento, `pnpm deploy:local` na lib faz build e dá push para os
-projetos que já têm o link via `yalc add`.
+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).
 
-## Publicação npm
+## Documentação
 
-Fluxo pronto (publish manual no fim do dev):
+Detalhe técnico mora em `docs/`:
 
-```bash
-pnpm build   # via prepublishOnly
-npm publish
-```
+| Assunto | Doc |
+|---------|-----|
+| Visão geral / arquitetura | [docs/architecture.md](docs/architecture.md) |
+| Blocos / registry / criar bloco | [docs/blocks.md](docs/blocks.md) |
+| Tema / cores / fonte / página / header | [docs/theme.md](docs/theme.md) |
+| Variáveis dinâmicas | [docs/variables.md](docs/variables.md) |
+| Autosave | [docs/autosave.md](docs/autosave.md) |
+| Build / yalc / publicação | [docs/build-and-consume.md](docs/build-and-consume.md) |
+| API pública / exports | [docs/api.md](docs/api.md) |

package/dist/index.cjs

@@ -1529,7 +1529,7 @@ function ColorPicker({
   const wrapperRef = e.useRef(null);
   const effective = value ?? fallback ?? "#000000";
   if (presets.length % 6 !== 0) {
-    console.warn(`[document-generator] paleta com ${presets.length} cores n\xE3o fecha linhas de 6 (docs/theme.md).`);
+    console.warn(`[vobi-document] paleta com ${presets.length} cores n\xE3o fecha linhas de 6 (docs/theme.md).`);
   }
   e.useEffect(() => {
     if (!open) return void 0;