@meistrari/minuta-react 1.2.0 → 1.4.0

package/README.md

@@ -35,6 +35,8 @@ um `Blob` de `.docx`. Buscar o documento, persistir a edição e baixar o arquiv
 | `chrome` | — | `{ header, footer, headerScope, footerScope, showPageNumber }` |
 | `variables` | — | catálogo `{ key, label, description?, group? }[]` → liga o modo template |
 | `uploadImage` | — | `(file) => Promise<{ src, vaultSrc } \| null>` |
+| `imageFallback` | `'dataUri'` | `'none'` = upload falhou → não insere nada, só `onImageUploadError` |
+| `onImageUploadError` | — | `(error, file) => void` |
 | `toolbar` | `true` | `false` = você monta a sua sobre `ref.current.tiptap` |
 | `blockClickWhileEditing` | `false` | dispara `onBlockClick` também em edição (padrão: só em leitura) |
 | `onChange` | — | `(html) => void`, a cada edição |
@@ -71,6 +73,28 @@ const t = editor.current?.tiptap
 <MinutaEditor ref={editor} html={html} toolbar={false} onTransaction={rerender} />
 ```
 
+### Numerar parágrafo
+
+O número dos parágrafos da peça ("12. A Ré…") é um nó próprio, não texto:
+continua a sequência do template e sai como numeração nativa no Word. Com a
+toolbar do pacote há o botão **1.**; numa toolbar própria:
+
+```tsx
+import { hasLeadingTopicNumber, toggleTopicNumber } from '@meistrari/minuta-react'
+
+// `editor.current` é null até o mount: proteja a leitura no render
+const tiptap = editor.current?.tiptap
+<Button type={tiptap && hasLeadingTopicNumber(tiptap) ? 'primary' : 'default'}
+        onClick={() => tiptap && toggleTopicNumber(tiptap)}>1.</Button>
+```
+
+(`toggleTopicNumber` equivale a `tiptap.chain().focus().toggleTopicNumber().run()`;
+há também `setTopicNumber()` e `unsetTopicNumber()`.) Enter no fim de um
+parágrafo numerado já cria o seguinte numerado, sem botão. **Não** use a
+"lista numerada" (`toggleOrderedList`) para isso: ela cria uma lista com recuo
+próprio, fora da sequência da peça.
+
+
 Os tipos de `chain().toggleBold()` viajam com o pacote — não precisa importar
 `@tiptap/*` no seu código.
 
@@ -81,13 +105,21 @@ de conta no defesa.ai:
 
 ```
 GET   /data/case/:id/html                    → { html, chrome, margins, source, editionId, variablesMarked, markedVariables }
-POST  /data/case/:id/editions { name, html } → cria a edição → { id, updatedAt, … }
-PATCH /data/case/:id/editions/:id            → salva → { updatedAt, updatedBy, … }
+POST  /data/case/:id/editions { name, html } → cria a edição → { id, updatedAt, contentHash, … }
+PATCH /data/case/:id/editions/:id            → salva → { updatedAt, updatedBy, contentHash, … }
       { html, baseUpdatedAt }                  400 sem o token; 409 se outro salvou antes
+GET   /data/case/:id/editions                → [{ id, updatedAt, updatedBy, contentHash, … }] sem html
 POST  /data/case/:id/editions/:id/versions   → marco no histórico (o PATCH NÃO cria versão)
+      { comment?, baseUpdatedAt? }             com baseUpdatedAt: 409 se a revisão mudou; já versionada → 200 reused
 POST  /data/case/:id/docx                    → .docx do estado atual (a edição, se existir)
 ```
 
+`contentHash` é o sha256 do `html` exatamente como foi gravado (o servidor não
+normaliza): num save que deu timeout, compare com o hash do que você enviou
+pela listagem, sem baixar o documento. `baseUpdatedAt` no `POST …/versions`
+amarra o checkpoint à revisão que você viu: a versão nunca sai com o seu nome
+e o texto que outra pessoa salvou depois, e repetir a chamada não duplica.
+
 ```tsx
 // abrir
 const doc = await api.get(`/case/${caseId}/html`)
@@ -175,20 +207,51 @@ Sobre o fluxo de "enviar variáveis de volta": com uma edição viva o documento
 modelo do defesa.ai), ou você mantém os dois vivos com `setVariableValue` +
 salva a edição. Decisão de UX do seu app; as duas funcionam.
 
+### Voltar ao checklist sem perder a edição
+
+Esqueceu uma tese ou variável no meio da edição? Mude o caso (`PATCH
+/data/case/:id`), busque o documento que o checklist gera agora e aplique sobre
+o texto editado — só o que mudou entra, e trecho que o advogado editou vira
+pergunta em vez de ser sobrescrito:
+
+```tsx
+const { html } = await api.get(`/data/case/${caseId}/html?source=blocks`)
+const result = editor.current!.applyChecklist(html)
+for (const c of result.conflicts) // 'replace' | 'remove' — a UI é sua
+    editor.current!.resolveChecklistConflict(c.blockId, 'keep' /* ou 'apply' */)
+// DEPOIS das decisões: bloco inserido ou aceito pode trazer imagem vault://
+await editor.current!.refreshVaultImages(resolver)
+```
+
+Para isso funcionar a edição precisa nascer marcada: depois de montar o editor
+com o HTML do checklist, antes do primeiro save, chame
+`editor.current!.stampGenerated()`.
+
 ### Imagens inseridas pelo advogado
 
 `uploadImage` devolve `{ src, vaultSrc }`: o editor grava a tag com o `src`
-(presignado, expira) e `data-vault-src` (a `vault://`, durável). Ao reabrir uma
-edição salva, renove os links antes de mostrar:
+(presignado, expira) e `data-vault-src` (a `vault://`, durável). Persista o
+`getHTML()` como está: o `POST /data/case/:id/docx` usa o `data-vault-src` e
+resolve `vault://` sozinho. Ao reabrir uma edição salva, renove os links antes
+de mostrar:
 
 ```tsx
 // resolver: POST /data/vault/download-url { vaultUrl } → { downloadUrl } (pelo seu backend)
 await editor.current!.refreshVaultImages(vaultUrl => api.post('/vault/download-url', { vaultUrl }).then(r => r.downloadUrl))
 ```
 
