@immense/vue-pom-generator 1.0.47 → 1.0.49

package/README.md

@@ -3,7 +3,7 @@
 `@immense/vue-pom-generator` is a Vite plugin for Vue 3 that does two compile-time jobs:
 
 1. it injects a test-id attribute into interactive elements in `.vue` templates
-2. it turns the collected ids into an aggregated Page Object Model library for Playwright, with optional Playwright fixtures and optional C# output
+2. it turns the collected ids into a Page Object Model library for Playwright, with aggregated or split TypeScript output, optional Playwright fixtures, and optional C# output
 
 If you already use Playwright with `getByTestId`, the point is simple: this package removes the repetitive work of keeping test ids in sync with Vue templates and then hand-writing page objects around those ids.
 
@@ -11,7 +11,7 @@ If you already use Playwright with `getByTestId`, the point is simple: this pack
 
 - **Injects test ids during Vue compilation, not at runtime.** It hooks into the Vue template compiler and rewrites the compiled template output.
 - **Uses real template signals to name ids and methods.** Click handlers, `v-model`, `id`/`name`, `:to`, wrapper configuration, and a few targeted fallbacks all feed the generated API.
-- **Generates one aggregated TypeScript POM file** plus a stable `index.ts` barrel.
+- **Generates TypeScript POM output as either one aggregate or split per class, always with a stable `index.ts` barrel.**
 - **Can generate Playwright fixtures** so tests can request `userListPage` instead of constructing `new UserListPage(page)` manually.
 - **Can fail fast on unnameable wrapper-button actions** so complex inline handlers do not silently degrade into low-signal generated APIs.
 - **Can emit a single C# POM file** for Playwright .NET consumers.
