@justeattakeaway/pie-webc-core 0.10.0 → 0.12.0-next.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.12.0-next.0
+
+### Minor Changes
+
+- [Changed] - `@validPropertyValues` and `@requiredProperty` decorators to support Lit 3. ([#999](https://github.com/justeattakeaway/pie/pull/999)) by [@siggerzz](https://github.com/siggerzz)
+
+## 0.11.0
+
+### Minor Changes
+
+- [Added] - defineCustomElement helper function to protect against duplicate component registration errors ([#905](https://github.com/justeattakeaway/pie/pull/905)) by [@jamieomaguire](https://github.com/jamieomaguire)
+
 ## 0.10.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justeattakeaway/pie-webc-core",
-  "version": "0.10.0",
+  "version": "0.12.0-next.0",
   "description": "PIE design system base classes, mixins and utilities for web components",
   "type": "module",
   "main": "index.ts",

package/src/decorators/required-property.ts

@@ -11,15 +11,11 @@ export const requiredProperty = <T>(componentName: string) => function validateR
             return this[privatePropertyKey];
         },
         set (value: T): void {
-            const oldValue = this[privatePropertyKey];
-
             if (value === undefined || value === null || (typeof value === 'string' && value.trim() === '')) {
                 console.error(`<${componentName}> Missing required attribute "${propertyKey}"`);
             }
             this[privatePropertyKey] = value;
-
-            this.requestUpdate(propertyKey, oldValue);
         },
+        configurable: true,
     });
 };
-

package/src/decorators/test/required-property.spec.ts

