@immense/vue-pom-generator 1.0.116 → 1.0.118

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -27,10 +27,29 @@ const SETTINGS_STORAGE_KEY = "vpg-annotator-settings";
27
27
  const ANNOTATIONS_STORAGE_KEY = "vpg-annotator-annotations";
28
28
  const TOOLBAR_POSITION_STORAGE_KEY = "vpg-annotator-toolbar-position";
29
29
  const RUNTIME_GUARD = "__VUE_POM_GENERATOR_ANNOTATOR_RUNTIME__";
30
+ /**
31
+ * Where an app registers a submit handler at runtime. Annotator options are serialized into the
32
+ * injected client, so a function can't be passed through the Vite config.
33
+ */
34
+ const SUBMIT_HOOK = "__VUE_POM_GENERATOR_ANNOTATOR_SUBMIT__";
30
35
 
31
- type RuntimeWindow = Window & {
32
- [RUNTIME_GUARD]?: AnnotatorRuntime;
33
- };
36
+ /**
37
+ * Receives every queued annotation at once, so feedback that only makes sense together is sent
38
+ * together. Return true only after the submission is accepted: it clears exactly the submitted
39
+ * records that are still unchanged. Any other return (false, undefined) or a throw retains the
40
+ * queue with visible feedback.
41
+ */
42
+ export type AnnotatorSubmitHandler = (
43
+ annotations: FormattedAnnotation[],
44
+ context: { pageUrl: string },
45
+ ) => boolean | Promise<boolean>;
46
+
47
+ declare global {
48
+ interface Window {
49
+ [RUNTIME_GUARD]?: AnnotatorRuntime;
50
+ [SUBMIT_HOOK]?: AnnotatorSubmitHandler;
51
+ }
52
+ }
34
53
 
35
54
  interface ToolbarPosition {
36
55
  left: number;
@@ -43,13 +62,14 @@ interface ButtonOptions {
43
62
  disabled?: boolean;
44
63
  }
45
64
 
46
- type ToolbarIconName = "drag" | "inspect" | "preview" | "copy" | "clear" | "settings";
65
+ type ToolbarIconName = "drag" | "inspect" | "preview" | "copy" | "submit" | "clear" | "settings";
47
66
 
48
67
  const TOOLBAR_ICON_MARKUP: Record<ToolbarIconName, string> = {
49
68
  drag: '<svg viewBox="0 0 16 16"><path d="M5 3h1v1H5zM10 3h1v1h-1zM5 7h1v1H5zM10 7h1v1h-1zM5 11h1v1H5zM10 11h1v1h-1z" fill="currentColor" stroke="none" /></svg>',
50
69
  inspect: '<svg viewBox="0 0 16 16"><circle cx="8" cy="8" r="4.5"/><path d="M8 1v2.5M8 12.5v2.5M1 8h2.5M12.5 8h2.5"/><circle cx="8" cy="8" r="0.9" fill="currentColor" stroke="none"/></svg>',
51
70
  preview: '<svg viewBox="0 0 16 16"><path d="M1.5 8s2.4-4 6.5-4 6.5 4 6.5 4-2.4 4-6.5 4-6.5-4-6.5-4Z"/><circle cx="8" cy="8" r="1.8"/></svg>',
52
71
  copy: '<svg viewBox="0 0 16 16"><path d="M6 2.5h6.5v9H6z"/><path d="M3.5 5.5H5v6.5h5.5v1.5h-7z"/></svg>',
72
+ submit: '<svg viewBox="0 0 16 16"><path d="M14 2 2 7.5l5 1.5 1.5 5z"/><path d="M14 2 7 9"/></svg>',
53
73
  clear: '<svg viewBox="0 0 16 16"><path d="M2.5 4.5h11"/><path d="M6 2.5h4"/><path d="M5 4.5v8"/><path d="M8 4.5v8"/><path d="M11 4.5v8"/><path d="M4 4.5h8l-.6 9H4.6z"/></svg>',
54
74
  settings: '<svg viewBox="0 0 16 16"><path d="M8 2.2l1 .6 1.2-.2.8 1 .9.7-.3 1.2.5 1-.5 1 .3 1.2-.9.7-.8 1-1.2-.2-1 .6-1-.6-1.2.2-.8-1-.9-.7.3-1.2-.5-1 .5-1-.3-1.2.9-.7.8-1 1.2.2z"/><circle cx="8" cy="8" r="2.2"/></svg>',
55
75
  };
@@ -230,6 +250,17 @@ async function copyTextToClipboard(text: string) {
230
250
  }
231
251
  }
232
252
 
