@immense/vue-pom-generator 1.0.12 → 1.0.14

package/RELEASE_NOTES.md

@@ -1,28 +1,39 @@
-● ## Highlights
+● ```markdown
+  # v1.0.14
 
-  - Fixed component name conversion to properly use PascalCase in TypeScript class declarations
-  - Improved test suite by removing invalid `aggregated` option from test calls
-  - Added PR release-notes preview comments to streamline the release process
+  ## Highlights
+
+  - **Animated cursor overlay** for Playwright recordings with enhanced visual feedback
+  - Added comprehensive PomElement wrapper design and implementation documentation
+  - Enhanced Pointer component with 249 lines of improvements
+  - Automated PR release notes preview comments via GitHub Actions
 
   ## Changes
 
-  **Bug Fixes**
-  - Convert component names to PascalCase in TypeScript class declarations
-  - Remove invalid `aggregated` option from `GenerateFilesOptions` call in tests
+  ### Features
+  - Animated cursor overlay for Playwright recordings to improve test visualization
+  - Enhanced `class-generation/Pointer.ts` with significant improvements (249 lines)
+
+  ### Documentation
+  - Added PomElement wrapper design document
+  (`docs/plans/2026-03-03-pom-element-wrapper-design.md`)
+  - Added PomElement wrapper implementation plan
+  (`docs/plans/2026-03-03-pom-element-wrapper-implementation.md`)
 
-  **CI/Tooling**
-  - Add automated PR release-notes preview comments
+  ### Automation
+  - PR release notes preview comments automatically generated on pull requests
 
   ## Breaking Changes
 
-  None.
+  None
 
   ## Pull Requests Included
 
-  - [#1](https://github.com/immense/vue-pom-generator/pull/1) Add PR release-notes preview
-  comments (@dkattan)
+  - #1 Add PR release-notes preview comments (https://github.com/immense/vue-pom-generator/pull/1)
+   by @dkattan
 
   ## Testing
 
-  Test coverage expanded with 70 new lines added to `class-generation-coverage.test.ts`.
+  Testing details not provided in release window.
+  ```
 

package/class-generation/Pointer.ts

@@ -1,39 +1,138 @@
 import type { PwLocator, PwPage } from "./playwright-types";
 
