@immense/vue-pom-generator 1.0.52 → 1.0.54

package/README.md

@@ -74,7 +74,7 @@ The generator does not use one naming trick. It layers several signals.
 - **Router links / `:to` bindings** can contribute route-based naming and typed navigation return types when the target can be resolved.
 - **Wrapper components** can be explicit (`nativeWrappers`) or inferred from simple local SFC templates.
 - **Fallback naming exists, but it is intentionally conservative.** That is why `generation.nameCollisionBehavior` exists.
-- **You can opt into stricter wrapper-action generation.** `errorBehavior: "error"` blocks button-like wrapper `:handler` expressions that the generator cannot turn into a semantic action name.
+- **Wrapper-action generation fails fast by default.** The generator blocks button-like wrapper `:handler` expressions that it cannot turn into a semantic action name; set `errorBehavior: "ignore"` if you explicitly want the old permissive fallback.
 
 Important limit: wrapper inference is helpful, not magical. The current implementation recursively inspects simple local SFC templates for the first inferable primitive (`input`, `textarea`, `select`, `button`, `vselect`, radio/checkbox inputs). It also recognizes some naming patterns like `*Button`. For anything more complex, configure `nativeWrappers` explicitly.
 
@@ -191,9 +191,10 @@ Exports:
 - `createVuePomGeneratorPlugins()`
 - `vuePomGenerator()` (alias)
 - `defineVuePomGeneratorConfig()`
+- `defineNuxtPomGeneratorConfig()`
 - `@immense/vue-pom-generator/eslint`
 
-## Basic Vite setup
+## Basic Vue/Vite setup
 
 ```ts
 import { defineConfig } from "vite";
@@ -208,7 +209,8 @@ const pomConfig = defineVuePomGeneratorConfig({
   injection: {
     attribute: "data-testid",
     viewsDir: "src/views",
-    scanDirs: ["src"],
+    componentDirs: ["src/components"],
+    layoutDirs: ["src/layouts"],
     wrapperSearchRoots: ["../shared-ui/src/components"],
     nativeWrappers: {
       AppButton: { role: "button" },
@@ -261,6 +263,29 @@ export default defineConfig({
 });
 ```
 
+## Basic Nuxt setup
+
+```ts
+import { defineNuxtConfig } from "nuxt/config";
+import { defineNuxtPomGeneratorConfig, vuePomGenerator } from "@immense/vue-pom-generator";
+
+const pomConfig = defineNuxtPomGeneratorConfig({
+  generation: {
+    outDir: "tests/playwright/__generated__",
+  },
+});
+
+export default defineNuxtConfig({
+  vite: {
+    plugins: [
+      ...vuePomGenerator(pomConfig),
+    ],
+  },
+});
+```
+
+Nuxt projects are auto-detected from standard project artifacts, and their pages/layouts/components are resolved from Nuxt's own config. That means custom page directories such as `dir.pages = "views"` come from `nuxt.config`, while component directories are picked up automatically from Nuxt conventions/config. `defineNuxtPomGeneratorConfig(...)` is optional, but it keeps the config surface Nuxt-specific at type-check time.
+
 ### Important Vite ownership rule
 
 By default, this package creates and returns its own `@vitejs/plugin-vue` instance.