-Não entra no undo nem dispara `onChange`. O `exportDocx()` do browser baixa
-pelo `src`, então renove antes de exportar também; o `POST /data/case/:id/docx`
-resolve `vault://` sozinho.
+Renova tanto `data-vault-src` quanto imagens salvas só com `src="vault://…"`
+(que ganham o `data-vault-src`), mantendo a referência durável. Não entra no
+undo nem dispara `onChange`: chame `getHTML()` depois se guarda uma cópia. O
+`exportDocx()` do browser baixa pelo `src`, então renove antes de exportar.
+
+Se o upload falhar (ou `uploadImage` devolver `null`), o padrão é embutir a
+imagem em base64. Um app cujo documento canônico depende de `vault://` não
+quer isso: `imageFallback="none"` não insere nada e `onImageUploadError` recebe
+o erro e o arquivo para você mostrar e deixar tentar de novo.
+
+`setVariableImage(id, src, vaultSrc)` grava o `data-vault-src` junto — use a
+forma de três argumentos para a imagem sobreviver à expiração do `src`.
 
 ## Next.js (App Router)
 

package/dist/index.d.mts

@@ -18,7 +18,7 @@
 import * as react from 'react';
 import { CSSProperties } from 'react';
 import { MinutaMargins, MinutaHeader, MinutaChromeText, MinutaVariableCatalog, MinutaEditorOptions, MinutaVariableRef, MinutaEditor as MinutaEditor$1 } from '@meistrari/minuta-editor';
