@immense/vue-pom-generator 1.0.100 → 1.0.102

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
@@ -298,6 +298,32 @@ if (import.meta.env.DEV) {
298
298
  }
299
299
  ```
300
300
 
301
+ ### Annotator overlay
302
+
303
+ The generator can inject its floating annotator overlay into either a Vite dev server
304
+ or a built application. Keep the environment decision in the Vite config and enable
305
+ the metadata and UI together:
306
+
307
+ ```ts
308
+ const pomConfig = defineVuePomGeneratorConfig({
309
+ runtime: {
310
+ annotator: {
311
+ enabled: true,
312
+ ui: {
313
+ enabled: true,
314
+ outputDetail: "forensic",
315
+ copyToClipboard: false,
316
+ showComponentTree: true,
317
+ },
318
+ },
319
+ },
320
+ });
321
+ ```
322
+
323
+ When `runtime.annotator.ui.enabled` is true, the same browser-only client is injected
324
+ for both `vite serve` and `vite build`. Disable it for production in your conditional
325
+ Vite config when the overlay is intended only for development or preview artifacts.
326
+
301
327
  ## Basic Nuxt setup
302
328
 
303
329
  ```ts
package/RELEASE_NOTES.md CHANGED
@@ -1,68 +1,47 @@
1
- I'll verify the actual commits and PR merge times in this release range before writing the notes.
2
-
3
- PR #63 merged at 22:00:03Z (before the window start of 22:06:13Z), so it's in the prior release.
4
- Only PR #62 is in range. Let me review the actual diff to write accurate notes.
5
-
6
- Now I have a complete picture. Only PR #62 falls in the release window (PR #63 merged before the
7
- window start). Here are the release notes:
8
-
9
1
  Highlights
10
2
 
