@immense/vue-pom-generator 1.0.116 → 1.0.117

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.
package/README.md CHANGED
@@ -378,6 +378,45 @@ When `runtime.annotator.ui.enabled` is true, the same browser-only client is inj
378
378
  for both `vite serve` and `vite build`. Disable it for production in your conditional
379
379
  Vite config when the overlay is intended only for development or preview artifacts.
380
380
 
381
+ To send annotations somewhere other than the clipboard, register a submit handler at
382
+ runtime. Annotator options are serialized into the injected client, so a function can't
383
+ go through the Vite config. While a handler is registered, the toolbar shows **Submit**,
384
+ which hands over every queued annotation at once, so feedback that only makes sense
385
+ together is sent together:
386
+
387
+ ```ts
388
+ import type { AnnotatorSubmitHandler } from "@immense/vue-pom-generator";
389
+
390
+ const submit: AnnotatorSubmitHandler = async (annotations, { pageUrl }) => {
391
+ // Each annotation carries `source` (`<file>:<line>:<column>`), its capture-time
392
+ // `pageUrl`, `comment`, `targetLabel`, ...
393
+ await postFeedback(annotations, pageUrl);
394
+ return true; // only an explicit true is a success; anything else retains the queue
395
+ };
396
+
397
+ window.__VUE_POM_GENERATOR_ANNOTATOR_SUBMIT__ = submit;
398
+ window.__VUE_POM_GENERATOR_ANNOTATOR_RUNTIME__?.refresh(); // if the overlay is already mounted
399
+ ```
400
+
401
+ The package types declare both window properties, so no local `declare global` is
402
+ needed. The handler is invoked synchronously from the button click, before the overlay
403
+ awaits anything — open popups (`window.open`) before your handler's first `await`.
404
+ Only an explicit `true` counts as a successful submit; any other return (`false`,
405
+ `undefined`) or a throw retains the queue and shows a **Submit failed** toast.
406
+ Thrown errors are also logged to the console with a `[vue-pom-generator]` prefix
407
+ for diagnostics. On success, exactly the submitted records that are still unchanged
408
+ are cleared — new
409
+ drafts and drafts edited while the submit was pending are kept (records are matched
410
+ by id and submitted content), so a retry hands over the same records with the same
411
+ ids. The Submit button is disabled while a submit is in flight.
412
+ Remove the handler and call `refresh()` again to hide the button.
413
+
414
+ The handler owns authentication, transport, and retry policy. Return `true` only
415
+ after the destination confirms acceptance. A timeout or a closed popup does not
416
+ prove that a remote write failed: retain the queue and reuse the same submission
417
+ identifier until the destination confirms a receipt. The annotator itself makes no
418
+ network requests and does not store destination credentials.
419
+
381
420
  ## Basic Nuxt setup
382
421
 