@@ -234,6 +234,7 @@ const pomConfig = defineVuePomGeneratorConfig({
     },
     playwright: {
       fixtures: true,
+      outputStructure: "split",
       customPoms: {
         dir: "tests/playwright/pom/custom",
         importAliases: {
@@ -294,9 +295,13 @@ By default, generation writes to `tests/playwright/__generated__`.
 
 TypeScript output:
 
-- `page-object-models.g.ts` — aggregated generated classes
-- `index.ts` — stable barrel re-exporting `page-object-models.g`
-- `_pom-runtime/` — copied runtime support files used by the aggregated output
+- default (`generation.playwright.outputStructure: "aggregated"`):
+  - `page-object-models.g.ts` — aggregated generated classes
+  - `index.ts` — stable barrel re-exporting `page-object-models.g`
+- split mode (`generation.playwright.outputStructure: "split"`):
+  - one `*.g.ts` file per generated class
+  - `index.ts` — stable barrel re-exporting the split files
+- `_pom-runtime/` — copied runtime support files used by the generated TypeScript output in either mode
 
 Optional Playwright fixture output:
 
@@ -313,7 +318,7 @@ If you emit outside a `__generated__` path, the generator also manages `.gitattr
 
 This is important if you are deciding whether the tool will fit into a real codebase.
 
-- **Dev server:** on startup, it scans the configured `scanDirs`, compiles each `.vue` file into a snapshot, writes the aggregated outputs once, then batches add/change/delete events and regenerates incrementally.
+- **Dev server:** on startup, it scans the configured `scanDirs`, compiles each `.vue` file into a snapshot, writes the configured TypeScript outputs once, then batches add/change/delete events and regenerates incrementally.
 - **Build:** it generates from the richest build pass it sees, which matters because Vite can run multiple passes (for example SSR plus client). The generator avoids letting a thinner pass clobber a richer one.
 - **Always-on virtual module:** `virtual:testids` is registered whether generation is enabled or disabled.
 - **Generation can be disabled:** `generation: false` still keeps compile-time test-id injection and the virtual module, but skips emitted POM files.
@@ -383,7 +388,7 @@ These two directories solve different problems.
 
 Default: `tests/playwright/pom/custom`
 
-This directory is for handwritten helper classes that the aggregated TypeScript output can import.
+This directory is for handwritten helper classes that the generated TypeScript output can import.
 
 It is the default helper directory even if you omit `generation.playwright.customPoms` entirely.
 
@@ -392,7 +397,7 @@ Actual current behavior:
 - the generator scans the directory **non-recursively**
 - it imports top-level `.ts` files only
 - it expects the file basename to match the exported class name (`Grid.ts` → `export class Grid {}`)
-- the helper files are imported into the generated aggregate; they are **not** automatically attached everywhere
+- the helper files are available to generated output; they are **not** automatically attached everywhere
 
 What it is for:
 
@@ -434,7 +439,7 @@ A typical override looks like this:
 
 ```ts
 // tests/playwright/pom/overrides/UserListPage.ts
-import { UserListPage as GeneratedUserListPage } from "../../__generated__/page-object-models.g";
+import { UserListPage as GeneratedUserListPage } from "../../__generated__";
 
 export class UserListPage extends GeneratedUserListPage {
   async openFirstUser() {
@@ -449,7 +454,10 @@ This is where most people need precision.
 
 ### Helper imports
 
-Every `.ts` file in `customPoms.dir` becomes an import in the aggregated TypeScript output.
+Every `.ts` file in `customPoms.dir` is available for import from the generated TypeScript output.
+
+- in aggregated mode, helper files become imports in the shared aggregate
+- in split mode, each generated file imports only the helpers it actually needs
 
 Benefits:
 
@@ -1037,6 +1045,17 @@ This object holds Playwright-specific additions on top of the generated TypeScri
   - `"path"` — if the string ends in `.ts` / `.tsx` / `.mts` / `.cts`, it is treated as a file path; otherwise as an output directory
   - `{ outDir }` — emit to a custom directory
 
+#### `generation.playwright.outputStructure`
+
+- **What it does:** Chooses whether generated TypeScript POMs are emitted as one aggregate or split per class.
+- **Why it exists:** very large generated files are harder to browse, inspect, and discover in editors.
+- **Benefit:** `"split"` keeps the same stable barrel and fixtures surface while making individual classes and methods easier to find.
+- **Without it:** the default is `"aggregated"`.
+- **Accepted values:**
+  - `"aggregated"` — emit `page-object-models.g.ts` plus `index.ts`
+  - `"split"` — emit one `*.g.ts` file per class plus `index.ts`
+- **Current limit:** this setting only affects the generated TypeScript Playwright output; C# output remains a single aggregated file.
+
 #### `generation.playwright.customPoms`
 
 - **What it does:** Configures handwritten helper imports and attachments.
@@ -1063,7 +1082,7 @@ This object holds Playwright-specific additions on top of the generated TypeScri
 #### `customPoms.importNameCollisionBehavior`
 
 - **What it does:** Controls how helper import names behave when they collide with generated class names.
-- **Why it exists:** aggregated output shares one import namespace.
+- **Why it exists:** generated files still need a conflict-free local import namespace.
 - **Benefit:** lets you fail hard or auto-alias based on team preference.
 - **Without it:** the default is `"error"`.
 

package/RELEASE_NOTES.md

@@ -1,49 +1,36 @@
-● ## Highlights
+● I'll gather the release data between v1.0.48 and HEAD to generate accurate release notes.
 
-  - **Fail-fast validation** for wrapper handlers that cannot be named, improving error detection
-  at build time
-  - Added comprehensive validation logic across plugin lifecycle (dev and build modes)
-  - Expanded test coverage with 54+ new test cases for handler naming scenarios
-  - Enhanced error reporting when anonymous or unnameable handlers are detected
-  - Updated documentation with new validation requirements and best practices
+● Based on the commit data, this is a focused release with one commit. Here are the release notes:
 
-  ## Changes
+  ---
+
+  ## Highlights
 
-  **Core Validation**
-  - Added fail-fast validation in `transform.ts` to detect unnameable wrapper handlers before
-  runtime
-  - Implemented handler name validation in `create-vue-pom-generator-plugins.ts` with detailed
-  error messages
-  - Added validation hooks in both `build-plugin.ts` and `dev-plugin.ts` for consistency across
-  modes
+  - **Enhanced Playwright visual debugging**: Cursor annotations now render properly during test
+  execution
+  - Improved test coverage with new Pointer test cases
+  - Better visual feedback for automated test runs
 
-  **Type System & API**
-  - Extended plugin types with new validation options and error handling interfaces
-  - Added support for configurable validation behavior in plugin options
+  ## Changes
 
-  **Testing**
-  - Added 54 new test cases in `options.test.ts` covering edge cases for handler naming
-  - Added 23 new tests in `transform.test.ts` for transformation validation
-  - Added 9 coverage tests in `utils-coverage.test.ts`
-  - Enhanced `dev-plugin-options.test.ts` with validation scenario tests
+  ### Fixes
+  - **Render Playwright annotations**: Fixed annotation rendering in the visual cursor overlay
+  system, ensuring annotation text displays correctly during animated pointer movements
 
-  **Documentation**
-  - Updated README.md with guidance on handler naming requirements and validation behavior
+  ### Tests
+  - Added comprehensive test coverage for Pointer annotation functionality
 
   ## Breaking Changes
 
-  - **Handler naming validation**: The plugin now throws errors when wrapper handlers cannot be
-  named (anonymous functions, computed property names, etc.). Code that previously compiled with
-  unnameable handlers will now fail at build time. Ensure all wrapper handlers have statically
-  determinable names.
+  None
 
   ## Pull Requests Included
 
-  - #11: feat: fail fast on unnameable wrapper handlers
-  (https://github.com/immense/vue-pom-generator/pull/11) by @dkattan
+  Based on the commit in this release, this appears to be a direct commit rather than a merged PR
+  within the specified time window.
 
   ## Testing
 
-  Comprehensive test coverage added with 80+ new test cases spanning handler naming validation,
-  transformation scenarios, plugin options, and edge case coverage.
+  - New test cases added to `tests/pointer.test.ts` validating annotation rendering
+  - Total test additions: 52 new lines of test code
 

package/class-generation/Pointer.ts

@@ -5,6 +5,7 @@ import type { PwLocator, PwPage } from "./playwright-types";
 // ---------------------------------------------------------------------------
 
 const __PW_CURSOR_ID__ = "__pw_cursor__";
+const __PW_CURSOR_ANNOTATION_ID__ = "__pw_cursor_annotation__";
 const __PW_EDITABLE_DESCENDANT_SELECTOR__
 	= "input, textarea, select, [contenteditable=''], [contenteditable='true'], [contenteditable]:not([contenteditable='false'])";
 
@@ -34,8 +35,9 @@ function __pw_set_cursor_pos__(page: PwPage, x: number, y: number): void {
 
 async function __pw_ensure_cursor__(page: PwPage): Promise<void> {
 	const exists = await page.evaluate(
-		(id: string) => document.getElementById(id) != null,
-		__PW_CURSOR_ID__,
+		({ cursorId, annotationId }: { cursorId: string; annotationId: string }) =>
+			document.getElementById(cursorId) != null && document.getElementById(annotationId) != null,
+		{ cursorId: __PW_CURSOR_ID__, annotationId: __PW_CURSOR_ANNOTATION_ID__ },
 	);
 	if (exists) return;
 
@@ -43,7 +45,7 @@ async function __pw_ensure_cursor__(page: PwPage): Promise<void> {
 	__pw_set_cursor_pos__(page, 0, 0);
 
 	await page.evaluate(
-		({ id, src }: { id: string; src: string }) => {
+		({ id, src, annotationId }: { id: string; src: string; annotationId: string }) => {
 			const img = document.createElement("img");
 			img.setAttribute("src", src);
 			img.setAttribute("id", id);
@@ -53,8 +55,32 @@ async function __pw_ensure_cursor__(page: PwPage): Promise<void> {
 				"position:fixed;z-index:2147483647;pointer-events:none;left:0;top:0;transform-origin:0 0;",
 			);
 			document.body.appendChild(img);
+
+			const annotation = document.createElement("div");
+			annotation.setAttribute("id", annotationId);
+			annotation.setAttribute(
+				"style",
+				[
+					"position:fixed",
+					"z-index:2147483647",
+					"pointer-events:none",
+					"left:18px",
+					"top:18px",
+					"max-width:320px",
+					"padding:6px 10px",
+					"border-radius:999px",
+					"background:rgba(15,23,42,0.92)",
+					"color:#f8fafc",
+					"font:600 13px/1.4 -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
+					"box-shadow:0 12px 30px rgba(15,23,42,0.35)",
+					"opacity:0",
+					"white-space:normal",
+					"transform:translate3d(0,0,0)",
+				].join(";"),
+			);
+			document.body.appendChild(annotation);
 		},
-		{ id: __PW_CURSOR_ID__, src: __PW_CURSOR_PNG__ },
+		{ id: __PW_CURSOR_ID__, src: __PW_CURSOR_PNG__, annotationId: __PW_CURSOR_ANNOTATION_ID__ },
 	);
 }
 
@@ -209,7 +235,7 @@ export class Pointer {
 		target: ElementTarget,
 		executeClick: boolean = true,
 		delayMs: number = 100,
-		_annotationText: string = "",
+		annotationText: string = "",
 		options?: {
 			afterClick?: AfterPointerClick;
 		},
@@ -248,6 +274,7 @@ export class Pointer {
 		const clickDelayMs = opts.pointer?.clickDelayMilliseconds ?? 0;
 		const extraDelayMs = Math.max(0, opts.extraDelayMs ?? 0);
 		const actionDelayMs = Math.max(0, delayMs);
+		const trimmedAnnotationText = annotationText.trim();
 
 		// Inject the visual cursor if it doesn't exist yet.
 		await __pw_ensure_cursor__(this.page);
@@ -263,22 +290,47 @@ export class Pointer {
 			if (moveDurationMs > 0 && distance > 0) {
 				// Glide the cursor image using a CSS transition.
 				await this.page.evaluate(
-					({ id, sx, sy, ex, ey, dur, style }: {
-						id: string; sx: number; sy: number; ex: number; ey: number; dur: number; style: string;
+					({ id, annotationId, sx, sy, ex, ey, dur, style, annotationText }: {
+						id: string; annotationId: string; sx: number; sy: number; ex: number; ey: number; dur: number; style: string; annotationText: string;
 					}) => {
 						const el = document.getElementById(id);
+						const annotation = document.getElementById(annotationId);
 						if (!el) return;
 						el.style.transition = "";
 						el.style.willChange = "left, top";
 						el.style.left = `${sx}px`;
 						el.style.top = `${sy}px`;
+						if (annotation) {
+							annotation.textContent = annotationText;
+							annotation.style.transition = "";
+							annotation.style.willChange = "left, top, opacity";
+							annotation.style.left = `${sx + 18}px`;
+							annotation.style.top = `${sy + 22}px`;
+							annotation.style.opacity = annotationText ? "1" : "0";
+						}
 						// Force reflow so the browser registers the start position before transitioning.
 						void el.offsetWidth;
+						void annotation?.offsetWidth;
 						el.style.transition = `left ${dur}ms ${style}, top ${dur}ms ${style}`;
 						el.style.left = `${ex}px`;
 						el.style.top = `${ey}px`;
+						if (annotation) {
+							annotation.style.transition = `left ${dur}ms ${style}, top ${dur}ms ${style}, opacity 120ms ease-in-out`;
+							annotation.style.left = `${ex + 18}px`;
+							annotation.style.top = `${ey + 22}px`;
+						}
+					},
+					{
+						id: __PW_CURSOR_ID__,
+						annotationId: __PW_CURSOR_ANNOTATION_ID__,
+						sx: startX,
+						sy: startY,
+						ex: endX,
+						ey: endY,
+						dur: moveDurationMs,
+						style: transitionStyle,
+						annotationText: trimmedAnnotationText,
 					},
-					{ id: __PW_CURSOR_ID__, sx: startX, sy: startY, ex: endX, ey: endY, dur: moveDurationMs, style: transitionStyle },
 				);
 				// Wait for the animation to finish.
 				await this.page.waitForTimeout(moveDurationMs + 25);
@@ -286,11 +338,18 @@ export class Pointer {
 			else {
 				// Teleport (distance 0 or duration 0).
 				await this.page.evaluate(
-					({ id, x, y }: { id: string; x: number; y: number }) => {
+					({ id, annotationId, x, y, annotationText }: { id: string; annotationId: string; x: number; y: number; annotationText: string }) => {
 						const el = document.getElementById(id);
 						if (el) { el.style.left = `${x}px`; el.style.top = `${y}px`; }
+						const annotation = document.getElementById(annotationId);
+						if (annotation) {
+							annotation.textContent = annotationText;
+							annotation.style.left = `${x + 18}px`;
+							annotation.style.top = `${y + 22}px`;
+							annotation.style.opacity = annotationText ? "1" : "0";
+						}
 					},
-					{ id: __PW_CURSOR_ID__, x: endX, y: endY },
+					{ id: __PW_CURSOR_ID__, annotationId: __PW_CURSOR_ANNOTATION_ID__, x: endX, y: endY, annotationText: trimmedAnnotationText },
 				);
 			}