@prolibu-suite/cobalt-core 0.10.4 → 0.11.1

package/dist/types/components/co-date-picker/co-date-picker.d.ts

@@ -17,19 +17,33 @@ import type { Placement } from '../../utils/positioning';
  *
  * Escape is owned here (co-popover `closeOnEscape=false`) so focus can return to
  * the field; outside-click stays with co-popover.
+ *
+ * Wrapper Vue: `CoDatePicker` de `@prolibu-suite/cobalt-vue`.
+ *
+ * @part label - Etiqueta del campo.
+ * @part helper - Texto de ayuda, o el `errorMessage` cuando el campo es inválido.
  */
 export declare class CoDatePicker {
     el: HTMLElement;
     /** Committed value, "YYYY-MM-DD" or null. */
     value: string | null;
+    /** Fecha mínima elegible, `YYYY-MM-DD`. */
     min?: string;
+    /** Fecha máxima elegible, `YYYY-MM-DD`. */
     max?: string;
+    /** Fechas bloqueadas `YYYY-MM-DD`: array, o JSON / lista separada por comas desde HTML. */
     disabledDates?: string[] | string;
+    /** Días de la semana bloqueados (0 = domingo … 6 = sábado): array, o JSON / lista separada por comas. */
     disabledDaysOfWeek?: number[] | string;
+    /** Locale BCP-47: nombres de meses y días, parseo de lo tipeado y textos de la UI (es/en/pt). */
     locale: string;
+    /** Formato de la fecha visible. Tokens: `yyyy yy MMMM MMM MM M dd d` (el valor sigue siendo `YYYY-MM-DD`). */
     displayFormat: string;
+    /** Primer día de la semana del calendario: 0 = domingo … 6 = sábado (default 1, lunes). */
     firstDayOfWeek: number;
+    /** Etiqueta del campo. */
     label?: string;
+    /** Placeholder del campo vacío; vacío = el del `locale`. */
     placeholder?: string;
     /** Field size, forwarded to the inner co-date-field. */
     size: 's' | 'sm' | 'md' | 'lg';
@@ -40,13 +54,21 @@ export declare class CoDatePicker {
      *  this prop existed. co-date-field itself has no `variant` prop, so this
      *  is applied from the outside via `::part(field)` — see co-date-picker.css. */
     variant: 'default' | 'flat';
+    /** Atributo `name` del input interno. */
     name?: string;
+    /** Deshabilita el campo y el calendario. */
     disabled: boolean;
+    /** Solo lectura: muestra la fecha pero no permite cambiarla. */
     readonly: boolean;
+    /** Campo obligatorio: marca la etiqueta con el indicador de requerido. */
     required: boolean;
+    /** Botón × para vaciar la fecha (default `true`); emite `coClear`. */
     clearable: boolean;
+    /** Marca el campo como inválido (validación externa): borde de error y `errorMessage` en lugar de `helperText`. */
     invalid: boolean;
+    /** Mensaje bajo el campo cuando es inválido (`invalid` o un tipeo que no se pudo interpretar). */
     errorMessage?: string;
+    /** Texto de ayuda bajo el campo. */
     helperText?: string;
     /** Label layout: vertical (label above) or horizontal (label beside) */
     layout: 'vertical' | 'horizontal';
@@ -60,15 +82,23 @@ export declare class CoDatePicker {
     mobileBreakpoint: number;
     /** True when the viewport is at/under `mobileBreakpoint`. */
     isMobile: boolean;
+    /** Texto crudo mientras se tipea (sin confirmar); `detail` = string. */
     coInput: EventEmitter<string>;
+    /** Se confirmó una fecha válida (tipeada o elegida en el calendario) o se vació: `detail` = `YYYY-MM-DD` o `null`. `value` ya está actualizado. */
     coChange: EventEmitter<string | null>;
+    /** Lo tipeado no es una fecha válida (p. ej. `31/02/2026`): no se confirma nada; `detail` = `{ raw }`. */
     coInvalid: EventEmitter<{
         raw: string;
     }>;
+    /** Se vació la fecha con la ×. Sin `detail`. */
     coClear: EventEmitter<void>;
+    /** El input ganó el foco. */
     coFocus: EventEmitter<void>;
+    /** El input perdió el foco. */
     coBlur: EventEmitter<void>;
+    /** Se abrió el calendario (popover u hoja en mobile). No burbujea. */
     coOpen: EventEmitter<void>;
+    /** Se cerró el calendario. No burbujea. */
     coClose: EventEmitter<void>;
     private internalInvalid;
     private fieldEl?;

package/dist/types/components/co-date-range/co-date-range.d.ts

@@ -1,6 +1,9 @@
 import { EventEmitter } from '../../stencil-public-runtime';
 import type { DateRangeValue } from '../co-date-range-picker/co-date-range-picker';
 /**
+ * Alias de compatibilidad de `co-date-range-picker`: no lo uses en código nuevo.
+ * Wrapper Vue: `CoDateRange` de `@prolibu-suite/cobalt-vue`.
+ *
  * @deprecated Use `<co-date-range-picker>` instead.
  *
  * Thin compatibility shim kept for one release: it renders the canonical
@@ -12,18 +15,27 @@ export declare class CoDateRange {
     el: HTMLElement;
     /** JSON `{from,to}` or empty string. */
     value: string;
+    /** Etiqueta del campo. */
     label: string;
+    /** Texto del trigger sin rango. */
     placeholder: string;
+    /** Deshabilita el campo. */
     disabled: boolean;
+    /** Acción «Limpiar» en el footer; emite `coClear`. */
     clearable: boolean;
+    /** Columna de rangos rápidos (hoy, esta semana…), traducidos según `locale`. */
     presets: boolean;
+    /** Texto de ayuda bajo el campo. */
     helperText: string;
     /** BCP-47 locale. */
     locale: string;
+    /** Texto del botón «Aplicar»; vacío = el del `locale`. */
     applyLabel?: string;
+    /** Texto de la acción «Limpiar»; vacío = el del `locale`. */
     clearLabel?: string;
     /** Fires (with `{from,to}`) when the user applies a range. */
     coChange: EventEmitter<DateRangeValue>;
+    /** Se vació el rango con «Limpiar». Sin `detail`. */
     coClear: EventEmitter<void>;
     private warned;
     connectedCallback(): void;

package/dist/types/components/co-date-range-picker/co-date-range-picker.d.ts

@@ -12,15 +12,25 @@ export interface DateRangeValue {
  * unset) so it survives JSX attribute serialization. The trigger shows the
  * COMMITTED range; the popover edits a draft that only commits on Apply (or, if
  * `applyOnSelect`, debounced once both ends are chosen — for table filters).
+ * Wrapper Vue: `CoDateRangePicker` de `@prolibu-suite/cobalt-vue`.
+ *
+ * @part label - Etiqueta del campo.
+ * @part trigger - Botón que muestra el rango confirmado y abre el popover.
+ * @part helper - Texto de ayuda, o el `errorMessage` cuando el campo es inválido.
  */
 export declare class CoDateRangePicker {
     el: HTMLElement;
     /** JSON `{from,to}` or '' (empty). */
     value: string;
+    /** Fecha mínima elegible, `YYYY-MM-DD`. */
     min?: string;
+    /** Fecha máxima elegible, `YYYY-MM-DD`. */
     max?: string;
+    /** Locale BCP-47: nombres de meses y días, parseo de lo tipeado y textos de la UI (es/en/pt). */
     locale: string;
+    /** Formato de las fechas en el trigger y los campos. Tokens: `yyyy yy MMMM MMM MM M dd d`. */
     displayFormat: string;
+    /** Primer día de la semana del calendario: 0 = domingo … 6 = sábado (default 1, lunes). */
     firstDayOfWeek: number;
     /** Show the quick-preset column. */
     presets: boolean;
@@ -38,17 +48,25 @@ export declare class CoDateRangePicker {
     minRangeDays?: number;
     /** Maximum span (inclusive days). */
     maxRangeDays?: number;
+    /** Muestra la acción «Limpiar» en el footer (default `true`); emite `coClear`. */
     clearable: boolean;
     /** Commit (emit coApply) as soon as a full valid range is picked, debounced. */
     applyOnSelect: boolean;
+    /** Deshabilita el campo: no abre el popover. */
     disabled: boolean;
+    /** Solo lectura: muestra el rango pero no permite cambiarlo. */
     readonly: boolean;
+    /** Marca el campo como inválido (validación externa): borde de error y `errorMessage` en lugar de `helperText`. */
     invalid: boolean;
+    /** Mensaje bajo el campo cuando `invalid` es `true`. */
     errorMessage?: string;
+    /** Texto de ayuda bajo el campo. */
     helperText?: string;
+    /** Etiqueta del campo. */
     label?: string;
     /** Whether the field is required (renders a required marker on the label). */
     required: boolean;
+    /** Texto del trigger sin rango; vacío = el del `locale`. */
     placeholder?: string;
     /** Label layout: vertical (label above) or horizontal (label beside) */
     layout: 'vertical' | 'horizontal';
@@ -59,22 +77,37 @@ export declare class CoDateRangePicker {
      *  focus ring, disabled and invalid states are unaffected. `default` (the
      *  standard bordered box) renders identically to before this prop existed. */
     variant: 'default' | 'flat';
+    /** Lado y alineación del popover respecto del trigger (default `bottom-start`). */
     placement: Placement;
+    /** Popover abierto (reflejado; el componente lo actualiza al abrir y cerrar). */
     open: boolean;
+    /** Texto del botón «Aplicar»; vacío = el del `locale`. */
     applyLabel?: string;
+    /** Texto del botón «Cancelar»; vacío = el del `locale`. */
     cancelLabel?: string;
+    /** Texto de la acción «Limpiar»; vacío = el del `locale`. */
     clearLabel?: string;
+    /** Etiqueta del campo de inicio («Desde»); vacío = la del `locale`. */
     fromLabel?: string;
+    /** Etiqueta del campo de fin («Hasta»); vacío = la del `locale`. */
     toLabel?: string;
     /** Max viewport width (px) that renders the picker as a bottom sheet. */
     mobileBreakpoint: number;
+    /** Cambió el inicio del borrador (sin confirmar); `detail` = `YYYY-MM-DD` o `null`. */
     coRangeStartChange: EventEmitter<string | null>;
+    /** Cambió el fin del borrador (sin confirmar); `detail` = `YYYY-MM-DD` o `null`. */
     coRangeEndChange: EventEmitter<string | null>;
+    /** Cambió el borrador del rango (sin confirmar); `detail` = `{ from, to }`. También sale al limpiar, con ambos en `null`. */
     coRangeChange: EventEmitter<DateRangeValue>;
+    /** Se confirmó el rango («Aplicar» o `applyOnSelect`): `value` ya está actualizado; `detail` = `{ from, to }`. */
     coApply: EventEmitter<DateRangeValue>;
+    /** «Cancelar»: descarta el borrador y cierra. Sin `detail`. */
     coCancel: EventEmitter<void>;
+    /** «Limpiar»: vacía `value` y cierra. Sin `detail`. */
     coClear: EventEmitter<void>;
+    /** Se abrió el popover (o la hoja en mobile). No burbujea. */
     coOpen: EventEmitter<void>;
+    /** Se cerró el popover (o la hoja en mobile). No burbujea. */
     coClose: EventEmitter<void>;
     /** Working range while the popover is open (commits on Apply). */
     draftFrom: string | null;

package/dist/types/components/co-date-time-picker/co-date-time-picker.d.ts

@@ -14,7 +14,7 @@ import type { Placement } from '../../utils/positioning';
  * (`@prolibu-suite/cobalt-calendar-utils`), so DST comes from the platform tz
  * database — the same boundary `co-calendar-timegrid` uses. A date-only value
  * ("2026-07-25") is NOT an instant: it is read as that wall-clock day in
- * `timeZone` at {@link DEFAULT_MINUTES} (09:00), never as UTC midnight (which
+ * `timeZone` at `DEFAULT_MINUTES` (09:00), never as UTC midnight (which
  * would shift the day west of UTC).
  *
  * INTERACTION (Google):
@@ -39,6 +39,8 @@ import type { Placement } from '../../utils/positioning';
  * to the field; outside-click/sheet-dismiss stay with co-popover/co-drawer and
  * are handled by `closeApplyingDraft` (see its doc for the Escape asymmetry).
  *
+ * Wrapper Vue: `CoDateTimePicker` de `@prolibu-suite/cobalt-vue`.
+ *
  * @part field - The bordered trigger row
  * @part label - The field label
  * @part display - The button that shows the formatted value
@@ -61,25 +63,39 @@ export declare class CoDateTimePicker {
     min?: string;
     /** Latest selectable day. Date-only "YYYY-MM-DD" or an instant. */
     max?: string;
+    /** Días bloqueados `YYYY-MM-DD`: array, o JSON / lista separada por comas desde HTML. */
     disabledDates?: string[] | string;
+    /** Días de la semana bloqueados (0 = domingo … 6 = sábado): array, o JSON / lista separada por comas. */
     disabledDaysOfWeek?: number[] | string;
+    /** Locale BCP-47: nombres de meses y días, formato de la hora y textos de la UI (es/en/pt). */
     locale: string;
     /** Date part of the trigger text (tokens yyyy/yy/MMMM/MMM/MM/M/dd/d). */
     displayFormat: string;
+    /** Primer día de la semana del calendario: 0 = domingo … 6 = sábado (default 1, lunes). */
     firstDayOfWeek: number;
+    /** Etiqueta del campo. */
     label?: string;
+    /** Texto del campo sin valor; vacío = el del `locale`. */
     placeholder?: string;
     /** Field size, mirrors co-input/co-date-field: s 28 / sm 32 / md 40 / lg 48. */
     size: 's' | 'sm' | 'md' | 'lg';
     /** `flat` strips the trigger's border/background so it reads as content. */
     variant: 'default' | 'flat';
+    /** Atributo `name` del campo. */
     name?: string;
+    /** Deshabilita el campo. */
     disabled: boolean;
+    /** Solo lectura: muestra el valor pero no abre el panel ni permite limpiar. */
     readonly: boolean;
+    /** Campo obligatorio: marca la etiqueta con el indicador de requerido. */
     required: boolean;
+    /** Botón × para vaciar el valor (default `true`); emite `coClear` y `coChange(null)`. */
     clearable: boolean;
+    /** Marca el campo como inválido (validación externa): borde de error y `errorMessage` en lugar de `helperText`. */
     invalid: boolean;
+    /** Mensaje bajo el campo cuando `invalid` es `true`. */
     errorMessage?: string;
+    /** Texto de ayuda bajo el campo. */
     helperText?: string;
     /** Label layout: vertical (label above) or horizontal (label beside). */
     layout: 'vertical' | 'horizontal';
@@ -95,10 +111,15 @@ export declare class CoDateTimePicker {
     draftMinutes: number;
     /** Committed instant (UTC ISO) or null. */
     coChange: EventEmitter<string | null>;
+    /** Se vació el valor con la ×; le sigue un `coChange(null)`. Sin `detail`. */
     coClear: EventEmitter<void>;
+    /** El campo ganó el foco. */
     coFocus: EventEmitter<void>;
+    /** El campo perdió el foco. */
     coBlur: EventEmitter<void>;
+    /** Se abrió el panel (popover u hoja en mobile). No burbujea. */
     coOpen: EventEmitter<void>;
+    /** Se cerró el panel. No burbujea. */
     coClose: EventEmitter<void>;
     private popoverEl?;
     private calendarEl?;

package/dist/types/components/co-document-editor/change-throttle.d.ts

@@ -0,0 +1,9 @@
+/** Ventana de `coChange`: avisa como mucho cada 250 ms (nunca por tecla). */
+export declare const DOC_CHANGE_THROTTLE_MS = 250;
+export interface Throttle {
+    run(): void;
+    flush(): void;
+    cancel(): void;
+    readonly pending: boolean;
+}
+export declare function createThrottle(ms: number, fn: () => void): Throttle;

package/dist/types/components/co-document-editor/co-document-editor.d.ts

@@ -0,0 +1,284 @@
+import { EventEmitter } from '../../stencil-public-runtime';
+import type { Editor, FieldInfo, ImageUploadHandler, MergeFieldAttributes, PrintImageMode, ToolbarExtraItem } from '@prolibu-suite/cobalt-rich-text';
+import { type RichTextStrings } from '../../utils/richTextI18n';
+export interface DocumentFeatures {
+    /** Campos `[[nombre]]` (default true). */
+    fields?: boolean;
+    /** Marcadores de firma `⟦sig:N⟧` (default true). */
+    signatureSlots?: boolean;
+}
+/** Igual al detalle que emite co-rich-text-toolbar para un botón del host (`extraItems`). */
+export interface DocumentActionDetail {
+    action: string;
+    payload: {
+        extra: true;
+    };
+}
+export interface DocumentHeaderDetail {
+    html: string;
+    showPageNumber: boolean;
+}
+export type DocumentPageSize = 'letter' | 'a4' | 'legal' | {
+    width: number;
+    height: number;
+};
+export interface DocumentMargins {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/**
+ * Editor de documentos paginado: hoja fija, encabezado en banda, campos y
+ * firmas (spec contracts-v2-contract-editor §4.2). Recibe y devuelve SOLO el
+ * cuerpo (HTML de impresión) y el HTML del encabezado; no sabe de contratos.
+ * Nunca serializa por tecla: `coChange` solo avisa y el host pide
+ * `getPrintHtml()` cuando lo necesita.
+ *
+ * `shadow: false` (como co-rich-text-editor): ProseMirror arma su DOM de forma
+ * imperativa y el CSS de impresión del host tiene que alcanzarlo.
+ *
+ * @slot aside - Panel lateral del host (ancho fijo del componente: `--co-doc-aside-width`, 320px por defecto). Mantener el hijo siempre montado (v-show).
+ * @part wrapper - Contenedor externo
+ * @part bar - Fila de la barra
+ * @part toolbar - Barra de formato
+ * @part canvas - Superficie donde se centran las hojas
+ * @part sheet - El papel
+ * @part header-band - Banda del encabezado de la primera hoja *
+ * Wrapper Vue: `CoDocumentEditor` de `@prolibu-suite/cobalt-vue`.
+ */
+export declare class CoDocumentEditor {
+    el: HTMLElement;
+    /** Cuerpo: HTML de impresión (tolera el que guardó V1) o JSON de ProseMirror como string. */
+    value: string | null;
+    /** HTML del encabezado (banda superior de cada hoja). Vacío = sin encabezado. */
+    headerHtml: string;
+    /** Número de página en la banda. Se lee como intención: `true` o `'true'`. */
+    showPageNumber: boolean | string;
+    /** `letter` | `a4` | `legal` o `{width, height}` en px a 96 dpi (objeto o JSON). */
+    pageSize: string | DocumentPageSize;
+    /** Márgenes en px (objeto o JSON). Default 38 px por lado (10 mm). */
+    margins?: string | DocumentMargins;
+    /** Alto de la banda del encabezado en px (cuando hay encabezado). */
+    headerHeight: number;
+    /** CSS de impresión del host; se acota a la hoja. */
+    pageStyles: string;
+    /** `{fields, signatureSlots}` (objeto o JSON). */
+    features?: string | DocumentFeatures;
+    /** `(file) => Promise<{src, fileId?}>` (propiedad JS). */
+    imageUpload?: ImageUploadHandler;
+    /** Solo lectura: sin barra ni edición (el encabezado tampoco se puede editar). */
+    readonly: boolean;
+    /** BCP-47 para los textos de la UI ('es', 'en', 'pt-BR'…). */
+    locale: string;
+    /** Botones del host al final de la barra (objeto o JSON): `[{id, label, icon?}]`. */
+    extraItems?: string | ToolbarExtraItem[];
+    /** Nombre accesible del área de edición. */
+    label?: string;
+    /** Hubo un cambio del usuario en el cuerpo (sin HTML; como mucho cada 250 ms). */
+    coChange: EventEmitter<void>;
+    /** Lista de campos (cuerpo + encabezado) cuando cambia. */
+    coFieldsChange: EventEmitter<FieldInfo[]>;
+    /** Encabezado confirmado. */
+    coHeaderChange: EventEmitter<DocumentHeaderDetail>;
+    /** Cantidad de páginas. */
+    coPagesChange: EventEmitter<number>;
+    /** Clic en un botón del host (`extraItems`): `{ action: <id>, payload: { extra: true } }`. */
+    coAction: EventEmitter<DocumentActionDetail>;
+    /** El editor terminó de montar. No burbujea. */
+    coReady: EventEmitter<void>;
+    ready: boolean;
+    pageCount: number;
+    /** `custom` = zoom libre por gesto (pinza del trackpad / ctrl+rueda); la escala queda donde la dejó el usuario. */
+    zoomMode: 'fit' | 'actual' | 'custom';
+    scale: number;
+    stageHeight: number;
+    /** La banda del encabezado está en edición (editor `print-header` montado). */
+    headerEditing: boolean;
+    /** Interruptor de número de página mientras se edita (se confirma con el encabezado). */
+    draftShowPageNumber: boolean;
+    /** Barra de diseño de la imagen seleccionada en el cuerpo (null = no hay). Posición en px del papel. */
+    imageBar: {
+        mode: PrintImageMode;
+        top: number;
+        left: number;
+    } | null;
+    private editor?;
+    private contentEl?;
+    private canvasEl?;
+    private stageEl?;
+    private styleEl?;
+    private resizeObserver?;
+    /** Encabezado vigente (confirmado). La Task 16 lo cambia al confirmar la banda. */
+    protected currentHeaderHtml: string;
+    protected currentShowPageNumber: boolean;
+    private headerEditor?;
+    private headerMountEl?;
+    private headerBandEl?;
+    /** JSON del encabezado confirmado (lista de campos sin montar un editor). */
+    private headerDoc;
+    private toolbarEl?;
+    private readonly instanceId;
+    private applyingExternal;
+    private lastAppliedValue;
+    private userDirty;
+    private lastFieldsKey;
+    /** src de imágenes insertadas por el usuario sin `width`: al cargar reciben uno (nota T8). */
+    private pendingImageSrcs;
+    private changeThrottle;
+    protected get s(): RichTextStrings;
+    private get resolvedFeatures();
+    private get parsedExtraItems();
+    private get pageSizePx();
+    private get marginsPx();
+    /** Con la banda en edición hay banda aunque el encabezado confirmado esté vacío. */
+    private get hasHeader();
+    private get sanitizedHeaderHtml();
+    private get pageScope();
+    /** Editor que maneja la barra: el del encabezado mientras la banda está en edición. */
+    private get activeEditor();
+    /** «Encabezado» en la barra: apagado en solo lectura y con la banda ya abierta. */
+    private get documentHeaderEnabled();
+    /** Paginación del cuerpo: tamaño, márgenes y banda del encabezado. */
+    private buildCustomExtensions;
+    /** Campos del cuerpo y, detrás, los del encabezado (el que se edita o el confirmado). */
+    private collectAllFields;
+    connectedCallback(): void;
+    componentWillLoad(): void;
+    componentDidLoad(): void;
+    componentDidRender(): void;
+    disconnectedCallback(): void;
+    onValueChange(next: string | null): void;
+    onReadonlyChange(): void;
+    onPageGeometryChange(): void;
+    onHeaderPropsChange(): void;
+    onPageStylesChange(): void;
+    onLabelChange(): void;
+    /** «Página N / M» de las bandas de salto sale del idioma: redibujarlas. */
+    onLocaleChange(): void;
+    /** Cuerpo en la forma canónica de impresión (spec §3.4). */
+    getPrintHtml(): Promise<string>;
+    /**
+     * HTML del encabezado confirmado: el de la prop tal cual, o la forma canónica
+     * si pasó por la banda o por `setFieldValues`. Lo que se está editando en la
+     * banda sin confirmar NO cuenta.
+     */
+    getHeaderHtml(): Promise<string>;
+    /** Cuerpo como JSON de ProseMirror, o `null` si todavía no montó. */
+    getJSON(): Promise<object | null>;
+    /**
+     * Emite YA el `coChange` pendiente (no-op si no hay). El host lo llama antes de
+     * decidir «cambios sin aplicar» (cerrar, navegar): `coChange` sale al final de
+     * la ventana de 250 ms y una edición recién tipeada todavía no avisó.
+     * El blur del editor y un Escape dentro del componente lo hacen solos.
+     */
+    flushChange(): Promise<void>;
+    /**
+     * ¿Cuerpo vacío? En print un documento vacío NO serializa a `''`
+     * (`<p><br class="ProseMirror-trailingBreak"></p>`): el host pregunta acá.
+     */
+    isEmpty(): Promise<boolean>;
+    /** Reemplaza el cuerpo (HTML de impresión, V1 incluido). A diferencia del RTE, NO emite coChange. */
+    setContent(html: string): Promise<void>;
+    /**
+     * Valores de los campos (cuerpo y encabezado) en UNA transacción por editor; no
+     * cuenta como edición del usuario ni emite coHeaderChange. Con la banda abierta
+     * se aplican también al confirmado, así cancelar no los pierde.
+     */
+    setFieldValues(values: Record<string, string>): Promise<void>;
+    /** Inserta un campo `[[name]]` en el cursor; `opts`: `required`, `type`, `enum`, `value`. */
+    insertField(name: string, opts?: Partial<Omit<MergeFieldAttributes, 'name'>>): Promise<void>;
+    /** Inserta el siguiente marcador de firma libre (`⟦sig:N⟧`) en el cursor. */
+    insertSignatureSlot(): Promise<void>;
+    /** Enfoca el cuerpo del documento. */
+    focusEditor(): Promise<void>;
+    /** Instancia Tiptap del cuerpo (escape hatch), o `null` antes de montar. */
+    getEditorInstance(): Promise<Editor | null>;
+    /** Listeners y atributos del editor del cuerpo. */
+    private wireEditor;
+    private imageModeLabel;
+    /**
+     * Barra bajo la imagen seleccionada (corre en cada transacción del cuerpo). Solo
+     * cambia el estado si cambió algo: sin re-render por tecla ni bucles.
+     */
+    private updateImageBar;
+    /**
+     * Sin `.focus()`: con el mouse el mousedown de la barra ya no le quita el foco al
+     * editor, y con el teclado el foco se queda en el botón (se puede seguir en la barra).
+     * H7: el comando re-selecciona el nodo, así la barra sigue tras el cambio.
+     */
+    private setImageMode;
+    /** Imágenes que entran por una transacción del usuario sin `width` (barra, pegar, soltar, subida). */
+    private trackInsertedImages;
+    /** Una imagen insertada sin ancho nace acotada a la columna (V1 la abriría a 800 px). */
+    private onBodyImageLoad;
+    /** Al salir del editor (p. ej. mousedown en «Cerrar») el aviso no espera la ventana. */
+    private onEditorBlur;
+    private onHostKeydown;
+    /** JSON de ProseMirror como string, o HTML de impresión (V1 incluido) por el lector tolerante. */
+    private parseBody;
+    private applyBody;
+    private onTransaction;
+    private emitPendingChange;
+    private emitFieldsIfChanged;
+    private syncToolbar;
+    /** La barra emite coAction burbujeante: se corta acá y solo salen los botones del host. */
+    private handleToolbarAction;
+    protected syncHeaderFromProps(): void;
+    private startHeaderEdit;
+    private mountHeaderEditor;
+    /** `resync`: devolverle la barra al cuerpo (no al desconectar: la barra ya se soltó). */
+    private teardownHeaderEditor;
+    /** Cambios en la banda: solo la lista de campos (decisión 16: el encabezado no emite coChange). */
+    private onHeaderTransaction;
+    /** Como fitHeaderImage de V1: una imagen sin ancho se ajusta a la banda (40×400) al cargar. */
+    private onHeaderImageLoad;
+    /** Clic afuera de la banda (y de la barra, que la edita) confirma. */
+    private onDocumentPointer;
+    /**
+     * Esc cancela y NO sigue hasta el editor ni burbujea al host (no cierra el overlay
+     * de abajo). Convive con `onHostKeydown`: el host captura antes (es ancestro) y
+     * solo adelanta el coChange pendiente del cuerpo.
+     */
+    private onHeaderKeydown;
+    /** ¿El foco está en la banda (editor, interruptor, ✓) o se perdió al `<body>`? */
+    private focusIsInBandOrLost;
+    /**
+     * `restoreFocus`: confirmar con el ✓ (teclado o clic) desmonta el botón enfocado →
+     * el foco vuelve al cuerpo. El clic afuera NO lo toca: el foco ya se fue adonde se hizo clic.
+     */
+    private commitHeader;
+    /** `restoreFocus` solo para la cancelación del usuario (Esc); un cambio de prop no roba el foco. */
+    private cancelHeader;
+    /** Tamaño, márgenes o banda cambiaron: la extensión redibuja bandas y vuelve a medir. */
+    protected refreshPagination(): void;
+    private applyPageStyles;
+    /** Cabecera de la hoja `page` dentro de una banda de salto (DOM imperativo: la pinta un widget). */
+    protected buildHeaderClone(page: number, count: number): HTMLElement | null;
+    private updateScale;
+    /** Escala que refleja el DOM (se actualiza en componentDidRender). */
+    private renderedScale;
+    /** Punto del papel a mantener bajo el cursor hasta el próximo render. */
+    private pendingAnchor?;
+    /**
+     * Zoom libre anclado al cursor: guarda el punto del PAPEL bajo el puntero (con la escala que el
+     * DOM muestra ahora) y, tras el render, corrige el scroll midiendo dónde quedó. Varios eventos
+     * antes de un render reusan el mismo punto: la hoja todavía no se movió.
+     */
+    private zoomTo;
+    private applyPendingAnchor;
+    private onCanvasWheel;
+    /** Safari no manda la pinza como ctrl+wheel sino como GestureEvent (escala acumulada desde el inicio). */
+    private gestureBase;
+    private onGestureStart;
+    private onGestureChange;
+    private setZoom;
+    /**
+     * Banda de la primera hoja. Siempre montada (oculta con `hidden`); doble clic la
+     * vuelve un editor `print-header` con el interruptor de número de página.
+     */
+    protected renderHeaderBand(): any;
+    /** Controles flotantes sobre la hoja: la barra de diseño de la imagen seleccionada. */
+    protected renderOverlays(): any;
+    render(): any;
+}

package/dist/types/components/co-document-editor/document-props.d.ts

@@ -0,0 +1,6 @@
+import type { DocumentMargins, DocumentPageSize } from './co-document-editor';
+export declare const DEFAULT_MARGINS: DocumentMargins;
+/** `true` o `'true'`. Un `'false'` que dejó el multipart de V1 cuenta como falso (spec §3.6). */
+export declare function toBoolIntent(v: unknown): boolean;
+export declare function parsePageSize(v: unknown): DocumentPageSize;
+export declare function parseMargins(v: unknown): DocumentMargins;

package/dist/types/components/co-document-editor/header-tools.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Herramientas de la banda del encabezado en edición (interruptor de número de
+ * página + ✓). La fila cuelga ENCIMA de la banda, dentro del margen superior de la
+ * hoja, y el papel tiene `overflow: clip`: tiene que entrar en el margen mínimo
+ * (10 mm = 38 px) o se recorta. `co-icon-button size="sm"` mide 48 px: el tamaño va
+ * por `box-size`. Fila = max(✓, switch de 24) + padding + borde (ver la prueba).
+ */
+export declare const HEADER_TOOL_BOX_PX = 28;
+export declare const HEADER_TOOL_ICON_PX = 16;
+/** Margen superior más chico que se admite (10 mm a 96 dpi, el default del componente). */
+export declare const MIN_TOP_MARGIN_PX = 38;

package/dist/types/components/co-document-editor/image-bar.d.ts

@@ -0,0 +1,50 @@
+import type { PrintImageMode } from '@prolibu-suite/cobalt-rich-text';
+/**
+ * Barra de diseño de imagen (4 modos de V1). Vive DENTRO del papel, que tiene
+ * `overflow: clip`: su posición se decide acá para que nunca quede recortada.
+ * Las medidas son las del CSS (`.co-doc-editor__image-bar` / `__image-mode`,
+ * ver la prueba): se calculan sin medir el DOM porque la barra todavía no existe
+ * cuando se decide dónde va.
+ */
+export declare const IMAGE_MODE_ICONS: Record<PrintImageMode, string>;
+/** Botón de modo (ancho = alto). */
+export declare const IMAGE_MODE_BUTTON_PX = 28;
+export declare const IMAGE_MODE_ICON_PX = 16;
+/** 4 botones × 28 + 3 separaciones de 2 + relleno 2 × 2 + borde 1 × 2. */
+export declare const IMAGE_BAR_SIZE: {
+    width: number;
+    height: number;
+};
+/** Aire entre la imagen y la barra. */
+export declare const IMAGE_BAR_GAP_PX = 4;
+export interface Box {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+}
+export type ImageBarPlacement = 'below' | 'above' | 'inside';
+/**
+ * Debajo de la imagen (por defecto: una imagen pegada al margen superior no la
+ * saca por arriba); si no entra debajo (final del papel), encima; si tampoco,
+ * dentro de la imagen, sobre su borde inferior. En horizontal se acota al papel.
+ * Un papel sin medidas (0) no acota.
+ */
+export declare function imageBarPosition(img: Box, sheet: {
+    width: number;
+    height: number;
+}, bar?: {
+    width: number;
+    height: number;
+}, gap?: number): {
+    top: number;
+    left: number;
+    placement: ImageBarPlacement;
+};
+/** `offsetLeft` acumulado hasta `root` (par de `layoutBox`, que da el top). */
+export declare function layoutLeft(el: HTMLElement, root: HTMLElement): number;
+/**
+ * Ancho con el que nace una imagen insertada (nota T8 / plan B §6.4): sin `width`,
+ * V1 la abre a 800 px, más que la columna (≈740 en carta). Nunca pasa de la columna.
+ */
+export declare function defaultImageWidth(naturalWidth: number, columnWidth: number): number | null;

package/dist/types/components/co-document-editor/page-styles.d.ts

@@ -0,0 +1 @@
+export declare function scopePageStyles(css: string, scope: string): string;