kviewer 0.0.9 → 0.0.11

package/dist/runtime/annotation/engine/tools/form-field.js

@@ -0,0 +1,117 @@
+import Konva from "konva";
+import {
+  AnnotationType
+} from "../types.js";
+import { Editor } from "../editor/editor.js";
+const TOO_SMALL = 6;
+const DEFAULT_CHECKBOX = 18;
+const DEFAULT_RADIO = 18;
+const DEFAULT_SIGNATURE = { width: 200, height: 60 };
+export class EditorFormField extends Editor {
+  fieldType;
+  pageHeight;
+  onPlaceField;
+  preview = null;
+  vertex = { x: 0, y: 0 };
+  constructor(editorOptions, opts) {
+    super({
+      ...editorOptions,
+      editorType: opts.fieldType === "text" ? AnnotationType.FORM_TEXT : opts.fieldType === "checkbox" ? AnnotationType.FORM_CHECKBOX : opts.fieldType === "radio" ? AnnotationType.FORM_RADIO : AnnotationType.FORM_SIGNATURE
+    });
+    this.fieldType = opts.fieldType;
+    this.pageHeight = opts.pageHeight;
+    this.onPlaceField = opts.onPlaceField;
+  }
+  setPageHeight(pageHeight) {
+    this.pageHeight = pageHeight;
+  }
+  mouseDownHandler(e) {
+    if (e.currentTarget !== this.konvaStage) return;
+    const pos = this.konvaStage.getRelativePointerPosition();
+    if (!pos) return;
+    this.isPainting = true;
+    this.vertex = { x: pos.x, y: pos.y };
+    this.preview = new Konva.Rect({
+      x: pos.x,
+      y: pos.y,
+      width: 0,
+      height: 0,
+      stroke: "#1677ff",
+      strokeWidth: 1,
+      dash: [4, 4],
+      strokeScaleEnabled: false,
+      visible: false,
+      listening: false
+    });
+    this.getBgLayer().add(this.preview);
+    window.addEventListener("mouseup", this.globalPointerUpHandler);
+  }
+  mouseMoveHandler(e) {
+    if (!this.isPainting || !this.preview) return;
+    e.evt.preventDefault();
+    const pos = this.konvaStage.getRelativePointerPosition();
+    if (!pos) return;
+    this.preview.show();
+    this.preview.setAttrs({
+      x: Math.min(this.vertex.x, pos.x),
+      y: Math.min(this.vertex.y, pos.y),
+      width: Math.abs(pos.x - this.vertex.x),
+      height: Math.abs(pos.y - this.vertex.y)
+    });
+  }
+  mouseUpHandler() {
+    if (!this.isPainting) return;
+    this.isPainting = false;
+    window.removeEventListener("mouseup", this.globalPointerUpHandler);
+    const preview = this.preview;
+    if (!preview) return;
+    let x = preview.x();
+    let y = preview.y();
+    let w = preview.width();
+    let h = preview.height();
+    const dragged = preview.isVisible() && Math.max(w, h) >= TOO_SMALL;
+    if (!dragged) {
+      if (this.fieldType === "checkbox") {
+        w = DEFAULT_CHECKBOX;
+        h = DEFAULT_CHECKBOX;
+        x = this.vertex.x - w / 2;
+        y = this.vertex.y - h / 2;
+      } else if (this.fieldType === "radio") {
+        w = DEFAULT_RADIO;
+        h = DEFAULT_RADIO;
+        x = this.vertex.x - w / 2;
+        y = this.vertex.y - h / 2;
+      } else if (this.fieldType === "signature") {
+        w = DEFAULT_SIGNATURE.width;
+        h = DEFAULT_SIGNATURE.height;
+        x = this.vertex.x - w / 2;
+        y = this.vertex.y - h / 2;
+      } else {
+        preview.destroy();
+        this.preview = null;
+        return;
+      }
+    }
+    preview.destroy();
+    this.preview = null;
+    const x1 = x;
+    const x2 = x + w;
+    const y2 = this.pageHeight - y;
+    const y1 = this.pageHeight - (y + h);
+    this.onPlaceField({
+      pageNumber: this.pageNumber,
+      fieldType: this.fieldType,
+      rectPdf: [x1, y1, x2, y2]
+    });
+  }
+  globalPointerUpHandler = (e) => {
+    if (e.button !== 0) return;
+    this.mouseUpHandler();
+  };
+  changeStyle(_a, _s) {
+  }
+  // Placed fields are never re-drawn from a konva string; the form-field
+  // HTML layer owns their visual representation.
+  addSerializedGroupToLayer() {
+  }
+}

