@testforgejs/vue-test-plugin-primevue 1.0.0-beta.2 → 1.0.0-beta.4

package/README.md

@@ -1,6 +1,6 @@
 # @testforgejs/vue-test-plugin-primevue
 
-Official TestForge plugin for PrimeVue integration in component tests.
+PrimeVue integration for TestForge component tests.
 
 ## Installation
 
@@ -28,12 +28,61 @@ yarn add -D @testforgejs/vue-test-plugin-primevue@beta
 
 ## Usage
 
-Register `primeVuePlugin` in the TestForge plugin manifest.
+### Using plugin defaults
+
+The plugin provides a project-independent default configuration through `getDefaultOptions()`:
 
 ```typescript
 import { createTestFramework } from "@testforgejs/vue-test-core";
 import { primeVuePlugin } from "@testforgejs/vue-test-plugin-primevue";
 
+const framework = createTestFramework({
+  presets: {
+    default: {
+      manifest: [
+        {
+          module: primeVuePlugin,
+          enabled: true,
+        },
+      ],
+      defaults: {
+        primevue: primeVuePlugin.getDefaultOptions(),
+      },
+    },
+  },
+});
+
+const factory = framework.testComponentFactory(MyComponent);
+
+const wrapper = factory();
+```
+
+`getDefaultOptions()` returns an options factory suitable for use in a preset.
+
+The plugin-provided defaults enable PrimeVue unstyled mode:
+
+```typescript
+{
+  unstyled: true,
+}
+```
+
+Unstyled mode provides a project-independent baseline without requiring a theme preset. PrimeVue components retain their functionality and accessibility, while PrimeVue's built-in styled-mode theme rules are not applied.
+
+Plugin defaults are **not applied automatically**. Adding the plugin to a preset manifest declares that the plugin is available and whether it is enabled; the preset explicitly decides whether to use the plugin-provided defaults or provide its own configuration.
+
+### Providing custom options
+
+You can define the PrimeVue configuration directly in the preset instead.
+
+For example, a project that uses PrimeVue styled mode can provide its theme configuration:
+
+```typescript
+import Aura from "@primeuix/themes/aura";
+
+import { createTestFramework } from "@testforgejs/vue-test-core";
+import { primeVuePlugin } from "@testforgejs/vue-test-plugin-primevue";
+
 const framework = createTestFramework({
   presets: {
     default: {
@@ -53,20 +102,109 @@ const framework = createTestFramework({
     },
   },
 });
+```
 
-const factory = framework.testComponentFactory(MyComponent);
+Using `getDefaultOptions()` is optional. Define custom defaults when tests need to reproduce application-specific PrimeVue configuration such as a theme preset, pass-through configuration, locale settings, ripple effects, or other PrimeVue behavior.
 
-const wrapper = factory();
+If the configuration references a PrimeVue theme preset such as Aura, the corresponding PrimeVue theme package must also be available in the project.
+
+## Configuration
+
+### PrimeVue options
+
+The plugin integrates TestForge with PrimeVue by registering the PrimeVue Vue plugin with the provided configuration.
+
+Configuration fields such as `unstyled`, `theme`, `pt`, `ptOptions`, `locale`, `ripple`, `zIndex`, and other PrimeVue options belong to PrimeVue.
+
+TestForge does not define an alternative configuration format for PrimeVue. The integration passes the provided configuration to the PrimeVue plugin during installation.
+
+Refer to the PrimeVue documentation for the complete set of supported configuration options and their behavior.
+
+### Styled and unstyled modes
+
+The plugin-provided defaults use:
+
+```typescript
+{
+  unstyled: true,
+}
 ```
 
-`defaults.primevue` is an options factory. Each invocation produces a fresh PrimeVue options object for the current pipeline context.
+This is intended as a project-independent testing baseline and does not attempt to reproduce an application's visual theme.
+
+If a component test depends on the application's PrimeVue theme or other styled-mode configuration, provide that configuration explicitly in a project-specific preset instead of relying on the plugin defaults.
+
+For example:
+
+```typescript
+defaults: {
+  primevue: () => ({
+    theme: {
+      preset: Aura,
+    },
+  }),
+},
+```
+
+This keeps application-specific presentation policy in the project preset while the plugin provides a minimal reusable baseline.
+
+### Options factories
+
+Preset defaults are defined as factories:
+
+```typescript
+defaults: {
+  primevue: () => ({
+    theme: {
+      preset: Aura,
+    },
+  }),
+},
+```
+
+Each invocation of the factory produces a fresh options object for the current TestForge pipeline execution.
+
+`primeVuePlugin.getDefaultOptions()` follows the same contract: it returns an options factory rather than a shared options object.
+
+This allows presets to choose explicitly between:
+
+- the project-independent defaults provided by the plugin; and
+- a custom PrimeVue configuration defined by the preset.
+
+## Package exports
+
+The package provides both descriptive and standardized plugin exports:
+
+```typescript
+import { primeVuePlugin, plugin, PLUGIN_NAME } from "@testforgejs/vue-test-plugin-primevue";
+```
+
+### `primeVuePlugin`
+
+The descriptive PrimeVue plugin module export.
+
+### `plugin`
+
+The standardized plugin module export.
+
+It references the same plugin module as `primeVuePlugin` and provides a consistent package-level API across TestForge plugin packages.
+
+### `PLUGIN_NAME`
+
+The standardized plugin identifier export.
+
+For this package:
+
+```typescript
+PLUGIN_NAME === "primevue";
+```
 
