@shopware-ag/storefront-types 0.1.1 → 0.2.0

package/README.md

@@ -1,18 +1,20 @@
 # Types for Shopware Storefront
 
-This package provides types for window bound classes in Shopware 6 Storefront:
+This package provides types for window-bound classes in Shopware 6 Storefront:
 
 - `window.PluginManager`
 - `window.PluginBaseClass`
 - `window.router`
 
+and all regular imports of the Storefront.
+
 Install this package with NPM:
 
 ```bash
 npm install @shopware-ag/storefront-types --save-dev
 ```
 
-To hav the types active, you need to create a `tsconfig.json` (`src/Resources/app/storefront/tsconfig.json`) with following content:
+To have the types active, you need to create a `tsconfig.json` (`src/Resources/app/storefront/tsconfig.json`) with the following content:
 
 ```json
 {
@@ -21,3 +23,29 @@ To hav the types active, you need to create a `tsconfig.json` (`src/Resources/ap
     }
 }
 ```
+
+## Typed Plugin Options
+
+You can use a generic type parameter to get fully typed options in your plugins:
+
+```ts
+const { PluginBaseClass } = window;
+
+interface MyPluginOptions {
+    option1: string;
+    option2: number | null;
+}
+
+export default class MyPlugin extends PluginBaseClass<MyPluginOptions> {
+    static options: MyPluginOptions = {
+        option1: 'default value',
+        option2: null
+    };
+
+    init() {
+        // this.options is fully typed
+        console.log(this.options.option1); // string
+        console.log(this.options.option2); // number | null
+    }
+}
+```

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@shopware-ag/storefront-types",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Provides Shopware Storefront Typescript types",
   "types": "index.d.ts",
+  "scripts": {
+    "test": "tsc --project tsconfig.test.json"
+  },
   "dependencies": {
     "@types/bootstrap": "^5.2.0"
   },

package/plugin-system/plugin-manager.d.ts

@@ -15,6 +15,12 @@ export default interface PluginManager {
      */
     extend(fromName: String, newName: string, pluginClass: Object, selector: String | NodeList | HTMLElement, options?: Object): boolean
 
+    /**
+     * Overrides an existing plugin with a new class.
+     * This is a convenience wrapper around extend() that uses the same name for both fromName and newName.
+     */
+    override(overrideName: String, pluginClass: Object, selector: String | NodeList | HTMLElement, options?: Object): boolean
+
     /**
      * Returns a list of all registered plugins.
      */

package/plugin-system/plugin.d.ts

@@ -1,19 +1,19 @@
 import NativeEventEmitter from "./native-event-emitter";
 
-export default interface PluginBaseClass {
-    new(el: HTMLElement, options?: any, pluginName?: false | string): PluginBaseClass;
+export default interface PluginBaseClass<Options extends object = Record<string, unknown>> {
+    new(el: HTMLElement, options?: Partial<Options>, pluginName?: false | string): PluginBaseClass<Options>;
 
     el: HTMLElement;
     $emitter: NativeEventEmitter;
     _pluginName: String;
-    initialOptions: object;
-    options: object;
+    initialOptions: Options;
+    options: Options;
     _initialized: boolean;
     init(): void;
     _update(): void;
     update(): void;
     _registerInstance(): void;
     _getPluginName(pluginName: false | string): String;
-    _mergeOptions(options: any): object;
+    _mergeOptions(options: Partial<Options>): Options;
     parseJsonOrFail(dashedPluginName: string): any | string;
 }

package/tests/plugin.test-d.ts

@@ -0,0 +1,49 @@
+import type PluginBaseClass from '../plugin-system/plugin';
+
+// Test: Generic with custom options type
+interface MyPluginOptions {
+    option1: string;
+    option2: number | null;
+    nested: {
+        value: boolean;
+    };
+}
+
+declare const myPlugin: PluginBaseClass<MyPluginOptions>;
+
+// Test: options should be typed correctly
+const opt1: string = myPlugin.options.option1;
+const opt2: number | null = myPlugin.options.option2;
+const nestedVal: boolean = myPlugin.options.nested.value;
+
+// Test: initialOptions should also be typed
+const initOpt1: string = myPlugin.initialOptions.option1;
+
+// Test: _mergeOptions should accept Partial<Options> and return Options
+const merged: MyPluginOptions = myPlugin._mergeOptions({ option1: 'test' });
+const mergedEmpty: MyPluginOptions = myPlugin._mergeOptions({});
+
+// Test: Default generic (backwards compatibility)
+declare const defaultPlugin: PluginBaseClass;
+
+// Default plugin options should be Record<string, unknown>
+const defaultOpt: unknown = defaultPlugin.options['anyKey'];
+const defaultInitOpt: unknown = defaultPlugin.initialOptions['anyKey'];
+
+// Test: Constructor options parameter should accept Partial<Options>
+declare const PluginClass: PluginBaseClass<MyPluginOptions>;
+declare const element: HTMLElement;
+const instance = new PluginClass(element, { option1: 'partial' });
+const instanceNoOpts = new PluginClass(element);
+
+// @ts-expect-error - Should error when accessing non-existent property on typed options
+myPlugin.options.nonExistent;
+
+// @ts-expect-error - Should error when assigning wrong type
+const wrongType: number = myPlugin.options.option1;
+
+// @ts-expect-error - Should error when passing wrong option type to constructor
+new PluginClass(element, { option1: 123 });
+
+// @ts-expect-error - Should error when passing unknown option to constructor
+new PluginClass(element, { unknownOption: 'value' });

package/tsconfig.test.json

@@ -0,0 +1,18 @@
+{
+    "compilerOptions": {
+        "module": "commonjs",
+        "lib": [
+            "es6",
+            "DOM"
+        ],
+        "noImplicitAny": true,
+        "noImplicitThis": true,
+        "strictNullChecks": true,
+        "strictFunctionTypes": true,
+        "noEmit": true,
+        "forceConsistentCasingInFileNames": true
+    },
+    "include": [
+        "tests/**/*.test-d.ts"
+    ]
+}

package/.github/workflows/release.yml

@@ -1,32 +0,0 @@
-name: Release
-
-on:
-  release:
-    types: [created]
-
-jobs:
-  publish-npm:
-    runs-on: ubuntu-latest
-    permissions:
-     contents: read
-     id-token: write
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Install Node 20.x
-        uses: actions/setup-node@v3
-        with:
-          node-version: '20.x'
-          registry-url: 'https://registry.npmjs.org'
-
-      - name: Change version
-        run: |
-          jq '.version = "${{ github.ref_name }}"' package.json > package.new.json
-          cp package.new.json package.json
-          rm package.new.json
-
-      - name: Release package
-        run: npm publish --provenance --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_PUBLISH_TOKEN }}