kviewer 0.2.0 → 0.2.2

package/dist/runtime/components/Viewer.vue

@@ -2,7 +2,11 @@
   <div ref="viewerRoot" class="flex flex-col h-full">
     <!-- Header slot: defaults to ViewerBar -->
     <slot name="header">
-      <ViewerBar :menu-items="props.menuItems" />
+      <ViewerBar :menu-items="props.menuItems" :tools="props.tools">
+        <template v-for="name in toolSlotNames" :key="name" #[name]="scope">
+          <slot :name="name" v-bind="scope" />
+        </template>
+      </ViewerBar>
     </slot>
 
     <div class="flex flex-1 min-h-0">
@@ -61,6 +65,7 @@
                     :page-number="singlePageMeta.pageNumber"
                     :page-meta="singlePageMeta"
                     :scale="pageScale"
+                    :view-window="pageViewWindow(singlePageMeta.pageNumber)"
                   />
                 </div>
               </div>
@@ -89,6 +94,7 @@
                     :page-number="meta.pageNumber"
                     :page-meta="meta"
                     :scale="pageScale"
+                    :view-window="pageViewWindow(meta.pageNumber)"
                   />
                 </div>
               </div>
@@ -122,6 +128,7 @@
                       :page-number="meta.pageNumber"
                       :page-meta="meta"
                       :scale="pageScale"
+                      :view-window="pageViewWindow(meta.pageNumber)"
                     />
                   </div>
                 </div>
@@ -133,6 +140,10 @@
 
       <ClientOnly>
         <FloatingPageIndicator :scroll-container="scrollContainer" />
+        <!-- Debug overlay for on-device profiling; renders only with
+             ?perf in the URL. Gated on `active` so tabbed hosts show a
+             single instance. -->
+        <PerfHud v-if="props.active" />
       </ClientOnly>
       </div>
 
@@ -181,14 +192,17 @@ import {
   nextTick,
   triggerRef,
   onMounted,
-  onBeforeUnmount
+  onBeforeUnmount,
+  useSlots
 } from "vue";
+import { useRuntimeConfig } from "#imports";
 import ViewerBar from "./ViewerBar.vue";
 import PdfPage from "./PdfPage.vue";
 import FreeTextModal from "./modals/FreeTextModal.vue";
 import PlacedFieldSidebar from "./panels/PlacedFieldSidebar.vue";
 import AnnotationToolbar from "./AnnotationToolbar.vue";
 import FloatingPageIndicator from "./FloatingPageIndicator.vue";
+import PerfHud from "./PerfHud.vue";
 import { providePageSettings } from "../composables/usePageSettings";
 import { mapViewModeToFitMode, normalizeZoom, provideViewerState } from "../composables/useViewerState";
 import { provideViewerSearch } from "../composables/useViewerSearch";
@@ -206,11 +220,13 @@ import { createPageProxyCache } from "../composables/usePageProxyCache";
 import { createSearchIndex } from "../composables/useSearchIndex";
 import { createShapeDetection } from "../composables/useShapeDetection";
 import { provideFormFields } from "../composables/useFormFields";
-import { extractCheckboxStyles, extractButtonCaptions } from "../annotation/parsers/extractCheckboxStyles";
+import { extractCheckboxStyles, extractButtonCaptions, extractSignedSignatureNames } from "../annotation/parsers/extractCheckboxStyles";
 import { isIPad } from "../annotation/engine/input-device";
 import { useInertiaPanzoom } from "../composables/useInertiaPanzoom";
 import { createScriptingManager } from "../composables/useScriptingManager";
 import { createScriptingBridge } from "../composables/useScriptingBridge";
