@shopware-ag/storefront-types 0.1.2 → 0.2.1

package/README.md

@@ -23,3 +23,29 @@ To have the types active, you need to create a `tsconfig.json` (`src/Resources/a
     }
 }
 ```
+
+## 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/declare/helper/dom-access.helper.d.ts

@@ -27,7 +27,8 @@ interface DomAccessHelper {
     /**
      * Returns the selected elements of a defined parent node
      */
-    querySelectorAll(element: HTMLElement, selector: string, strict?: boolean): HTMLElement[]
+    querySelectorAll(element: HTMLElement, selector: string, strict: true): NodeList
+    querySelectorAll(element: HTMLElement, selector: string, strict?: false): NodeList | false
 }
 
 declare module 'src/helper/dom-access.helper' {

package/global.d.ts

@@ -1,7 +1,7 @@
 declare global {
     interface Window {
         PluginManager: import('./plugin-system/plugin-manager').default,
-        PluginBaseClass: import('./plugin-system/plugin').default,
+        PluginBaseClass: typeof import('./plugin-system/plugin').default,
         router: {
             'frontend.cart.offcanvas': string,
             'frontend.cookie.offcanvas': string,

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@shopware-ag/storefront-types",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "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 class PluginBaseClass<Options extends object = Record<string, unknown>> {
+    constructor(el: HTMLElement, options?: Partial<Options>, pluginName?: false | string);
 
     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-extend-window.test-d.ts

@@ -0,0 +1,38 @@
+// Test case for using window.PluginBaseClass as shown in the issue
+/// <reference path="../global.d.ts" />
+
+const { PluginBaseClass } = window;
+
+interface MyPluginOptions {
+    option1: string;
+    option2: number | null;
+}
+
+class MyPlugin extends PluginBaseClass<MyPluginOptions> {
+    static options: MyPluginOptions = {
+        option1: 'default value',
+        option2: null,
+    };
+
+    init(): void {
+        // Test that instance properties are accessible
+        console.log(this.el);
+        console.log(this.options);
+        console.log(this.$emitter);
+        
+        // Test that options are properly typed
+        const opt1: string = this.options.option1;
+        const opt2: number | null = this.options.option2;
+    }
+}
+
+// Test: Can instantiate using the class from window
+const element = document.createElement('div');
+const plugin = new MyPlugin(element, { option1: 'custom' });
+
+// Test: Instance properties should be typed correctly
+const opt1: string = plugin.options.option1;
+const opt2: number | null = plugin.options.option2;
+
+// @ts-expect-error - Should error when accessing non-existent property
+plugin.options.nonExistent;

package/tests/plugin-extend.test-d.ts

@@ -0,0 +1,39 @@
+// Test case for extending PluginBaseClass as shown in the issue
+import PluginBaseClass from '../plugin-system/plugin';
+
+interface MyPluginOptions {
+    option1: string;
+    option2: number | null;
+}
+
+class MyPlugin extends PluginBaseClass<MyPluginOptions> {
+    static options: MyPluginOptions = {
+        option1: 'default value',
+        option2: null,
+    };
+
+    init(): void {
+        // Test that instance properties are accessible
+        console.log(this.el);
+        console.log(this.options);
+        console.log(this.$emitter);
+        
+        // Test that options are properly typed
+        const opt1: string = this.options.option1;
+        const opt2: number | null = this.options.option2;
+    }
+}
+
+// Test: Should be able to instantiate via constructor
+const element = document.createElement('div');
+const plugin = new MyPlugin(element, { option1: 'test' });
+
+// Test: Instance properties should be accessible
+const el: HTMLElement = plugin.el;
+const opt1: string = plugin.options.option1;
+
+// @ts-expect-error - Should error when accessing non-existent property
+plugin.options.nonExistent;
+
+// @ts-expect-error - Should error when assigning wrong type
+const wrongType: number = plugin.options.option1;

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: new (el: HTMLElement, options?: Partial<MyPluginOptions>, pluginName?: false | string) => 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"
+    ]
+}