@immense/vue-pom-generator 1.0.115 → 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,48 +1,29 @@
1
- The picture is clear: only #81 falls in the v1.0.114..HEAD range (#79 is the tagged v1.0.114 release
2
- itself; the long PR list is historical). Let me inspect the actual diff of #81 to summarize it
3
- accurately.
4
-
5
- v1.0.115
6
-
7
1
  Highlights
8
2
 
9
- - Fixed Windows dev-server crashes during POM generation: backslash paths handed to the Vue
10
- compiler were embedded verbatim in generated useCssVars code, producing SyntaxError: Bad character
11
- escape sequence for paths containing \u, \x, \8, or \9 (fixes #80).
12
- - SFC ids passed to compileScript are now posix-normalized in both the build collection path and
13
- the dev plugin, so binding metadata is no longer silently dropped for affected components.
14
- - Component-name resolution now compares paths in posix form, restoring correct hierarchical names
15
- for files under directories whose names contain a backslash.
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
16
7
 
17
8
  Changes
18
9
 
19
- Plugin
20
-
21
- - Exported the existing toPosixSlashes helper from plugin/path-utils.ts and applied it wherever
22
- paths become compiler ids: collectSource in plugin/vue-plugin.ts and getScriptInfo in
23
- plugin/internal/dev-plugin.ts.
24
- - collectSource now canonicalizes the two collection passes (native paths from the filesystem walk,
25
- posix module ids from Vite) to posix once, so naming, metadata, and generated manifests agree
26
- across passes.
27
-
28
- Path and scope resolution
10
+ Annotator runtime
29
11
 
30
- - resolveComponentNameFromPath posix-normalizes the filename and candidate roots and uses
31
- path.posix.relative/parse/join for prefix matching, so a configured root on POSIX that contains a
32
- backslash in a directory name still matches and no longer drops components to their basename.
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)
33
15
 
34
- Breaking Changes
16
+ Package surface & docs
35
17
 
36
- None.
18
+ - Export the new annotation submission API from index.ts
19
+ - Document runtime annotation submission in the README
37
20
 
38
21
  Pull Requests Included
39
22
 
40
- - ]8;id=md-1czplt1;https://github.com/immense/vue-pom-generator/pull/81#81]8;;]8;; — fix(plugin): posix-normalize SFC ids handed to the Vue compiler (@steve-price-immybot)]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;;
41
24
 
42
25
  Testing
43
26
 
44
- - Added regression tests: supplementing v-bind() components whose paths contain backslash
45
- separators, preserving hierarchical names for nested files under backslash directories, and a new
46
- toPosixSlashes unit suite covering Windows-separator conversion and untouched posix paths
47
- (tests/generate-vue-poms.test.ts, tests/path-utils-scope.test.ts).
27
+ - New tests/annotator-submit.test.ts adds broad coverage for the runtime submission path; no other
28
+ test changes reported.
48
29
 
package/dist/index.cjs CHANGED
@@ -9037,9 +9037,8 @@ function analyzeWrapperContractFromSfc(options) {
9037
9037
  role: null,
9038
9038
  targetRoles: [],
9039
9039
  forwardedTestIdTargetOffsets: /* @__PURE__ */ new Set(),
9040
- forwardedTestIdTargetSfcOffsets: /* @__PURE__ */ new Set(),
9041
- explicitlyForwardedTestIdTargetOffsets: /* @__PURE__ */ new Set(),
9042
- explicitlyForwardedTestIdTargetSfcOffsets: /* @__PURE__ */ new Set()
9040
+ attrsObjectNames: /* @__PURE__ */ new Set(),
9041
+ attrsFunctionNames: /* @__PURE__ */ new Set()
9043
9042
  };
9044
9043
  }