-The plugin provides PrimeVue integration for components mounted through TestForge.
+The standardized `plugin` and `PLUGIN_NAME` exports are useful for tooling and other code that works with TestForge plugin packages generically.
 
 ## Supported versions
 
-- Vue: 3.x
-- PrimeVue: 3.x and 4.x
+- Vue: 3.3.0 or higher
+- PrimeVue: 4.x
 
 ## Documentation
 

package/dist/index.cjs

@@ -30,6 +30,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  PLUGIN_NAME: () => PRIMEVUE_PLUGIN_NAME,
+  plugin: () => primeVuePlugin,
   primeVuePlugin: () => primeVuePlugin
 });
 module.exports = __toCommonJS(index_exports);
@@ -41,24 +43,25 @@ function createPrimeVuePlugin(options) {
   return (0, import_vue_test_core.createVuePlugin)(import_config.default, options);
 }
 
+// src/defaults.ts
+var defaultOptions = () => () => ({
+  unstyled: true
+});
+
+// src/constants/constants.ts
+var PRIMEVUE_PLUGIN_NAME = "primevue";
+
 // src/module/primeVuePlugin.ts
 var primeVuePlugin = {
-  /**
-   * Returns the plugin identifier used in TestForge configuration.
-   *
-   * @returns The plugin registration key (`"primevue"`).
-   */
-  getName: () => "primevue",
-  /**
-   * Returns the PrimeVue plugin lifecycle definition.
-   *
-   * @returns Plugin lifecycle hooks consumed by the TestForge kernel.
-   */
+  getName: () => PRIMEVUE_PLUGIN_NAME,
   getDefinition: () => ({
     create: createPrimeVuePlugin
-  })
+  }),
+  getDefaultOptions: defaultOptions
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  PLUGIN_NAME,
+  plugin,
   primeVuePlugin
 });

package/dist/index.d.cts

@@ -1,69 +1,73 @@
 import PrimeVue, { PrimeVueConfiguration } from 'primevue/config';