@@ -289,7 +314,7 @@ export default defineConfig({
 });
 ```
 
-Nuxt-style routing also uses the resolved app-owned Vue plugin. In practice, if you use `generation.router.type: "nuxt"`, think in terms of external Vue plugin ownership.
+Nuxt-style routing also uses the resolved app-owned Vue plugin. In practice, Nuxt projects are auto-detected and use external Vue plugin ownership automatically.
 
 ## What gets generated
 
@@ -320,7 +345,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 configured TypeScript outputs once, then batches add/change/delete events and regenerates incrementally.
+- **Dev server:** on startup, it scans the configured Vue page/component/layout directories (or the directories resolved from Nuxt config in Nuxt mode), 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.
@@ -592,6 +617,7 @@ What it gives you:
 - lower-camel-case fixtures for component classes too
 - `pomFactory.create(Ctor)` for ad-hoc page-object construction inside tests
 - an `animation` option that wires the generated runtime's pointer settings
+- per-page `renderers` overrides so you can keep the simple default callout or swap in a custom pointer / callout overlay implementation such as the bundled `floating-ui-callout.ts` renderer
 
 Current caveats:
 
@@ -600,6 +626,12 @@ Current caveats:
 - component fixtures are skipped when their lower-camel-case name would collide with reserved Playwright fixture names such as `page`, `context`, `browser`, or `request`
 - an override class still needs a `new (page)`-compatible constructor because that is what fixtures call
 
+By default the runtime uses a simple red fallback bubble. The example below uses the optional floating-ui renderer so the callout can auto-place around nearby UI and point back to the target with an arrow.
+
+Example floating-ui callout sequence captured from the Playwright fixture coverage:
+
+![Pointer callout sequence](./docs/assets/pointer-callout-sequence.gif)
+
 ## TypeScript vs C# output
 
 ### TypeScript output
@@ -821,12 +853,12 @@ The sections below follow the actual `VuePomGeneratorPluginOptions` shape from `
 
 - **What it does:** Controls strict/error behavior for generator checks.
 - **Why it exists:** complex inline handlers can otherwise fall through to generic naming, which makes generated APIs harder to discover and review.
-- **Benefit:** `"error"` lets you opt into fail-fast behavior globally, while the object form lets you turn on only the checks you care about.
-- **Without it:** the default is `"ignore"`, so existing permissive fallback behavior remains in place.
+- **Benefit:** fail-fast behavior is the default, while `"ignore"` or the object form let you opt back into only the permissive checks you want.
+- **Without it:** the default is `"error"`, so unsupported button-wrapper handlers stop generation instead of silently falling back.
 - **Accepted values:**
   - `"ignore"` — keep permissive defaults for all supported checks
-  - `"error"` — enable error-on-failure behavior for all supported checks
-  - `{ missingSemanticNameBehavior: "error" }` — enable only the button-wrapper semantic-name check
+  - `"error"` — enable error-on-failure behavior for all supported checks (default)
+  - `{ missingSemanticNameBehavior: "ignore" }` — opt out only of the button-wrapper semantic-name check
 - **Current scope:** this first pass is intentionally narrow. The object form currently supports `missingSemanticNameBehavior`, which targets button-like wrappers with `:handler`; value/model-driven wrappers still use their existing naming flow.
 
 ### `injection`
@@ -857,6 +889,30 @@ The sections below follow the actual `VuePomGeneratorPluginOptions` shape from `
   injection: { viewsDir: "app/pages" }
   ```
 
+#### `injection.componentDirs`
+
+- **What it does:** Lists the directories that should be treated as reusable component roots.
+- **Why it exists:** Vue apps often keep components outside a single catch-all tree, and the generator needs explicit component roots now that generic scan lists are gone.
+- **Benefit:** component naming and filesystem supplementation stay aligned with the directories you actually consider components.
+- **Without it:** the generator uses `["src/components"]`.
+- **Example:**
+
+  ```ts
+  injection: { componentDirs: ["src/components", "../shared-ui/src/components"] }
+  ```
+
+#### `injection.layoutDirs`
+
+- **What it does:** Lists layout-style Vue directories that should be included in generation and naming.
+- **Why it exists:** some Vue apps keep shell components outside `views` and `components`, but still want them in the generated POM graph.
+- **Benefit:** layouts participate explicitly without falling back to a generic scan of unrelated folders.
+- **Without it:** the generator uses `["src/layouts"]`.
+- **Example:**
+
+  ```ts
+  injection: { layoutDirs: ["src/layouts"] }
+  ```
+
 #### `injection.nativeWrappers`
 
 - **What it does:** Describes wrapper components so the generator can treat them like native controls.
@@ -910,24 +966,12 @@ The sections below follow the actual `VuePomGeneratorPluginOptions` shape from `
   injection: { excludeComponents: ["LegacyWidget"] }
   ```
 
