kviewer 0.3.4 → 0.3.6

package/dist/runtime/components/ViewerTabs.vue

@@ -63,13 +63,12 @@
           :menu-items="menuItems"
           :selection-items="selectionItems"
           :tools="tools"
-          :role-colors="roleColors"
-          :active-role-id="activeRoleId"
           :click-to-sign="clickToSign"
           :editable-placed-fields="editablePlacedFields"
           :field-defaults="fieldDefaults"
-          @update:active-role-id="(v) => emit('update:activeRoleId', v)"
           @field-placed="(f) => emit('field-placed', f)"
+          @field-updated="(f, p) => emit('field-updated', f, p)"
+          @field-removed="(f) => emit('field-removed', f)"
           @signed-status-changed="(p) => emit('signed-status-changed', p)"
         >
           <template v-if="$slots.header" #header>
@@ -109,8 +108,6 @@ const props = defineProps({
   viewMode: { type: String, required: false, default: "fit-width" },
   zoom: { type: Number, required: false, default: 1 },
   minTabs: { type: Number, required: false, default: 0 },
-  roleColors: { type: Object, required: false, default: void 0 },
-  activeRoleId: { type: [String, null], required: false, default: void 0 },
   scripting: { type: Boolean, required: false, default: false },
   menuItems: { type: Array, required: false, default: void 0 },
   selectionItems: { type: Array, required: false, default: void 0 },
@@ -123,7 +120,7 @@ const slots = useSlots();
 const toolSlotNames = computed(
   () => Object.keys(slots).filter((name) => name.startsWith("tool-"))
 );
-const emit = defineEmits(["update:activeTab", "tab-added", "tab-close", "tab-removed", "update:activeRoleId", "field-placed", "signed-status-changed"]);
+const emit = defineEmits(["update:activeTab", "tab-added", "tab-close", "tab-removed", "field-placed", "field-updated", "field-removed", "signed-status-changed"]);
 let idCounter = 0;
 function generateId() {
   return `tab-${Date.now()}-${++idCounter}`;

package/dist/runtime/components/ViewerTabs.vue.d.ts

@@ -54,11 +54,6 @@ type __VLS_Props = {
     zoom?: number;
     /** Minimum number of tabs -- prevents closing below this count. */
     minTabs?: number;
-    /** Forwarded to every Viewer instance — see KViewer's `roleColors`. */
-    roleColors?: Record<string, string>;
-    /** Forwarded to every Viewer instance — see KViewer's `activeRoleId`.
-     *  Supports v-model via `v-model:active-role-id`. */
-    activeRoleId?: string | null;
     /** Forwarded to every Viewer instance — see KViewer's `scripting`.
      *  Per-tab override via `ViewerTabItem.scripting` wins when set. */
     scripting?: boolean;
@@ -82,7 +77,7 @@ declare function addTab(item: Omit<ViewerTabItem, 'id'> & {
 declare function removeTab(id: string): boolean;
 declare function activateTab(id: string): void;
 declare function getViewer(id: string): ComponentPublicInstance | null;
-declare var __VLS_7: {}, __VLS_21: {}, __VLS_34: {
+declare var __VLS_7: {}, __VLS_21: {}, __VLS_35: {
     tab: {
         id: string;
         label: string;
@@ -182,7 +177,7 @@ declare var __VLS_7: {}, __VLS_21: {}, __VLS_34: {
         shapeDetection?: boolean | undefined;
         scripting?: boolean | undefined;
     };
-}, __VLS_37: {
+}, __VLS_38: {
     tab: {
         id: string;
         label: string;
@@ -282,21 +277,21 @@ declare var __VLS_7: {}, __VLS_21: {}, __VLS_34: {
         shapeDetection?: boolean | undefined;
         scripting?: boolean | undefined;
     };
-}, __VLS_41: string, __VLS_42: {
+}, __VLS_42: string, __VLS_43: {
     state: import("../composables/useViewerState.js").ViewerState;
-}, __VLS_44: {};
+}, __VLS_45: {};
 type __VLS_Slots = {} & {
-    [K in NonNullable<typeof __VLS_41>]?: (props: typeof __VLS_42) => any;
+    [K in NonNullable<typeof __VLS_42>]?: (props: typeof __VLS_43) => any;
 } & {
     'tabs-leading'?: (props: typeof __VLS_7) => any;
 } & {
     'tabs-trailing'?: (props: typeof __VLS_21) => any;
 } & {
-    header?: (props: typeof __VLS_34) => any;
+    header?: (props: typeof __VLS_35) => any;
 } & {
-    footer?: (props: typeof __VLS_37) => any;
+    footer?: (props: typeof __VLS_38) => any;
 } & {
-    empty?: (props: typeof __VLS_44) => any;
+    empty?: (props: typeof __VLS_45) => any;
 };
 declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     addTab: typeof addTab;
@@ -405,7 +400,8 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     }[];
 }, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     "field-placed": (field: FormFieldDefinition) => any;
-    "update:activeRoleId": (value: string | null) => any;
+    "field-updated": (field: FormFieldDefinition, patch: Partial<FormFieldDefinition>) => any;
+    "field-removed": (field: FormFieldDefinition) => any;
     "signed-status-changed": (payload: {
         allSigned: boolean;
         fields: SignatureFieldStatus[];
@@ -416,7 +412,8 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     "tab-removed": (id: string) => any;
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
     "onField-placed"?: ((field: FormFieldDefinition) => any) | undefined;
-    "onUpdate:activeRoleId"?: ((value: string | null) => any) | undefined;
+    "onField-updated"?: ((field: FormFieldDefinition, patch: Partial<FormFieldDefinition>) => any) | undefined;
+    "onField-removed"?: ((field: FormFieldDefinition) => any) | undefined;
     "onSigned-status-changed"?: ((payload: {
         allSigned: boolean;
         fields: SignatureFieldStatus[];
@@ -435,8 +432,6 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     stamps: StampDefinition[];
     signatureHandlers: SignatureHandlers;
     viewMode: ViewMode;
-    roleColors: Record<string, string>;
-    activeRoleId: string | null;
     editablePlacedFields: boolean;
     fieldDefaults: PlacedFieldDefaults;
     selectionItems: ViewerSelectionItem[];

package/dist/runtime/components/form-fields/FormFieldWrapper.vue

@@ -4,17 +4,19 @@
     :class="{
   'kviewer-form-field--editable': showChrome,
   'kviewer-form-field--placed': isPlaced,
-  'kviewer-form-field--selected': props.selected
+  'kviewer-form-field--selected': props.selected,
+  'kviewer-form-field--readonly': isReadonlyOutsideAuthoring
 }"
     :style="[positionStyle, {
   '--kvw-field-color': chromeColor,
   '--kvw-handle-zoom': handleZoom
 }]"
     :data-element-id="props.field.id"
+    @contextmenu="onContextMenu"
   >
     <div
       class="kviewer-form-field__body"
-      :class="{ 'kviewer-form-field__body--locked': showChrome }"
+      :class="{ 'kviewer-form-field__body--locked': chromeMode === 'authoring' }"
     >
       <FormTextField v-if="props.field.fieldType === 'text'" :field="props.field" />
       <FormCheckbox v-else-if="props.field.fieldType === 'checkbox'" :field="props.field" />
@@ -30,6 +32,7 @@
       :selected="props.selected"
       :scale="props.scale"
       :page-height="props.pageTransform.height"
+      :mode="chromeMode ?? 'authoring'"
       @select="emit('select')"
     />
 
@@ -64,18 +67,27 @@ const state = useViewerState();
 const formFields = useFormFields();
 const isPlaced = computed(() => props.field.origin === "placed");
 const isFormEditMode = computed(() => state.formEditMode.value);
-const showChrome = computed(
-  () => isFormEditMode.value || formFields.editablePlacedFields.value && isPlaced.value
+const chromeMode = computed(() => {
+  if (isFormEditMode.value) return "authoring";
+  if (formFields.editablePlacedFields.value && isPlaced.value && !props.field.readOnly) {
+    return "live";
+  }
+  return null;
+});
+const showChrome = computed(() => chromeMode.value !== null);
+const isReadonlyOutsideAuthoring = computed(
+  () => props.field.readOnly && !isFormEditMode.value
 );
+function onContextMenu(e) {
+  if (chromeMode.value !== "live") return;
+  e.preventDefault();
+  emit("select");
+}
 const handleZoom = computed(() => {
   const totalZoom = (props.scale || 1) * (state.visualZoom.value || 1);
   return (1 / totalZoom).toFixed(3);
 });
-const chromeColor = computed(() => {
-  const id = props.field.roleId;
-  if (!id) return "#1677ff";
-  return formFields.roleColors.value[id] ?? "#1677ff";
-});
+const chromeColor = computed(() => props.field.fieldColor ?? "#1677ff");
 const positionStyle = computed(() => {
   const rect = props.field.rect;
   const r = convertPdfRectToCanvas(props.pageTransform, [rect[0], rect[1], rect[2], rect[3]]);

package/dist/runtime/components/form-fields/FormSignatureField.vue

@@ -55,10 +55,18 @@ const signatureUrl = computed(() => {
 });
 const hasSigned = computed(() => !!signatureUrl.value);
 const clickToSignEnabled = computed(() => state.clickToSign.value);
-async function onClickSign() {
-  if (!clickToSignEnabled.value) return;
+const liveEditing = computed(
+  () => formFields.editablePlacedFields.value && props.field.origin === "placed" && !state.formEditMode.value
+);
+async function onClickSign(e) {
   if (props.field.readOnly || state.readonly.value) return;
   if (formFields.isFieldLocked(props.field.id)) return;
+  if (liveEditing.value && (hasSigned.value || !clickToSignEnabled.value)) {
+    e.stopPropagation();
+    formFields.selectPlacedField(props.field.id);
+    return;
+  }
+  if (!clickToSignEnabled.value) return;
   if (state.signatures.value.length > 0) {
     const sig = state.signatures.value[0];
     if (sig) {

package/dist/runtime/components/form-fields/PlacedFieldChrome.d.vue.ts

@@ -6,6 +6,10 @@ type __VLS_Props = {
     scale: number;
     /** PDF-space page height (kept for parity; unused here). */
     pageHeight: number;
+    /** 'authoring' = form-edit mode (chrome is the whole interactive
+     *  surface). 'live' = editablePlacedFields outside form-edit mode
+     *  (chrome is transparent except grip and handles). */
+    mode: 'authoring' | 'live';
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {} & {
     select: () => any;

package/dist/runtime/components/form-fields/PlacedFieldChrome.vue

@@ -1,11 +1,16 @@
 <template>
-  <!-- The whole chrome is the interactive surface in form-edit mode:
-       click to select, drag anywhere to move, plus a label bar above and
-       eight resize handles when selected. -->
+  <!-- Two interaction modes. Authoring (form-edit mode): the whole chrome
+       is the interactive surface — click to select, drag anywhere to move.
+       Live (editablePlacedFields): the surface is transparent so the field
+       body stays usable (click-to-sign, text input); management happens on
+       the always-visible grip ("handle = manage, body = use"). -->
   <div
     ref="rootEl"
     class="kviewer-placed-chrome"
-    :class="{ 'kviewer-placed-chrome--selected': selected }"
+    :class="{
+  'kviewer-placed-chrome--selected': selected,
+  'kviewer-placed-chrome--live': mode === 'live'
+}"
     @pointerdown.stop="onChromePointerDown"
     @click.stop
   >
@@ -17,9 +22,11 @@
 }"
     />
     <div
-      v-if="selected"
+      v-if="selected || mode === 'live'"
       class="kviewer-placed-chrome__grip"
       :title="field.fieldName"
+      @pointerdown.stop="onChromePointerDown"
+      @click.stop
     >
       <UIcon name="i-lucide-grip-vertical" class="kviewer-placed-chrome__grip-dots" />
       <span class="kviewer-placed-chrome__grip-label">{{ field.fieldName }}</span>
@@ -46,7 +53,8 @@ const props = defineProps({
   field: { type: Object, required: true },
   selected: { type: Boolean, required: true },
   scale: { type: Number, required: true },
-  pageHeight: { type: Number, required: true }
+  pageHeight: { type: Number, required: true },
+  mode: { type: String, required: true }
 });
 const emit = defineEmits(["select"]);
 const formFields = useFormFields();
@@ -91,12 +99,16 @@ function onChromePointerDown(e) {
       startRect[2] + dx,
       startRect[3] + pdfDy
     ];
-    formFields.updatePlacedField(props.field.id, { rect: next });
+    formFields.updatePlacedField(props.field.id, { rect: next }, { silent: true });
   };
   const onUp = () => {
     window.removeEventListener("pointermove", onMove);
     window.removeEventListener("pointerup", onUp);
-    if (!dragging) emit("select");
+    if (!dragging) {
+      emit("select");
+      return;
+    }
+    formFields.updatePlacedField(props.field.id, { rect: [...props.field.rect] });
   };
   window.addEventListener("pointermove", onMove);
   window.addEventListener("pointerup", onUp);
@@ -106,6 +118,7 @@ function onHandlePointerDown(e, name) {
   const startY = e.clientY;
   const [sx1, sy1, sx2, sy2] = props.field.rect;
   const s = effectiveScale();
+  let resized = false;
   const onMove = (ev) => {
     const dx = (ev.clientX - startX) / s;
     const dy = (ev.clientY - startY) / s;
@@ -115,11 +128,15 @@ function onHandlePointerDown(e, name) {
     if (name.includes("s")) y1 = Math.min(y2 - 4, sy1 + pdfDy);
     if (name.includes("e")) x2 = Math.max(x1 + 4, sx2 + dx);
     if (name.includes("w")) x1 = Math.min(x2 - 4, sx1 + dx);
-    formFields.updatePlacedField(props.field.id, { rect: [x1, y1, x2, y2] });
+    resized = true;
+    formFields.updatePlacedField(props.field.id, { rect: [x1, y1, x2, y2] }, { silent: true });
   };
   const onUp = () => {
     window.removeEventListener("pointermove", onMove);
     window.removeEventListener("pointerup", onUp);
+    if (resized) {
+      formFields.updatePlacedField(props.field.id, { rect: [...props.field.rect] });
+    }
   };
   window.addEventListener("pointermove", onMove);
   window.addEventListener("pointerup", onUp);
@@ -127,5 +144,5 @@ function onHandlePointerDown(e, name) {
 </script>
 
 <style>
-.kviewer-placed-chrome{cursor:move;inset:0;pointer-events:auto;position:absolute;touch-action:none}.kviewer-placed-chrome__outline{border:1px dashed color-mix(in srgb,var(--kvw-field-color,#1677ff) 45%,transparent);box-sizing:border-box;height:calc(100%/var(--kvw-handle-zoom, 1));left:0;pointer-events:none;position:absolute;top:0;transform:scale(var(--kvw-handle-zoom,1));transform-origin:0 0;width:calc(100%/var(--kvw-handle-zoom, 1))}.kviewer-placed-chrome__outline--placed{border-color:color-mix(in srgb,var(--kvw-field-color,#1677ff) 75%,transparent)}.kviewer-placed-chrome__outline--selected{border:1.5px dashed var(--kvw-field-color,#1677ff)}.kviewer-placed-chrome__grip{align-items:center;background:color-mix(in srgb,var(--kvw-field-color,#1677ff) 15%,transparent);border:1px solid color-mix(in srgb,var(--kvw-field-color,#1677ff) 40%,transparent);border-radius:4px;bottom:calc(100% + 4px*var(--kvw-handle-zoom, 1));box-sizing:border-box;color:var(--kvw-field-color,#1677ff);cursor:move;display:flex;font-size:12px;gap:4px;height:22px;left:0;line-height:1;overflow:hidden;padding:0 8px 0 3px;pointer-events:auto;position:absolute;touch-action:none;transform:scale(var(--kvw-handle-zoom,1));transform-origin:0 100%;-webkit-user-select:none;-moz-user-select:none;user-select:none;width:calc(100%/var(--kvw-handle-zoom, 1))}.kviewer-placed-chrome__grip-dots{color:var(--kvw-field-color,#1677ff);flex:0 0 auto;height:13px;width:13px}.kviewer-placed-chrome__grip-label{flex:1 1 auto;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.kviewer-placed-chrome__handle{background:#fff;border:1px solid var(--kvw-field-color,#1677ff);border-radius:2px;height:8px;pointer-events:auto;position:absolute;touch-action:none;transform:scale(var(--kvw-handle-zoom,1));width:8px}.kviewer-placed-chrome__handle:before{content:"";inset:-8px;position:absolute}.kviewer-placed-chrome__handle--n{left:50%;top:-4px;transform:translateX(-50%) scale(var(--kvw-handle-zoom,1))}.kviewer-placed-chrome__handle--s{bottom:-4px;left:50%;transform:translateX(-50%) scale(var(--kvw-handle-zoom,1))}.kviewer-placed-chrome__handle--e{right:-4px;top:50%;transform:translateY(-50%) scale(var(--kvw-handle-zoom,1))}.kviewer-placed-chrome__handle--w{left:-4px;top:50%;transform:translateY(-50%) scale(var(--kvw-handle-zoom,1))}.kviewer-placed-chrome__handle--ne{right:-4px;top:-4px}.kviewer-placed-chrome__handle--nw{left:-4px;top:-4px}.kviewer-placed-chrome__handle--se{bottom:-4px;right:-4px}.kviewer-placed-chrome__handle--sw{bottom:-4px;left:-4px}
+.kviewer-placed-chrome{cursor:move;inset:0;pointer-events:auto;position:absolute;touch-action:none}.kviewer-placed-chrome--live{cursor:default;pointer-events:none}.kviewer-placed-chrome__outline{border:1px dashed color-mix(in srgb,var(--kvw-field-color,#1677ff) 45%,transparent);box-sizing:border-box;height:calc(100%/var(--kvw-handle-zoom, 1));left:0;pointer-events:none;position:absolute;top:0;transform:scale(var(--kvw-handle-zoom,1));transform-origin:0 0;width:calc(100%/var(--kvw-handle-zoom, 1))}.kviewer-placed-chrome__outline--placed{border-color:color-mix(in srgb,var(--kvw-field-color,#1677ff) 75%,transparent)}.kviewer-placed-chrome__outline--selected{border:1.5px dashed var(--kvw-field-color,#1677ff)}.kviewer-placed-chrome__grip{align-items:center;background:color-mix(in srgb,var(--kvw-field-color,#1677ff) 15%,transparent);border:1px solid color-mix(in srgb,var(--kvw-field-color,#1677ff) 40%,transparent);border-radius:4px;bottom:calc(100% + 4px*var(--kvw-handle-zoom, 1));box-sizing:border-box;color:var(--kvw-field-color,#1677ff);cursor:move;display:flex;font-size:12px;gap:4px;height:22px;left:0;line-height:1;overflow:hidden;padding:0 8px 0 3px;pointer-events:auto;position:absolute;touch-action:none;transform:scale(var(--kvw-handle-zoom,1));transform-origin:0 100%;-webkit-user-select:none;-moz-user-select:none;user-select:none;width:calc(100%/var(--kvw-handle-zoom, 1))}.kviewer-placed-chrome__grip-dots{color:var(--kvw-field-color,#1677ff);flex:0 0 auto;height:13px;width:13px}.kviewer-placed-chrome__grip-label{flex:1 1 auto;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.kviewer-placed-chrome__handle{background:#fff;border:1px solid var(--kvw-field-color,#1677ff);border-radius:2px;height:8px;pointer-events:auto;position:absolute;touch-action:none;transform:scale(var(--kvw-handle-zoom,1));width:8px}.kviewer-placed-chrome__handle:before{content:"";inset:-8px;position:absolute}.kviewer-placed-chrome__handle--n{left:50%;top:-4px;transform:translateX(-50%) scale(var(--kvw-handle-zoom,1))}.kviewer-placed-chrome__handle--s{bottom:-4px;left:50%;transform:translateX(-50%) scale(var(--kvw-handle-zoom,1))}.kviewer-placed-chrome__handle--e{right:-4px;top:50%;transform:translateY(-50%) scale(var(--kvw-handle-zoom,1))}.kviewer-placed-chrome__handle--w{left:-4px;top:50%;transform:translateY(-50%) scale(var(--kvw-handle-zoom,1))}.kviewer-placed-chrome__handle--ne{right:-4px;top:-4px}.kviewer-placed-chrome__handle--nw{left:-4px;top:-4px}.kviewer-placed-chrome__handle--se{bottom:-4px;right:-4px}.kviewer-placed-chrome__handle--sw{bottom:-4px;left:-4px}
 </style>

package/dist/runtime/components/form-fields/PlacedFieldChrome.vue.d.ts

@@ -6,6 +6,10 @@ type __VLS_Props = {
     scale: number;
     /** PDF-space page height (kept for parity; unused here). */
     pageHeight: number;
+    /** 'authoring' = form-edit mode (chrome is the whole interactive
+     *  surface). 'live' = editablePlacedFields outside form-edit mode
+     *  (chrome is transparent except grip and handles). */
+    mode: 'authoring' | 'live';
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {} & {
     select: () => any;

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

@@ -27,10 +27,22 @@ export interface FormFieldsState {
      *  `addPlacedField` with full control over the field's properties.
      *  Returns the created definition. */
     addFormField: (payload: AddFormFieldPayload) => FormFieldDefinition;
-    /** Update a form field's rect, name, or flags. */
-    updatePlacedField: (id: string, patch: Partial<FormFieldDefinition>) => void;
-    /** Remove a form field and its value. */
-    removePlacedField: (id: string) => void;
+    /** Update a form field's rect, name, or flags. Notifies the field-event
+     *  sink unless `opts.silent` — pass silent from the public API (the host
+     *  knows about its own calls) and from high-frequency gesture updates
+     *  (commit one non-silent update on gesture end instead). */
+    updatePlacedField: (id: string, patch: Partial<FormFieldDefinition>, opts?: {
+        silent?: boolean;
+    }) => void;
+    /** Remove a form field and its value. Same `silent` contract as
+     *  `updatePlacedField`. */
+    removePlacedField: (id: string, opts?: {
+        silent?: boolean;
+    }) => void;
+    /** Install the sink that receives user-driven field mutations. Viewer.vue
+     *  owns it and fans out to the `field-updated` / `field-removed` emits and
+     *  the embed bridge. Survives document changes (unlike the value sink). */
+    setFieldEventSink: (sink: FieldEventSink | null) => void;
     /** All form-field definitions, flattened across pages. */
     getAllFields: () => FormFieldDefinition[];
     /** All user-placed field definitions (used by export). */
@@ -45,19 +57,6 @@ export interface FormFieldsState {
     selectedPlacedFieldId: Ref<string | null>;
     /** Select or deselect a placed field. Pass null to deselect. */
     selectPlacedField: (id: string | null) => void;
-    /** Opaque role id new placements are auto-tagged with. The host owns
-     *  what roles exist; the editor only carries the active id forward to
-     *  newly placed fields and looks up its color via roleColors. */
-    activeRoleId: Ref<string | null>;
-    /** Set or clear the active role for upcoming placements. */
-    setActiveRole: (id: string | null) => void;
-    /** Map from roleId → CSS color, supplied by the host via the KViewer
-     *  `roleColors` prop. Reading this drives the chrome and placement
-     *  preview color. The editor never mutates role definitions itself. */
-    roleColors: ShallowRef<Record<string, string>>;
-    /** Replace the host-provided color map. Called by KViewer when the
-     *  prop changes. */
-    setRoleColors: (colors: Record<string, string>) => void;
     /** Per-field-type presets merged into every tool placement. Host-owned
      *  via the KViewer `fieldDefaults` prop or the bridge; programmatic
      *  `addFormField` calls are NOT affected (the payload is explicit). */
@@ -110,5 +109,17 @@ export interface FormFieldsState {
 /** Sink signature used by [[setValueWriteSink]]. Receives every user-driven
  *  field value write (the primary id AND each mirrored sibling). */
 export type ValueWriteSink = (fieldId: string, value: string | boolean | string[]) => void;
+/** User-driven field mutation, delivered to the sink installed via
+ *  [[setFieldEventSink]]. `field` is the post-mutation definition for
+ *  updates and the last-known definition for removals. */
+export type FieldEvent = {
+    type: 'updated';
+    field: FormFieldDefinition;
+    patch: Partial<FormFieldDefinition>;
+} | {
+    type: 'removed';
+    field: FormFieldDefinition;
+};
+export type FieldEventSink = (event: FieldEvent) => void;
 export declare function provideFormFields(): FormFieldsState;
 export declare function useFormFields(): FormFieldsState;

package/dist/runtime/composables/useFormFields.js

@@ -12,16 +12,8 @@ export function provideFormFields() {
   const fieldDefinitions = shallowRef(/* @__PURE__ */ new Map());
   const fieldValues = shallowRef(/* @__PURE__ */ new Map());
   const selectedPlacedFieldId = ref(null);
-  const activeRoleId = ref(null);
-  const roleColors = shallowRef({});
   const placedFieldDefaults = shallowRef({});
   const editablePlacedFields = ref(false);
-  function setActiveRole(id) {
-    activeRoleId.value = id;
-  }
-  function setRoleColors(colors) {
-    roleColors.value = colors;
-  }
   function setPlacedFieldDefaults(defaults) {
     placedFieldDefaults.value = defaults;
   }
@@ -43,6 +35,10 @@ export function provideFormFields() {
   function setValueWriteSink(sink) {
     valueWriteSink = sink;
   }
+  let fieldEventSink = null;
+  function setFieldEventSink(sink) {
+    fieldEventSink = sink;
+  }
   let checkboxStyleMap = null;
   let buttonCaptionMap = null;
   let signedSignatureNames = null;
@@ -297,9 +293,7 @@ export function provideFormFields() {
         )
       );
     }
-    if (activeRoleId.value) {
-      def.roleId = activeRoleId.value;
-    }
+    if (def.meta) def.meta = { ...def.meta };
     if (payload.fieldType === "radio") {
       def.buttonValue = nextRadioOptionValue(fieldName);
     }
@@ -340,7 +334,8 @@ export function provideFormFields() {
       required: payload.required ?? false,
       origin: "placed"
     };
-    if (payload.roleId !== void 0) def.roleId = payload.roleId;
+    if (payload.fieldColor !== void 0) def.fieldColor = payload.fieldColor;
+    if (payload.meta !== void 0) def.meta = { ...payload.meta };
     if (payload.defaultValue !== void 0) def.defaultValue = payload.defaultValue;
     if (payload.fontSize !== void 0) def.fontSize = payload.fontSize;
     if (payload.fontName !== void 0) def.fontName = payload.fontName;
@@ -401,7 +396,7 @@ export function provideFormFields() {
     while (used.has(`Option_${n}`)) n += 1;
     return `Option_${n}`;
   }
-  function updatePlacedField(id, patch) {
+  function updatePlacedField(id, patch, opts) {
     let found;
     for (const [page, defs] of fieldDefinitions.value.entries()) {
       const idx = defs.findIndex((d) => d.id === id);
@@ -422,12 +417,16 @@ export function provideFormFields() {
       fv.fieldType = found.fieldType;
       triggerRef(fieldValues);
     }
+    if (!opts?.silent && fieldEventSink) {
+      fieldEventSink({ type: "updated", field: found, patch });
+    }
   }
-  function removePlacedField(id) {
-    let removed = false;
+  function removePlacedField(id, opts) {
+    let removed;
     for (const [page, defs] of fieldDefinitions.value.entries()) {
       const idx = defs.findIndex((d) => d.id === id);
       if (idx === -1) continue;
+      removed = defs[idx];
       const nextDefs = defs.slice();
       nextDefs.splice(idx, 1);
       if (nextDefs.length === 0) {
@@ -435,7 +434,6 @@ export function provideFormFields() {
       } else {
         fieldDefinitions.value.set(page, nextDefs);
       }
-      removed = true;
       break;
     }
     if (!removed) return;
@@ -446,6 +444,9 @@ export function provideFormFields() {
     if (selectedPlacedFieldId.value === id) {
       selectedPlacedFieldId.value = null;
     }
+    if (!opts?.silent && fieldEventSink) {
+      fieldEventSink({ type: "removed", field: removed });
+    }
   }
   function getPlacedFields() {
     const out = [];
@@ -477,14 +478,12 @@ export function provideFormFields() {
         if (d.fieldType !== "signature") continue;
         const fv = fieldValues.value.get(d.id);
         const signed = typeof fv?.value === "string" && fv.value !== "" || d.signedInSource === true;
-        const status = {
+        out.push({
           id: d.id,
           fieldName: d.fieldName,
           pageNumber: d.pageNumber,
           signed
-        };
-        if (d.roleId) status.roleId = d.roleId;
-        out.push(status);
+        });
       }
     }
     return out;
@@ -556,11 +555,8 @@ export function provideFormFields() {
     resetValues,
     reset,
     setValueWriteSink,
+    setFieldEventSink,
     applyFieldValueFromExternal,
-    activeRoleId,
-    setActiveRole,
-    roleColors,
-    setRoleColors,
     placedFieldDefaults,
     setPlacedFieldDefaults,
     editablePlacedFields,

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

@@ -17,6 +17,11 @@ export interface Transform {
     tx: number;
     ty: number;
 }
+export interface ScrollDelta {
+    x: number;
+    y: number;
+}
+export declare function getUnconsumedScrollDelta(requested: ScrollDelta, before: Transform, after: Transform): ScrollDelta;
 export interface InertiaPanzoomHandle {
     /** Bind gesture handlers to the given element (its parent becomes the viewport). */
     attach: (target: HTMLElement) => void;
@@ -30,8 +35,9 @@ export interface InertiaPanzoomHandle {
     getTransform: () => Transform;
     /** Animate the view so `elem` is at the top (or center) of the viewport. */
     scrollToElement: (elem: HTMLElement, opts?: ScrollToElementOptions) => void;
-    /** Pan by a delta in viewport pixels (clamped to bounds). */
-    scrollBy: (dx: number, dy: number) => void;
+    /** Pan by a delta in viewport pixels and return the portion that could not
+     *  be consumed because the viewport reached a boundary. */
+    scrollBy: (dx: number, dy: number) => ScrollDelta;
     /** Enable/disable pan+pinch gestures (wheel/scrollbar/keyboard still work). */
     setGesturesEnabled: (enabled: boolean) => void;
     /** Subscribe to transform updates. Returns an unsubscribe function. */

package/dist/runtime/composables/useInertiaPanzoom.js

@@ -1,14 +1,17 @@
 import { onBeforeUnmount } from "vue";
+export function getUnconsumedScrollDelta(requested, before, after) {
+  return {
+    x: requested.x - (before.tx - after.tx),
+    y: requested.y - (before.ty - after.ty)
+  };
+}
 const DECELERATION = 0.998;
 const RUBBER_BAND_C = 0.55;
 const BOUNCE_BACK_RATE = 0.04;
 const BOUNCE_VELOCITY_DECAY = 0.04;
 const MIN_VELOCITY = 0.01;
 export function useInertiaPanzoom(options = {}) {
-  const {
-    axisLockThreshold = 10,
-    axisLockRatio = 2
-  } = options;
+  const { axisLockThreshold = 10, axisLockRatio = 2 } = options;
   let minScale = options.minScale ?? 0.5;
   let maxScale = options.maxScale ?? 4;
   const subscribers = /* @__PURE__ */ new Set();
@@ -139,11 +142,17 @@ export function useInertiaPanzoom(options = {}) {
       if (barDrag.axis === "y") {
         const dy = e.clientY - barDrag.startPointer;
         const b = getBounds();
-        ty = Math.max(b.minY, Math.min(b.maxY, barDrag.startT - dy * barDrag.ratio));
+        ty = Math.max(
+          b.minY,
+          Math.min(b.maxY, barDrag.startT - dy * barDrag.ratio)
+        );
       } else {
         const dx = e.clientX - barDrag.startPointer;
         const b = getBounds();
-        tx = Math.max(b.minX, Math.min(b.maxX, barDrag.startT - dx * barDrag.ratio));
+        tx = Math.max(
+          b.minX,
+          Math.min(b.maxX, barDrag.startT - dx * barDrag.ratio)
+        );
       }
       apply();
     }
@@ -226,8 +235,10 @@ export function useInertiaPanzoom(options = {}) {
       return { minX, maxX, minY, maxY };
     }
     function rubberBandAxis(v, min, max, dim) {
-      if (v < min) return min - (1 - 1 / ((min - v) * RUBBER_BAND_C / dim + 1)) * dim;
-      if (v > max) return max + (1 - 1 / ((v - max) * RUBBER_BAND_C / dim + 1)) * dim;
+      if (v < min)
+        return min - (1 - 1 / ((min - v) * RUBBER_BAND_C / dim + 1)) * dim;
+      if (v > max)
+        return max + (1 - 1 / ((v - max) * RUBBER_BAND_C / dim + 1)) * dim;
       return v;
     }
     function stopMomentum() {
@@ -320,7 +331,10 @@ export function useInertiaPanzoom(options = {}) {
         const dist = Math.hypot(pts[0].x - pts[1].x, pts[0].y - pts[1].y);
         const midX = (pts[0].x + pts[1].x) / 2;
         const midY = (pts[0].y + pts[1].y) / 2;
-        const newScale = Math.max(minScale, Math.min(maxScale, pinchStart.s * (dist / pinchStart.dist)));
+        const newScale = Math.max(
+          minScale,
+          Math.min(maxScale, pinchStart.s * (dist / pinchStart.dist))
+        );
         const rect = parent.getBoundingClientRect();
         const focalX = (pinchStart.midX - rect.left - pinchStart.tx) / pinchStart.s;
         const focalY = (pinchStart.midY - rect.top - pinchStart.ty) / pinchStart.s;
@@ -386,7 +400,10 @@ export function useInertiaPanzoom(options = {}) {
       const mx = e.clientX - rect.left;
       const my = e.clientY - rect.top;
       const delta = e.deltaY < 0 ? 1 : -1;
-      const newScale = Math.max(minScale, Math.min(maxScale, scale * Math.exp(delta * 0.1)));
+      const newScale = Math.max(
+        minScale,
+        Math.min(maxScale, scale * Math.exp(delta * 0.1))
+      );
       const focalX = (mx - tx) / scale;
       const focalY = (my - ty) / scale;
       tx = mx - newScale * focalX;
@@ -398,7 +415,8 @@ export function useInertiaPanzoom(options = {}) {
     }
     function setTransform(t) {
       stopMomentum();
-      if (t.scale !== void 0) scale = Math.max(minScale, Math.min(maxScale, t.scale));
+      if (t.scale !== void 0)
+        scale = Math.max(minScale, Math.min(maxScale, t.scale));
       if (t.tx !== void 0) tx = t.tx;
       if (t.ty !== void 0) ty = t.ty;
       const b = getBounds();
@@ -424,9 +442,15 @@ export function useInertiaPanzoom(options = {}) {
     function scrollBy(dx, dy) {
       stopMomentum();
       const b = getBounds();
+      const before = { scale, tx, ty };
       tx = Math.max(b.minX, Math.min(b.maxX, tx - dx));
       ty = Math.max(b.minY, Math.min(b.maxY, ty - dy));
       apply();
+      return getUnconsumedScrollDelta({ x: dx, y: dy }, before, {
+        scale,
+        tx,
+        ty
+      });
     }
     parent.addEventListener("pointerdown", onDown);
     parent.addEventListener("pointermove", onMove);
@@ -504,7 +528,7 @@ export function useInertiaPanzoom(options = {}) {
     getScale: () => controller?.getScale() ?? 1,
     getTransform: () => controller?.getTransform() ?? { scale: 1, tx: 0, ty: 0 },
     scrollToElement: (elem, opts) => controller?.scrollToElement(elem, opts),
-    scrollBy: (dx, dy) => controller?.scrollBy(dx, dy),
+    scrollBy: (dx, dy) => controller?.scrollBy(dx, dy) ?? { x: dx, y: dy },
     setGesturesEnabled: (enabled) => controller?.setGesturesEnabled(enabled),
     setTransform: (t) => controller?.setTransform(t),
     setScaleLimits: (min, max) => {