+// ---------------------------------------------------------------------------
+// Cursor visual overlay helpers
+// ---------------------------------------------------------------------------
+
+const __PW_CURSOR_ID__ = "__pw_cursor__";
+
+// A minimal 16×24 arrow cursor encoded as a base64 PNG.
+const __PW_CURSOR_PNG__ =
+	"data:image/png;base64,"
+	+ "iVBORw0KGgoAAAANSUhEUgAAABQAAAAeCAQAAACGG/bgAAAAAmJLR0QA/4ePzL8AAAAJcEhZcwAA"
+	+ "HsYAAB7GAZEt8iwAAAAHdElNRQfgAwgMIwdxU/i7AAABZklEQVQ4y43TsU4UURSH8W+XmYwkS2I0"
+	+ "9CRKpKGhsvIJjG9giQmliHFZlkUIGnEF7KTiCagpsYHWhoTQaiUUxLixYZb5KAAZZhbunu7O/PKf"
+	+ "e+fcA+/pqwb4DuximEqXhT4iI8dMpBWEsWsuGYdpZFttiLSSgTvhZ1W/SvfO1CvYdV1kPghV68a3"
+	+ "0zzUWZH5pBqEui7dnqlFmLoq0gxC1XfGZdoLal2kea8ahLoqKXNAJQBT2yJzwUTVt0bS6ANqy1ga"
+	+ "VCEq/oVTtjji4hQVhhnlYBH4WIJV9vlkXLm+10R8oJb79Jl1j9UdazJRGpkrmNkSF9SOz2T71s7M"
+	+ "SIfD2lmmfjGSRz3hK8l4w1P+bah/HJLN0sys2JSMZQB+jKo6KSc8vLlLn5ikzF4268Wg2+pPOWW6"
+	+ "ONcpr3PrXy9VfS473M/D7H+TLmrqsXtOGctvxvMv2oVNP+Av0uHbzbxyJaywyUjx8TlnPY2YxqkD"
+	+ "dAAAAABJRU5ErkJggg==";
+
+// Per-page cursor position (viewport coords). WeakMap so pages can be GC'd.
+const __pw_cursor_positions__ = new WeakMap<object, { x: number; y: number }>();
+
+function __pw_get_cursor_pos__(page: PwPage): { x: number; y: number } {
+	return __pw_cursor_positions__.get(page as object) ?? { x: 0, y: 0 };
+}
+
+function __pw_set_cursor_pos__(page: PwPage, x: number, y: number): void {
+	__pw_cursor_positions__.set(page as object, { x, y });
+}
+
+async function __pw_ensure_cursor__(page: PwPage): Promise<void> {
+	const exists = await page.evaluate(
+		(id: string) => document.getElementById(id) != null,
+		__PW_CURSOR_ID__,
+	);
+	if (exists) return;
+
+	// Reset tracked position for this page.
+	__pw_set_cursor_pos__(page, 0, 0);
+
+	await page.evaluate(
+		({ id, src }: { id: string; src: string }) => {
+			const img = document.createElement("img");
+			img.setAttribute("src", src);
+			img.setAttribute("id", id);
+			// position:fixed keeps coordinates viewport-relative (matching Playwright boundingBox).
+			img.setAttribute(
+				"style",
+				"position:fixed;z-index:2147483647;pointer-events:none;left:0;top:0;transform-origin:0 0;",
+			);
+			document.body.appendChild(img);
+		},
+		{ id: __PW_CURSOR_ID__, src: __PW_CURSOR_PNG__ },
+	);
+}
+
+// ---------------------------------------------------------------------------
+// Animation options
+// ---------------------------------------------------------------------------
+
 export interface PlaywrightAnimationOptions {
 	/**
-	 * When false, cursor animations are disabled (but clicks/fills still happen).
-	 *
+	 * Set to false to disable all animations and delays. Clicks/fills still happen.
 	 * Default: true
 	 */
 	enabled?: boolean;
 
 	/**
-	 * Extra delay in ms before performing the action.
-	 *
+	 * Extra delay (ms) added before every action on top of per-action delays.
 	 * Default: 0
 	 */
 	extraDelayMs?: number;
+
+	/** Visual cursor / pointer-movement configuration. */
+	pointer?: {
+		/**
+		 * Duration of the CSS-transition cursor glide in ms.
+		 * Set to 0 to teleport the cursor without animation.
+		 * Default: 250
+		 */
+		durationMilliseconds?: number;
+
+		/**
+		 * CSS transition timing function for the cursor glide.
+		 * Default: "ease-in-out"
+		 */
+		transitionStyle?: "linear" | "ease" | "ease-in" | "ease-out" | "ease-in-out";
+
+		/**
+		 * Delay (ms) passed to element.click({ delay }) for a realistic press.
+		 * Default: 0
+		 */
+		clickDelayMilliseconds?: number;
+	};
+
+	/** Keyboard / typing configuration. */
+	keyboard?: {
+		/**
+		 * Delay between keystrokes in ms – makes typing visible on screen / in video.
+		 * Default: 100
+		 */
+		typeDelayMilliseconds?: number;
+	};
 }
 
