kviewer 0.0.11 → 0.1.1

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

@@ -0,0 +1,143 @@
+import {
+  KVIEWER_EMBED_PROTOCOL_VERSION,
+  REQUEST_KIND,
+  isEvent,
+  isResponse
+} from "./protocol.js";
+let nextRequestId = 0;
+function makeRequestId() {
+  nextRequestId += 1;
+  return `kvr-${Date.now().toString(36)}-${nextRequestId.toString(36)}`;
+}
+export class KViewerEmbedClient {
+  iframe;
+  options;
+  win;
+  allowAny;
+  pending = /* @__PURE__ */ new Map();
+  handlers = /* @__PURE__ */ new Map();
+  disposed = false;
+  constructor(iframe, options) {
+    this.iframe = iframe;
+    this.options = options;
+    this.allowAny = options.iframeOrigin === "*";
+    const win = options.windowRef ?? (typeof window !== "undefined" ? window : void 0);
+    if (!win) {
+      throw new Error("KViewerEmbedClient requires a window (browser environment)");
+    }
+    this.win = win;
+    this.win.addEventListener("message", this.handleMessage);
+  }
+  /** Tear down the message listener and reject any in-flight requests. */
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.win.removeEventListener("message", this.handleMessage);
+    const err = new Error("KViewerEmbedClient was disposed");
+    for (const { reject } of this.pending.values()) reject(err);
+    this.pending.clear();
+    this.handlers.clear();
+  }
+  /** Subscribe to an iframe-emitted event. Returns an unsubscribe fn. */
+  on(name, handler) {
+    let set = this.handlers.get(name);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.handlers.set(name, set);
+    }
+    set.add(handler);
+    return () => {
+      set?.delete(handler);
+    };
+  }
+  // ── method mirrors ─────────────────────────────────────────────────────
+  getAnnotations() {
+    return this.call("getAnnotations");
+  }
+  importAnnotations(annotations, options) {
+    return this.call("importAnnotations", annotations, options);
+  }
+  exportPdf(options) {
+    return this.call("exportPdf", options);
+  }
+  getFormFieldValues() {
+    return this.call("getFormFieldValues");
+  }
+  setFormFieldValue(fieldName, value) {
+    return this.call("setFormFieldValue", fieldName, value);
+  }
+  addFormField(payload) {
+    return this.call("addFormField", payload);
+  }
+  updateFormField(id, patch) {
+    return this.call("updateFormField", id, patch);
+  }
+  removeFormField(id) {
+    return this.call("removeFormField", id);
+  }
+  getFormFields() {
+    return this.call("getFormFields");
+  }
+  getFormEditMode() {
+    return this.call("getFormEditMode");
+  }
+  setFormEditMode(enabled) {
+    return this.call("setFormEditMode", enabled);
+  }
+  toggleFormEditMode() {
+    return this.call("toggleFormEditMode");
+  }
+  // ── internals ──────────────────────────────────────────────────────────
+  call(method, ...args) {
+    if (this.disposed) {
+      return Promise.reject(new Error("KViewerEmbedClient was disposed"));
+    }
+    const target = this.iframe.contentWindow;
+    if (!target) {
+      return Promise.reject(new Error("iframe has no contentWindow"));
+    }
+    const id = makeRequestId();
+    const message = {
+      kind: REQUEST_KIND,
+      v: KVIEWER_EMBED_PROTOCOL_VERSION,
+      id,
+      method,
+      args
+    };
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, {
+        resolve,
+        reject
+      });
+      target.postMessage(message, this.options.iframeOrigin);
+    });
+  }
+  handleMessage = (event) => {
+    if (!this.allowAny && event.origin !== this.options.iframeOrigin) return;
+    if (event.source !== this.iframe.contentWindow) return;
+    if (isResponse(event.data)) {
+      const pending = this.pending.get(event.data.id);
+      if (!pending) return;
+      this.pending.delete(event.data.id);
+      if (event.data.ok) {
+        pending.resolve(event.data.result);
+      } else {
+        const err = new Error(event.data.error.message);
+        if (event.data.error.name) err.name = event.data.error.name;
+        pending.reject(err);
+      }
+      return;
+    }
+    if (isEvent(event.data)) {
+      const set = this.handlers.get(event.data.name);
+      if (!set) return;
+      for (const handler of set) {
+        try {
+          handler(event.data.payload);
+        } catch (err) {
+          console.error("[KViewerEmbedClient] event handler threw:", err);
+        }
+      }
+    }
+  };
+}

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