-#### `injection.scanDirs`
-
-- **What it does:** Sets which directories are scanned for `.vue` files when building the POM graph.
-- **Why it exists:** real projects rarely keep all SFCs under one folder, especially in Nuxt or monorepos.
-- **Benefit:** generation sees the same files your app actually uses.
-- **Without it:** the generator scans `src`.
-- **Example:**
-
-  ```ts
-  injection: { scanDirs: ["src", "components", "layouts"] }
-  ```
-
 #### `injection.wrapperSearchRoots`
 
-- **What it does:** Adds extra roots for wrapper inference outside `scanDirs`.
+- **What it does:** Adds extra roots for wrapper inference outside the configured page/component/layout directories.
 - **Why it exists:** wrapper components often live in sibling packages or shared UI workspaces.
 - **Benefit:** local wrapper inference can still work across package boundaries.
-- **Without it:** no extra wrapper lookup is done outside the scanned app directories.
+- **Without it:** no extra wrapper lookup is done outside the configured app directories.
 - **Example:**
 
   ```ts
@@ -1013,13 +1057,13 @@ If omitted, router introspection is off.
 
 #### `generation.router.type`
 
-- **What it does:** Chooses the router discovery strategy.
-- **Why it exists:** standard Vue-router apps and Nuxt file-based routing need different discovery paths.
-- **Benefit:** one config field covers both app styles.
+- **What it does:** Chooses the Vue-router discovery strategy for standard Vue apps.
+- **Why it exists:** some Vue apps want router introspection without any Nuxt integration.
+- **Benefit:** keeps Vue-router discovery explicit.
 - **Without it:** defaults to `"vue-router"`.
+- **Nuxt note:** Nuxt projects are auto-detected. Do not set `generation.router.type: "nuxt"`.
 - **Current options:**
   - `"vue-router"`
-  - `"nuxt"`
 
 #### `generation.router.moduleShims`
 

package/RELEASE_NOTES.md

@@ -1,43 +1,54 @@
-● # Release Notes: v1.0.52
-
-  ## Highlights
-
-  - Relaxed Vite peer dependency constraint to support newer Vite versions
-  - Improved AST-based handling of nullish coalescing in key expressions
-  - Fixed repository-wide lint failures and updated lint configuration
-  - Enhanced test coverage for utility functions and transform edge cases
+● ## Highlights
+
+  - **Zero runtime dependencies**: Eliminated all runtime dependencies for smaller bundle size and
+   reduced version conflicts
+  - **Pluggable callout renderer architecture**: Extracted floating-ui implementation into
+  swappable renderer system
+  - **Stricter semantic naming**: Unnameable wrapper handlers now fail fast by default instead of
+  silently succeeding
+  - **Streamlined callout placement pipeline**: Refactored pointer callout rendering for improved
+  maintainability
+  - **Removed peer dependencies**: No longer requires `vue`, `vitest`, or `@vue/shared` as peer
+  dependencies
 
   ## Changes
 
-  **Dependencies**
-  - Relaxed Vite peer dependency version range to improve compatibility with downstream projects
+  ### Dependencies
+  - Eliminated all runtime dependencies
+  ([#9](https://github.com/immense/vue-pom-generator/pull/9))
+  - Removed `vue`, `vitest`, and `@vue/shared` peer dependencies
+  - Updated package structure for zero external runtime requirements
 
-  **Code Quality & Linting**
-  - Added ESLint rule exceptions for generated runtime code patterns
-  - Clarified AST and lint rule interactions in configuration
-  - Polished lint cleanup helper utilities
-  - Fixed existing lint violations across the codebase
+  ### Callout Rendering
+  - Extracted floating-ui callout renderer into separate module (`floating-ui-callout.ts`)
+  - Introduced pluggable pointer callout renderer system
+  - Streamlined callout placement pipeline for better performance
+  - Refactored pointer rendering logic for extensibility
 
-  **AST & Transform Logic**
-  - Implemented AST-based splitting for nullish coalescing key expressions
-  - Updated transform logic to handle edge cases more robustly
-  - Improved runtime generation to meet updated lint expectations
+  ### Error Handling
+  - Semantic-name validation failures now default to throwing errors instead of warnings
+  - Improved fail-fast behavior for unnameable wrapper handlers
 
-  **Testing**
-  - Added test coverage for new utility functions
-  - Updated test expectations for class generation coverage
-  - Enhanced transform tests with additional edge case scenarios
+  ### Testing
+  - Aligned dev plugin options across test suite
+  - Added pointer callout sequence documentation (GIF)
+  - Enhanced test coverage for pointer rendering
 
   ## Breaking Changes
 
-  None.
+  - **Peer dependencies removed**: `vue`, `vitest`, and `@vue/shared` are no longer peer
+  dependencies. Ensure your build still works if you relied on these being present.
+  - **Semantic naming errors**: Invalid semantic names now throw by default instead of warning.
+  Handlers that cannot be named semantically will cause build failures unless explicitly
+  configured otherwise.
 
   ## Pull Requests Included
 
-  - #13 Relax Vite peer dependency range (https://github.com/immense/vue-pom-generator/pull/13)
+  - [#9](https://github.com/immense/vue-pom-generator/pull/9) - refactor(deps): eliminate all
+  runtime dependencies
 
   ## Testing
 
-  All changes validated through existing test suite (`npm test`). Added test coverage for new
-  utility functions and transform edge cases.
+  Comprehensive test updates included to validate dependency removal, plugin option alignment, and
+   pointer callout rendering behavior.
 

package/class-generation/base-page.ts

@@ -2,8 +2,8 @@ import type { PwLocator, PwPage } from "./playwright-types";
 import { TESTID_CLICK_EVENT_NAME, TESTID_CLICK_EVENT_STRICT_FLAG } from "../click-instrumentation";
 import type { TestIdClickEventDetail } from "../click-instrumentation";
 import { Callout } from "./callout";
-import { Pointer } from "./pointer";
-import type { AfterPointerClick, AfterPointerClickInfo } from "./pointer";
+import type { CalloutRenderer } from "./callout";
+import { Pointer, type AfterPointerClick, type AfterPointerClickInfo, type PointerRenderer } from "./pointer";
 
 // Click instrumentation is optional for generated POMs.
 //
@@ -55,6 +55,14 @@ export type Fluent<T extends object> = DeepFluent<T, T> & PromiseLike<T>;
 
 export type ValueFluent<T> = DeepValueFluent<T> & PromiseLike<T>;
 
+export interface BasePageOptions {
+  renderers?: {
+    callout?: CalloutRenderer;
+    pointer?: PointerRenderer;
+  };
+  testIdAttribute?: string;
+}
+
 export class ObjectId {
   private readonly raw: string;
 
@@ -99,11 +107,15 @@ export class BasePage {
   /**
    * @param {Page} page - Playwright page object
    */
-  constructor(protected page: PwPage, options?: { testIdAttribute?: string }) {
+  public constructor(protected page: PwPage, options?: BasePageOptions) {
     this.testIdAttribute = (options?.testIdAttribute || "data-testid").trim() || "data-testid";
 
-    this.callout = new Callout(this.page);
-    this.pointer = new Pointer(this.page, this.testIdAttribute, this.callout);
+    const pointerRenderer = options?.renderers?.pointer;
+    this.callout = new Callout(this.page, {
+      extraOverlayIds: pointerRenderer?.overlayIds,
+      renderer: options?.renderers?.callout,
+    });
+    this.pointer = new Pointer(this.page, this.testIdAttribute, this.callout, pointerRenderer);
   }
 
   private async waitForTestIdClickEventAfter(testId: string, options?: { timeoutMs?: number }): Promise<void> {
@@ -237,7 +249,7 @@ export class BasePage {
   }
 
   /**
-   * Animates the cursor to an element.
+   * Animates the pointer to an element.
    */
   protected async animateCursorToElement(
     target: string | PwLocator,