kviewer 0.3.5 → 0.3.6

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "kviewer",
   "configKey": "kviewer",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

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

@@ -1,4 +1,5 @@
 import { type ViewMode } from '../composables/useViewerState.js';
+import type { ScrollBoundaryPayload } from '../embed/protocol.js';
 import type { AddFormFieldPayload, FormFieldDefinition, IAnnotationStore, PlacedFieldDefaults, SignatureFieldStatus, StampDefinition, SignatureHandlers } from '../annotation/engine/types.js';
 import { type ExportPdfOptions } from '../annotation/pdf-export/export.js';
 import type { ViewerMenuItem } from '../menu-items.js';
@@ -154,6 +155,9 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
         allSigned: boolean;
         fields: SignatureFieldStatus[];
     }) => void) => (() => void);
+    /** Subscribe to vertical wheel movement left over when the viewer reaches
+     *  a document boundary. Used by the embed bridge for parent scrolling. */
+    onScrollBoundary: (cb: (payload: ScrollBoundaryPayload) => void) => (() => void);
     /** Reactive form-edit-mode flag — read with `.value`. */
     formEditMode: import("vue").Ref<boolean, boolean>;
     /** Programmatically enter or leave form-edit mode. */

package/dist/runtime/components/Viewer.vue

@@ -263,6 +263,7 @@ const fieldPlacedCallbacks = /* @__PURE__ */ new Set();
 const signedStatusCallbacks = /* @__PURE__ */ new Set();
 const fieldUpdatedCallbacks = /* @__PURE__ */ new Set();
 const fieldRemovedCallbacks = /* @__PURE__ */ new Set();
+const scrollBoundaryCallbacks = /* @__PURE__ */ new Set();
 const viewerRoot = ref(null);
 const scrollContainer = ref(null);
 const { state: viewerState, setScrollToPageFn, setDownloadPdfFn, setPrintPdfFn, setApplyScaleFn } = provideViewerState();
@@ -864,28 +865,43 @@ function initPanzoom() {
   inertiaPanzoom.attach(zoomWrapper.value);
 }
 let wheelCooldown = false;
+function notifyScrollBoundary(deltaY) {
+  if (deltaY === 0) return;
+  const payload = {
+    edge: deltaY > 0 ? "end" : "start",
+    deltaY
+  };
+  for (const callback of scrollBoundaryCallbacks) callback(payload);
+}
 function onWheel(event) {
   if (event.ctrlKey || event.metaKey) return;
   if (isSinglePageMode.value) {
     event.preventDefault();
-    if (wheelCooldown) return;
+    const total = viewerState.totalPages.value;
+    const cur = viewerState.currentPage.value;
+    const isAtBoundary = event.deltaY > 0 && cur >= total || event.deltaY < 0 && cur <= 1;
+    if (wheelCooldown) {
+      if (isAtBoundary) notifyScrollBoundary(event.deltaY);
+      return;
+    }
     wheelCooldown = true;
     setTimeout(() => {
       wheelCooldown = false;
     }, 300);
-    const total = viewerState.totalPages.value;
-    const cur = viewerState.currentPage.value;
     if (event.deltaY > 0 && cur < total) {
       viewerState.currentPage.value = cur + 1;
     } else if (event.deltaY < 0 && cur > 1) {
       viewerState.currentPage.value = cur - 1;
+    } else {
+      notifyScrollBoundary(event.deltaY);
     }
     return;
   }
   event.preventDefault();
   const dx = event.shiftKey ? event.deltaY : event.deltaX;
   const dy = event.shiftKey ? 0 : event.deltaY;
-  inertiaPanzoom.scrollBy(dx, dy);
+  const remaining = inertiaPanzoom.scrollBy(dx, dy);
+  notifyScrollBoundary(remaining.y);
 }
 function isTextInputTarget(target) {
   if (!(target instanceof HTMLElement)) return false;
@@ -1181,6 +1197,12 @@ defineExpose({
     signedStatusCallbacks.add(cb);
     return () => signedStatusCallbacks.delete(cb);
   },
+  /** Subscribe to vertical wheel movement left over when the viewer reaches
+   *  a document boundary. Used by the embed bridge for parent scrolling. */
+  onScrollBoundary: (cb) => {
+    scrollBoundaryCallbacks.add(cb);
+    return () => scrollBoundaryCallbacks.delete(cb);
+  },
   /** Reactive form-edit-mode flag — read with `.value`. */
   formEditMode: viewerState.formEditMode,
   /** Programmatically enter or leave form-edit mode. */

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

@@ -1,4 +1,5 @@
 import { type ViewMode } from '../composables/useViewerState.js';
+import type { ScrollBoundaryPayload } from '../embed/protocol.js';
 import type { AddFormFieldPayload, FormFieldDefinition, IAnnotationStore, PlacedFieldDefaults, SignatureFieldStatus, StampDefinition, SignatureHandlers } from '../annotation/engine/types.js';
 import { type ExportPdfOptions } from '../annotation/pdf-export/export.js';
 import type { ViewerMenuItem } from '../menu-items.js';
@@ -154,6 +155,9 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
         allSigned: boolean;
         fields: SignatureFieldStatus[];
     }) => void) => (() => void);