@@ -0,0 +1,59 @@
+import { type Ref } from 'vue';
+import type { ExportPdfOptions } from '../annotation/pdf-export/export.js';
+import type { AddFormFieldPayload, FormFieldDefinition, FormFieldValue, IAnnotationStore } from '../annotation/engine/types.js';
+import { type MethodName } from './protocol.js';
+/**
+ * Surface the bridge calls on the KViewer template ref. Mirrors the
+ * methods defined in `defineExpose` inside Viewer.vue. Kept as a
+ * structural type so a real `<KViewer>` ref satisfies it without any
+ * extra wiring at the call site.
+ */
+export interface KViewerApi {
+    getAnnotations: () => IAnnotationStore[];
+    importAnnotations: (annotations: IAnnotationStore[], options?: {
+        mode?: 'replace' | 'merge';
+    }) => Promise<{
+        loaded: number;
+        skipped: number;
+    }>;
+    exportPdf: (options?: ExportPdfOptions) => Promise<Uint8Array>;
+    getFormFieldValues: () => FormFieldValue[];
+    setFormFieldValue: (fieldName: string, value: string | boolean | string[]) => void;
+    addFormField: (payload: AddFormFieldPayload) => FormFieldDefinition;
+    updateFormField: (id: string, patch: Partial<FormFieldDefinition>) => void;
+    removeFormField: (id: string) => void;
+    getFormFields: () => FormFieldDefinition[];
+    formEditMode: Ref<boolean>;
+    setFormEditMode: (enabled: boolean) => void;
+    toggleFormEditMode: () => boolean;
+}
+export interface KViewerEmbedBridgeOptions {
+    /**
+     * Origin of the parent window that hosts this iframe. Used both as
+     * the inbound origin allowlist (anything else is dropped) and as the
+     * `targetOrigin` for outbound messages.
+     *
+     * Pass `'*'` to allow any origin. Demo / development only — there is
+     * no origin verification in that mode and `postMessage` will broadcast
+     * to whatever window happens to be the parent.
+     */
+    parentOrigin: string;
+    /**
+     * Optional override for the window the host listens on. Defaults to
+     * `window`. Useful for tests.
+     */
+    windowRef?: Window;
+    /**
+     * Optional override for the parent window receiver. Defaults to
+     * `window.parent`. The bridge falls back to the request's
+     * `event.source` for replies, so this is only needed for the unsolicited
+     * `ready` and `formEditMode-changed` events.
+     */
+    parentWindow?: Window;
+}
+interface BridgeHandle {
+    /** Manually tear down listeners. Called automatically on scope dispose. */
+    unmount: () => void;
+}
+export declare function useKViewerEmbedBridge(viewerRef: Ref<KViewerApi | null | undefined>, options: KViewerEmbedBridgeOptions): BridgeHandle;
+export type { MethodName };

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