-import { PluginModule } from '@testforgejs/vue-test-core';
+import { PluginModuleWithDefaults } from '@testforgejs/vue-test-core';
 
 /**
- * Vue Test Utils compatible plugin tuple for PrimeVue.
+ * Stable TestForge identifier for the managed PrimeVue plugin.
  *
- * PrimeVue is an install-based Vue plugin and therefore integrates
- * through a standard `[plugin, options]` tuple instead of a runtime instance.
+ * Use this identifier when declaring PrimeVue configuration
+ * in presets and other plugin-aware TestForge APIs.
+ */
+declare const PRIMEVUE_PLUGIN_NAME: "primevue";
+
+/**
+ * Vue Test Utils-compatible plugin tuple for PrimeVue.
+ *
+ * Represents the install-based PrimeVue plugin together with its configuration,
+ * as accepted by Vue Test Utils through `global.plugins`.
  *
- * @see {@link PrimeVue}
- * @see {@link PrimeVueConfiguration}
+ * @see `PrimeVueConfiguration` from `primevue/config`.
  */
 type PrimeVueMountPlugin = [typeof PrimeVue, PrimeVueConfiguration];
 /**
- * Configuration options for the PrimeVue TestForge plugin.
+ * Configuration options for the managed PrimeVue plugin.
  *
- * This type maps directly to the official PrimeVue configuration object
- * and intentionally does not include TestForge runtime controls such as
- * `expose()` or `__meta.instance`, because PrimeVue does not create
- * a reusable runtime instance.
+ * Maps directly to the standard PrimeVue configuration.
  *
- * @see {@link PrimeVueConfiguration}
+ * Unlike plugins that create a dedicated runtime instance, PrimeVue uses
+ * an install-based Vue plugin integration and therefore does not support
+ * TestForge instance controls such as `expose`.
+ *
+ * @example
+ * Configure the managed PrimeVue plugin for a component test:
+ *
+ * ```ts
+ * factory({}, {
+ *   plugins: {
+ *     primevue: {
+ *       ripple: true,
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * @see `PrimeVueConfiguration` from `primevue/config`.
  */
 type VueTestPrimeVueOptions = PrimeVueConfiguration;
 
 /**
- * Extends TestForge kernel types for PrimeVue integration.
- *
- * Registers the `primevue` configuration key inside the global
- * plugin options map, enabling strict typing and IDE autocompletion
- * when configuring PrimeVue in component tests.
+ * TestForge core type augmentation for PrimeVue integration.
  *
- * @module Augmentation
+ * Registers the public plugin configuration type
+ * used by TestForge's managed plugin APIs.
  */
 declare module "@testforgejs/vue-test-core" {
     /**
-     * Global TestForge plugin configuration registry.
+     * Global map for TestForge plugin configuration options.
      */
     interface PluginOptionsMap {
         /**
-         * Configuration for the `primevue` plugin.
-         *
-         * Accepts standard {@link VueTestPrimeVueOptions}
-         * which correspond directly to PrimeVue configuration options.
-         *
-         * @example
-         * ```ts
-         * factory({}, {
-         *   plugins: {
-         *     primevue: {
-         *       ripple: true
-         *     }
-         *   }
-         * })
-         * ```
+         * Configuration accepted by the managed `primevue` plugin.
          */
-        primevue: VueTestPrimeVueOptions;
+        [PRIMEVUE_PLUGIN_NAME]: VueTestPrimeVueOptions;
     }
 }
 
 /**
- * Official TestForge integration module for PrimeVue.
+ * Managed PrimeVue plugin module for TestForge.
  *
- * Registers PrimeVue in the TestForge plugin pipeline and exposes
- * the `primevue` configuration key for presets and mount options.
+ * Provides the runtime integration for mounting PrimeVue as an install-based
+ * Vue plugin and exposes the default configuration used by TestForge-managed presets.
  */
-declare const primeVuePlugin: PluginModule<PrimeVueMountPlugin, VueTestPrimeVueOptions>;
+declare const primeVuePlugin: PluginModuleWithDefaults<PrimeVueMountPlugin, VueTestPrimeVueOptions>;
 
-export { type PrimeVueMountPlugin, type VueTestPrimeVueOptions, primeVuePlugin };
+export { PRIMEVUE_PLUGIN_NAME as PLUGIN_NAME, type PrimeVueMountPlugin, type VueTestPrimeVueOptions, primeVuePlugin as plugin, primeVuePlugin };

package/dist/index.d.ts

@@ -1,69 +1,73 @@
 import PrimeVue, { PrimeVueConfiguration } from 'primevue/config';
-import { PluginModule } from '@testforgejs/vue-test-core';
+import { PluginModuleWithDefaults } from '@testforgejs/vue-test-core';
 
 /**
- * Vue Test Utils compatible plugin tuple for PrimeVue.
+ * Stable TestForge identifier for the managed PrimeVue plugin.
  *
- * PrimeVue is an install-based Vue plugin and therefore integrates
- * through a standard `[plugin, options]` tuple instead of a runtime instance.
+ * Use this identifier when declaring PrimeVue configuration
+ * in presets and other plugin-aware TestForge APIs.
+ */
+declare const PRIMEVUE_PLUGIN_NAME: "primevue";
+
+/**
+ * Vue Test Utils-compatible plugin tuple for PrimeVue.
+ *
+ * Represents the install-based PrimeVue plugin together with its configuration,
+ * as accepted by Vue Test Utils through `global.plugins`.
  *
- * @see {@link PrimeVue}
- * @see {@link PrimeVueConfiguration}
+ * @see `PrimeVueConfiguration` from `primevue/config`.
  */
 type PrimeVueMountPlugin = [typeof PrimeVue, PrimeVueConfiguration];
 /**
- * Configuration options for the PrimeVue TestForge plugin.
+ * Configuration options for the managed PrimeVue plugin.
  *
- * This type maps directly to the official PrimeVue configuration object
- * and intentionally does not include TestForge runtime controls such as
- * `expose()` or `__meta.instance`, because PrimeVue does not create
- * a reusable runtime instance.
+ * Maps directly to the standard PrimeVue configuration.
  *
- * @see {@link PrimeVueConfiguration}
+ * Unlike plugins that create a dedicated runtime instance, PrimeVue uses
+ * an install-based Vue plugin integration and therefore does not support
+ * TestForge instance controls such as `expose`.
+ *
+ * @example
+ * Configure the managed PrimeVue plugin for a component test:
+ *
+ * ```ts
+ * factory({}, {
+ *   plugins: {
+ *     primevue: {
+ *       ripple: true,
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * @see `PrimeVueConfiguration` from `primevue/config`.
  */
 type VueTestPrimeVueOptions = PrimeVueConfiguration;
 
 /**
- * Extends TestForge kernel types for PrimeVue integration.
- *
- * Registers the `primevue` configuration key inside the global
- * plugin options map, enabling strict typing and IDE autocompletion
- * when configuring PrimeVue in component tests.
+ * TestForge core type augmentation for PrimeVue integration.
  *
- * @module Augmentation
+ * Registers the public plugin configuration type
+ * used by TestForge's managed plugin APIs.
  */
 declare module "@testforgejs/vue-test-core" {
     /**
-     * Global TestForge plugin configuration registry.
+     * Global map for TestForge plugin configuration options.
      */
     interface PluginOptionsMap {
         /**
-         * Configuration for the `primevue` plugin.
-         *
-         * Accepts standard {@link VueTestPrimeVueOptions}
-         * which correspond directly to PrimeVue configuration options.
-         *
-         * @example
-         * ```ts
-         * factory({}, {
-         *   plugins: {
-         *     primevue: {
-         *       ripple: true
-         *     }
-         *   }
-         * })
-         * ```
+         * Configuration accepted by the managed `primevue` plugin.
          */
-        primevue: VueTestPrimeVueOptions;
+        [PRIMEVUE_PLUGIN_NAME]: VueTestPrimeVueOptions;
     }
 }
 
 /**
- * Official TestForge integration module for PrimeVue.
+ * Managed PrimeVue plugin module for TestForge.
  *
- * Registers PrimeVue in the TestForge plugin pipeline and exposes
- * the `primevue` configuration key for presets and mount options.
+ * Provides the runtime integration for mounting PrimeVue as an install-based
+ * Vue plugin and exposes the default configuration used by TestForge-managed presets.
  */