+import { provideKviewerI18n } from "../composables/useKviewerI18n";
+import { KVIEWER_LOCALES } from "../i18n/messages";
 const props = defineProps({
   source: { type: null, required: true },
   textLayer: { type: Boolean, required: false },
@@ -227,12 +243,19 @@ const props = defineProps({
   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 }
+  menuItems: { type: Array, required: false, default: void 0 },
+  tools: { type: Array, required: false, default: void 0 },
+  locale: { type: null, required: false, default: void 0 },
+  messages: { type: Object, required: false, default: void 0 }
 });
-const emit = defineEmits(["update:formEditMode", "update:activeRoleId"]);
+const slots = useSlots();
+const toolSlotNames = computed(
+  () => Object.keys(slots).filter((name) => name.startsWith("tool-"))
+);
+const emit = defineEmits(["update:formEditMode", "update:activeRoleId", "update:viewedPages", "all-pages-read"]);
 const viewerRoot = ref(null);
 const scrollContainer = ref(null);
-const { state: viewerState, setScrollToPageFn, setDownloadPdfFn } = provideViewerState();
+const { state: viewerState, setScrollToPageFn, setDownloadPdfFn, setApplyScaleFn } = provideViewerState();
 watchEffect(() => {
   viewerState.readonly.value = props.readonly ?? false;
 });
@@ -255,6 +278,14 @@ watch(
 );
 const viewerSearch = provideViewerSearch();
 const formFieldsState = provideFormFields();
+const kviewerPublicConfig = useRuntimeConfig().public.kviewer;
+provideKviewerI18n(
+  computed(() => {
+    const candidate = props.locale ?? kviewerPublicConfig?.locale ?? "en";
+    return KVIEWER_LOCALES.includes(candidate) ? candidate : "en";
+  }),
+  computed(() => props.messages ?? {})
+);
 watch(
   () => props.roleColors,
   (v) => {
@@ -295,6 +326,7 @@ const proxyCache = createPageProxyCache();
 const searchIndex = createSearchIndex();
 const shapeDetectionCache = createShapeDetection();
 const doc = shallowRef(null);
+let destroyActiveDoc = null;
 let painter = null;
 let scriptingManager = null;
 let scriptingBridge = null;
@@ -306,6 +338,31 @@ watch(
     viewerState.currentPage.value = page;
   }
 );
+watch(
+  () => viewerState.currentPage.value,
+  (page) => virtualization.markPageViewed(page),
+  { immediate: true }
+);
+watch(
+  () => pageMetas.value.length,
+  (len) => {
+    if (len > 0 && !isSinglePageMode.value) {
+      nextTick(() => virtualization.updateCurrentPageByRect());
+    }
+  }
+);
+watch(
+  virtualization.allPagesRead,
+  (read, prev) => {
+    if (read && !prev) emit("all-pages-read");
+  }
+);
+watch(
+  virtualization.viewedPages,
+  (pages) => {
+    emit("update:viewedPages", [...pages].sort((a, b) => a - b));
+  }
+);
 function onPageRef(pageNumber, el) {
   if (el) {
     virtualization.observePage(pageNumber, el);
@@ -328,6 +385,116 @@ const isRotatedSideways = computed(() => {
 });
 const zoomWrapper = ref(null);
 const inertiaPanzoom = useInertiaPanzoom({ minScale: 0.5, maxScale: 4 });
+const MIN_ZOOM = 0.25;
+const MAX_ZOOM = 4;
+let suppressScaleReset = false;
+async function commitZoom(target) {
+  const s0 = viewerState.scale.value;
+  target = Math.min(Math.max(MAX_ZOOM, s0), Math.max(Math.min(MIN_ZOOM, s0), target));
+  const viewportEl = zoomWrapper.value?.parentElement ?? null;
+  const anchor = virtualization.getPageElement(viewerState.currentPage.value);
+  const visual = inertiaPanzoom.getScale();
+  if (target === viewerState.scale.value && Math.abs(visual - 1) < 5e-3) return;
+  if (!viewportEl || !anchor || !anchor.isConnected) {
+    viewerState.fitMode.value = "custom";
+    viewerState.scale.value = target;
+    return;
+  }
+  const vpRect = viewportEl.getBoundingClientRect();
+  const fx = vpRect.width / 2;
+  const fy = vpRect.height / 2;
+  const aRect = anchor.getBoundingClientRect();
+  const qx = (vpRect.left + fx - aRect.left) / aRect.width;
+  const qy = (vpRect.top + fy - aRect.top) / aRect.height;
+  suppressScaleReset = target !== viewerState.scale.value;
+  viewerState.fitMode.value = "custom";
+  viewerState.scale.value = target;
+  await nextTick();
+  const t = inertiaPanzoom.getTransform();
+  const vp2 = viewportEl.getBoundingClientRect();
+  const a2 = anchor.getBoundingClientRect();
+  const layoutLeft = (a2.left - vp2.left - t.tx) / t.scale;
+  const layoutTop = (a2.top - vp2.top - t.ty) / t.scale;
+  const layoutW = a2.width / t.scale;
+  const layoutH = a2.height / t.scale;
+  inertiaPanzoom.setTransform({
+    scale: 1,
+    tx: fx - (layoutLeft + qx * layoutW),
+    ty: fy - (layoutTop + qy * layoutH)
+  });
+  viewWindows.value = {};
+  computeViewWindows();
+}
+setApplyScaleFn((value) => {
+  void commitZoom(value);
+});
+watch(
+  () => viewerState.scale.value,
+  (s) => inertiaPanzoom.setScaleLimits(
+    Math.min(1, MIN_ZOOM / s),
+    Math.max(1, MAX_ZOOM / s)
+  ),
+  { immediate: true }
+);
+inertiaPanzoom.onZoomEnd((visual) => {
+  if (Math.abs(visual - 1) < 5e-3) return;
+  void commitZoom(viewerState.scale.value * visual);
+});
+const viewWindows = shallowRef({});
+const VIEW_WINDOW_MARGIN = 0.25;
+function computeViewWindows() {
+  const viewportEl = zoomWrapper.value?.parentElement;
+  if (!viewportEl) return;
+  const vpRect = viewportEl.getBoundingClientRect();
+  if (vpRect.width === 0 || vpRect.height === 0) return;
+  const prev = viewWindows.value;
+  const next = {};
+  let changed = false;
+  for (const meta of pageMetas.value) {
+    const el = virtualization.getPageElement(meta.pageNumber);
+    if (!el) continue;
+    const r = el.getBoundingClientRect();
+    if (r.width === 0 || el.offsetWidth === 0) continue;
+    const k = r.width / el.offsetWidth;
+    const vx = (Math.max(vpRect.left, r.left) - r.left) / k;
+    const vy = (Math.max(vpRect.top, r.top) - r.top) / k;
+    const vr = (Math.min(vpRect.right, r.right) - r.left) / k;
+    const vb = (Math.min(vpRect.bottom, r.bottom) - r.top) / k;
+    if (vr <= vx || vb <= vy) continue;
+    const old = prev[meta.pageNumber];
+    if (old && vx >= old.x && vy >= old.y && vr <= old.x + old.width && vb <= old.y + old.height) {
+      next[meta.pageNumber] = old;
+      continue;
+    }
+    const mx = vpRect.width / k * VIEW_WINDOW_MARGIN;
+    const my = vpRect.height / k * VIEW_WINDOW_MARGIN;
+    next[meta.pageNumber] = {
+      x: vx - mx,
+      y: vy - my,
+      width: vr - vx + 2 * mx,
+      height: vb - vy + 2 * my
+    };
+    changed = true;
+  }
+  if (changed || Object.keys(next).length !== Object.keys(prev).length) {
+    viewWindows.value = next;
+  }
+}
+let viewWindowTimer = 0;
+let lastViewWindowUpdate = 0;
+inertiaPanzoom.onChange(() => {
+  const now = performance.now();
+  const wait = Math.max(0, 250 - (now - lastViewWindowUpdate));
+  clearTimeout(viewWindowTimer);
+  viewWindowTimer = window.setTimeout(() => {
+    lastViewWindowUpdate = performance.now();
+    computeViewWindows();
+  }, wait);
+});
+function pageViewWindow(pageNumber) {
+  if (pageSettings.rotation.value !== 0) return null;
+  return viewWindows.value[pageNumber] ?? null;
+}
 function pageSlotStyle(meta) {
   const s = pageScale.value;
   if (isRotatedSideways.value) {
@@ -424,26 +591,36 @@ async function loadDocument() {
     }
     const source = props.source;
     const baseParams = source instanceof Uint8Array || typeof source === "string" ? { url: typeof source === "string" ? source : void 0, data: source instanceof Uint8Array ? source : void 0 } : { ...source };
+    if (baseParams.data instanceof Uint8Array) {
+      baseParams.data = baseParams.data.slice();
+    } else if (baseParams.data instanceof ArrayBuffer) {
+      baseParams.data = baseParams.data.slice(0);
+    }
     const docParams = {
       ...baseParams,
       standardFontDataUrl: "/_kviewer/standard_fonts/",
       cMapUrl: "/_kviewer/cmaps/",
       cMapPacked: true,
-      useSystemFonts: true
+      useSystemFonts: true,
+      wasmUrl: "/_kviewer/wasm/",
+      iccUrl: "/_kviewer/iccs/"
     };
     const loadingTask = pdfjs.getDocument(docParams);
+    destroyActiveDoc = () => loadingTask.destroy();
     const pdfDoc = await loadingTask.promise;
     doc.value = pdfDoc;
     viewerState.doc.value = pdfDoc;
     viewerState.totalPages.value = pdfDoc.numPages;
     proxyCache.setDocument(pdfDoc);
     pdfDoc.getData().then(async (bytes) => {
-      const [styles, captions] = await Promise.all([
+      const [styles, captions, signedSigs] = await Promise.all([
         extractCheckboxStyles(bytes),
-        extractButtonCaptions(bytes)
+        extractButtonCaptions(bytes),
+        extractSignedSignatureNames(bytes)
       ]);
       if (styles.size > 0) formFieldsState.applyCheckboxStyles(styles);
       if (captions.size > 0) formFieldsState.applyButtonCaptions(captions);
+      if (signedSigs.size > 0) formFieldsState.applySignedSignatures(signedSigs);
     }).catch((err) => console.warn("[KViewer] Failed to read MK data from source PDF:", err));
     if (!scrollContainer.value) {
       await nextTick();
@@ -794,10 +971,18 @@ onMounted(() => {
       { immediate: true }
     );
     watch(() => viewerState.scale.value, async () => {
+      if (suppressScaleReset) {
+        suppressScaleReset = false;
+        return;
+      }
       await nextTick();
       inertiaPanzoom.reset();
+      viewWindows.value = {};
+      computeViewWindows();
+    });
+    watch(() => viewerState.currentPage.value, () => {
+      if (isSinglePageMode.value) inertiaPanzoom.reset();
     });
-    watch(() => viewerState.currentPage.value, () => inertiaPanzoom.reset());
   }
   if (isIPad()) {
     viewerState.setStylusMode(true);
@@ -818,7 +1003,7 @@ watch(
     searchIndex.destroy();
     virtualization.destroy();
     proxyCache.clear();
-    doc.value?.destroy();
+    void destroyActiveDoc?.();
     loadDocument();
   }
 );
@@ -850,6 +1035,7 @@ watch(
 );
 onBeforeUnmount(() => {
   window.removeEventListener("keydown", onGlobalKeydown);
+  clearTimeout(viewWindowTimer);
   scrollContainer.value?.removeEventListener("wheel", onWheel);
   inertiaPanzoom.detach();
   resizeObserver?.disconnect();
@@ -864,7 +1050,8 @@ onBeforeUnmount(() => {
   virtualization.destroy();
   proxyCache.clear();
   painter?.destroy();
-  doc.value?.destroy();
+  void destroyActiveDoc?.();
+  destroyActiveDoc = null;
 });
 defineExpose({
   getAnnotations: () => painter?.getData() ?? [],
@@ -892,7 +1079,15 @@ defineExpose({
     const next = !viewerState.formEditMode.value;
     viewerState.setFormEditMode(next);
     return next;
-  }
+  },
+  /** True once the user has viewed every page — each page has entered the
+   *  viewport at least once. Use to gate a "must read all pages" sign action.
+   *  See also the `all-pages-read` event for a push-style signal. */
+  allPagesRead: () => virtualization.allPagesRead.value,
+  /** Page numbers viewed so far, ascending. */
+  getViewedPages: () => [...virtualization.viewedPages.value].sort((a, b) => a - b),
+  /** Clear viewed-page tracking, e.g. to restart a signing session. */
+  resetViewedPages: () => virtualization.resetViewedPages()
 });
 </script>
 

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

@@ -2,6 +2,9 @@ import { type ViewMode } from '../composables/useViewerState.js';
 import type { AddFormFieldPayload, FormFieldDefinition, IAnnotationStore, StampDefinition, SignatureHandlers } from '../annotation/engine/types.js';
 import { type ExportPdfOptions } from '../annotation/pdf-export/export.js';
 import type { ViewerMenuItem } from '../menu-items.js';
+import type { ViewerToolEntry } from '../toolbar-tools.js';
+import { type KviewerMessageOverrides } from '../composables/useKviewerI18n.js';
+import { type KviewerLocale } from '../i18n/messages.js';
 type __VLS_Props = {
     source: string | Uint8Array | object;
     textLayer?: boolean;
@@ -45,6 +48,19 @@ type __VLS_Props = {
      *  toggles or actions without replacing the entire header. Ignored
      *  when the host supplies a custom `#header` slot. */
     menuItems?: ViewerMenuItem[];
+    /** Configures which toolbar tools render and in what order. Entries are
+     *  built-in tool IDs (strings) or `{ type: 'slot', ... }` objects that
+     *  inject a custom button via a `#tool-<name>` slot. When omitted, the
+     *  default toolbar is rendered unchanged. Ignored when the host supplies
+     *  a custom `#header` slot. See {@link ViewerToolEntry}. */
+    tools?: ViewerToolEntry[];
+    /** UI language for built-in viewer strings (toolbar, search, modals,
+     *  form sidebar). Defaults to the `kviewer.locale` module option, then
+     *  'en'. Hosts with their own i18n just bind their active locale. */
+    locale?: KviewerLocale;
+    /** Per-string overrides for built-in messages — wins over the locale
+     *  catalog. Useful for app-specific wording without forking locales. */
+    messages?: KviewerMessageOverrides;
 };
 declare function exportPdf(options?: ExportPdfOptions): Promise<Uint8Array>;
 type ImportMode = 'replace' | 'merge';
@@ -55,11 +71,15 @@ declare function importAnnotations(annotations: IAnnotationStore[], options?: {
     skipped: number;
 }>;
 declare function getKonvaCanvasState(): Record<number, string>;
-declare var __VLS_1: {}, __VLS_51: {};
+declare var __VLS_1: {}, __VLS_11: string, __VLS_12: {
+    state: import("../composables/useViewerState.js").ViewerState;
+}, __VLS_62: {};
 type __VLS_Slots = {} & {
+    [K in NonNullable<typeof __VLS_11>]?: (props: typeof __VLS_12) => any;
+} & {
     header?: (props: typeof __VLS_1) => any;
 } & {
-    footer?: (props: typeof __VLS_51) => any;
+    footer?: (props: typeof __VLS_62) => any;
 };
 declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     getAnnotations: () => IAnnotationStore[];
@@ -84,12 +104,24 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     setFormEditMode: (enabled: boolean) => void;
     /** Flip form-edit mode. Returns the new state. */
     toggleFormEditMode: () => boolean;
+    /** True once the user has viewed every page — each page has entered the
+     *  viewport at least once. Use to gate a "must read all pages" sign action.
+     *  See also the `all-pages-read` event for a push-style signal. */
+    allPagesRead: () => boolean;
+    /** Page numbers viewed so far, ascending. */
+    getViewedPages: () => number[];
+    /** Clear viewed-page tracking, e.g. to restart a signing session. */
+    resetViewedPages: () => void;
 }, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "all-pages-read": () => any;
     "update:formEditMode": (value: boolean) => any;
     "update:activeRoleId": (value: string | null) => any;
+    "update:viewedPages": (pages: number[]) => any;
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    "onAll-pages-read"?: (() => any) | undefined;
     "onUpdate:formEditMode"?: ((value: boolean) => any) | undefined;
     "onUpdate:activeRoleId"?: ((value: string | null) => any) | undefined;
+    "onUpdate:viewedPages"?: ((pages: number[]) => any) | undefined;
 }>, {
     userName: string;
     freehandGroupingDelay: number;
@@ -97,6 +129,7 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     readonly: boolean;
     active: boolean;
     menuItems: ViewerMenuItem[];
+    tools: ViewerToolEntry[];
     scripting: boolean;
     stamps: StampDefinition[];
     signatureHandlers: SignatureHandlers;
@@ -105,6 +138,8 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     formEditMode: boolean;
     roleColors: Record<string, string>;
     activeRoleId: string | null;
+    locale: KviewerLocale;
+    messages: KviewerMessageOverrides;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
 declare const _default: typeof __VLS_export;

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

@@ -1,9 +1,29 @@
 import type { ViewerMenuItem } from '../menu-items.js';
+import { type ViewerToolEntry } from '../toolbar-tools.js';
 type __VLS_Props = {
     /** Extra items appended to the burger menu after the built-ins.
      *  See {@link ViewerMenuItem}. Pure forwarding from `<KViewer>`. */
     menuItems?: ViewerMenuItem[];
+    /** Configures which toolbar tools render and in what order. When
+     *  omitted, the default toolbar is rendered. See {@link ViewerToolEntry}. */
+    tools?: ViewerToolEntry[];
 };
-declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare var __VLS_109: string, __VLS_110: {
+    state: import("../composables/useViewerState.js").ViewerState;
+}, __VLS_154: string, __VLS_155: {
+    state: import("../composables/useViewerState.js").ViewerState;
+};
+type __VLS_Slots = {} & {
+    [K in NonNullable<typeof __VLS_109>]?: (props: typeof __VLS_110) => any;
+} & {
+    [K in NonNullable<typeof __VLS_154>]?: (props: typeof __VLS_155) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
 declare const _default: typeof __VLS_export;
 export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};