383
422
  ```ts
package/RELEASE_NOTES.md CHANGED
@@ -1,34 +1,29 @@
1
- v1.0.116
2
-
3
1
  Highlights
4
2
 
5
- - Wrapper targeting fixed: a component's own fallthrough target is now matched by element, not by
6
- offset in the wrapper contract (#83) — wrappers no longer bind to the wrong node when sibling
7
- structure shifts.
8
- - Corrected the corresponding logic in transform.ts so generated wrappers stay consistent with the
9
- new element-based matching.
10
- - Added regression coverage in tests/transform.test.ts and trimmed the offset-based assumptions in
11
- tests/wrapper-contract.test.ts.
3
+ - The runtime annotator can now submit captured annotations at runtime, not just collect them (#84)
4
+ - New submission capability is exported from the package entry point for consumer apps
5
+ - New dedicated test suite (tests/annotator-submit.test.ts, ~250 lines) covers the submission flow
6
+ - README updated with documentation for the new workflow
12
7
 
13
8
  Changes
14
9
 
15
- Fixed
10
+ Annotator runtime
16
11
 
17
- - wrapper-contract: match a component's own fallthrough target by element rather than by positional
18
- offset (#83).
19
- - transform: updated transform behavior to align with element-based fallthrough matching.
12
+ - Add runtime annotation submission to the annotator client (plugin/runtime/annotator/client.ts)
13
+ - Extend annotator formatting helpers to support the submission payload
14
+ (plugin/runtime/annotator/format.ts)
20
15
 
21
- Tests
16
+ Package surface & docs
22
17
 
23
- - tests/transform.test.ts: new cases covering element-based fallthrough target matching.
24
- - tests/wrapper-contract.test.ts: updated expectations for the corrected matching behavior.
18
+ - Export the new annotation submission API from index.ts
19
+ - Document runtime annotation submission in the README
25
20
 
26
21
  Pull Requests Included
27
22
 
28
- - #83 — fix(wrappers): match a component's own fallthrough target by element, not offset —
29
- ]8;id=md-1cfqef3;https://github.com/immense/vue-pom-generator/pull/83@darrenator[bot]]8;;
23
+ - ]8;id=md-1blrlc6;https://github.com/immense/vue-pom-generator/pull/84#84 — feat(annotator): add runtime annotation submission]8;;]8;; by @darrenator[bot]]8;;
30
24
 
31
25
  Testing
32
26
 
33
- - Unit tests added/updated for transform and wrapper-contract matching behavior.
27
+ - New tests/annotator-submit.test.ts adds broad coverage for the runtime submission path; no other
28
+ test changes reported.
34
29
 
package/dist/index.cjs CHANGED
@@ -12388,11 +12388,13 @@ const SETTINGS_STORAGE_KEY = "vpg-annotator-settings";
12388
12388
  const ANNOTATIONS_STORAGE_KEY = "vpg-annotator-annotations";
12389
12389
  const TOOLBAR_POSITION_STORAGE_KEY = "vpg-annotator-toolbar-position";
12390
12390
  const RUNTIME_GUARD = "__VUE_POM_GENERATOR_ANNOTATOR_RUNTIME__";
12391
+ const SUBMIT_HOOK = "__VUE_POM_GENERATOR_ANNOTATOR_SUBMIT__";
12391
12392
  const TOOLBAR_ICON_MARKUP = {
12392
12393
  drag: '<svg viewBox="0 0 16 16"><path d="M5 3h1v1H5zM10 3h1v1h-1zM5 7h1v1H5zM10 7h1v1h-1zM5 11h1v1H5zM10 11h1v1h-1z" fill="currentColor" stroke="none" /></svg>',
12393
12394
  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>',
12394
12395
  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>',
12395
12396
  copy: '<svg viewBox="0 0 16 16"><path d="M6 2.5h6.5v9H6z"/><path d="M3.5 5.5H5v6.5h5.5v1.5h-7z"/></svg>',
12397
+ 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>',
12396
12398
  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>',
12397
12399
  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>'
12398
12400
  };
@@ -12525,6 +12527,9 @@ async function copyTextToClipboard(text) {
12525
12527
  throw new Error("Clipboard copy failed.");
12526
12528
  }
12527
12529
  }
12530
+ function annotationMatchesSubmitted(submitted, current) {
12531
+ return submitted.comment === current.comment && submitted.targetLabel === current.targetLabel && submitted.source === current.source && submitted.component === current.component && submitted.uiText === current.uiText && submitted.locator === current.locator && submitted.domHint === current.domHint && submitted.pageUrl === current.pageUrl;
12532
+ }
12528
12533
  class AnnotatorRuntime {
12529
12534
  options;
12530
12535
  settings;
@@ -12546,6 +12551,7 @@ class AnnotatorRuntime {
12546
12551
  currentPanelEl = null;
12547
12552
  toastTimer = null;
12548
12553
  toolbarPosition = null;
12554
+ submitting = false;
12549
12555
  constructor(options) {
12550
12556
  this.options = options;
12551
12557
  this.settings = this.loadSettings();
@@ -12611,12 +12617,15 @@ class AnnotatorRuntime {
12611
12617
  const copyButton = createIconButton("Copy annotations", "copy", () => this.copyAnnotations(), {
12612
12618
  disabled: this.annotations.length === 0
12613
12619
  });
12620
+ const submitButton = typeof window[SUBMIT_HOOK] === "function" ? createIconButton("Submit annotations", "submit", () => void this.submitAnnotations(), {
12621
+ disabled: this.submitting || this.annotations.length === 0
12622
+ }) : null;
12614
12623
  const clearButton = createIconButton("Clear annotations", "clear", () => this.clearAnnotations(), {
12615
12624
  disabled: this.annotations.length === 0
12616
12625
  });
12617
12626
  const settingsButton = createIconButton("Annotator settings", "settings", () => this.openSettings());
12618
12627
  this.settingsButton = settingsButton;
12619
- this.toolbarEl.append(handle, selectButton, previewButton, copyButton, clearButton, settingsButton, count);
12628
+ this.toolbarEl.append(handle, selectButton, previewButton, copyButton, ...submitButton ? [submitButton] : [], clearButton, settingsButton, count);
12620
12629
  this.applyToolbarPosition();
12621
12630
  }
12622
12631
  renderMarkers() {
@@ -12846,6 +12855,7 @@ class AnnotatorRuntime {
12846
12855
  uiText: getNearbyText(element),
12847
12856
  locator: getNearbyLocator(element),
12848
12857
  domHint: getElementPath(element),
12858
+ pageUrl: window.location.href,
12849
12859
  pageX: rect.left + rect.width / 2,
12850
12860
  pageY: rect.top + window.scrollY
12851
12861
  };
@@ -13075,6 +13085,43 @@ class AnnotatorRuntime {
13075
13085
  this.showToast("Copy failed");
13076
13086
  }
13077
13087
  }
13088
+ /** Re-renders the toolbar, for example after an app registers or removes a submit handler. */
13089
+ refresh() {
13090
+ this.renderToolbar();
13091
+ }
13092
+ async submitAnnotations() {
13093
+ if (this.submitting || !this.annotations.length) {
13094
+ return;
13095
+ }
13096
+ const handler = window[SUBMIT_HOOK];
13097
+ if (typeof handler !== "function") {
13098
+ return;
13099
+ }
13100
+ this.submitting = true;
13101
+ this.renderToolbar();
13102
+ const batch = [...this.annotations];
13103
+ const submitted = new Map(batch.map((annotation) => [annotation.id, { ...annotation }]));
13104
+ try {
13105
+ const accepted = await handler(batch, { pageUrl: window.location.href });
13106
+ if (accepted !== true) {
13107
+ this.showToast("Submit failed");
13108
+ return;
13109
+ }
13110
+ this.annotations = this.annotations.filter((annotation) => {
13111
+ const snapshot = submitted.get(annotation.id);
13112
+ return snapshot === void 0 || !annotationMatchesSubmitted(snapshot, annotation);
13113
+ });
13114
+ this.saveAnnotations();
13115
+ this.closePanel();
13116
+ this.showToast("Submitted");
13117
+ } catch (error) {
13118
+ console.error("[vue-pom-generator] Annotator submit handler failed", error);
13119
+ this.showToast("Submit failed");
13120
+ } finally {
13121
+ this.submitting = false;
13122
+ this.renderToolbar();
13123
+ }
13124
+ }
13078
13125
  showToast(message) {
13079
13126
  this.toastEl?.remove();
13080
13127
  if (this.toastTimer !== null) {
@@ -13096,13 +13143,12 @@ class AnnotatorRuntime {
13096
13143
  }
13097
13144
  }
13098
13145
  function mountAnnotatorClient(options) {
13099
- const runtimeWindow = window;
13100
- if (runtimeWindow[RUNTIME_GUARD]) {
13101
- return runtimeWindow[RUNTIME_GUARD];
13146
+ if (window[RUNTIME_GUARD]) {
13147
+ return window[RUNTIME_GUARD];
13102
13148
  }
13103
13149
  const runtime = new AnnotatorRuntime(options);
13104
13150
  runtime.mount();
13105
- runtimeWindow[RUNTIME_GUARD] = runtime;
13151
+ window[RUNTIME_GUARD] = runtime;
13106
13152
  return runtime;
13107
13153
  }
13108
13154
  let generating = false;