@@ -0,0 +1,136 @@
+import { onScopeDispose, watch } from "vue";
+import {
+  EVENT_KIND,
+  KVIEWER_EMBED_PROTOCOL_VERSION,
+  RESPONSE_KIND,
+  isRequest
+} from "./protocol.js";
+export function useKViewerEmbedBridge(viewerRef, options) {
+  const allowAny = options.parentOrigin === "*";
+  const winMaybe = options.windowRef ?? (typeof window !== "undefined" ? window : void 0);
+  if (!winMaybe) {
+    return { unmount: () => {
+    } };
+  }
+  const win = winMaybe;
+  const parent = options.parentWindow ?? win.parent;
+  function originAllowed(origin) {
+    return allowAny || origin === options.parentOrigin;
+  }
+  function postEvent(name, payload) {
+    if (!parent || parent === win) return;
+    const message = {
+      kind: EVENT_KIND,
+      v: KVIEWER_EMBED_PROTOCOL_VERSION,
+      name,
+      payload
+    };
+    parent.postMessage(message, options.parentOrigin);
+  }
+  async function dispatch(req) {
+    const viewer = viewerRef.value;
+    if (!viewer) {
+      throw new Error("KViewer ref is not yet available");
+    }
+    switch (req.method) {
+      case "getAnnotations":
+        return viewer.getAnnotations();
+      case "importAnnotations": {
+        const [annotations, opts] = req.args;
+        return viewer.importAnnotations(annotations, opts);
+      }
+      case "exportPdf": {
+        const [opts] = req.args;
+        return viewer.exportPdf(opts);
+      }
+      case "getFormFieldValues":
+        return viewer.getFormFieldValues();
+      case "setFormFieldValue": {
+        const [name, value] = req.args;
+        viewer.setFormFieldValue(name, value);
+        return void 0;
+      }
+      case "addFormField": {
+        const [payload] = req.args;
+        return viewer.addFormField(payload);
+      }
+      case "updateFormField": {
+        const [id, patch] = req.args;
+        viewer.updateFormField(id, patch);
+        return void 0;
+      }
+      case "removeFormField": {
+        const [id] = req.args;
+        viewer.removeFormField(id);
+        return void 0;
+      }
+      case "getFormFields":
+        return viewer.getFormFields();
+      case "getFormEditMode":
+        return viewer.formEditMode.value;
+      case "setFormEditMode": {
+        const [enabled] = req.args;
+        viewer.setFormEditMode(enabled);
+        return void 0;
+      }
+      case "toggleFormEditMode":
+        return viewer.toggleFormEditMode();
+      default:
+        throw new Error(`Unknown KViewer embed method: ${req.method}`);
+    }
+  }
+  async function handleMessage(event) {
+    if (!originAllowed(event.origin)) return;
+    if (!isRequest(event.data)) return;
+    const req = event.data;
+    let reply;
+    try {
+      const result = await dispatch(req);
+      reply = {
+        kind: RESPONSE_KIND,
+        v: KVIEWER_EMBED_PROTOCOL_VERSION,
+        id: req.id,
+        ok: true,
+        result
+      };
+    } catch (err) {
+      reply = {
+        kind: RESPONSE_KIND,
+        v: KVIEWER_EMBED_PROTOCOL_VERSION,
+        id: req.id,
+        ok: false,
+        error: {
+          message: err instanceof Error ? err.message : String(err),
+          name: err instanceof Error ? err.name : void 0
+        }
+      };
+    }
+    const target = event.source ?? parent;
+    if (!target) return;
+    target.postMessage(reply, event.origin === "" ? options.parentOrigin : event.origin);
+  }
+  win.addEventListener("message", handleMessage);
+  let stopFormEditWatch = null;
+  const stopViewerWatch = watch(
+    viewerRef,
+    (viewer) => {
+      stopFormEditWatch?.();
+      stopFormEditWatch = null;
+      if (!viewer) return;
+      postEvent("ready", { protocolVersion: KVIEWER_EMBED_PROTOCOL_VERSION });
+      stopFormEditWatch = watch(
+        viewer.formEditMode,
+        (enabled) => postEvent("formEditMode-changed", { enabled })
+      );
+    },
+    { immediate: true }
+  );
+  function unmount() {
+    win.removeEventListener("message", handleMessage);
+    stopViewerWatch();
+    stopFormEditWatch?.();
+    stopFormEditWatch = null;
+  }
+  onScopeDispose(unmount);
+  return { unmount };
+}

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