-declare const primeVuePlugin: PluginModule<PrimeVueMountPlugin, VueTestPrimeVueOptions>;
+declare const primeVuePlugin: PluginModuleWithDefaults<PrimeVueMountPlugin, VueTestPrimeVueOptions>;
 
-export { type PrimeVueMountPlugin, type VueTestPrimeVueOptions, primeVuePlugin };
+export { PRIMEVUE_PLUGIN_NAME as PLUGIN_NAME, type PrimeVueMountPlugin, type VueTestPrimeVueOptions, primeVuePlugin as plugin, primeVuePlugin };

package/dist/index.js

@@ -5,23 +5,24 @@ function createPrimeVuePlugin(options) {
   return createVuePlugin(PrimeVue, options);
 }
 
+// src/defaults.ts
+var defaultOptions = () => () => ({
+  unstyled: true
+});
+
+// src/constants/constants.ts
+var PRIMEVUE_PLUGIN_NAME = "primevue";
+
 // src/module/primeVuePlugin.ts
 var primeVuePlugin = {
-  /**
-   * Returns the plugin identifier used in TestForge configuration.
-   *
-   * @returns The plugin registration key (`"primevue"`).
-   */
-  getName: () => "primevue",
-  /**
-   * Returns the PrimeVue plugin lifecycle definition.
-   *
-   * @returns Plugin lifecycle hooks consumed by the TestForge kernel.
-   */
+  getName: () => PRIMEVUE_PLUGIN_NAME,
   getDefinition: () => ({
     create: createPrimeVuePlugin
-  })
+  }),
+  getDefaultOptions: defaultOptions
 };
 export {
+  PRIMEVUE_PLUGIN_NAME as PLUGIN_NAME,
+  primeVuePlugin as plugin,
   primeVuePlugin
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testforgejs/vue-test-plugin-primevue",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.4",
   "type": "module",
   "description": "Official TestForge plugin for PrimeVue integration in component tests",
   "homepage": "https://github.com/testforgejs/testforge#readme",
@@ -41,12 +41,18 @@
   "license": "MIT",
   "author": "Roman Levchenko",
   "peerDependencies": {
-    "primevue": "^3.0.0 || ^4.0.0",
-    "@testforgejs/vue-test-core": "1.0.0-beta.2"
+    "primevue": "^4.0.0",
+    "@testforgejs/vue-test-core": "1.0.0-beta.4"
   },
   "devDependencies": {
     "primevue": "^4.0.0",
-    "@testforgejs/vue-test-core": "1.0.0-beta.2"
+    "@testforgejs/vue-test-core": "1.0.0-beta.4"
+  },
+  "testforge": {
+    "plugin": {
+      "schemaVersion": 1,
+      "displayName": "PrimeVue"
+    }
   },
   "scripts": {
     "build": "tsup",