-let animationOptions: PlaywrightAnimationOptions = { enabled: true, extraDelayMs: 0 };
+let animationOptions: PlaywrightAnimationOptions = {
+	enabled: true,
+	extraDelayMs: 0,
+	pointer: { durationMilliseconds: 250, transitionStyle: "ease-in-out", clickDelayMilliseconds: 0 },
+	keyboard: { typeDelayMilliseconds: 100 },
+};
 
 export function setPlaywrightAnimationOptions(options: PlaywrightAnimationOptions): void {
 	animationOptions = {
 		enabled: options?.enabled ?? true,
 		extraDelayMs: options?.extraDelayMs ?? 0,
+		pointer: {
+			durationMilliseconds: options?.pointer?.durationMilliseconds ?? 250,
+			transitionStyle: options?.pointer?.transitionStyle ?? "ease-in-out",
+			clickDelayMilliseconds: options?.pointer?.clickDelayMilliseconds ?? 0,
+		},
+		keyboard: {
+			typeDelayMilliseconds: options?.keyboard?.typeDelayMilliseconds ?? 100,
+		},
 	};
 }
 
 export interface AfterPointerClickInfo {
-	/**
-	 * Resolved test id from the clicked element (if present).
-	 */
+	/** Resolved test id from the clicked element (if present). */
 	testId?: string;
 
 	/**
-	 * Whether the click should be considered “instrumented”.
-	 *
+	 * Whether the click should be considered "instrumented".
 	 * BasePage uses this flag to decide whether to wait for the injected click event.
 	 */
 	instrumented: boolean;
@@ -43,6 +142,10 @@ export type AfterPointerClick = (info: AfterPointerClickInfo) => void | Promise<
 
 type ElementTarget = string | PwLocator;
 
+// ---------------------------------------------------------------------------
+// Pointer class
+// ---------------------------------------------------------------------------
+
 export class Pointer {
 	private readonly page: PwPage;
 	private readonly testIdAttribute: string;
@@ -73,35 +176,118 @@ export class Pointer {
 	): Promise<void> {
 		const locator = this.toLocator(target);
 
-		// Best-effort “animation”: make sure the element is scrolled into view and add a delay.
 		try {
 			await locator.first().scrollIntoViewIfNeeded();
 		}
 		catch {
-			// If the element detaches during navigation, let the subsequent click/fill surface the error.
+			// Element may detach during navigation; let the subsequent action surface the error.
 		}
 
-		const totalDelay = Math.max(0, delayMs) + Math.max(0, animationOptions.extraDelayMs ?? 0);
-		if (animationOptions.enabled !== false && totalDelay > 0) {
-			await this.page.waitForTimeout(totalDelay);
+		const opts = animationOptions;
+		const animEnabled = opts.enabled !== false;
+
+		if (!animEnabled) {
+			// Fast path: no animations.
+			const extraDelay = Math.max(0, opts.extraDelayMs ?? 0);
+			if (extraDelay > 0) await this.page.waitForTimeout(extraDelay);
+
+			let clickedTestId: string | undefined;
+			if (executeClick) {
+				try { clickedTestId = await this.getTestId(locator); } catch { /* noop */ }
+				await locator.first().click({ force: true });
+			}
+			if (options?.afterClick) {
+				await options.afterClick({ testId: clickedTestId, instrumented: Boolean(clickedTestId) });
+			}
+			return;
 		}
 
+		// --- Animated path ---
+		const moveDurationMs = opts.pointer?.durationMilliseconds ?? 250;
+		const transitionStyle = opts.pointer?.transitionStyle ?? "ease-in-out";
+		const clickDelayMs = opts.pointer?.clickDelayMilliseconds ?? 0;
+		const extraDelayMs = Math.max(0, opts.extraDelayMs ?? 0);
+		const actionDelayMs = Math.max(0, delayMs);
+
+		// Inject the visual cursor if it doesn't exist yet.
+		await __pw_ensure_cursor__(this.page);
+
+		// Move the cursor to the target element.
+		const box = await locator.first().boundingBox();
+		if (box) {
+			const endX = box.x + box.width / 2;
+			const endY = box.y + box.height / 2;
+			const { x: startX, y: startY } = __pw_get_cursor_pos__(this.page);
+			const distance = Math.sqrt((endX - startX) ** 2 + (endY - startY) ** 2);
+
+			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;
+					}) => {
+						const el = document.getElementById(id);
+						if (!el) return;
+						el.style.transition = "";
+						el.style.willChange = "left, top";
+						el.style.left = `${sx}px`;
+						el.style.top = `${sy}px`;
+						// Force reflow so the browser registers the start position before transitioning.
+						void el.offsetWidth;
+						el.style.transition = `left ${dur}ms ${style}, top ${dur}ms ${style}`;
+						el.style.left = `${ex}px`;
+						el.style.top = `${ey}px`;
+					},
+					{ 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);
+			}
+			else {
+				// Teleport (distance 0 or duration 0).
+				await this.page.evaluate(
+					({ id, x, y }: { id: string; x: number; y: number }) => {
+						const el = document.getElementById(id);
+						if (el) { el.style.left = `${x}px`; el.style.top = `${y}px`; }
+					},
+					{ id: __PW_CURSOR_ID__, x: endX, y: endY },
+				);
+			}
+
+			__pw_set_cursor_pos__(this.page, endX, endY);
+		}
+
+		// Apply action delay + extra delay.
+		const totalDelay = actionDelayMs + extraDelayMs;
+		if (totalDelay > 0) await this.page.waitForTimeout(totalDelay);
+
 		let clickedTestId: string | undefined;
 		if (executeClick) {
-			try {
-				clickedTestId = await this.getTestId(locator);
+			// Brief scale-down "press" animation on the cursor image.
+			if (moveDurationMs > 0) {
+				const pressDur = Math.max(80, Math.round(moveDurationMs / 3));
+				await this.page.evaluate(
+					({ id, dur }: { id: string; dur: number }) => {
+						const el = document.getElementById(id);
+						if (el) {
+							el.style.transition = `transform ${dur}ms`;
+							el.style.transform = "scale(0.6)";
+							setTimeout(() => {
+								el.style.transition = `transform ${dur}ms`;
+								el.style.transform = "scale(1)";
+							}, dur);
+						}
+					},
+					{ id: __PW_CURSOR_ID__, dur: pressDur },
+				);
 			}
-			catch {
-				clickedTestId = undefined;
-			}
-			await locator.first().click({ force: true });
+
+			try { clickedTestId = await this.getTestId(locator); } catch { /* noop */ }
+			await locator.first().click({ delay: clickDelayMs, force: true });
 		}
 
 		if (options?.afterClick) {
-			await options.afterClick({
-				testId: clickedTestId,
-				instrumented: Boolean(clickedTestId),
-			});
+			await options.afterClick({ testId: clickedTestId, instrumented: Boolean(clickedTestId) });
 		}
 	}
 
@@ -115,10 +301,19 @@ export class Pointer {
 			afterClick?: AfterPointerClick;
 		},
 	): Promise<void> {
-		// Reuse the click flow so the afterClick callback observes the click.
+		// Animate cursor + click first.
 		await this.animateCursorToElement(target, executeClick, delayMs, annotationText, options);
 
 		const locator = this.toLocator(target);
-		await locator.first().fill(text);
+		const typeDelayMs = animationOptions.keyboard?.typeDelayMilliseconds ?? 100;
+
+		if (animationOptions.enabled !== false && typeDelayMs > 0) {
+			// Clear existing content, then type character-by-character so keystrokes are visible.
+			await locator.first().clear();
+			await this.page.keyboard.type(text, { delay: typeDelayMs });
+		}
+		else {
+			await locator.first().fill(text);
+		}
 	}
 }