9045
9044
  const scriptMetadata = analyzeScriptForwardingMetadata(
@@ -9048,7 +9047,6 @@ function analyzeWrapperContractFromSfc(options) {
9048
9047
  );
9049
9048
  const ast = compilerDom.parse(template, { comments: false });
9050
9049
  const targets = /* @__PURE__ */ new Map();
9051
- const explicitTargetOffsets = /* @__PURE__ */ new Set();
9052
9050
  if (scriptMetadata.inheritAttrs) {
9053
9051
  for (const element of getRenderedRootElements(ast)) {
9054
9052
  targets.set(element.loc.start.offset, element);
@@ -9057,7 +9055,6 @@ function analyzeWrapperContractFromSfc(options) {
9057
9055
  walkTemplate(ast, (element) => {
9058
9056
  if (elementExplicitlyForwardsTestId(element, options.testIdAttribute, scriptMetadata)) {
9059
9057
  targets.set(element.loc.start.offset, element);
9060
- explicitTargetOffsets.add(element.loc.start.offset);
9061
9058
  }
9062
9059
  });
9063
9060
  const targetRoles = [...targets.values()].map((element) => {
@@ -9072,17 +9069,12 @@ function analyzeWrapperContractFromSfc(options) {
9072
9069
  });
9073
9070
  const uniqueRoles = new Set(targetRoles);
9074
9071
  const role = uniqueRoles.size === 1 && !uniqueRoles.has(null) ? targetRoles[0] ?? null : null;
9075
- const templateContentStartOffset = descriptor.template?.loc.start.offset ?? 0;
9076
- const toSfcOffsets = (offsets) => new Set(
9077
- [...offsets].map((offset) => offset + templateContentStartOffset)
9078
- );
9079
9072
  return {
9080
9073
  role,
9081
9074
  targetRoles,
9082
9075
  forwardedTestIdTargetOffsets: new Set(targets.keys()),
9083
- forwardedTestIdTargetSfcOffsets: toSfcOffsets(targets.keys()),
9084
- explicitlyForwardedTestIdTargetOffsets: explicitTargetOffsets,
9085
- explicitlyForwardedTestIdTargetSfcOffsets: toSfcOffsets(explicitTargetOffsets)
9076
+ attrsObjectNames: scriptMetadata.attrsObjectNames,
9077
+ attrsFunctionNames: scriptMetadata.attrsFunctionNames
9086
9078
  };
9087
9079
  }
9088
9080
  function resolveWrapperContractForTag(options) {
@@ -9751,8 +9743,7 @@ function createTestIdTransform(componentName, componentHierarchyMap, nativeWrapp
9751
9743
  }
9752
9744
  }
9753
9745
  const ownWrapperContract = getWrapperContract(componentName);
9754
- const elementStartOffset = element.loc.start.offset;
9755
- const isExplicitFallthroughTarget = ownWrapperContract?.explicitlyForwardedTestIdTargetOffsets.has(elementStartOffset) || ownWrapperContract?.explicitlyForwardedTestIdTargetSfcOffsets.has(elementStartOffset);
9746
+ const isExplicitFallthroughTarget = !!ownWrapperContract && elementExplicitlyForwardsTestId(element, testIdAttribute, ownWrapperContract);
9756
9747
  if (!dependencies.isView && isExplicitFallthroughTarget) {
9757
9748
  return;
9758
9749
  }
@@ -12397,11 +12388,13 @@ const SETTINGS_STORAGE_KEY = "vpg-annotator-settings";
12397
12388
  const ANNOTATIONS_STORAGE_KEY = "vpg-annotator-annotations";
12398
12389
  const TOOLBAR_POSITION_STORAGE_KEY = "vpg-annotator-toolbar-position";
12399
12390
  const RUNTIME_GUARD = "__VUE_POM_GENERATOR_ANNOTATOR_RUNTIME__";
12391
+ const SUBMIT_HOOK = "__VUE_POM_GENERATOR_ANNOTATOR_SUBMIT__";
12400
12392
  const TOOLBAR_ICON_MARKUP = {
12401
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>',
12402
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>',
12403
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>',
12404
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>',
12405
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>',
12406
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>'
12407
12400
  };
@@ -12534,6 +12527,9 @@ async function copyTextToClipboard(text) {
12534
12527
  throw new Error("Clipboard copy failed.");
12535
12528
  }
12536
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
+ }
12537
12533
  class AnnotatorRuntime {
12538
12534
  options;
12539
12535
  settings;
@@ -12555,6 +12551,7 @@ class AnnotatorRuntime {
12555
12551
  currentPanelEl = null;
12556
12552
  toastTimer = null;
12557
12553
  toolbarPosition = null;
12554
+ submitting = false;
12558
12555
  constructor(options) {
12559
12556
  this.options = options;
12560
12557
  this.settings = this.loadSettings();
@@ -12620,12 +12617,15 @@ class AnnotatorRuntime {
12620
12617
  const copyButton = createIconButton("Copy annotations", "copy", () => this.copyAnnotations(), {
12621
12618
  disabled: this.annotations.length === 0
12622
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;
12623
12623
  const clearButton = createIconButton("Clear annotations", "clear", () => this.clearAnnotations(), {
12624
12624
  disabled: this.annotations.length === 0
12625
12625
  });
12626
12626
  const settingsButton = createIconButton("Annotator settings", "settings", () => this.openSettings());
12627
12627
  this.settingsButton = settingsButton;
12628
- this.toolbarEl.append(handle, selectButton, previewButton, copyButton, clearButton, settingsButton, count);
12628
+ this.toolbarEl.append(handle, selectButton, previewButton, copyButton, ...submitButton ? [submitButton] : [], clearButton, settingsButton, count);
12629
12629
  this.applyToolbarPosition();
12630
12630
  }
12631
12631
  renderMarkers() {
@@ -12855,6 +12855,7 @@ class AnnotatorRuntime {
12855
12855
  uiText: getNearbyText(element),
12856
12856
  locator: getNearbyLocator(element),
12857
12857
  domHint: getElementPath(element),
12858
+ pageUrl: window.location.href,
12858
12859
  pageX: rect.left + rect.width / 2,
12859
12860
  pageY: rect.top + window.scrollY
12860
12861
  };
@@ -13084,6 +13085,43 @@ class AnnotatorRuntime {
13084
13085
  this.showToast("Copy failed");
13085
13086
  }
13086
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
+ }
13087
13125
  showToast(message) {
13088
13126
  this.toastEl?.remove();
13089
13127
  if (this.toastTimer !== null) {
@@ -13105,13 +13143,12 @@ class AnnotatorRuntime {
13105
13143
  }
13106
13144
  }
13107
13145
  function mountAnnotatorClient(options) {
13108
- const runtimeWindow = window;
13109
- if (runtimeWindow[RUNTIME_GUARD]) {
13110
- return runtimeWindow[RUNTIME_GUARD];
13146
+ if (window[RUNTIME_GUARD]) {
13147
+ return window[RUNTIME_GUARD];
13111
13148
  }
13112
13149
  const runtime = new AnnotatorRuntime(options);
13113
13150
  runtime.mount();
13114
- runtimeWindow[RUNTIME_GUARD] = runtime;
13151
+ window[RUNTIME_GUARD] = runtime;
13115
13152
  return runtime;
13116
13153
  }
13117
13154
  let generating = false;