-export { MinutaChromeText, MinutaEditor as MinutaEditorInstance, MinutaEditorOptions, MinutaHeader, MinutaMargins, MinutaVariableCatalog, MinutaVariableDef, MinutaVariableRef, extractTemplateVariables, resolveTemplateVariables } from '@meistrari/minuta-editor';
+export { MinutaChromeText, MinutaEditor as MinutaEditorInstance, MinutaEditorOptions, MinutaHeader, MinutaMargins, MinutaVariableCatalog, MinutaVariableDef, MinutaVariableRef, extractTemplateVariables, hasLeadingTopicNumber, resolveTemplateVariables, toggleTopicNumber } from '@meistrari/minuta-editor';
 
 interface MinutaEditorProps {
     /**
@@ -32,6 +32,9 @@ interface MinutaEditorProps {
     chrome?: Partial<MinutaChromeText>;
     variables?: MinutaVariableCatalog;
     uploadImage?: MinutaEditorOptions['uploadImage'];
+    /** `'dataUri'` (default) embute em base64 quando o upload falha; `'none'` não insere e avisa por `onImageUploadError` */
+    imageFallback?: MinutaEditorOptions['imageFallback'];
+    onImageUploadError?: MinutaEditorOptions['onImageUploadError'];
     /** barra de formatação do pacote (default: true). `false` = monte a sua sobre `ref.tiptap` */
     toolbar?: boolean;
     showBlockOrigin?: boolean;

package/dist/index.d.ts

@@ -18,7 +18,7 @@
 import * as react from 'react';
 import { CSSProperties } from 'react';
 import { MinutaMargins, MinutaHeader, MinutaChromeText, MinutaVariableCatalog, MinutaEditorOptions, MinutaVariableRef, MinutaEditor as MinutaEditor$1 } from '@meistrari/minuta-editor';
-export { MinutaChromeText, MinutaEditor as MinutaEditorInstance, MinutaEditorOptions, MinutaHeader, MinutaMargins, MinutaVariableCatalog, MinutaVariableDef, MinutaVariableRef, extractTemplateVariables, resolveTemplateVariables } from '@meistrari/minuta-editor';
+export { MinutaChromeText, MinutaEditor as MinutaEditorInstance, MinutaEditorOptions, MinutaHeader, MinutaMargins, MinutaVariableCatalog, MinutaVariableDef, MinutaVariableRef, extractTemplateVariables, hasLeadingTopicNumber, resolveTemplateVariables, toggleTopicNumber } from '@meistrari/minuta-editor';
 
 interface MinutaEditorProps {
     /**
@@ -32,6 +32,9 @@ interface MinutaEditorProps {
     chrome?: Partial<MinutaChromeText>;
     variables?: MinutaVariableCatalog;
     uploadImage?: MinutaEditorOptions['uploadImage'];
+    /** `'dataUri'` (default) embute em base64 quando o upload falha; `'none'` não insere e avisa por `onImageUploadError` */
+    imageFallback?: MinutaEditorOptions['imageFallback'];
+    onImageUploadError?: MinutaEditorOptions['onImageUploadError'];
     /** barra de formatação do pacote (default: true). `false` = monte a sua sobre `ref.tiptap` */
     toolbar?: boolean;
     showBlockOrigin?: boolean;

package/dist/index.mjs

@@ -1,7 +1,7 @@
 'use client';
 import { forwardRef, useRef, useLayoutEffect, useEffect, useImperativeHandle, createElement } from 'react';
 import { createMinutaEditor } from '@meistrari/minuta-editor';
-export { extractTemplateVariables, resolveTemplateVariables } from '@meistrari/minuta-editor';
+export { extractTemplateVariables, hasLeadingTopicNumber, resolveTemplateVariables, toggleTopicNumber } from '@meistrari/minuta-editor';
 
 const MinutaEditor = forwardRef((props, ref) => {
   const host = useRef(null);
@@ -21,6 +21,8 @@ const MinutaEditor = forwardRef((props, ref) => {
       variables: props.variables,
       // lido na hora do upload, não no mount: o host pode trocar a função
       uploadImage: (file) => callbacks.current.uploadImage ? callbacks.current.uploadImage(file) : Promise.resolve(null),
+      imageFallback: props.imageFallback,
+      onImageUploadError: (error, file) => callbacks.current.onImageUploadError?.(error, file),
       toolbar: props.toolbar,
       showBlockOrigin: props.showBlockOrigin,
       blockClickWhileEditing: props.blockClickWhileEditing,
@@ -64,6 +66,9 @@ const MinutaEditor = forwardRef((props, ref) => {
   useEffect(() => {
     instance.current?.setBlockClickWhileEditing(props.blockClickWhileEditing === true);
   }, [props.blockClickWhileEditing]);
+  useEffect(() => {
+    instance.current?.setImageFallback(props.imageFallback ?? "dataUri");
+  }, [props.imageFallback]);
   useImperativeHandle(ref, () => instance.current);
   return createElement("div", {
     ref: host,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meistrari/minuta-react",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Componente React do editor de minuta do defesa.ai — casca fina sobre @meistrari/minuta-editor",
   "repository": {
     "type": "git",
@@ -28,7 +28,7 @@
     "test:pack": "node scripts/verify-pack.mjs"
   },
   "dependencies": {
-    "@meistrari/minuta-editor": "^1.0.0",
+    "@meistrari/minuta-editor": "^1.7.0",
     "@tiptap/core": "2.11.9",
     "@tiptap/extension-blockquote": "2.11.9",
     "@tiptap/extension-bold": "2.11.9",