@@ -0,0 +1,105 @@
+import type { ExportPdfOptions } from '../annotation/pdf-export/export.js';
+import type { AddFormFieldPayload, FormFieldDefinition, FormFieldValue, IAnnotationStore } from '../annotation/engine/types.js';
+export declare const KVIEWER_EMBED_PROTOCOL_VERSION = 1;
+export declare const REQUEST_KIND: "kviewer:request";
+export declare const RESPONSE_KIND: "kviewer:response";
+export declare const EVENT_KIND: "kviewer:event";
+export type ImportAnnotationsMode = 'replace' | 'merge';
+export interface MethodSignatures {
+    getAnnotations: {
+        args: [];
+        result: IAnnotationStore[];
+    };
+    importAnnotations: {
+        args: [annotations: IAnnotationStore[], options?: {
+            mode?: ImportAnnotationsMode;
+        }];
+        result: {
+            loaded: number;
+            skipped: number;
+        };
+    };
+    exportPdf: {
+        args: [options?: ExportPdfOptions];
+        result: Uint8Array;
+    };
+    getFormFieldValues: {
+        args: [];
+        result: FormFieldValue[];
+    };
+    setFormFieldValue: {
+        args: [fieldName: string, value: string | boolean | string[]];
+        result: undefined;
+    };
+    addFormField: {
+        args: [payload: AddFormFieldPayload];
+        result: FormFieldDefinition;
+    };
+    updateFormField: {
+        args: [id: string, patch: Partial<FormFieldDefinition>];
+        result: undefined;
+    };
+    removeFormField: {
+        args: [id: string];
+        result: undefined;
+    };
+    getFormFields: {
+        args: [];
+        result: FormFieldDefinition[];
+    };
+    getFormEditMode: {
+        args: [];
+        result: boolean;
+    };
+    setFormEditMode: {
+        args: [enabled: boolean];
+        result: undefined;
+    };
+    toggleFormEditMode: {
+        args: [];
+        result: boolean;
+    };
+}
+export type MethodName = keyof MethodSignatures;
+export interface RequestMessage<M extends MethodName = MethodName> {
+    kind: typeof REQUEST_KIND;
+    v: typeof KVIEWER_EMBED_PROTOCOL_VERSION;
+    id: string;
+    method: M;
+    args: MethodSignatures[M]['args'];
+}
+export type ResponseMessage<M extends MethodName = MethodName> = {
+    kind: typeof RESPONSE_KIND;
+    v: typeof KVIEWER_EMBED_PROTOCOL_VERSION;
+    id: string;
+    ok: true;
+    result: MethodSignatures[M]['result'];
+} | {
+    kind: typeof RESPONSE_KIND;
+    v: typeof KVIEWER_EMBED_PROTOCOL_VERSION;
+    id: string;
+    ok: false;
+    error: {
+        message: string;
+        name?: string;
+    };
+};
+export interface EventPayloads {
+    ready: {
+        protocolVersion: number;
+    };
+    'formEditMode-changed': {
+        enabled: boolean;
+    };
+}
+export type EventName = keyof EventPayloads;
+export interface EventMessage<E extends EventName = EventName> {
+    kind: typeof EVENT_KIND;
+    v: typeof KVIEWER_EMBED_PROTOCOL_VERSION;
+    name: E;
+    payload: EventPayloads[E];
+}
+export type AnyMessage = RequestMessage | ResponseMessage | EventMessage;
+export declare function isRequest(msg: unknown): msg is RequestMessage;
+export declare function isResponse(msg: unknown): msg is ResponseMessage;
+export declare function isEvent(msg: unknown): msg is EventMessage;

package/dist/runtime/embed/protocol.js

@@ -0,0 +1,13 @@
+export const KVIEWER_EMBED_PROTOCOL_VERSION = 1;
+export const REQUEST_KIND = "kviewer:request";
+export const RESPONSE_KIND = "kviewer:response";
+export const EVENT_KIND = "kviewer:event";
+export function isRequest(msg) {
+  return !!msg && typeof msg === "object" && msg.kind === REQUEST_KIND && msg.v === KVIEWER_EMBED_PROTOCOL_VERSION;
+}
+export function isResponse(msg) {
+  return !!msg && typeof msg === "object" && msg.kind === RESPONSE_KIND && msg.v === KVIEWER_EMBED_PROTOCOL_VERSION;
+}
+export function isEvent(msg) {
+  return !!msg && typeof msg === "object" && msg.kind === EVENT_KIND && msg.v === KVIEWER_EMBED_PROTOCOL_VERSION;
+}