11
- - The generator now infers semantic option identities automatically instead of relying solely on
12
- Vue's :key directive.
13
- - Radio inputs derive identity from :value and emit selectByValue(value); elements with
14
- role="option" derive identity from :data-value.
15
- - optionKeyAttribute is repurposed as an explicit override — map to "key" to opt back into Vue's
16
- reconciliation key, or to a custom bound attribute.
17
- - Missing identity bindings on recognized option controls now fail fast with a clear, actionable
18
- error instead of silently falling back.
3
+ - The annotator overlay can now be mounted in configured builds (vite build), not just vite serve
4
+ (#65).
5
+ - Browser-only safety: the annotator client is explicitly excluded from SSR builds, and SSR
6
+ transforms are skipped.
7
+ - New packed smoke checks verify the overlay ships in browser bundles, that no Node-only generator
8
+ code leaks into them, and that SSR builds stay clean.
19
9
 
20
10
  Changes
21
11
 
22
- Semantic option identity inference
23
-
24
- - Added getConventionalOptionIdentityAttribute to detect radio (:value) and ARIA option
25
- (:data-value) controls by role and tag.
26
- - Repeated radios generate selectByValue(value); repeated role="option" elements generate a keyed
27
- option action keyed off :data-value.
28
- - Other repeated controls continue to use Vue's :key identity unchanged.
29
-
30
- optionKeyAttribute override semantics
12
+ Runtime annotator
31
13
 
32
- - Explicit component configuration wins over semantic inference.
33
- - Mapping a component to "key" selects Vue's reconciliation :key; any other value must match a
34
- bound attribute on the option element.
35
- - A configured or conventional binding that is missing on a repeated option control throws a
36
- descriptive error with file/line context.
14
+ - Changed the annotator UI plugin's apply logic so it runs during vite serve or any non-SSR vite
15
+ build, instead of the previous serve-only restriction (#65).
16
+ - Skipped the annotator transform for SSR requests (transformOptions?.ssr) so the browser-only
17
+ client never reaches server bundles (#65).
18
+ - Updated option documentation: runtime.annotator and runtime.annotator.ui are no longer described
19
+ as dev-only; both vite serve and vite build inject the same browser-side overlay when enabled (#65).
37
20
 
38
- Documentation & types
21
+ Documentation
39
22
 
40
- - Updated README.md and plugin/types.ts to document the new conventions, override behavior, and
41
- fail-fast guarantee.
23
+ - Added an "Annotator overlay" section to the README showing how to enable metadata + UI together
24
+ in the Vite config, and how to keep it out of production via conditional config (#65).
42
25
 
43
- Tests
26
+ Tooling / CI
44
27
 
45
- - Added fixtures covering missing :value on mousedown handlers, option-change handlers without
46
- :value, and option elements missing :data-value.
47
- - Updated transform.test.ts and semantic-component-instances.test.ts to reflect the new identity
48
- resolution.
28
+ - Extended the packed smoke check to enable runtime.annotator and assert on built output: the
29
+ vpg-annotator-toolbar client must be present in browser assets, Node-only code (createRequire) must
30
+ be absent, and an SSR build (vite build --ssr) must neither include the client nor fail to evaluate
31
+ its emitted entry (#65).
49
32
 
50
33
  Breaking Changes
51
34
 
52
- - Repeated radios must bind :value. Repeated elements with role="option" must bind :data-value.
53
- Templates that previously relied on an implicit :key fallback for these controls will now fail
54
- generation with a directed error message.
55
- - Missing optionKeyAttribute overrides no longer silently fall back to :key. A configured binding
56
- is required on recognized option controls; absence is a hard error.
35
+ None.
57
36
 
58
37
  Pull Requests Included
59
38
 
60
- - ]8;id=md-co5m4y;https://github.com/immense/vue-pom-generator/pull/62#62 Infer semantic option identities]8;;]8;; (@dkattan)]8;;
39
+ - #65 fix: mount annotator in configured builds —
40
+ ]8;id=md-ba7lo3;https://github.com/immense/vue-pom-generator/pull/65https://github.com/immense/vue-pom-generator/pull/65]8;;
61
41
 
62
42
  Testing
63
43
 
64
- - npm test (42 files, 431 tests), npm run typecheck, npm run lint (0 errors), npm run smoke:pack,
65
- and npm run test:playwright (3 tests) all pass.
66
- - Validated against an ImmyBot generated-POM migration build (643 entries, 1,442 selectors) using a
67
- local packed dependency.
44
+ - Packed smoke check extended with new assertions: annotator client present in the browser build,
45
+ no Node-only generator code in the client, and the SSR build excludes the annotator and evaluates
46
+ cleanly.
68
47
 
package/dist/index.cjs CHANGED
@@ -2766,7 +2766,7 @@ function findTestIdAttribute(element, attributeName) {
2766
2766
  return staticAttr;
2767
2767
  return findDirectiveByName(element, "bind", attributeName) ?? null;
2768
2768
  }
2769
- function upsertAttribute(element, attributeName, value) {
2769
+ function upsertAttribute(element, attributeName, value, context) {
2770
2770
  element.props = element.props.filter((prop) => {
2771
2771
  if (prop.type === compilerCore.NodeTypes.ATTRIBUTE && prop.name === attributeName) {
2772
2772
  return false;
@@ -2777,6 +2777,7 @@ function upsertAttribute(element, attributeName, value) {
2777
2777
  return true;
2778
2778
  });
2779
2779
  if (value.kind === "template") {
2780
+ const expression = compilerCore.createSimpleExpression(`\`${value.template}\``, false, element.loc);
2780
2781
  element.props.push({
2781
2782
  type: compilerCore.NodeTypes.DIRECTIVE,
2782
2783
  name: "bind",
@@ -2787,7 +2788,10 @@ function upsertAttribute(element, attributeName, value) {
2787
2788
  constType: 0,
2788
2789
  loc: element.loc
2789
2790
  },
2790
- exp: compilerCore.createSimpleExpression(`\`${value.template}\``, false, element.loc),
2791
+ // Custom node transforms run after Vue's built-in expression transform.
2792
+ // Process generator-owned bindings explicitly so setup bindings, props,
2793
+ // and v-for/slot locals retain the same runtime scope as authored bindings.
2794
+ exp: context?.prefixIdentifiers ? compilerCore.processExpression(expression, context) : expression,
2791
2795
  modifiers: [],
2792
2796
  loc: element.loc
2793
2797
  });
@@ -3360,7 +3364,12 @@ Fix: make the element identifiable (e.g. add id/name/inner text or use a more sp
3360
3364
  }
3361
3365
  const normalizedParameters = selectorIsParameterized ? setPomParameter(parameters, selectorParameterName, keyTypeFromValues) : removePomParameter(parameters, selectorParameterName);
3362
3366
  if (addHtmlAttribute && !fromExisting) {
3363
- upsertAttribute(args.element, testIdAttribute, dataTestId);
3367
+ upsertAttribute(
3368
+ args.element,
3369
+ testIdAttribute,
3370
+ runtimeDataTestId,
3371
+ args.preferredRuntimeValue ? args.context : void 0
3372
+ );
3364
3373
  }
3365
3374
  const childComponentName = args.element.tag;
3366
3375
  const dataTestIdEntry = {
@@ -3398,13 +3407,18 @@ Fix: make the element identifiable (e.g. add id/name/inner text or use a more sp
3398
3407
  throw new Error(`[vue-pom-generator] runtime.annotator.enabled requires element source locations for ${args.componentName}.`);
3399
3408
  }
3400
3409
  const metadataAttributePrefix = args.annotatorMetadata.metadataAttributePrefix;
3401
- upsertAttribute(args.element, args.annotatorMetadata.sourceAttribute, staticAttributeValue(`${filename}:${sourceLocation.line}:${sourceLocation.column}`));
3402
- upsertAttribute(args.element, `${metadataAttributePrefix}-component`, staticAttributeValue(args.componentName));
3403
- upsertAttribute(args.element, `${metadataAttributePrefix}-tag`, staticAttributeValue(args.element.tag));
3404
- upsertAttribute(args.element, `${metadataAttributePrefix}-testid`, runtimeDataTestId);
3405
- upsertAttribute(args.element, `${metadataAttributePrefix}-action`, staticAttributeValue(buildPomGeneratedActionName(dataTestIdEntry.pom)));
3406
- upsertAttribute(args.element, `${metadataAttributePrefix}-property`, staticAttributeValue(buildPomGeneratedPropertyName(dataTestIdEntry.pom)));
3407
- upsertAttribute(args.element, `${metadataAttributePrefix}-role`, staticAttributeValue(normalizedRole));
3410
+ upsertAttribute(args.element, args.annotatorMetadata.sourceAttribute, staticAttributeValue(`${filename}:${sourceLocation.line}:${sourceLocation.column}`), args.context);
3411
+ upsertAttribute(args.element, `${metadataAttributePrefix}-component`, staticAttributeValue(args.componentName), args.context);
3412
+ upsertAttribute(args.element, `${metadataAttributePrefix}-tag`, staticAttributeValue(args.element.tag), args.context);
3413
+ upsertAttribute(
3414
+ args.element,
3415
+ `${metadataAttributePrefix}-testid`,
3416
+ runtimeDataTestId,
3417
+ args.preferredRuntimeValue ? args.context : void 0
3418
+ );
3419
+ upsertAttribute(args.element, `${metadataAttributePrefix}-action`, staticAttributeValue(buildPomGeneratedActionName(dataTestIdEntry.pom)), args.context);
3420
+ upsertAttribute(args.element, `${metadataAttributePrefix}-property`, staticAttributeValue(buildPomGeneratedPropertyName(dataTestIdEntry.pom)), args.context);
3421
+ upsertAttribute(args.element, `${metadataAttributePrefix}-role`, staticAttributeValue(normalizedRole), args.context);
3408
3422
  }
3409
3423
  args.dependencies.childrenComponentSet.add(childComponentName);
3410
3424
  args.dependencies.usedComponentSet.add(childComponentName);
@@ -9363,7 +9377,10 @@ File: ${context.filename ?? "unknown"}:${loc.line}:${loc.column}`
9363
9377
  const propName = crossFileKeyRegistry.get(componentName);
9364
9378
  if (propName) {
9365
9379
  const fallbackExpr = buildSlotScopeFallbackKeyExpression(propName);
9366
- return toResolvedKeyInfo(fallbackExpr, fallbackExpr);
9380
+ const runtimeExpression = compilerCore.createSimpleExpression(fallbackExpr, false, element.loc);
9381
+ const selectorExpression = context.prefixIdentifiers ? compilerCore.processExpression(runtimeExpression, context) : runtimeExpression;
9382
+ const selectorSource = getVueExpressionSource(selectorExpression, "compiled", "content");
9383
+ return toResolvedKeyInfo(selectorSource, fallbackExpr);
9367
9384
  }
9368
9385
  }
9369
9386
  return null;
@@ -9399,7 +9416,7 @@ File: ${context.filename ?? "unknown"}:${loc.line}:${loc.column}`
9399
9416
  });
9400
9417
  const runtimeMarker = componentInstanceKeyInfo ? templateAttributeValue(`${componentName}-${componentInstanceKeyInfo.runtimeFragment}-${instanceName}-component`) : staticAttributeValue(`${componentName}-${instanceName}-component`);
9401
9418
  const selector = componentInstanceKeyInfo ? createPomStringPattern(`${componentName}-\${key}-${instanceName}-component`, "parameterized", ["key"]) : createPomStringPattern(`${componentName}-${instanceName}-component`, "static", []);
9402
- upsertAttribute(element, POM_INSTANCE_ATTRIBUTE, runtimeMarker);
9419
+ upsertAttribute(element, POM_INSTANCE_ATTRIBUTE, runtimeMarker, context);
9403
9420
  const slotTemplate = getContainedInSlotTemplateNode(element, hierarchyMap);
9404
9421
  const slotName = slotTemplate ? getSlotNameFromTemplate(slotTemplate) : null;
9405
9422
  const slotOwner = slotTemplate ? getNearestComponentAncestor(slotTemplate, hierarchyMap, isComponentLikeTag2) : null;
@@ -9571,7 +9588,7 @@ Existing ${attrLabel}: ${JSON.stringify(existing.value)}
9571
9588
  Fix: remove the explicit ${attrLabel}, or change existingIdBehavior to "overwrite" or "error".`
9572
9589
  );
9573
9590
  }
9574
- upsertAttribute(element, "option-data-testid-prefix", optionDataTestIdPrefixValue);
9591
+ upsertAttribute(element, "option-data-testid-prefix", optionDataTestIdPrefixValue, context);
9575
9592
  }
9576
9593
  const nativeRole = resolvedNativeWrappers[element.tag]?.role ?? element.tag;
9577
9594
  const wrapperHintCandidates = [
@@ -10980,7 +10997,9 @@ function createAnnotatorUiPlugin(options) {
10980
10997
  });
10981
10998
  return {
10982
10999
  name: "vue-pom-generator:annotator-ui",
10983
- apply: "serve",
11000
+ apply(config, { command }) {
11001
+ return command === "serve" || !config.build?.ssr;
11002
+ },
10984
11003
  resolveId(id) {
10985
11004
  if (id === ANNOTATOR_CLIENT_VIRTUAL_ID) {
10986
11005
  return ANNOTATOR_CLIENT_RESOLVED_ID;
@@ -10996,8 +11015,8 @@ function createAnnotatorUiPlugin(options) {
10996
11015
  ""
10997
11016
  ].join("\n");
10998
11017
  },
10999
- transform(code, id) {
11000
- if (!options.enabled) {
11018
+ transform(code, id, transformOptions) {
11019
+ if (!options.enabled || transformOptions?.ssr) {
11001
11020
  return null;
11002
11021
  }
11003
11022
  const normalizedId = normalizePathSeparators(id);