253
+ function annotationMatchesSubmitted(submitted: FormattedAnnotation, current: FormattedAnnotation): boolean {
254
+ return submitted.comment === current.comment
255
+ && submitted.targetLabel === current.targetLabel
256
+ && submitted.source === current.source
257
+ && submitted.component === current.component
258
+ && submitted.uiText === current.uiText
259
+ && submitted.locator === current.locator
260
+ && submitted.domHint === current.domHint
261
+ && submitted.pageUrl === current.pageUrl;
262
+ }
263
+
233
264
  class AnnotatorRuntime {
234
265
  private readonly options: AnnotatorClientOptions;
235
266
  private readonly settings: AnnotatorSettings;
@@ -251,6 +282,7 @@ class AnnotatorRuntime {
251
282
  private currentPanelEl: HTMLElement | null = null;
252
283
  private toastTimer: number | null = null;
253
284
  private toolbarPosition: ToolbarPosition | null = null;
285
+ private submitting = false;
254
286
 
255
287
  constructor(options: AnnotatorClientOptions) {
256
288
  this.options = options;
@@ -332,6 +364,13 @@ class AnnotatorRuntime {
332
364
  disabled: this.annotations.length === 0,
333
365
  });
334
366
 
367
+ // Only when the app has registered a handler; otherwise Copy is the way out.
368
+ const submitButton = typeof window[SUBMIT_HOOK] === "function"
369
+ ? createIconButton("Submit annotations", "submit", () => void this.submitAnnotations(), {
370
+ disabled: this.submitting || this.annotations.length === 0,
371
+ })
372
+ : null;
373
+
335
374
  const clearButton = createIconButton("Clear annotations", "clear", () => this.clearAnnotations(), {
336
375
  disabled: this.annotations.length === 0,
337
376
  });
@@ -339,7 +378,7 @@ class AnnotatorRuntime {
339
378
  const settingsButton = createIconButton("Annotator settings", "settings", () => this.openSettings());
340
379
  this.settingsButton = settingsButton;
341
380
 
342
- this.toolbarEl.append(handle, selectButton, previewButton, copyButton, clearButton, settingsButton, count);
381
+ this.toolbarEl.append(handle, selectButton, previewButton, copyButton, ...(submitButton ? [submitButton] : []), clearButton, settingsButton, count);
343
382
  this.applyToolbarPosition();
344
383
  }
345
384
 
@@ -602,6 +641,7 @@ class AnnotatorRuntime {
602
641
  uiText: getNearbyText(element),
603
642
  locator: getNearbyLocator(element),
604
643
  domHint: getElementPath(element),
644
+ pageUrl: window.location.href,
605
645
  pageX: rect.left + rect.width / 2,
606
646
  pageY: rect.top + window.scrollY,
607
647
  };
@@ -868,6 +908,54 @@ class AnnotatorRuntime {
868
908
  }
869
909
  }
870
910
 
911
+ /** Re-renders the toolbar, for example after an app registers or removes a submit handler. */
912
+ refresh() {
913
+ this.renderToolbar();
914
+ }
915
+
916
+ private async submitAnnotations() {
917
+ if (this.submitting || !this.annotations.length) {
918
+ return;
919
+ }
920
+ const handler = window[SUBMIT_HOOK];
921
+ if (typeof handler !== "function") {
922
+ return;
923
+ }
924
+
925
+ this.submitting = true;
926
+ this.renderToolbar();
927
+ // Snapshot the queue so annotations added while the handler runs are not cleared with it, and
928
+ // keep a copy of the exact submitted content: retry sends the same records, and a record is
929
+ // only cleared if its id AND content still match the snapshot.
930
+ const batch = [...this.annotations];
931
+ const submitted = new Map(batch.map(annotation => [annotation.id, { ...annotation }]));
932
+ try {
933
+ const accepted = await handler(batch, { pageUrl: window.location.href });
934
+ // Strict: only an explicit true is a successful submit. Anything else — false, undefined
935
+ // from an untyped caller, or a throw — retains the queue with visible feedback.
936
+ if (accepted !== true) {
937
+ this.showToast("Submit failed");
938
+ return;
939
+ }
940
+ // Keep new drafts and drafts edited (or mutated) after the snapshot; id + content decide.
941
+ this.annotations = this.annotations.filter((annotation) => {
942
+ const snapshot = submitted.get(annotation.id);
943
+ return snapshot === undefined || !annotationMatchesSubmitted(snapshot, annotation);
944
+ });
945
+ this.saveAnnotations();
946
+ this.closePanel();
947
+ this.showToast("Submitted");
948
+ }
949
+ catch (error) {
950
+ console.error("[vue-pom-generator] Annotator submit handler failed", error);
951
+ this.showToast("Submit failed");
952
+ }
953
+ finally {
954
+ this.submitting = false;
955
+ this.renderToolbar();
956
+ }
957
+ }
958
+
871
959
  private showToast(message: string) {
872
960
  this.toastEl?.remove();
873
961
  if (this.toastTimer !== null) {
@@ -890,18 +978,18 @@ class AnnotatorRuntime {
890
978
  }
891
979
 
892
980
  export function mountAnnotatorClient(options: AnnotatorClientOptions) {
893
- const runtimeWindow = window as RuntimeWindow;
894
- if (runtimeWindow[RUNTIME_GUARD]) {
895
- return runtimeWindow[RUNTIME_GUARD]!;
981
+ if (window[RUNTIME_GUARD]) {
982
+ return window[RUNTIME_GUARD]!;
896
983
  }
897
984
 
898
985
  const runtime = new AnnotatorRuntime(options);
899
986
  runtime.mount();
900
- runtimeWindow[RUNTIME_GUARD] = runtime;
987
+ window[RUNTIME_GUARD] = runtime;
901
988
  return runtime;
902
989
  }
903
990
 
904
- // Exposed for unit tests. Pure helper (no DOM access).
991
+ // Test-only values and pure helpers (no DOM access).
905
992
  export const __internal = {
993
+ annotationsStorageKey: ANNOTATIONS_STORAGE_KEY,
906
994
  placementPrimarySide,
907
995
  };
@@ -3,6 +3,8 @@ import { normalizeInlineText } from "./text-utils";
3
3
  export type OutputDetail = "standard" | "forensic";
4
4
 
5
5
  export interface FormattedAnnotation {
6
+ /** Stable runtime id of the queued annotation; same id on retries, changed content keeps the id. */
7
+ id?: string;
6
8
  comment: string;
7
9
  targetLabel: string;
8
10
  source?: string;
@@ -10,6 +12,8 @@ export interface FormattedAnnotation {
10
12
  uiText?: string;
11
13
  locator?: string;
12
14
  domHint?: string;
15
+ /** Page URL where the annotation was captured (recorded at creation time, survives SPA route changes). */
16
+ pageUrl?: string;
13
17
  }
14
18
 
15
19
  export function formatAnnotations(