package/dist/runtime/menu-items.d.ts

@@ -0,0 +1,34 @@
+/** A custom item appended to the viewer's burger menu. Pass an array of
+ *  these to `<KViewer :menu-items="...">` (or `<KViewerTabs>`) to extend
+ *  the menu without replacing the built-in entries.
+ *
+ *  Inspired by Nuxt UI's `UNavigationMenu` items pattern, but scoped to
+ *  the small set of controls a viewer menu needs in practice. */
+export type ViewerMenuItem = ViewerMenuButtonItem | ViewerMenuCheckboxItem | ViewerMenuSeparatorItem;
+export interface ViewerMenuButtonItem {
+    type: 'button';
+    /** Stable key for Vue list rendering. Keep unique within the array. */
+    key: string;
+    label: string;
+    /** Lucide-style icon name passed through to the underlying UButton. */
+    icon?: string;
+    /** Fired on click. */
+    onSelect: () => void;
+    /** Disables the item without removing it. */
+    disabled?: boolean;
+}
+export interface ViewerMenuCheckboxItem {
+    type: 'checkbox';
+    key: string;
+    label: string;
+    icon?: string;
+    /** Current checked state — keep this reactive (Vue will re-render). */
+    checked: boolean;
+    /** Fired with the new state when the user toggles the item. */
+    onUpdate: (checked: boolean) => void;
+    disabled?: boolean;
+}
+export interface ViewerMenuSeparatorItem {
+    type: 'separator';
+    key: string;
+}

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

@@ -1,4 +1,11 @@
 export type { ExportPdfOptions } from './annotation/pdf-export/export.js';
 export type { ViewerTabItem, AddTabOptions } from './components/ViewerTabs.vue.js';
-export type { SignatureData, SignatureHandlers } from './annotation/engine/types.js';
+export type { AddFormFieldPayload, CheckboxStyle, FormFieldDefinition, FormFieldOrigin, FormFieldType, FormFieldValue, SignatureData, SignatureHandlers, } from './annotation/engine/types.js';
 export type { ViewMode } from './composables/viewMode.js';
+export type { KViewerApi, KViewerEmbedBridgeOptions, } from './embed/bridge-host.js';
+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 { KVIEWER_EMBED_PROTOCOL_VERSION } from './embed/protocol.js';
+export type { ViewerMenuItem, ViewerMenuButtonItem, ViewerMenuCheckboxItem, ViewerMenuSeparatorItem, } from './menu-items.js';

package/dist/runtime/public-types.js

@@ -0,0 +1,3 @@
+export { useKViewerEmbedBridge } from "./embed/bridge-host.js";
+export { KViewerEmbedClient } from "./embed/bridge-client.js";
+export { KVIEWER_EMBED_PROTOCOL_VERSION } from "./embed/protocol.js";

package/dist/types.d.mts

@@ -1,4 +1,4 @@
-export { type ExportPdfOptions, type SignatureData, type SignatureHandlers, type ViewMode } from '../dist/runtime/public-types.js'
+export { type AddFormFieldPayload, type CheckboxStyle, type ExportPdfOptions, type FormFieldDefinition, type FormFieldOrigin, type FormFieldType, type FormFieldValue, type KVIEWER_EMBED_PROTOCOL_VERSION, type KViewerApi, type KViewerEmbedBridgeOptions, type KViewerEmbedClient, type KViewerEmbedClientOptions, type KViewerEmbedEventName, type KViewerEmbedEventPayloads, type KViewerEmbedMethodName, type SignatureData, type SignatureHandlers, type ViewMode, type ViewerMenuButtonItem, type ViewerMenuCheckboxItem, type ViewerMenuItem, type ViewerMenuSeparatorItem, type useKViewerEmbedBridge } from '../dist/runtime/public-types.js'
 
 export { default } from './module.mjs'
 

package/package.json

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