@meistrari/minuta-react 1.0.0

package/README.md

@@ -0,0 +1,157 @@
+# @meistrari/minuta-react
+
+O editor de minuta do **defesa.ai** como componente React — a folha A4 paginada,
+edição rica, placeholders de variável e export DOCX fiel ao preview. Casca fina
+sobre [`@meistrari/minuta-editor`](../minuta-editor), o núcleo sem framework.
+
+```tsx
+import { useRef } from 'react'
+import { MinutaEditor, type MinutaEditorHandle } from '@meistrari/minuta-react'
+import '@meistrari/minuta-editor/style.css'
+
+function Lapidacao({ html, onSave }: { html: string, onSave: (html: string) => void }) {
+    const editor = useRef<MinutaEditorHandle>(null)
+    return (
+        <>
+            <button onClick={() => onSave(editor.current!.getHTML())}>Salvar</button>
+            <MinutaEditor ref={editor} html={html} style={{ height: '80vh' }} />
+        </>
+    )
+}
+```
+
+**Zero I/O.** O componente não busca nem salva nada — recebe HTML, devolve HTML e
+um `Blob` de `.docx`. Buscar o documento, persistir a edição e baixar o arquivo
+é do seu app (abaixo, o fluxo com a Data API do defesa.ai).
+
+## Props
+
+| prop | default | |
+|---|---|---|
+| `html` | — | documento inicial. **Lido uma vez** — para carregar outro, troque a `key` |
+| `editable` | `true` | |
+| `margins` | 2,5cm / 3cm | `{ top, right, bottom, left }` em px @96dpi |
+| `header` | — | `{ logoUrl, position }` |
+| `chrome` | — | `{ header, footer, headerScope, footerScope, showPageNumber }` |
+| `variables` | — | catálogo `{ key, label, description?, group? }[]` → liga o modo template |
+| `uploadImage` | — | `(file) => Promise<{ src, vaultSrc } \| null>` |
+| `toolbar` | `true` | `false` = você monta a sua sobre `ref.current.tiptap` |
+| `onChange` | — | `(html) => void`, a cada edição |
+| `onTransaction` | — | qualquer transação, inclusive só de seleção — para toolbar própria |
+| `onReady`, `onEditChrome`, `onBlockClick`, `onError` | — | |
+
+O `ref` entrega a instância do editor: `getHTML()`, `exportDocx()` (→ `Blob`),
+`usedVariables()`, `setEditable()`, `setChrome()`, `tiptap` (a instância do
+Tiptap — escotilha de fuga), `root`/`container`/`sheet` (os elementos).
+
+### Por que o `html` é lido uma vez
+
+O editor é a fonte da verdade enquanto vive. Realimentá-lo com o próprio
+`getHTML()` a cada tecla remontaria o documento e mandaria o cursor para o
+começo. Guarde o que `onChange` entrega; para abrir outro documento, mude a
+`key`:
+
+```tsx
+<MinutaEditor key={edicao.id} html={edicao.html} onChange={setHtml} />
+```
+
+### Toolbar própria (antd, Material…)
+
+`toolbar={false}` e fale com o Tiptap direto. `onTransaction` é o que faz
+`isActive` acompanhar o cursor, não só o texto:
+
+```tsx
+const [, rerender] = useReducer(x => x + 1, 0)
+const t = editor.current?.tiptap
+
+<Button type={t?.isActive('bold') ? 'primary' : 'default'} onClick={() => t?.chain().focus().toggleBold().run()}>B</Button>
+<MinutaEditor ref={editor} html={html} toolbar={false} onTransaction={rerender} />
+```
+
+Os tipos de `chain().toggleBold()` viajam com o pacote — não precisa importar
+`@tiptap/*` no seu código.
+
+## O fluxo com a Data API do defesa.ai
+
+Tudo pelo seu backend, com `x-api-key` + `x-org-id` — seus usuários não precisam
+de conta no defesa.ai:
+
+```
+GET   /data/case/:id/html                         → { html, chrome, margins, source, editionId }
+POST  /data/case/:id/editions { name, html }      → cria a edição (o documento lapidado)
+PATCH /data/case/:id/editions/:editionId { html } → salva (versão automática)
+POST  /data/case/:id/docx                         → .docx do estado atual (a edição, se existir)
+```
+
+```tsx
+// abrir
+const doc = await api.get(`/case/${caseId}/html`)
+<MinutaEditor key={caseId} html={doc.html} chrome={doc.chrome ?? undefined} margins={doc.margins ?? undefined} onChange={setHtml} />
+
+// salvar (debounce do seu lado)
+await api.patch(`/case/${caseId}/editions/${editionId}`, { html })
+
+// baixar — fiel ao preview, gerado no browser
+const blob = await editor.current!.exportDocx()
+```
+
+Mande `x-user-email` / `x-user-name` nas chamadas de edição para a autoria
+ficar registrada.
+
+## Formulário ↔ documento
+
+O HTML do `GET /data/case/:id/html` vem com cada variável marcada —
+`<span data-variable-id="nome_cliente" data-parent-block-id="…">valor</span>` —
+e o editor trata a marca como nó atômico. Isso dá as duas direções sem casar
+texto (que erra quando o valor coincide com algo que já existia no template):
+
+```tsx
+// documento → formulário: clicou no trecho, foca o campo
+<MinutaEditor ref={editor} html={html} onVariableClick={v => focusField(v.variableId)} />
+
+// formulário → documento: focou o campo, rola até o trecho
+editor.current!.scrollToVariable('nome_cliente')
+
+// e o formulário continua valendo DEPOIS da edição livre: a marca sobrevive
+// à lapidação, então mudar o valor troca o trecho sem tocar no texto em volta
+editor.current!.setVariableValue('nome_cliente', 'Maria da Silva')   // → nº de ocorrências
+editor.current!.variablesInDocument()                                 // → ['nome_cliente', …]
+```
+
+A resposta do endpoint traz `variablesMarked` e `markedVariables`: numa
+edição criada a partir de HTML já resolvido (sem marcas) a ponte não existe, e
+é melhor saber antes de montar a tela do que descobrir com
+`variablesInDocument()` vazio.
+
+Sobre o fluxo de "enviar variáveis de volta": com uma edição viva o documento
+**é** a edição — o `PATCH` de variáveis no case não re-renderiza a peça (senão
+apagaria o texto do advogado). Ou o formulário trava quando a lapidação começa
+(o 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.
+
+## Next.js (App Router)
+
+O entry publicado carrega `'use client'`: dá para importar o componente direto
+de um Server Component, que o Next faz a fronteira de cliente sozinho. O editor
+é DOM, então `dynamic(() => import(...), { ssr: false })` continua sendo uma
+boa ideia em página renderizada no servidor.
+
+## Props depois do mount
+
+Todas as props são sincronizadas com o editor enquanto ele vive — `toolbar`,
+`margins`, `chrome`, `header`, `variables`, `editable`, `showBlockOrigin`. A
+única só de mount é `html`; voltar uma prop a `undefined` volta ao default.
+
+## StrictMode
+
+Funciona com o `<React.StrictMode>` do React 18: o duplo-mount do efeito destrói
+e recria a instância sobre o mesmo nó, sem instância órfã nem listener duplicado.
+O playground roda assim de propósito.
+
+## Desenvolvimento
+
+```bash
+bun install && bun link @meistrari/minuta-editor   # o core, via link em dev
+bun run dev                                          # playground em :3299 (caso real como fixture)
+bun run build
+```

package/dist/index.d.mts

@@ -0,0 +1,56 @@
+/// <reference types="@tiptap/extension-bold" />
+/// <reference types="@tiptap/extension-blockquote" />
+/// <reference types="@tiptap/extension-bullet-list" />
+/// <reference types="@tiptap/extension-code" />
+/// <reference types="@tiptap/extension-code-block" />
+/// <reference types="@tiptap/extension-hard-break" />
+/// <reference types="@tiptap/extension-heading" />
+/// <reference types="@tiptap/extension-history" />
+/// <reference types="@tiptap/extension-horizontal-rule" />
+/// <reference types="@tiptap/extension-italic" />
+/// <reference types="@tiptap/extension-list-item" />
+/// <reference types="@tiptap/extension-ordered-list" />
+/// <reference types="@tiptap/extension-paragraph" />
+/// <reference types="@tiptap/extension-strike" />
+/// <reference types="@tiptap/extension-text" />
+/// <reference types="@tiptap/extension-table" />
+/// <reference types="@tiptap/extension-bubble-menu" />
+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';
+
+interface MinutaEditorProps {
+    /**
+     * Documento inicial (HTML). A ÚNICA prop só de mount: lida uma vez — troque a
+     * `key` para carregar outro. As demais são sincronizadas com o editor.
+     */
+    html: string;
+    editable?: boolean;
+    margins?: MinutaMargins;
+    header?: MinutaHeader;
+    chrome?: Partial<MinutaChromeText>;
+    variables?: MinutaVariableCatalog;
+    uploadImage?: MinutaEditorOptions['uploadImage'];
+    /** barra de formatação do pacote (default: true). `false` = monte a sua sobre `ref.tiptap` */
+    toolbar?: boolean;
+    showBlockOrigin?: boolean;
+    onReady?: MinutaEditorOptions['onReady'];
+    /** o documento mudou por edição — recebe o HTML atual */
+    onChange?: (html: string) => void;
+    /** qualquer transação, inclusive só de seleção (para toolbar própria) */
+    onTransaction?: () => void;
+    onEditChrome?: MinutaEditorOptions['onEditChrome'];
+    /** clique numa variável do case no documento — a ponte documento → formulário */
+    onVariableClick?: (variable: MinutaVariableRef) => void;
+    onBlockClick?: MinutaEditorOptions['onBlockClick'];
+    onError?: MinutaEditorOptions['onError'];
+    className?: string;
+    style?: CSSProperties;
+}
+/** o que o `ref` entrega: a instância do editor (ou `null` antes do mount) */
+type MinutaEditorHandle = MinutaEditor$1;
+declare const MinutaEditor: react.ForwardRefExoticComponent<MinutaEditorProps & react.RefAttributes<MinutaEditor$1 | null>>;
+
+export { MinutaEditor };
+export type { MinutaEditorHandle, MinutaEditorProps };

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+/// <reference types="@tiptap/extension-bold" />
+/// <reference types="@tiptap/extension-blockquote" />
+/// <reference types="@tiptap/extension-bullet-list" />
+/// <reference types="@tiptap/extension-code" />
+/// <reference types="@tiptap/extension-code-block" />
+/// <reference types="@tiptap/extension-hard-break" />
+/// <reference types="@tiptap/extension-heading" />
+/// <reference types="@tiptap/extension-history" />
+/// <reference types="@tiptap/extension-horizontal-rule" />
+/// <reference types="@tiptap/extension-italic" />
+/// <reference types="@tiptap/extension-list-item" />
+/// <reference types="@tiptap/extension-ordered-list" />
+/// <reference types="@tiptap/extension-paragraph" />
+/// <reference types="@tiptap/extension-strike" />
+/// <reference types="@tiptap/extension-text" />
+/// <reference types="@tiptap/extension-table" />
+/// <reference types="@tiptap/extension-bubble-menu" />
+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';
+
+interface MinutaEditorProps {
+    /**
+     * Documento inicial (HTML). A ÚNICA prop só de mount: lida uma vez — troque a
+     * `key` para carregar outro. As demais são sincronizadas com o editor.
+     */
+    html: string;
+    editable?: boolean;
+    margins?: MinutaMargins;
+    header?: MinutaHeader;
+    chrome?: Partial<MinutaChromeText>;
+    variables?: MinutaVariableCatalog;
+    uploadImage?: MinutaEditorOptions['uploadImage'];
+    /** barra de formatação do pacote (default: true). `false` = monte a sua sobre `ref.tiptap` */
+    toolbar?: boolean;
+    showBlockOrigin?: boolean;
+    onReady?: MinutaEditorOptions['onReady'];
+    /** o documento mudou por edição — recebe o HTML atual */
+    onChange?: (html: string) => void;
+    /** qualquer transação, inclusive só de seleção (para toolbar própria) */
+    onTransaction?: () => void;
+    onEditChrome?: MinutaEditorOptions['onEditChrome'];
+    /** clique numa variável do case no documento — a ponte documento → formulário */
+    onVariableClick?: (variable: MinutaVariableRef) => void;
+    onBlockClick?: MinutaEditorOptions['onBlockClick'];
+    onError?: MinutaEditorOptions['onError'];
+    className?: string;
+    style?: CSSProperties;
+}
+/** o que o `ref` entrega: a instância do editor (ou `null` antes do mount) */
+type MinutaEditorHandle = MinutaEditor$1;
+declare const MinutaEditor: react.ForwardRefExoticComponent<MinutaEditorProps & react.RefAttributes<MinutaEditor$1 | null>>;
+
+export { MinutaEditor };
+export type { MinutaEditorHandle, MinutaEditorProps };

package/dist/index.mjs

@@ -0,0 +1,72 @@
+'use client';
+import { forwardRef, useRef, useLayoutEffect, useEffect, useImperativeHandle, createElement } from 'react';
+import { createMinutaEditor } from '@meistrari/minuta-editor';
+export { extractTemplateVariables, resolveTemplateVariables } from '@meistrari/minuta-editor';
+
+const MinutaEditor = forwardRef((props, ref) => {
+  const host = useRef(null);
+  const instance = useRef(null);
+  const callbacks = useRef(props);
+  callbacks.current = props;
+  useLayoutEffect(() => {
+    const el = host.current;
+    if (!el)
+      return;
+    const editor = createMinutaEditor(el, {
+      html: props.html,
+      editable: props.editable,
+      margins: props.margins,
+      header: props.header,
+      chrome: props.chrome,
+      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),
+      toolbar: props.toolbar,
+      showBlockOrigin: props.showBlockOrigin,
+      onReady: (tiptap) => callbacks.current.onReady?.(tiptap),
+      onChange: () => callbacks.current.onChange?.(editor.getHTML()),
+      onTransaction: () => callbacks.current.onTransaction?.(),
+      onEditChrome: (part) => callbacks.current.onEditChrome?.(part),
+      onVariableClick: (v) => callbacks.current.onVariableClick?.(v),
+      onBlockClick: (id) => callbacks.current.onBlockClick?.(id),
+      onError: (message) => callbacks.current.onError?.(message)
+    });
+    instance.current = editor;
+    return () => {
+      editor.destroy();
+      instance.current = null;
+    };
+  }, []);
+  useEffect(() => {
+    if (props.editable !== void 0)
+      instance.current?.setEditable(props.editable);
+  }, [props.editable]);
+  useEffect(() => {
+    instance.current?.setChrome(props.chrome ?? { header: "", footer: "", headerScope: "all", footerScope: "all", showPageNumber: true });
+  }, [props.chrome?.header, props.chrome?.footer, props.chrome?.headerScope, props.chrome?.footerScope, props.chrome?.showPageNumber]);
+  useEffect(() => {
+    instance.current?.setHeader(props.header ?? { logoUrl: null, position: "left" });
+  }, [props.header?.logoUrl, props.header?.position]);
+  useEffect(() => {
+    instance.current?.setVariables(props.variables);
+  }, [props.variables]);
+  useEffect(() => {
+    instance.current?.setToolbar(props.toolbar !== false);
+  }, [props.toolbar]);
+  useEffect(() => {
+    if (props.margins)
+      instance.current?.setMargins(props.margins);
+  }, [props.margins?.top, props.margins?.right, props.margins?.bottom, props.margins?.left]);
+  useEffect(() => {
+    instance.current?.setShowBlockOrigin(props.showBlockOrigin !== false);
+  }, [props.showBlockOrigin]);
+  useImperativeHandle(ref, () => instance.current);
+  return createElement("div", {
+    ref: host,
+    className: props.className,
+    style: { height: "100%", width: "100%", minHeight: 0, display: "flex", flexDirection: "column", ...props.style }
+  });
+});
+MinutaEditor.displayName = "MinutaEditor";
+
+export { MinutaEditor };

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "@meistrari/minuta-react",
+  "version": "1.0.0",
+  "description": "Componente React do editor de minuta do defesa.ai — casca fina sobre @meistrari/minuta-editor",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/meistrari/case-defense-builder.git",
+    "directory": "packages/minuta-react"
+  },
+  "license": "UNLICENSED",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prepack": "bun run build",
+    "build": "unbuild && node scripts/finish-dist.mjs",
+    "dev": "vite playground --port 3299",
+    "typecheck": "tsc --noEmit",
+    "test:pack": "node scripts/verify-pack.mjs"
+  },
+  "dependencies": {
+    "@meistrari/minuta-editor": "^1.0.0",
+    "@tiptap/core": "2.11.9",
+    "@tiptap/extension-blockquote": "2.11.9",
+    "@tiptap/extension-bold": "2.11.9",
+    "@tiptap/extension-bubble-menu": "2.11.9",
+    "@tiptap/extension-bullet-list": "2.11.9",
+    "@tiptap/extension-code": "2.11.9",
+    "@tiptap/extension-code-block": "2.11.9",
+    "@tiptap/extension-dropcursor": "2.11.9",
+    "@tiptap/extension-gapcursor": "2.11.9",
+    "@tiptap/extension-hard-break": "2.11.9",
+    "@tiptap/extension-heading": "2.11.9",
+    "@tiptap/extension-history": "2.11.9",
+    "@tiptap/extension-horizontal-rule": "2.11.9",
+    "@tiptap/extension-italic": "2.11.9",
+    "@tiptap/extension-list-item": "2.11.9",
+    "@tiptap/extension-ordered-list": "2.11.9",
+    "@tiptap/extension-paragraph": "2.11.9",
+    "@tiptap/extension-strike": "2.11.9",
+    "@tiptap/extension-table": "2.11.9",
+    "@tiptap/extension-table-cell": "2.11.9",
+    "@tiptap/extension-table-header": "2.11.9",
+    "@tiptap/extension-table-row": "2.11.9",
+    "@tiptap/extension-text": "2.11.9",
+    "@tiptap/pm": "2.11.9"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "18.3.31",
+    "@types/react-dom": "18.3.7",
+    "@vitejs/plugin-react": "4.7.0",
+    "react": "18.3.1",
+    "react-dom": "18.3.1",
+    "typescript": "5.9.3",
+    "unbuild": "2.0.0",
+    "vite": "6.4.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "overrides": {
+    "@tiptap/core": "2.11.9",
+    "@tiptap/extension-blockquote": "2.11.9",
+    "@tiptap/extension-bold": "2.11.9",
+    "@tiptap/extension-bubble-menu": "2.11.9",
+    "@tiptap/extension-bullet-list": "2.11.9",
+    "@tiptap/extension-code": "2.11.9",
+    "@tiptap/extension-code-block": "2.11.9",
+    "@tiptap/extension-document": "2.11.9",
+    "@tiptap/extension-dropcursor": "2.11.9",
+    "@tiptap/extension-floating-menu": "2.11.9",
+    "@tiptap/extension-gapcursor": "2.11.9",
+    "@tiptap/extension-hard-break": "2.11.9",
+    "@tiptap/extension-heading": "2.11.9",
+    "@tiptap/extension-history": "2.11.9",
+    "@tiptap/extension-horizontal-rule": "2.11.9",
+    "@tiptap/extension-italic": "2.11.9",
+    "@tiptap/extension-list-item": "2.11.9",
+    "@tiptap/extension-ordered-list": "2.11.9",
+    "@tiptap/extension-paragraph": "2.11.9",
+    "@tiptap/extension-strike": "2.11.9",
+    "@tiptap/extension-text": "2.11.9",
+    "@tiptap/extension-text-style": "2.11.9",
+    "@tiptap/pm": "2.11.9"
+  }
+}