package/dist/runtime/annotation/engine/types.d.ts

@@ -53,7 +53,11 @@ export declare enum AnnotationType {
     STAMP = 10,
     NOTE = 11,
     ARROW = 12,
-    CLOUD = 13
+    CLOUD = 13,
+    FORM_TEXT = 14,
+    FORM_CHECKBOX = 15,
+    FORM_SIGNATURE = 16,
+    FORM_RADIO = 17
 }
 export interface IAnnotationType {
     name: string;
@@ -134,16 +138,42 @@ export interface IAnnotationStore {
     draggable: boolean;
 }
 export type FormFieldType = 'text' | 'checkbox' | 'radio' | 'dropdown' | 'signature' | 'button';
+/**
+ * Standard PDF checkbox glyph styles, per Acrobat's "Check Box Style"
+ * options. Each maps to a single ZapfDingbats character written to the
+ * widget's `/MK /CA` entry — see ISO 32000-1 §12.5.6.19.
+ */
+export type CheckboxStyle = 'check' | 'cross' | 'diamond' | 'circle' | 'star' | 'square';
+/**
+ * Where a form field came from. Export uses this to decide whether to
+ * update an existing PDF widget ('parsed') or create a new one ('placed',
+ * 'detected'). Missing = 'parsed' for backward compat.
+ */
+export type FormFieldOrigin = 'parsed' | 'detected' | 'placed';
 export interface FormFieldDefinition {
     id: string;
     pageNumber: number;
     fieldType: FormFieldType;
     fieldName: string;
     rect: [number, number, number, number];
+    /** The rect this field had when first parsed from the source PDF. Used
+     *  on export to detect that a parsed field has been moved/resized so
+     *  its existing widget can be updated in place. Unset for placed and
+     *  detected fields (their `rect` IS their original rect). */
+    originalRect?: [number, number, number, number];
     readOnly: boolean;
     required: boolean;
+    origin?: FormFieldOrigin;
     /** Visual shape hint for detected checkboxes (circle renders round, rectangle renders square). */
     shapeType?: DetectedShapeType;
+    /** Checkbox glyph style. Only used when fieldType === 'checkbox'.
+     *  Defaults to 'check' for placed checkboxes; populated from `/MK /CA`
+     *  for parsed checkboxes when the source PDF specifies a non-default. */
+    checkboxStyle?: CheckboxStyle;
+    /** The checkbox style this field had when first parsed from the source
+     *  PDF. Used on export to detect that a parsed checkbox's style was
+     *  changed in form-edit mode, so we know to overwrite its `/MK /CA`. */
+    originalCheckboxStyle?: CheckboxStyle;
     defaultValue?: string;
     maxLen?: number;
     multiLine?: boolean;
@@ -159,7 +189,23 @@ export interface FormFieldDefinition {
     multiSelect?: boolean;
     editable?: boolean;
     buttonLabel?: string;
+    /** Signature-only: placeholder text shown on the unsigned widget.
+     *  Defaults to 'Click to sign' when unset. */
+    promptText?: string;
+    /** Signature-only: when this signature is filled, lock other fields in
+     *  the form so they can no longer be edited. Mirrors PDF spec
+     *  /Lock /Action: 'all' locks every other field; 'include' locks only
+     *  fields listed in lockFieldNames; 'exclude' locks every field NOT
+     *  listed. Enforced inside the viewer (the viewer flattens signatures
+     *  to images on export, so this doesn't round-trip as a real /Sig
+     *  /Lock dict). */
+    lockAction?: 'all' | 'include' | 'exclude';
+    /** Field names referenced by lockAction = 'include' or 'exclude'. */
+    lockFieldNames?: string[];
     fontSize?: number;
+    /** PDF font name as parsed from `/DA` (e.g. "Helv", "HelvB", "Times-Bold").
+     *  Used to derive CSS font-family / font-weight / font-style. */
+    fontName?: string;
     color?: number[];
     backgroundColor?: number[];
     textAlignment?: number;
@@ -170,6 +216,13 @@ export interface FormFieldValue {
     fieldType: FormFieldType;
     value: string | boolean | string[];
 }
+/** Payload for placing a new form field via the drawing tool. */
+export interface PlaceFieldPayload {
+    pageNumber: number;
+    fieldType: FormFieldType;
+    /** PDF-space rect [x1, y1, x2, y2], bottom-left origin. */
+    rectPdf: [number, number, number, number];
+}
 export interface DetectedShapeRect {
     x: number;
     y: number;

package/dist/runtime/annotation/engine/types.js

@@ -54,6 +54,10 @@ export var AnnotationType = /* @__PURE__ */ ((AnnotationType2) => {
   AnnotationType2[AnnotationType2["NOTE"] = 11] = "NOTE";
   AnnotationType2[AnnotationType2["ARROW"] = 12] = "ARROW";
   AnnotationType2[AnnotationType2["CLOUD"] = 13] = "CLOUD";
+  AnnotationType2[AnnotationType2["FORM_TEXT"] = 14] = "FORM_TEXT";
+  AnnotationType2[AnnotationType2["FORM_CHECKBOX"] = 15] = "FORM_CHECKBOX";
+  AnnotationType2[AnnotationType2["FORM_SIGNATURE"] = 16] = "FORM_SIGNATURE";
+  AnnotationType2[AnnotationType2["FORM_RADIO"] = 17] = "FORM_RADIO";
   return AnnotationType2;
 })(AnnotationType || {});
 export var CommentStatus = /* @__PURE__ */ ((CommentStatus2) => {

package/dist/runtime/annotation/font-style.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Decode the font name parsed from a PDF widget's `/DA` (Default
+ * Appearance) string into CSS font properties.
+ *
+ * PDF /DA font names come in two flavours:
+ *  - PDF "abbreviations" used by Acrobat for the standard 14 fonts
+ *    (`Helv`, `HelvB`, `HelvO`, `HelvBO`, `TiRo`, `TiBo`, `TiIt`,
+ *    `TiBI`, `Cour`, `CoBo`, `CoOb`, `CoBO`, `ZaDb`, `Symb`).
+ *  - Full PostScript-style names (`Helvetica-Bold`, `Times-Italic`,
+ *    `Courier-BoldOblique`, etc.) — common in PDFs produced by other
+ *    tools.
+ *
+ * Anything we don't recognize falls back to sans-serif regular —
+ * exactly what pdf.js's annotation layer renders. Unrecognized names
+ * still keep weight/style detection via the `Bold`/`Italic`/`Oblique`
+ * substring check, so e.g. `MyFont-Bold` becomes `bold`.
+ */
+export interface DecodedFontStyle {
+    fontFamily: string;
+    fontWeight: 'normal' | 'bold';
+    fontStyle: 'normal' | 'italic';
+}
+export declare function decodeFontName(fontName: string | undefined): DecodedFontStyle;

package/dist/runtime/annotation/font-style.js

@@ -0,0 +1,57 @@
+const STANDARD_14 = {
+  // Helvetica family
+  Helv: { fontFamily: '"Helvetica Neue", Helvetica, Arial, sans-serif', fontWeight: "normal", fontStyle: "normal" },
+  HelvB: { fontFamily: '"Helvetica Neue", Helvetica, Arial, sans-serif', fontWeight: "bold", fontStyle: "normal" },
+  HelvO: { fontFamily: '"Helvetica Neue", Helvetica, Arial, sans-serif', fontWeight: "normal", fontStyle: "italic" },
+  HelvBO: { fontFamily: '"Helvetica Neue", Helvetica, Arial, sans-serif', fontWeight: "bold", fontStyle: "italic" },
+  Helvetica: { fontFamily: '"Helvetica Neue", Helvetica, Arial, sans-serif', fontWeight: "normal", fontStyle: "normal" },
+  "Helvetica-Bold": { fontFamily: '"Helvetica Neue", Helvetica, Arial, sans-serif', fontWeight: "bold", fontStyle: "normal" },
+  "Helvetica-Oblique": { fontFamily: '"Helvetica Neue", Helvetica, Arial, sans-serif', fontWeight: "normal", fontStyle: "italic" },
+  "Helvetica-BoldOblique": { fontFamily: '"Helvetica Neue", Helvetica, Arial, sans-serif', fontWeight: "bold", fontStyle: "italic" },
+  // Times family
+  TiRo: { fontFamily: '"Times New Roman", Times, serif', fontWeight: "normal", fontStyle: "normal" },
+  TiBo: { fontFamily: '"Times New Roman", Times, serif', fontWeight: "bold", fontStyle: "normal" },
+  TiIt: { fontFamily: '"Times New Roman", Times, serif', fontWeight: "normal", fontStyle: "italic" },
+  TiBI: { fontFamily: '"Times New Roman", Times, serif', fontWeight: "bold", fontStyle: "italic" },
+  "Times-Roman": { fontFamily: '"Times New Roman", Times, serif', fontWeight: "normal", fontStyle: "normal" },
+  "Times-Bold": { fontFamily: '"Times New Roman", Times, serif', fontWeight: "bold", fontStyle: "normal" },
+  "Times-Italic": { fontFamily: '"Times New Roman", Times, serif', fontWeight: "normal", fontStyle: "italic" },
+  "Times-BoldItalic": { fontFamily: '"Times New Roman", Times, serif', fontWeight: "bold", fontStyle: "italic" },
+  // Courier family
+  Cour: { fontFamily: '"Courier New", Courier, monospace', fontWeight: "normal", fontStyle: "normal" },
+  CoBo: { fontFamily: '"Courier New", Courier, monospace', fontWeight: "bold", fontStyle: "normal" },
+  CoOb: { fontFamily: '"Courier New", Courier, monospace', fontWeight: "normal", fontStyle: "italic" },
+  CoBO: { fontFamily: '"Courier New", Courier, monospace', fontWeight: "bold", fontStyle: "italic" },
+  Courier: { fontFamily: '"Courier New", Courier, monospace', fontWeight: "normal", fontStyle: "normal" },
+  "Courier-Bold": { fontFamily: '"Courier New", Courier, monospace', fontWeight: "bold", fontStyle: "normal" },
+  "Courier-Oblique": { fontFamily: '"Courier New", Courier, monospace', fontWeight: "normal", fontStyle: "italic" },
+  "Courier-BoldOblique": { fontFamily: '"Courier New", Courier, monospace', fontWeight: "bold", fontStyle: "italic" }
+};
+const DEFAULT_STYLE = {
+  fontFamily: "sans-serif",
+  fontWeight: "normal",
+  fontStyle: "normal"
+};
+export function decodeFontName(fontName) {
+  if (!fontName) return DEFAULT_STYLE;
+  const name = fontName.startsWith("/") ? fontName.slice(1) : fontName;
+  const standard = STANDARD_14[name];
+  if (standard) return standard;
+  const stripped = /^[A-Z]{6}\+/.test(name) ? name.slice(7) : name;
+  const lower = stripped.toLowerCase();
+  let fontFamily = "sans-serif";
+  if (/serif|times|roman|georgia|garamond|cambria/.test(lower)) {
+    fontFamily = '"Times New Roman", Times, serif';
+  } else if (/mono|courier|consolas|menlo|inconsolata/.test(lower)) {
+    fontFamily = '"Courier New", Courier, monospace';
+  } else if (/helvet|arial|verdana|tahoma|sans/.test(lower)) {
+    fontFamily = '"Helvetica Neue", Helvetica, Arial, sans-serif';
+  }
+  const isBold = /bold|black|heavy|semibold|demibold/i.test(stripped);
+  const isItalic = /italic|oblique/i.test(stripped);
+  return {
+    fontFamily,
+    fontWeight: isBold ? "bold" : "normal",
+    fontStyle: isItalic ? "italic" : "normal"
+  };
+}

package/dist/runtime/annotation/parsers/extractCheckboxStyles.d.ts

@@ -0,0 +1,21 @@
+import type { CheckboxStyle } from '../engine/types.js';
+/**
+ * Walk the AcroForm of a source PDF and extract the checkbox style hint
+ * (`/MK /CA`) for every checkbox widget. pdf.js does not surface this
+ * field, so without a side-channel parse we cannot know whether an
+ * existing checkbox should render as a check, cross, diamond, etc.
+ *
+ * Returns a Map keyed by field name. If multiple widgets share a name
+ * (uncommon for checkboxes, normal for radio groups), the first hit
+ * wins.
+ */
+export declare function extractCheckboxStyles(pdfBytes: Uint8Array | ArrayBuffer): Promise<Map<string, CheckboxStyle>>;
+/**
+ * Walk the AcroForm and extract push-button captions from `/MK /CA`.
+ * pdf.js exposes neither the caption nor a button label, so without this
+ * side-channel parse every push button would render with our generic
+ * "Button" fallback (e.g. a Reset button shows the wrong text).
+ *
+ * Returns a Map keyed by the button's fully qualified field name.
+ */
+export declare function extractButtonCaptions(pdfBytes: Uint8Array | ArrayBuffer): Promise<Map<string, string>>;

package/dist/runtime/annotation/parsers/extractCheckboxStyles.js

@@ -0,0 +1,75 @@
+import { PDFButton, PDFCheckBox, PDFDocument, PDFDict, PDFHexString, PDFName, PDFString } from "pdf-lib";
+import { captionToStyle } from "../checkbox-styles.js";
+export async function extractCheckboxStyles(pdfBytes) {
+  const out = /* @__PURE__ */ new Map();
+  let doc;
+  try {
+    doc = await PDFDocument.load(pdfBytes, { ignoreEncryption: true });
+  } catch {
+    return out;
+  }
+  let form;
+  try {
+    form = doc.getForm();
+  } catch {
+    return out;
+  }
+  for (const field of form.getFields()) {
+    if (!(field instanceof PDFCheckBox)) continue;
+    const acro = field.acroField;
+    const name = field.getName();
+    if (!name || out.has(name)) continue;
+    const widgets = acro.getWidgets();
+    for (const widget of widgets) {
+      const mk = widget.dict.get(PDFName.of("MK"));
+      if (!(mk instanceof PDFDict)) continue;
+      const ca = mk.get(PDFName.of("CA"));
+      let caption;
+      if (ca instanceof PDFString || ca instanceof PDFHexString) {
+        caption = ca.decodeText();
+      }
+      if (!caption) continue;
+      const style = captionToStyle(caption);
+      if (style) {
+        out.set(name, style);
+        break;
+      }
+    }
+  }
+  return out;
+}
+export async function extractButtonCaptions(pdfBytes) {
+  const out = /* @__PURE__ */ new Map();
+  let doc;
+  try {
+    doc = await PDFDocument.load(pdfBytes, { ignoreEncryption: true });
+  } catch {
+    return out;
+  }
+  let form;
+  try {
+    form = doc.getForm();
+  } catch {
+    return out;
+  }
+  for (const field of form.getFields()) {
+    if (!(field instanceof PDFButton)) continue;
+    const acro = field.acroField;
+    const name = field.getName();
+    if (!name || out.has(name)) continue;
+    const widgets = acro.getWidgets();
+    for (const widget of widgets) {
+      const mk = widget.dict.get(PDFName.of("MK"));
+      if (!(mk instanceof PDFDict)) continue;
+      const ca = mk.get(PDFName.of("CA"));
+      if (ca instanceof PDFString || ca instanceof PDFHexString) {
+        const caption = ca.decodeText();
+        if (caption) {
+          out.set(name, caption);
+          break;
+        }
+      }
+    }
+  }
+  return out;
+}

package/dist/runtime/annotation/parsers/parseFormFields.js

@@ -19,8 +19,10 @@ export function parseFormFields(annotations, pageNumber) {
       fieldType,
       fieldName: ann.fieldName ?? "",
       rect: normalizedRect,
+      originalRect: [...normalizedRect],
       readOnly: Boolean(ann.readOnly),
-      required: Boolean(ann.required)
+      required: Boolean(ann.required),
+      origin: "parsed"
     };
     if (fieldType === "text") {
       if (ann.fieldValue != null) def.defaultValue = String(ann.fieldValue);
@@ -68,8 +70,19 @@ export function parseFormFields(annotations, pageNumber) {
     if (fieldType === "button") {
       def.buttonLabel = ann.alternativeText ?? ann.fieldValue ?? ann.fieldName ?? "Button";
     }
-    if (typeof ann.fontSize === "number") def.fontSize = ann.fontSize;
-    if (Array.isArray(ann.color)) {
+    const da = ann.defaultAppearanceData ?? {};
+    if (typeof da.fontSize === "number" && da.fontSize > 0) {
+      def.fontSize = da.fontSize;
+    } else if (typeof ann.fontSize === "number" && ann.fontSize > 0) {
+      def.fontSize = ann.fontSize;
+    }
+    if (typeof da.fontName === "string" && da.fontName.length > 0) {
+      def.fontName = da.fontName;
+    }
+    if (da.fontColor && da.fontColor.length >= 3) {
+      const fc = da.fontColor;
+      def.color = [fc[0] ?? 0, fc[1] ?? 0, fc[2] ?? 0];
+    } else if (Array.isArray(ann.color)) {
       def.color = ann.color.map(
         (c) => (
           // pdf.js colors may be 0-1 floats or 0-255 integers

package/dist/runtime/annotation/pdf-export/export-form-fields.d.ts

@@ -1,9 +1,12 @@
-import type { PDFDocument } from 'pdf-lib';
-import type { FormFieldValue } from '../engine/types.js';
+import { type PDFDocument } from 'pdf-lib';
+import type { FormFieldDefinition, FormFieldValue } from '../engine/types.js';
 /**
  * Write form field values back to the PDF using pdf-lib's AcroForm API.
  *
- * This updates existing form fields in the PDF with the values the user
- * entered in the viewer. It does NOT create new fields.
+ * - Placed/detected fields that originate from the viewer are created as new
+ *   AcroForm widgets (text, checkbox, radio). Signature fields are drawn as
+ *   flat images (pdf-lib does not support creating AcroForm signature widgets).
+ * - Parsed fields (already present in the source PDF) get their values
+ *   updated in place.
  */
-export declare function writeFormFieldsToPdf(pdfDoc: PDFDocument, fieldValues: FormFieldValue[]): Promise<void>;
+export declare function writeFormFieldsToPdf(pdfDoc: PDFDocument, fieldValues: FormFieldValue[], placedDefinitions?: FormFieldDefinition[]): Promise<void>;