@meistrari/minuta-nuxt 0.1.0 → 1.1.0

package/dist/runtime/components/MinutaTemplateEditor.vue

@@ -0,0 +1,225 @@
+<script setup lang="ts">
+import { computed, onMounted, onUnmounted, reactive, ref, watch } from 'vue'
+import type { Editor } from '@tiptap/core'
+import MinutaDocxEditor from './MinutaDocxEditor.vue'
+import MinutaChromeEditor from './MinutaChromeEditor.vue'
+import type { MinutaVariableDef } from '../utils/templateVariables'
+import { extractTemplateVariables } from '../utils/templateVariables'
+import type { MinutaChrome } from '../composables/useMinutaApi'
+
+/**
+ * Editor de TEMPLATE de minuta — o mesmo documento paginado A4 do
+ * `<MinutaEmbed>`, só que sem minuta: o conteúdo é `v-model` do app hospedeiro,
+ * e onde entra um valor há um placeholder de variável.
+ *
+ * É componente separado do `MinutaEmbed` de propósito. O embed é uma minuta
+ * concreta: tem id, salva sozinho no CDB, tem histórico, agente, análise de
+ * margem e documentos-fonte — nada disso existe num template. Um `mode` no
+ * embed significaria desligar 80% dele e manter os dois caminhos vivos em cada
+ * mudança futura.
+ *
+ * O CDB não guarda template nenhum: quem persiste é o host, que já tem cadastro
+ * (na Omni, a definição de ocorrência). O que sai daqui é o HTML do documento e
+ * a lista de variáveis usadas — o host nunca precisa ler HTML.
+ *
+ * ```vue
+ * <MinutaTemplateEditor
+ *   v-model="definicao.templateHtml"
+ *   :variables="PETICAO_VARIAVEIS"
+ *   @update:used-variables="keys => definicao.variaveis = keys"
+ * />
+ * ```
+ */
+
+const props = withDefaults(defineProps<{
+    /** HTML do template (documento com os placeholders) */
+    modelValue?: string | null
+    /** catálogo de variáveis disponíveis — definido pelo host */
+    variables?: MinutaVariableDef[]
+    editable?: boolean
+    /** barra superior com o resumo das variáveis usadas (default: true) */
+    showToolbar?: boolean
+    /** margens da página em px @96dpi (default: 2,5cm topo/rodapé, 3cm laterais) */
+    margins?: { top: number, right: number, bottom: number, left: number }
+    /** cabeçalho/rodapé da folha; `v-model:chrome` para persistir junto */
+    chrome?: MinutaChrome | null
+}>(), {
+    modelValue: '',
+    variables: () => [],
+    editable: true,
+    showToolbar: true,
+    margins: () => ({ top: 95, right: 113, bottom: 95, left: 113 }),
+    chrome: null,
+})
+
+const emit = defineEmits<{
+    'update:modelValue': [html: string]
+    /** chaves usadas no documento, na ordem de aparição e sem repetição */
+    'update:usedVariables': [keys: string[]]
+    'update:chrome': [chrome: MinutaChrome]
+    'ready': [editor: Editor]
+}>()
+
+const HEADER = { logoUrl: null as string | null, position: 'left' as const }
+
+const editor = ref<Editor | null>(null)
+const editorCompRef = ref<any>(null)
+/**
+ * Conteúdo inicial CONGELADO no mount. O editor é a fonte da verdade enquanto
+ * está vivo; realimentá-lo com o `modelValue` que ele mesmo acabou de emitir
+ * remontaria o documento a cada tecla e o cursor iria para o começo.
+ */
+const initialHtml = ref(props.modelValue || '<p></p>')
+
+const chromeText = reactive({
+    header: props.chrome?.header ?? '',
+    footer: props.chrome?.footer ?? '',
+    headerScope: props.chrome?.headerScope ?? 'all' as 'all' | 'first',
+    footerScope: props.chrome?.footerScope ?? 'all' as 'all' | 'first',
+    showPageNumber: props.chrome?.showPageNumber !== false,
+})
+
+const usedVariables = ref<string[]>(extractTemplateVariables(props.modelValue))
+
+const catalogByKey = computed(() => new Map(props.variables.map(v => [v.key, v])))
+
+/**
+ * Variáveis no documento que saíram do catálogo — o host renomeou ou removeu.
+ * Nunca vão resolver, então merecem aviso na hora de salvar, não na geração.
+ */
+const unknownVariables = computed(() =>
+    usedVariables.value.filter(key => !catalogByKey.value.has(key)))
+
+function labelOf(key: string) {
+    return catalogByKey.value.get(key)?.label ?? key
+}
+
+function currentHtml(): string {
+    return editor.value?.getHTML() ?? ''
+}
+
+function syncOut() {
+    const html = currentHtml()
+    const keys = extractTemplateVariables(html)
+    const changed = keys.length !== usedVariables.value.length
+        || keys.some((key, i) => key !== usedVariables.value[i])
+    if (changed) {
+        usedVariables.value = keys
+        emit('update:usedVariables', keys)
+    }
+    emit('update:modelValue', html)
+}
+
+function onReady(instance: Editor) {
+    editor.value = instance
+    // o parse do HTML inicial pode normalizar o documento (nós desconhecidos,
+    // wrapper de bloco): emite uma vez para o host guardar o que o editor de
+    // fato tem, e não o que ele mandou
+    syncOut()
+    emit('ready', instance)
+}
+
+// --- cabeçalho/rodapé (mesmo canvas do embed) ---
+const chromeEditor = ref<{ part: 'header' | 'footer' } | null>(null)
+
+function onEditChrome(event: Event) {
+    if (!props.editable)
+        return
+    const part = (event as CustomEvent).detail?.part
+    if (part === 'header' || part === 'footer')
+        chromeEditor.value = { part }
+}
+
+function applyChrome({ html, scope, showPageNumber }: { html: string, scope: 'all' | 'first', showPageNumber?: boolean }) {
+    if (!chromeEditor.value)
+        return
+    const part = chromeEditor.value.part
+    chromeText[part] = html
+    chromeText[part === 'header' ? 'headerScope' : 'footerScope'] = scope
+    if (showPageNumber !== undefined)
+        chromeText.showPageNumber = showPageNumber
+    chromeEditor.value = null
+    emit('update:chrome', { ...chromeText })
+}
+
+onMounted(() => window.addEventListener('poc:edit-chrome', onEditChrome))
+onUnmounted(() => window.removeEventListener('poc:edit-chrome', onEditChrome))
+
+// host trocando o template inteiro (abrir outro cadastro): remonta o editor
+watch(() => props.modelValue, (value) => {
+    if (!editor.value || value == null)
+        return
+    if (value === currentHtml())
+        return
+    initialHtml.value = value || '<p></p>'
+    editor.value.commands.setContent(initialHtml.value, false)
+    syncOut()
+})
+
+defineExpose({ editor, getHtml: currentHtml, usedVariables })
+</script>
+
+<template>
+    <div class="minuta-tpl">
+        <div v-if="showToolbar" class="minuta-tpl__bar">
+            <slot name="toolbar-start" />
+            <span class="minuta-tpl__count">
+                {{ usedVariables.length }}
+                {{ usedVariables.length === 1 ? 'variável no template' : 'variáveis no template' }}
+            </span>
+            <div class="minuta-tpl__chips">
+                <span
+                    v-for="key in usedVariables"
+                    :key="key"
+                    class="minuta-tpl__chip"
+                    :class="{ 'minuta-tpl__chip--unknown': !catalogByKey.has(key) }"
+                    :title="key"
+                >
+                    {{ labelOf(key) }}
+                </span>
+            </div>
+            <slot name="toolbar-end" />
+        </div>
+
+        <p v-if="unknownVariables.length" class="minuta-tpl__warn">
+            {{ unknownVariables.length === 1 ? 'A variável' : 'As variáveis' }}
+            <b>{{ unknownVariables.join(', ') }}</b>
+            {{ unknownVariables.length === 1 ? 'não está' : 'não estão' }}
+            no catálogo — {{ unknownVariables.length === 1 ? 'ela nunca vai' : 'elas nunca vão' }}
+            receber valor na geração.
+        </p>
+
+        <div class="minuta-tpl__body">
+            <MinutaDocxEditor
+                ref="editorCompRef"
+                :initial-html="initialHtml"
+                :margins="props.margins"
+                :header="HEADER"
+                :editable="props.editable"
+                :show-block-origin="false"
+                :variables="props.variables"
+                :chrome-text="chromeText"
+                @ready="onReady"
+                @changed="syncOut"
+            />
+
+            <div v-if="chromeEditor" class="minuta-tpl__chrome-overlay">
+                <MinutaChromeEditor
+                    :key="chromeEditor.part"
+                    :part="chromeEditor.part"
+                    :html="chromeText[chromeEditor.part]"
+                    :scope="chromeText[chromeEditor.part === 'header' ? 'headerScope' : 'footerScope']"
+                    :band-height-px="chromeEditor.part === 'header' ? props.margins.top : props.margins.bottom"
+                    :show-page-number="chromeText.showPageNumber"
+                    :allow-page-number-toggle="true"
+                    @apply="applyChrome"
+                    @close="chromeEditor = null"
+                />
+            </div>
+        </div>
+    </div>
+</template>
+
+<style scoped>
+.minuta-tpl{background:#f7f7f8;display:flex;flex-direction:column;height:100%}.minuta-tpl__bar{align-items:center;background:#fff;border-bottom:1px solid #e5e7eb;display:flex;font-size:13px;gap:8px;padding:8px 16px}.minuta-tpl__count{color:#6b7280;white-space:nowrap}.minuta-tpl__chips{display:flex;flex:1;flex-wrap:wrap;gap:4px;min-width:0}.minuta-tpl__chip{background:rgba(251,191,36,.16);border-radius:999px;box-shadow:inset 0 0 0 1px rgba(180,83,9,.25);color:#78350f;font-size:12px;padding:1px 8px}.minuta-tpl__chip--unknown{background:rgba(244,63,94,.12);box-shadow:inset 0 0 0 1px rgba(190,18,60,.35);color:#881337}.minuta-tpl__warn{background:#fff1f2;border-bottom:1px solid #fecdd3;color:#881337;font-size:12px;margin:0;padding:8px 16px}.minuta-tpl__body{flex:1;min-height:0;position:relative}.minuta-tpl__chrome-overlay{inset:0;position:absolute;z-index:40}
+</style>

package/dist/runtime/components/MinutaVariablePicker.vue

@@ -0,0 +1,149 @@
+<script setup lang="ts">
+import { computed, onMounted, ref, watch } from 'vue'
+import type { MinutaVariableDef } from '../utils/templateVariables'
+
+/**
+ * Seletor de variável do template — o popover que abre pelo `/` no texto ou
+ * pelo botão da toolbar.
+ *
+ * A busca é por RÓTULO, não por chave: quem monta o template pensa em "número
+ * do processo", não em `PROCESSO`. A chave aparece ao lado porque é ela que o
+ * host recebe de volta, e ver as duas juntas é o que ensina o vocabulário.
+ */
+
+const props = defineProps<{
+    variables: MinutaVariableDef[]
+    /** posição absoluta dentro do container do editor */
+    top: number
+    left: number
+    /** texto digitado depois do `/` (busca ao vivo do gatilho no documento) */
+    query?: string
+}>()
+
+const emit = defineEmits<{ select: [variable: MinutaVariableDef], close: [] }>()
+
+const search = ref('')
+const activeIndex = ref(0)
+const searchInput = ref<HTMLInputElement | null>(null)
+
+/** o gatilho `/` filtra pelo que está sendo digitado NO DOCUMENTO; o botão, pelo campo */
+const term = computed(() => (props.query ?? search.value).trim().toLowerCase())
+
+const filtered = computed(() => {
+    if (!term.value)
+        return props.variables
+    return props.variables.filter(v =>
+        v.label.toLowerCase().includes(term.value)
+        || v.key.toLowerCase().includes(term.value)
+        || (v.description?.toLowerCase().includes(term.value) ?? false),
+    )
+})
+
+/** lista achatada com cabeçalhos de grupo — o índice ativo anda só nos itens */
+const rows = computed(() => {
+    const out: Array<{ kind: 'group', label: string } | { kind: 'item', variable: MinutaVariableDef, index: number }> = []
+    let index = 0
+    let lastGroup: string | null = null
+    for (const variable of filtered.value) {
+        const group = variable.group ?? null
+        if (group && group !== lastGroup)
+            out.push({ kind: 'group', label: group })
+        lastGroup = group
+        out.push({ kind: 'item', variable, index })
+        index++
+    }
+    return out
+})
+
+watch(filtered, () => {
+    activeIndex.value = 0
+})
+
+/**
+ * Aberto pelo BOTÃO (sem `query`), o filtro é o campo daqui e ele precisa do
+ * foco — quem abriu não estava digitando no documento. Aberto pelo GATILHO `/`,
+ * o foco fica no editor de propósito: a pessoa continua digitando o texto do
+ * filtro no próprio parágrafo, e é o pai que encaminha as teclas para cá.
+ *
+ * `onMounted`, e não um watcher `immediate`: no watcher o ref do input ainda
+ * não existe, e o foco caía no editor — daí o que se digitava virar texto do
+ * documento em vez de busca.
+ */
+onMounted(() => {
+    if (props.query === undefined)
+        searchInput.value?.focus()
+})
+
+function move(delta: number) {
+    const total = filtered.value.length
+    if (!total)
+        return
+    activeIndex.value = (activeIndex.value + delta + total) % total
+}
+
+function choose(index = activeIndex.value) {
+    const variable = filtered.value[index]
+    if (variable)
+        emit('select', variable)
+}
+
+/** o gatilho `/` mantém o foco no editor — o pai delega as teclas para cá */
+defineExpose({ move, choose, hasResults: () => filtered.value.length > 0 })
+</script>
+
+<template>
+    <div
+        class="poc-varpicker"
+        :style="{ top: `${top}px`, left: `${left}px` }"
+        @click.stop
+    >
+        <input
+            v-if="query === undefined"
+            ref="searchInput"
+            v-model="search"
+            class="poc-varpicker__search"
+            placeholder="Buscar variável…"
+            spellcheck="false"
+            @keydown.down.prevent="move(1)"
+            @keydown.up.prevent="move(-1)"
+            @keydown.enter.prevent="choose()"
+            @keydown.esc.prevent="emit('close')"
+        >
+        <div v-else class="poc-varpicker__hint">
+            Variável<span v-if="query">: <b>{{ query }}</b></span>
+        </div>
+
+        <!-- `mousedown.prevent` só na lista: na raiz ele impediria o clique de
+             focar o próprio campo de busca. Aqui ele serve para o clique num
+             item não tirar o foco de onde está (editor ou campo) antes do
+             `click` — o que fecharia o popover pelo caminho de "clicou fora". -->
+        <div class="poc-varpicker__list" @mousedown.prevent>
+            <p v-if="!filtered.length" class="poc-varpicker__empty">
+                Nenhuma variável encontrada.
+            </p>
+            <template v-for="(row, i) in rows" :key="i">
+                <div v-if="row.kind === 'group'" class="poc-varpicker__group">
+                    {{ row.label }}
+                </div>
+                <button
+                    v-else
+                    type="button"
+                    class="poc-varpicker__item"
+                    :class="{ 'poc-varpicker__item--on': row.index === activeIndex }"
+                    @mouseenter="activeIndex = row.index"
+                    @click="choose(row.index)"
+                >
+                    <span class="poc-varpicker__label">{{ row.variable.label }}</span>
+                    <span class="poc-varpicker__key">{{ row.variable.key }}</span>
+                    <span v-if="row.variable.description" class="poc-varpicker__desc">
+                        {{ row.variable.description }}
+                    </span>
+                </button>
+            </template>
+        </div>
+    </div>
+</template>
+
+<style scoped>
+.poc-varpicker{background:#fff;border:1px solid #e5e7eb;border-radius:10px;box-shadow:0 12px 24px -8px rgba(0,0,0,.25);display:flex;flex-direction:column;font-size:13px;max-height:300px;overflow:hidden;position:absolute;width:320px;z-index:60}.poc-varpicker__search{border:0;border-bottom:1px solid #f3f4f6;font-family:inherit;font-size:13px;outline:none;padding:10px 12px}.poc-varpicker__hint{border-bottom:1px solid #f3f4f6;color:#6b7280;font-size:12px;padding:8px 12px}.poc-varpicker__list{flex:1;min-height:0;overflow-y:auto;padding:4px}.poc-varpicker__empty{color:#6b7280;font-size:12px;margin:0;padding:12px}.poc-varpicker__group{color:#9ca3af;font-size:11px;font-weight:600;letter-spacing:.04em;padding:8px 8px 4px;text-transform:uppercase}.poc-varpicker__item{background:none;border:0;border-radius:6px;cursor:pointer;display:grid;font-family:inherit;gap:2px 8px;grid-template-columns:1fr auto;padding:6px 8px;text-align:left;width:100%}.poc-varpicker__item--on{background:#f3f4f6}.poc-varpicker__label{color:#111827;font-weight:500}.poc-varpicker__key{color:#9ca3af;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:11px}.poc-varpicker__desc{color:#6b7280;display:-webkit-box;font-size:11px;grid-column:1/-1;-webkit-line-clamp:2;line-height:1.4;overflow:hidden;-webkit-box-orient:vertical}
+</style>

package/dist/runtime/composables/annotationAnchors.d.ts

@@ -11,7 +11,6 @@ export interface AnnotationTarget {
     /** título da seção onde o item aparece (fallback) */
     onde?: string | null;
 }
-/** range PM de um recorte verbatim do documento (busca whitespace-tolerante) */
 export declare function findTextRange(editor: Editor, needle: string): {
     from: number;
     to: number;

package/dist/runtime/composables/annotationAnchors.js

@@ -50,18 +50,24 @@ function findRange(text, posAt, needle) {
   }
   return null;
 }
+function plainNeedle(needle) {
+  if (!needle.includes("<") && !needle.includes("&"))
+    return needle;
+  const doc = new DOMParser().parseFromString(needle, "text/html");
+  return doc.body.textContent ?? needle;
+}
 export function findTextRange(editor, needle) {
   const { text, posAt } = buildTextIndex(editor);
   if (!text.length)
     return null;
-  return findRange(text, posAt, needle);
+  return findRange(text, posAt, plainNeedle(needle));
 }
 export function locateAnnotationDetailed(editor, target) {
   const { text, posAt } = buildTextIndex(editor);
   if (!text.length)
     return null;
   if (target.trecho) {
-    const range = findRange(text, posAt, target.trecho);
+    const range = findRange(text, posAt, plainNeedle(target.trecho));
     if (range)
       return { range, matchedBy: "trecho" };
   }
@@ -227,7 +233,8 @@ export function setUserEditRanges(editor, ranges) {
 export function scrollToAnnotation(editor, from, scrollContainer) {
   try {
     const coords = editor.view.coordsAtPos(from);
-    if (scrollContainer) {
+    const rolavel = !!scrollContainer && scrollContainer.scrollHeight > scrollContainer.clientHeight + 4;
+    if (scrollContainer && rolavel) {
       const rect = scrollContainer.getBoundingClientRect();
       scrollContainer.scrollTo({
         top: scrollContainer.scrollTop + (coords.top - rect.top) - rect.height * 0.3,

package/dist/runtime/composables/docxExport.js

@@ -202,6 +202,12 @@ function inlineToRuns(node, base, ctx) {
       }
       return;
     }
+    if (child.type.name === "templateVariable") {
+      const label = child.attrs.label || child.attrs.varKey || "";
+      if (label)
+        runs.push(new TextRun({ text: `[${label}]`, ...runOptions(base) }));
+      return;
+    }
     if (child.type.name === "variableChip") {
       if (child.attrs.text)
         runs.push(new TextRun({ text: child.attrs.text, ...runOptions(base) }));
@@ -327,7 +333,9 @@ function textBlockToParagraph(node, pos, ctx, opts = {}) {
   const runs = inlineToRuns(node, base, ctx);
   const paragraph = new Paragraph({
     children: runs,
-    alignment: m?.align ?? parseAlignment(style),
+    // sem alinhamento explícito, corpo de peça vai justificado (o Word
+    // usaria esquerda e o .docx sairia diferente da praxe e do preview)
+    alignment: m?.align ?? parseAlignment(style) ?? (opts.heading ? void 0 : AlignmentType.JUSTIFIED),
     spacing,
     indent: total ? { left: total } : void 0,
     heading: opts.heading ? headingLevelFor(opts.heading) : void 0,
@@ -1211,7 +1219,11 @@ export async function pocExportDocx(editor, margins, chrome, options = {}) {
   const doc = editor.state.doc;
   const ctx = {
     view: editor.view,
-    breakSet: new Set((options.breaks ?? []).map((b) => b.pos)),
+    // quebras `soft` (dentro de um parágrafo) não viram pageBreakBefore:
+    // partir o parágrafo em dois no Word entregaria ao advogado um arquivo
+    // que não reflui ao editar. Ali o Word quebra sozinho, no mesmo lugar
+    // ou a uma linha de distância.
+    breakSet: new Set((options.breaks ?? []).filter((b) => !b.soft).map((b) => b.pos)),
     pending: { breakBefore: false },
     lastAfterTw: 0,
     meta: /* @__PURE__ */ new WeakMap(),

package/dist/runtime/composables/editorExtensions.d.ts

@@ -1,6 +1,8 @@
 import type { Editor } from '@tiptap/core';
 import { Extension as TiptapExtension, Mark as TiptapMark, Node as TiptapNode } from '@tiptap/core';
+import type { EditorView as PMEditorView } from '@tiptap/pm/view';
 import type { PocPageConfig } from './paginationPlugin.js';
+import type { MinutaVariableDef } from '../utils/templateVariables.js';
 /**
  * Extensões Tiptap da PoC do editor de minuta.
  *
@@ -8,6 +10,7 @@ import type { PocPageConfig } from './paginationPlugin.js';
  * - minutaBlock: wrapper com proveniência (blockId/título do bloco do template)
  * - htmlIsland: tabelas/listas/imagens/svg preservados como ilhas não-editáveis (HTML cru)
  * - variableChip: <span data-variable-id> vira nó atômico — a variável continua "viva"
+ * - templateVariable: <span data-minuta-var> — placeholder NÃO resolvido do template
  * - inlineStyle/styledDiv/passthrough: preservam o CSS inline do pipeline de render
  */
 /**
@@ -39,6 +42,26 @@ export declare const PocHtmlIsland: TiptapNode<any, any>;
  */
 export declare const PocMissingImage: TiptapNode<any, any>;
 export declare const PocVariableChip: TiptapNode<any, any>;
+/**
+ * Placeholder de variável do TEMPLATE — o `#NOME_VARIAVEL` de antigamente, só
+ * que como nó atômico em vez de texto (ver `utils/templateVariables.ts` para o
+ * porquê e para o formato).
+ *
+ * O catálogo (`options.catalog`) vem do app hospedeiro: o CDB não sabe o que é
+ * `SIGLA_FORO`, só sabe que existe um lugar no documento com esse nome. O nó
+ * guarda o rótulo junto (para um template abrir legível sem catálogo, ex.: no
+ * histórico), mas quem manda na exibição é o catálogo — renomear uma variável
+ * no host reflete em todo template já salvo, sem migrar documento nenhum.
+ *
+ * Sobrevive à geração: `resolveTemplateVariables` só troca o que tem valor, e o
+ * que sobra continua sendo este nó — um buraco visível no parágrafo em que ele
+ * está, e não um erro genérico no rodapé de um modal.
+ */
+/** o catálogo pode chegar depois do mount (host que carrega async) — daí o getter */
+export type MinutaVariableCatalog = MinutaVariableDef[] | (() => MinutaVariableDef[]);
+export declare const PocTemplateVariable: TiptapNode<{
+    catalog: MinutaVariableCatalog;
+}, any>;
 /**
  * Nota de rodapé: o render devolve `<sup data-footnote="texto">n</sup>` e o
  * export transforma em nota de rodapé DE VERDADE no Word (o pipeline legado faz
@@ -53,4 +76,18 @@ export declare const PocInlineStyle: TiptapMark<any, any>;
 export declare const PocUnderline: TiptapMark<any, any>;
 /** Preserva style/class inline nos blocos de texto (o pipeline de render inlina todo o CSS). */
 export declare const PocStylePassthrough: TiptapExtension<any, any>;
-export declare function buildPocExtensions(pageConfig?: PocPageConfig): (TiptapNode<any, any> | TiptapMark<any, any> | TiptapExtension<any, any>)[];
+export declare function buildPocExtensions(pageConfig?: PocPageConfig, options?: {
+    /** catálogo de variáveis do host — habilita os chips do modo template */
+    variables?: MinutaVariableCatalog;
+    /**
+     * Primeiro a ver o teclado, ANTES do keymap do editor. Devolver `true`
+     * consome a tecla.
+     *
+     * Existe porque `editorProps.handleKeyDown` não serve: o `someProp` do
+     * ProseMirror percorre os plugins antes das props diretas, então o keymap
+     * do StarterKit trata o Enter (quebra o parágrafo) e o handler da view
+     * nunca roda. Quem precisa de um popover dirigido pelo teclado com o foco
+     * ainda no editor — o seletor de variável — depende disso.
+     */
+    handleKeyDown?: (view: PMEditorView, event: KeyboardEvent) => boolean;
+}): (TiptapNode<any, any> | TiptapMark<any, any> | TiptapExtension<any, any>)[];

package/dist/runtime/composables/editorExtensions.js

@@ -4,6 +4,7 @@ import Table from "@tiptap/extension-table";
 import TableCell from "@tiptap/extension-table-cell";
 import TableHeader from "@tiptap/extension-table-header";
 import TableRow from "@tiptap/extension-table-row";
+import { Plugin as PMPlugin } from "@tiptap/pm/state";
 import { sanitizeRichHtml } from "../utils/sanitizeRichHtml.js";
 import { PocPaginationPlugin } from "./paginationPlugin.js";
 export const POC_ASSET_SWAP = "pocAssetSwap";
@@ -272,6 +273,74 @@ export const PocVariableChip = TiptapNode.create({
     };
   }
 });
+function readCatalog(catalog) {
+  return typeof catalog === "function" ? catalog() : catalog;
+}
+export const PocTemplateVariable = TiptapNode.create({
+  name: "templateVariable",
+  inline: true,
+  group: "inline",
+  atom: true,
+  selectable: true,
+  addOptions() {
+    return { catalog: [] };
+  },
+  addAttributes() {
+    return {
+      varKey: { default: null },
+      label: { default: null }
+    };
+  },
+  parseHTML() {
+    return [{
+      // acima do PocInlineStyle (40): é nó, não span estilizado
+      tag: "span[data-minuta-var]",
+      priority: 115,
+      getAttrs: (el) => {
+        const key = el.getAttribute("data-minuta-var")?.trim();
+        if (!key)
+          return false;
+        return {
+          varKey: key,
+          label: el.getAttribute("data-minuta-var-label")?.trim() || el.textContent?.trim() || key
+        };
+      }
+    }];
+  },
+  renderHTML({ node }) {
+    const key = node.attrs.varKey ?? "";
+    const label = node.attrs.label || key;
+    return ["span", {
+      "data-minuta-var": key,
+      "data-minuta-var-label": label,
+      "class": "poc-tplvar"
+    }, label];
+  },
+  addNodeView() {
+    return ({ node }) => {
+      const key = node.attrs.varKey ?? "";
+      const catalog = readCatalog(this.options.catalog);
+      const def = catalog.find((item) => item.key === key);
+      const dom = document.createElement("span");
+      dom.className = "poc-tplvar";
+      dom.contentEditable = "false";
+      dom.setAttribute("data-minuta-var", key);
+      dom.textContent = def?.label || node.attrs.label || key;
+      dom.title = def?.description ? `${key} \u2014 ${def.description}` : key;
+      if (catalog.length && !def)
+        dom.classList.add("poc-tplvar--unknown");
+      return { dom };
+    };
+  },
+  addCommands() {
+    return {
+      insertTemplateVariable: (variable) => ({ commands }) => commands.insertContent({
+        type: "templateVariable",
+        attrs: { varKey: variable.key, label: variable.label }
+      })
+    };
+  }
+});
 export const PocFootnoteRef = TiptapNode.create({
   name: "footnoteRef",
   inline: true,
@@ -391,7 +460,7 @@ export const PocInlineStyle = TiptapMark.create({
       tag: "span",
       priority: 40,
       getAttrs: (el) => {
-        if (el.hasAttribute("data-variable-id"))
+        if (el.hasAttribute("data-variable-id") || el.hasAttribute("data-minuta-var"))
           return false;
         const style = el.getAttribute("style");
         const cls = el.getAttribute("class");
@@ -436,7 +505,7 @@ export const PocStylePassthrough = TiptapExtension.create({
     }];
   }
 });
-export function buildPocExtensions(pageConfig) {
+export function buildPocExtensions(pageConfig, options) {
   const extensions = [
     PocDocument,
     TiptapStarterKit.configure({ document: false }),
@@ -448,12 +517,25 @@ export function buildPocExtensions(pageConfig) {
     PocHtmlIsland,
     PocMissingImage,
     PocVariableChip,
+    PocTemplateVariable.configure({ catalog: options?.variables ?? [] }),
     PocFootnoteRef,
     PocStyledDiv,
     PocInlineStyle,
     PocUnderline,
     PocStylePassthrough
   ];
+  const handleKeyDown = options?.handleKeyDown;
+  if (handleKeyDown) {
+    extensions.push(TiptapExtension.create({
+      name: "pocKeyDownFirst",
+      // acima do StarterKit (100): o ExtensionManager ordena os plugins
+      // por prioridade, e é essa ordem que o someProp percorre
+      priority: 1e3,
+      addProseMirrorPlugins() {
+        return [new PMPlugin({ props: { handleKeyDown } })];
+      }
+    }));
+  }
   if (pageConfig) {
     extensions.push(TiptapExtension.create({
       name: "pocPagination",

package/dist/runtime/composables/paginationPlugin.d.ts

@@ -54,11 +54,24 @@ export interface PocPageNote {
     text: string;
     /** corpo declarado no template, em pontos (default: 8pt, como o Word) */
     size?: number | null;
+    /**
+     * posição do MARCADOR no documento. Só é usada para repartir as notas
+     * quando a quebra cai no meio do parágrafo: a nota mora na página da
+     * chamada, então as que ficam depois do corte viajam para a página nova.
+     */
+    at?: number;
 }
 export interface PocPageBreak {
     pos: number;
     filler: number;
     pageNo: number;
+    /**
+     * quebra no MEIO de um parágrafo (entre linhas). O DOCX não recebe
+     * pageBreakBefore nessas: partir o parágrafo em dois no Word entregaria
+     * ao advogado um arquivo que não reflui quando ele edita o texto. Aqui o
+     * Word quebra naturalmente, e o preview só antecipa onde.
+     */
+    soft?: boolean;
     /** notas cujos marcadores estão nesta página — desenhadas acima do rodapé */
     notes?: PocPageNote[];
     /** altura reservada pelas notas (já descontada do filler) */