@justeattakeaway/pie-webc-core 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 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.11.0",
   "description": "PIE design system base classes, mixins and utilities for web components",
   "type": "module",
   "main": "index.ts",

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';