+    /** Subscribe to vertical wheel movement left over when the viewer reaches
+     *  a document boundary. Used by the embed bridge for parent scrolling. */
+    onScrollBoundary: (cb: (payload: ScrollBoundaryPayload) => void) => (() => void);
     /** Reactive form-edit-mode flag — read with `.value`. */
     formEditMode: import("vue").Ref<boolean, boolean>;
     /** Programmatically enter or leave form-edit mode. */

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) => {

package/dist/runtime/embed/bridge-client.d.ts

@@ -22,7 +22,7 @@ type EventHandler<E extends EventName> = (payload: EventPayloads[E]) => void;
  * viewer's exposed methods, and surfaces iframe-emitted events
  * (`ready`, `formEditMode-changed`, `viewedPages-changed`, `all-pages-read`,
  * `field-placed`, `field-updated`, `field-removed`, `signedStatus-changed`)
- * via `on()`.
+ * and `scroll-boundary`) via `on()`.
  */
 export declare class KViewerEmbedClient {
     private readonly iframe;

package/dist/runtime/embed/bridge-host.d.ts

@@ -1,7 +1,7 @@
 import { type Ref } from 'vue';
 import type { ExportPdfOptions } from '../annotation/pdf-export/export.js';
 import type { AddFormFieldPayload, FormFieldDefinition, FormFieldValue, IAnnotationStore, PlacedFieldDefaults, SignatureFieldStatus } from '../annotation/engine/types.js';
-import { type MethodName } from './protocol.js';
+import { type MethodName, type ScrollBoundaryPayload } from './protocol.js';
 /**
  * Surface the bridge calls on the KViewer template ref. Mirrors the
  * methods defined in `defineExpose` inside Viewer.vue. Kept as a
@@ -35,6 +35,7 @@ export interface KViewerApi {
         allSigned: boolean;
         fields: SignatureFieldStatus[];
     }) => void) => () => void;
+    onScrollBoundary: (cb: (payload: ScrollBoundaryPayload) => void) => () => void;
     formEditMode: boolean | Ref<boolean>;
     setFormEditMode: (enabled: boolean) => void;
     toggleFormEditMode: () => boolean;

package/dist/runtime/embed/bridge-host.js

@@ -226,6 +226,14 @@ export function useKViewerEmbedBridge(viewerRef, options) {
           )
         );
       }
+      if (typeof viewer.onScrollBoundary === "function") {
+        events.push("scroll-boundary");
+        stopViewerStateWatches.push(
+          viewer.onScrollBoundary(
+            (payload) => postEvent("scroll-boundary", payload)
+          )
+        );
+      }
       if (typeof viewer.allPagesRead === "function") {
         events.push("all-pages-read");
         stopViewerStateWatches.push(

package/dist/runtime/embed/protocol.d.ts

@@ -11,6 +11,10 @@ export declare const EVENT_KIND: "kviewer:event";
  */
 export declare const UNSUPPORTED_METHOD_ERROR_NAME = "KViewerUnsupportedMethodError";
 export type ImportAnnotationsMode = 'replace' | 'merge';
+export interface ScrollBoundaryPayload {
+    edge: 'start' | 'end';
+    deltaY: number;
+}
 export interface MethodSignatures {
     getAnnotations: {
         args: [];
@@ -145,6 +149,9 @@ export interface EventPayloads {
     /** Fires once when the final unseen page is viewed. Re-arms after
      *  `resetViewedPages()` or a new document. */
     'all-pages-read': Record<string, never>;
+    /** Vertical wheel movement that the embedded viewer could not consume
+     *  because it reached the start or end of the document. */
+    'scroll-boundary': ScrollBoundaryPayload;
     /** The user placed a form field via a placement tool. Patch it with
      *  `updateFormField()` to set host-driven properties. */
     'field-placed': {

package/dist/runtime/public-types.d.ts

@@ -7,7 +7,7 @@ export type { KViewerApi, KViewerHostApi, KViewerEmbedBridgeOptions, } from './e
 export { useKViewerEmbedBridge } from './embed/bridge-host.js';
 export type { KViewerEmbedClientOptions } from './embed/bridge-client.js';
 export { KViewerEmbedClient } from './embed/bridge-client.js';
-export type { EventName as KViewerEmbedEventName, EventPayloads as KViewerEmbedEventPayloads, MethodName as KViewerEmbedMethodName, } from './embed/protocol.js';
+export type { EventName as KViewerEmbedEventName, EventPayloads as KViewerEmbedEventPayloads, MethodName as KViewerEmbedMethodName, ScrollBoundaryPayload, } from './embed/protocol.js';
 export { KVIEWER_EMBED_PROTOCOL_VERSION, UNSUPPORTED_METHOD_ERROR_NAME as KVIEWER_EMBED_UNSUPPORTED_METHOD_ERROR_NAME, } from './embed/protocol.js';
 export type { ViewerMenuItem, ViewerMenuButtonItem, ViewerMenuCheckboxItem, ViewerMenuSeparatorItem, } from './menu-items.js';
 export type { ViewerSelectionItem, ViewerSelectionButtonItem, ViewerSelectionSelectItem, ViewerSelectionContext, } from './selection-items.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kviewer",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "Kabema PDF Editor",
   "repository": "kabema/kviewer",
   "license": "MIT",