package/class-generation/index.ts

@@ -603,7 +603,25 @@ function generateAggregatedCSharpFiles(
       const baseGetterName = upperFirst(pom.getterNameOverride ?? pom.methodName);
       const locatorName = baseGetterName.endsWith(roleSuffix) ? baseGetterName : `${baseGetterName}${roleSuffix}`;
       const testIdExpr = toCSharpTestIdExpression(pom.formattedDataTestId);
-      const { signature, argNames } = formatCSharpParams(pom.params);
+
+      // Ensure all template variables referenced in formattedDataTestId (e.g. `${key}`)
+      // appear in the C# method signature.  utils.ts may omit `key` for input/select
+      // elements even when the test ID is dynamic, causing CS0103 compile errors.
+      const templateVarMatches = [...pom.formattedDataTestId.matchAll(/\$\{(\w+)\}/g)];
+      const templateVars = templateVarMatches.map(m => m[1]);
+      const augmentedParams: Record<string, string> = { ...pom.params };
+      for (const v of templateVars) {
+        if (!Object.prototype.hasOwnProperty.call(augmentedParams, v)) {
+          augmentedParams[v] = "string";
+        }
+      }
+      // Place template vars first so they precede text/value/annotationText.
+      const orderedParams: Record<string, string> = Object.fromEntries([
+        ...templateVars.map(v => [v, augmentedParams[v]] as [string, string]),
+        ...Object.entries(augmentedParams).filter(([k]) => !templateVars.includes(k)),
+      ]);
+
+      const { signature, argNames } = formatCSharpParams(orderedParams);
       const args = argNames.join(", ");
 
       const allTestIds = [pom.formattedDataTestId, ...(pom.alternateFormattedDataTestIds ?? [])]

package/dist/index.cjs

@@ -1992,18 +1992,18 @@ Fix: make the element identifiable (e.g. add id/name/inner text or use a more sp
     case "input":
       params.text = "string";
       params.annotationText = 'string = ""';
-      delete params.key;
+      if (!isKeyed) delete params.key;
       break;
     case "select":
       params.value = "string";
       params.annotationText = 'string = ""';
-      delete params.key;
+      if (!isKeyed) delete params.key;
       break;
     case "vselect":
       params.value = "string";
       params.timeOut = "number = 500";
       params.annotationText = 'string = ""';
-      delete params.key;
+      if (!isKeyed) delete params.key;
       break;
     case "radio":
       params.annotationText = 'string = ""';
@@ -2071,11 +2071,11 @@ Fix: make the element identifiable (e.g. add id/name/inner text or use a more sp
     }
     switch (role) {
       case "input":
-        return { params: 'text: string, annotationText: string = ""', argNames: ["text", "annotationText"] };
+        return needsKey2 ? { params: `key: ${keyType}, text: string, annotationText: string = ""`, argNames: ["key", "text", "annotationText"] } : { params: 'text: string, annotationText: string = ""', argNames: ["text", "annotationText"] };
       case "select":
-        return { params: 'value: string, annotationText: string = ""', argNames: ["value", "annotationText"] };
+        return needsKey2 ? { params: `key: ${keyType}, value: string, annotationText: string = ""`, argNames: ["key", "value", "annotationText"] } : { params: 'value: string, annotationText: string = ""', argNames: ["value", "annotationText"] };
       case "vselect":
-        return { params: "value: string, timeOut = 500", argNames: ["value", "timeOut"] };
+        return needsKey2 ? { params: `key: ${keyType}, value: string, timeOut = 500`, argNames: ["key", "value", "timeOut"] } : { params: "value: string, timeOut = 500", argNames: ["value", "timeOut"] };
       case "radio":
         return needsKey2 ? { params: `key: ${keyType}, annotationText: string = ""`, argNames: ["key", "annotationText"] } : { params: 'annotationText: string = ""', argNames: ["annotationText"] };
       default:
@@ -3084,7 +3084,19 @@ function generateAggregatedCSharpFiles(componentHierarchyMap, outDir, options =
       const baseGetterName = upperFirst(pom.getterNameOverride ?? pom.methodName);
       const locatorName = baseGetterName.endsWith(roleSuffix) ? baseGetterName : `${baseGetterName}${roleSuffix}`;
       const testIdExpr = toCSharpTestIdExpression(pom.formattedDataTestId);
-      const { signature, argNames } = formatCSharpParams(pom.params);
+      const templateVarMatches = [...pom.formattedDataTestId.matchAll(/\$\{(\w+)\}/g)];
+      const templateVars = templateVarMatches.map((m) => m[1]);
+      const augmentedParams = { ...pom.params };
+      for (const v of templateVars) {
+        if (!Object.prototype.hasOwnProperty.call(augmentedParams, v)) {
+          augmentedParams[v] = "string";
+        }
+      }
+      const orderedParams = Object.fromEntries([
+        ...templateVars.map((v) => [v, augmentedParams[v]]),
+        ...Object.entries(augmentedParams).filter(([k]) => !templateVars.includes(k))
+      ]);
+      const { signature, argNames } = formatCSharpParams(orderedParams);
       const args = argNames.join(", ");
       const allTestIds = [pom.formattedDataTestId, ...pom.alternateFormattedDataTestIds ?? []].filter((v, idx, arr) => v && arr.indexOf(v) === idx);
       if (pom.formattedDataTestId.includes("${")) {
@@ -4599,6 +4611,37 @@ function createTestIdTransform(componentName, componentHierarchyMap, nativeWrapp
     }
   };
 }
+function resolveComponentNameFromPath(options) {
+  const { projectRoot, viewsDirAbs, scanDirs, extraRoots = [] } = options;
+  const cleanFilename = options.filename.includes("?") ? options.filename.substring(0, options.filename.indexOf("?")) : options.filename;
+  const absFilename = path.isAbsolute(cleanFilename) ? cleanFilename : path.resolve(projectRoot, cleanFilename);
+  const rootBases = [projectRoot, ...extraRoots.filter((r) => r !== projectRoot)];
+  const roots = [viewsDirAbs, ...rootBases.flatMap((base) => scanDirs.map((d) => path.resolve(base, d)))];
+  for (const base of rootBases) {
+    for (const dir of scanDirs) {
+      const absDir = path.resolve(base, dir);
+      try {
+        const pagesDir = path.join(absDir, "pages");
+        if (fs.existsSync(pagesDir))
+          roots.push(pagesDir);
+        const componentsDir = path.join(absDir, "components");
+        if (fs.existsSync(componentsDir))
+          roots.push(componentsDir);
+      } catch {
+      }
+    }
+  }
+  const potentialRoots = Array.from(new Set(roots.map((r) => path.normalize(r)))).sort((a, b) => b.length - a.length);
+  for (const root of potentialRoots) {
+    if (absFilename.startsWith(root + path.sep) || absFilename === root) {
+      const rel = path.relative(root, absFilename);
+      const parsed = path.parse(rel);
+      const segments = path.join(parsed.dir, parsed.name);
+      return toPascalCase(segments);
+    }
+  }
+  return toPascalCase(path.parse(absFilename).name);
+}
 function createDevProcessorPlugin(options) {
   const {
     nativeWrappers,
@@ -4717,7 +4760,13 @@ function createDevProcessorPlugin(options) {
         const existing = filePathToComponentName.get(normalized);
         if (existing)
           return existing;
-        const name = path.basename(normalized, ".vue");
+        const name = resolveComponentNameFromPath({
+          filename: normalized,
+          projectRoot: projectRootRef.current,
+          viewsDirAbs: getViewsDirAbs(),
+          scanDirs,
+          extraRoots: [process.cwd()]
+        });
         filePathToComponentName.set(normalized, name);
         return name;
       };
@@ -5202,41 +5251,13 @@ function createVuePluginWithTestIds(options) {
     getProjectRoot
   } = options;
   const getComponentNameFromPath = (filename) => {
-    const cleanPath = filename.includes("?") ? filename.substring(0, filename.indexOf("?")) : filename;
-    const projectRoot = getProjectRoot();
-    const absFilename = path.isAbsolute(cleanPath) ? cleanPath : path.resolve(projectRoot, cleanPath);
-    const viewsDirAbs = getViewsDirAbs();
-    const roots = [viewsDirAbs, ...scanDirs.map((d) => path.resolve(projectRoot, d))];
-    for (const dir of scanDirs) {
-      const absDir = path.resolve(projectRoot, dir);
-      try {
-        const pagesDir = path.join(absDir, "pages");
-        if (fs.existsSync(pagesDir)) {
-          roots.push(pagesDir);
-        }
-        const componentsDir = path.join(absDir, "components");
-        if (fs.existsSync(componentsDir)) {
-          roots.push(componentsDir);
-        }
-      } catch {
-      }
-    }
-    const potentialRoots = Array.from(new Set(roots.map((r) => path.normalize(r)))).sort((a, b) => b.length - a.length);
-    let componentName = "";
-    for (const root of potentialRoots) {
-      if (absFilename.startsWith(root + path.sep) || absFilename === root) {
-        const rel = path.relative(root, absFilename);
-        const parsed = path.parse(rel);
-        const segments = path.join(parsed.dir, parsed.name);
-        componentName = toPascalCase(segments);
-        break;
-      }
-    }
-    if (!componentName) {
-      const parsed = path.parse(absFilename);
-      componentName = toPascalCase(parsed.name);
-    }
-    return componentName;
+    return resolveComponentNameFromPath({
+      filename,
+      projectRoot: getProjectRoot(),
+      viewsDirAbs: getViewsDirAbs(),
+      scanDirs,
+      extraRoots: [process.cwd()]
+    });
   };
   const isFileInScope = (filename) => {
     if (!filename)