Events

KViewer pushes state changes to the host through events. The same events reach three surfaces:

• <KViewer> — Vue emits (@field-placed, v-model:form-edit-mode, …).
• <KViewerTabs> — forwards a subset of the viewer events from the active tab's viewer, plus its own tab events.
• The embed bridge — a cross-origin parent page subscribes via KViewerEmbedClient.on(). Some bridge events use different names and payload shapes than their Vue counterparts; see Embed bridge.

Overview

Form fields

See FormFieldDefinition for the payload type.

User changes only

The field events report what the user did. Changes the host makes through addFormField(), updateFormField(), or removeFormField() do not fire an event — the host already knows about them. If you keep a copy of the field list, apply your own calls to it directly instead of waiting for an event.

Frequency

• Moving or resizing a field with the chrome fires one field-updated per gesture, on release — not one per pointer move.
• Editing a property in the form-edit sidebar fires once per keystroke while typing a field name, for example. Treat field-updated as an upsert keyed by field.id, and debounce it yourself if every event triggers a network request.

Keeping host state in sync

With these rules, the host never needs to poll getFormFields() or reconcile against it:

<template>
  <KViewer
    ref="viewer"
    :source="pdfUrl"
    :tools="tools"
    editable-placed-fields
    @field-placed="onFieldPlaced"
    @field-updated="(field) => fields.set(field.id, field)"
    @field-removed="(field) => fields.delete(field.id)"
  />
</template>

<script setup lang="ts">
import type { FormFieldDefinition } from 'kviewer'

const viewer = ref()
const fields = reactive(new Map<string, FormFieldDefinition>())
let signatureCount = 0

function onFieldPlaced(field: FormFieldDefinition) {
  // updateFormField() doesn't fire field-updated, so record the rename here too
  const fieldName = field.fieldType === 'signature'
    ? `signature_${++signatureCount}`
    : field.fieldName
  viewer.value.updateFormField(field.id, { fieldName })
  fields.set(field.id, { ...field, fieldName })
}
</script>

Signing

This is the push-style counterpart to getSignedStatus() and getSignatureFieldStatus(). allSigned is vacuously true when the document has no signature fields — check fields.length when at least one signature must exist.

Read tracking

A page counts as viewed once it has scrolled into the viewport. See allPagesRead() for the pull-style check.

Mode changes

Tabs

<KViewerTabs> emits its own tab events:

It also forwards field-placed, field-updated, field-removed, and signed-status-changed from the active tab's viewer, with the same payloads as <KViewer>. Read-tracking and mode events are not forwarded.

Embed bridge

A parent page that embeds the viewer in an iframe subscribes with KViewerEmbedClient.on(), which returns an unsubscribe function. Bridge payloads are always a single object, so events with multiple Vue arguments are wrapped:

Behavior matches the Vue events: field events report user changes only, and all-pages-read fires once per document.

Two events exist only on the bridge:

• ready fires once the viewer inside the iframe has mounted. events lists the events this iframe actually emits, and methods the methods it supports — both are undefined on older viewers that predate capability discovery, where you can assume everything is available.
• scroll-boundary reports vertical scroll the viewer couldn't consume because it reached the start or end of the document, so the parent page can continue scrolling itself.

const client = new KViewerEmbedClient(iframe, { iframeOrigin: 'https://viewer.example.com' })

client.on('ready', ({ events }) => {
  console.log('viewer emits', events)
})

const stop = client.on('field-updated', ({ field, patch }) => {
  fields.set(field.id, field)
})

client.on('signedStatus-changed', ({ allSigned }) => {
  finalizeButton.disabled = !allSigned
})

// later
stop()
client.dispose()