@@ -25,16 +25,6 @@ describe('requiredProperty', () => {
     class MockComponent {
         @requiredProperty('mock-component')
             color?: string | null;
-
-        private _requestUpdateArgs = {};
-
-        requestUpdate (propertyKey: string, oldValue: unknown) {
-            this._requestUpdateArgs = { propertyKey, oldValue };
-        }
-
-        requestUpdateCalledWith () {
-            return this._requestUpdateArgs;
-        }
     }
 
     it('should log an error if the property is undefined', () => {
@@ -80,15 +70,4 @@ describe('requiredProperty', () => {
         // Assert
         expect(consoleErrorSpy).not.toHaveBeenCalled();
     });
-
-    it('should call requestUpdate when the property is set', () => {
-        // Arrange
-        const mockComponent = new MockComponent();
-
-        // Act
-        mockComponent.color = 'blue';
-
-        // Assert
-        expect(mockComponent.requestUpdateCalledWith()).toStrictEqual({ propertyKey: 'color', oldValue: undefined });
-    });
 });

package/src/decorators/test/valid-property-values.spec.ts

@@ -25,16 +25,6 @@ describe('validPropertyValues', () => {
     class MockComponent {
         @validPropertyValues('mock-component', ['red', 'green', 'blue'], 'red')
             color = 'red';
-
-        private _requestUpdateArgs = {};
-
-        requestUpdate (propertyKey: string, oldValue: unknown) {
-            this._requestUpdateArgs = { propertyKey, oldValue };
-        }
-
-        requestUpdateCalledWith () {
-            return this._requestUpdateArgs;
-        }
     }
 
     it('should allow value to be updated with a valid value', () => {
@@ -75,16 +65,4 @@ describe('validPropertyValues', () => {
             'Falling back to default value: "red"',
         );
     });
-
-    it('should call requestUpdate when the property is set', () => {
-        // Arrange
-        const mockComponent = new MockComponent();
-
-        // Act
-        mockComponent.color = 'yellow';
-
-        // Assert
-        expect(mockComponent.color).toBe('red');
-        expect(mockComponent.requestUpdateCalledWith()).toStrictEqual({ propertyKey: 'color', oldValue: 'red' });
-    });
 });

package/src/decorators/valid-property-values.ts

@@ -5,7 +5,7 @@
  * @param defaultValue - The value to fall back on
  * @returns  - The decorator function
  */
-export const validPropertyValues = <T>(componentName: string, validValues: readonly T[], defaultValue: T) => function validatePropertyValues (target: object, propertyKey: string): void {
+export const validPropertyValues = <T>(componentName: string, validValues: readonly T[], defaultValue: T) => function validatePropertyValues (target: object, propertyKey: string) : void {
     const privatePropertyKey = `#${propertyKey}`;
 
     Object.defineProperty(target, propertyKey, {
@@ -13,8 +13,6 @@ export const validPropertyValues = <T>(componentName: string, validValues: reado
             return this[privatePropertyKey];
         },
         set (value: T): void {
-            const oldValue = this[privatePropertyKey];
-
             if (!validValues.includes(value)) {
                 console.error(
                         `<${componentName}> Invalid value "${value}" provided for property "${propertyKey}".`,
@@ -25,8 +23,7 @@ export const validPropertyValues = <T>(componentName: string, validValues: reado
             } else {
                 this[privatePropertyKey] = value;
             }
-
-            this.requestUpdate(propertyKey, oldValue);
         },
+        configurable: true,
     });
 };

package/src/functions/defineCustomElement.ts

@@ -0,0 +1,47 @@
+import { LitElement } from 'lit';
+
+/**
+ * Defines a web component, ensuring that the component is only defined once in the Custom Element Registry.
+ *
+ * If the component has already been defined with the same name, a warning is logged to the console.
+ *
+ * @param {string} elementSelector - The selector of the custom element. Must be a valid custom element selector, containing a dash. I.e. 'my-component'
+ * @param {typeof LitElement} elementClass - The class that defines the custom element, extending LitElement.
+ *
+ * @example
+ *
+ * ```javascript
+ * import { css, html, LitElement } from 'lit';
+ *
+ * // IMPORTANT: Add the following JSDoc comment above your class setting the `@tagname` to the selector you want to use. - This is mandatory.
+ * // "@tagname my-component"
+ * class MyComponent extends LitElement {
+ *   static styles = css`
+ *     :host {
+ *       display: block;
+ *       padding: 16px;
+ *       color: var(--my-component-text-color, black);
+ *     }
+ *   `;
+ *
+ *   render() {
+ *     return html`
+ *       <p>My custom element content goes here!</p>
+ *     `;
+ *   }
+ * }
+ *
+ * defineCustomElement('my-component', MyComponent);
+ * ```
+ *
+ * NOTE: The inclusion of the `@tagname` JSDoc comment above your class is essential for correct functionality. Ensure it matches the tag you're registering.
+ *
+ * @returns {void}
+ */
+export function defineCustomElement (elementSelector: string, elementClass: typeof LitElement): void {
+    if (!customElements.get(elementSelector)) {
+        customElements.define(elementSelector, elementClass);
+    } else {
+        console.warn(`PIE Web Component: "${elementSelector}" has already been defined. Please ensure the component is only being defined once in your application.`);
+    }
+}

package/src/functions/index.ts

@@ -0,0 +1 @@
+export * from './defineCustomElement';

package/src/functions/test/defineCustomElement.spec.ts

@@ -0,0 +1,81 @@
+/* eslint-disable max-classes-per-file */
+import { LitElement } from 'lit';
+import {
+    vi, expect, it,
+} from 'vitest';
+import { defineCustomElement } from '../defineCustomElement';
+
+it('should call console.warn when a component is defined twice', () => {
+    // Arrange
+    class MockComponentA extends LitElement {}
+
+    const warnSpy = vi.spyOn(console, 'warn');
+    const errorSpy = vi.spyOn(console, 'error');
+
+    // Act
+    defineCustomElement('mock-component-a', MockComponentA);
+    defineCustomElement('mock-component-a', MockComponentA);
+
+    // Assert
+    const [[warning]] = warnSpy.mock.calls;
+
+    expect(warnSpy).toHaveBeenCalledOnce();
+    expect(warning).toMatch('PIE Web Component: "mock-component-a" has already been defined. Please ensure the component is only being defined once in your application.');
+    expect(errorSpy).not.toHaveBeenCalled();
+    expect(customElements.get('mock-component-a')).toBe(MockComponentA);
+});
+
+it('should define the component without warnings when called once', () => {
+    // Arrange
+    class MockComponentB extends LitElement {}
+
+    const warnSpy = vi.spyOn(console, 'warn');
+    const errorSpy = vi.spyOn(console, 'error');
+
+    // Act
+    defineCustomElement('mock-component-b', MockComponentB);
+
+    // Assert
+    expect(warnSpy).not.toHaveBeenCalled();
+    expect(errorSpy).not.toHaveBeenCalled();
+    expect(customElements.get('mock-component-b')).toBe(MockComponentB);
+});
+
+it('should warn when defining the same component name with a different class', () => {
+    // Arrange
+    class MockComponentC extends LitElement {}
+
+    class MockComponentD extends LitElement {}
+
+    const warnSpy = vi.spyOn(console, 'warn');
+    const errorSpy = vi.spyOn(console, 'error');
+
+    // Act
+    defineCustomElement('mock-component-c', MockComponentC);
+    defineCustomElement('mock-component-c', MockComponentD);
+
+    // Assert
+    const [[warning]] = warnSpy.mock.calls;
+
+    expect(warnSpy).toHaveBeenCalledOnce();
+    expect(warning).toMatch('PIE Web Component: "mock-component-c" has already been defined. Please ensure the component is only being defined once in your application.');
+    expect(errorSpy).not.toHaveBeenCalled();
+    expect(customElements.get('mock-component-c')).toBe(MockComponentC);
+});
+
+it('Should correctly accept component classes that use multiple levels of inheritance', () => {
+    // Arrange
+    class MockComponentE extends LitElement {}
+    class MockComponentF extends MockComponentE {}
+
+    const warnSpy = vi.spyOn(console, 'warn');
+    const errorSpy = vi.spyOn(console, 'error');
+
+    // Act
+    defineCustomElement('mock-component-f', MockComponentF);
+
+    // Assert
+    expect(warnSpy).not.toHaveBeenCalled();
+    expect(errorSpy).not.toHaveBeenCalled();
+    expect(customElements.get('mock-component-f')).toBe(MockComponentF);
+});

package/src/index.ts

@@ -1,2 +1,3 @@
 export * from './mixins';
 export * from './decorators';
+export * from './functions';