@justeattakeaway/pie-webc-core 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.6.0
+
+### Minor Changes
+
+- [Changed] - Improve TS typings in RTL mixin and provde extendable prop interface for components ([#623](https://github.com/justeattakeaway/pie/pull/623)) by [@jamieomaguire](https://github.com/jamieomaguire)
+
+## 0.5.0
+
+### Minor Changes
+
+- [Removed] - Function for CSS loading in Safari visual tests due to fix on Percy side. ([#575](https://github.com/justeattakeaway/pie/pull/575)) by [@JoshuaNg2332](https://github.com/JoshuaNg2332)
+
 ## 0.4.0
 
 ### Minor Changes

package/declaration.d.ts

@@ -0,0 +1,9 @@
+declare module '*.scss' {
+    const content: Record<string, string>;
+    export default content;
+}
+
+declare module '*.scss?inline' {
+    const content: Record<string, string>;
+    export default content;
+}

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@justeattakeaway/pie-webc-core",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "PIE design system base classes, mixins and utilities for web components",
   "type": "module",
   "main": "index.ts",
   "author": "JustEatTakeaway - Design System Web Team",
   "license": "Apache-2.0",
+  "scripts": {
+    "test": "run -T vitest run"
+  },
   "volta": {
     "extends": "../../../package.json"
   }

package/src/decorators/required-property.ts

@@ -3,17 +3,17 @@
  * If the property's value is `undefined`, `null` or empty string, an error is logged.
  * @returns {Function} - The decorator function.
  */
-export const requiredProperty = (componentName: string) => function (target: any, propertyKey: string) : void {
+export const requiredProperty = <T>(componentName: string) => function validateRequiredProperty (target: object, propertyKey: string): void {
     const privatePropertyKey = `#${propertyKey}`;
 
     Object.defineProperty(target, propertyKey, {
-        get () : any {
+        get (): T {
             return this[privatePropertyKey];
         },
-        set (value: any) : void {
+        set (value: T): void {
             const oldValue = this[privatePropertyKey];
 
-            if (value === undefined || value === null || value === '') {
+            if (value === undefined || value === null || (typeof value === 'string' && value.trim() === '')) {
                 console.error(`<${componentName}> Missing required attribute "${propertyKey}"`);
             }
             this[privatePropertyKey] = value;
@@ -22,3 +22,4 @@ export const requiredProperty = (componentName: string) => function (target: any
         },
     });
 };
+

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

@@ -0,0 +1,94 @@
+import {
+    beforeEach,
+    afterEach,
+    describe,
+    it,
+    expect,
+    vi,
+} from 'vitest';
+
+import { requiredProperty } from '../required-property';
+
+describe('requiredProperty', () => {
+    let consoleErrorSpy: unknown;
+
+    beforeEach(() => {
+        // eslint-disable-next-line @typescript-eslint/no-empty-function
+        consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    // Mock class to test the decorator
+    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', () => {
+        // Arrange
+        const mockComponent = new MockComponent();
+
+        // Act
+        mockComponent.color = undefined;
+
+        // Assert
+        expect(consoleErrorSpy).toHaveBeenCalled();
+    });
+
+    it('should log an error if the property is null', () => {
+        // Arrange
+        const mockComponent = new MockComponent();
+
+        // Act
+        mockComponent.color = null;
+
+        // Assert
+        expect(consoleErrorSpy).toHaveBeenCalled();
+    });
+
+    it('should log an error if the property is an empty string', () => {
+        // Arrange
+        const mockComponent = new MockComponent();
+
+        // Act
+        mockComponent.color = '';
+
+        // Assert
+        expect(consoleErrorSpy).toHaveBeenCalled();
+    });
+
+    it('should not log an error if the property is a non-empty string', () => {
+        // Arrange
+        const mockComponent = new MockComponent();
+
+        // Act
+        mockComponent.color = 'blue';
+
+        // 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

@@ -0,0 +1,90 @@
+import {
+    beforeEach,
+    afterEach,
+    describe,
+    it,
+    expect,
+    vi,
+} from 'vitest';
+
+import { validPropertyValues } from '../valid-property-values';
+
+describe('validPropertyValues', () => {
+    let consoleErrorSpy: unknown;
+
+    beforeEach(() => {
+        // eslint-disable-next-line @typescript-eslint/no-empty-function
+        consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    // Mock class to test the decorator
+    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', () => {
+        // Arrange
+        const mockComponent = new MockComponent();
+
+        // Act
+        mockComponent.color = 'green';
+
+        // Assert
+        expect(mockComponent.color).toBe('green');
+        expect(consoleErrorSpy).not.toHaveBeenCalled();
+    });
+
+    it('should fallback to the default value if an invalid value is assigned', () => {
+        // Arrange
+        const mockComponent = new MockComponent();
+
+        // Act
+        mockComponent.color = 'yellow';
+
+        // Assert
+        expect(mockComponent.color).toBe('red');
+        expect(consoleErrorSpy).toHaveBeenCalled();
+    });
+
+    it('should log an error message if an invalid value is assigned', () => {
+        // Arrange
+        const mockComponent = new MockComponent();
+
+        // Act
+        mockComponent.color = 'yellow';
+
+        // Assert
+        expect(consoleErrorSpy).toHaveBeenCalledWith(
+            '<mock-component> Invalid value "yellow" provided for property "color".',
+            'Must be one of: red | green | blue.',
+            '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,14 +5,14 @@
  * @param defaultValue - The value to fall back on
  * @returns  - The decorator function
  */
-export const validPropertyValues = (componentName: string, validValues: any[], defaultValue: any) => function (target: any, 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, {
-        get () : any {
+        get (): T {
             return this[privatePropertyKey];
         },
-        set (value: any) : void {
+        set (value: T): void {
             const oldValue = this[privatePropertyKey];
 
             if (!validValues.includes(value)) {

package/src/index.ts

@@ -1,3 +1,3 @@
 export * from './mixins';
 export * from './decorators';
-export * from './test-helpers';
+export * from './type-helpers';

package/src/mixins/rtl/rtlMixin.ts

@@ -2,18 +2,29 @@
 import { LitElement } from 'lit';
 import { property } from 'lit/decorators/property.js';
 
+// According to TS, "A mixin class must have a constructor with a single rest parameter of type 'any[]'."
 type Constructor<T> = new (...args: any[]) => T;
 
-declare class RTLInterface {
-    dir: string;
+type htmlDirAttribute = 'ltr' | 'rtl' | 'auto';
+
+/**
+ * Any component property interface that implements RTL should extend this interface. See the ModalProps interface for an example of this.
+ */
+export interface RTLComponentProps {
+    dir: htmlDirAttribute
+}
+
+// This is just used by the dynamically constructed class below and does not need to be imported or referenced anywhere else
+declare class _RTLInterface {
+    dir: htmlDirAttribute;
     isRTL: boolean;
 }
 
 export const RtlMixin =
     <T extends Constructor<LitElement>>(superClass: T) => {
-        class RTLElement extends superClass {
-            @property({ type: String })
-                dir = '';
+        class RTLElement extends superClass implements _RTLInterface {
+            @property({ type: String, reflect: true })
+                dir : htmlDirAttribute = 'ltr';
 
             /**
              * Returns true if the element is in Right to Left mode.
@@ -37,5 +48,5 @@ export const RtlMixin =
             }
         }
 
-        return RTLElement as Constructor<RTLInterface> & T;
+        return RTLElement as Constructor<_RTLInterface> & T;
     };

package/src/type-helpers/DependentMap.ts

@@ -0,0 +1,6 @@
+/**
+ * A type alias that represents a specialized version of the built-in Map type, but with a custom get method that enforces stricter type checking
+ */
+export type DependentMap<T> = Omit<Map<keyof T, T[keyof T]>, 'get'> & {
+    get<K extends keyof T>(key: K): T[K] | undefined;
+}

package/src/type-helpers/index.ts

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

package/src/test-helpers/components/index.ts

@@ -1 +0,0 @@
-export * from './web-component-test-wrapper/WebComponentTestWrapper';

package/src/test-helpers/components/web-component-test-wrapper/WebComponentTestWrapper.ts

@@ -1,58 +0,0 @@
-import { LitElement, html, unsafeCSS } from 'lit'; // eslint-disable-line import/no-extraneous-dependencies
-import { property } from 'lit/decorators.js';
-import styles from './webComponentTestWrapper.scss?inline';
-
-/**
- * This is a Web Component used for visual testing purposes.
- * It allows us to wrap a component we'd like to test in a container
- * that displays the component's props as a label.
- *
- * Components can be tested without this, but it's useful if your tests
- * require additional markup when testing a component.
- */
-export class WebComponentTestWrapper extends LitElement {
-    static styles = unsafeCSS(styles);
-
-    /**
-     * The prop key and values to display above the component.
-     * This should be a single string representing a comma separated list of prop key/value pairs.
-     * Such as: 'size: small, isFullWidth: true'
-     */
-    @property({ type: String })
-        propKeyValues = '';
-
-    // Renders a string such as 'size: small, isFullWidth: true'
-    // as HTML such as:
-    // <p class="c-webComponentTestWrapper-label"><b>size</b>: <code>small</code></p>
-    // <p class="c-webComponentTestWrapper-label"><b>isFullWidth</b>: <code>true</code></p>
-    _renderPropKeyValues () {
-        return this.propKeyValues.split(',').map((propKeyValueString) => {
-            const [key, value] = propKeyValueString.split(':');
-
-            return html`<p class="c-webComponentTestWrapper-label"><b>${key}</b>: <code>${value}</code></p>`;
-        });
-    }
-
-    // eslint-disable-next-line class-methods-use-this
-    render () {
-        return html`
-            <div class="c-webComponentTestWrapper">
-                ${this._renderPropKeyValues()}
-                <div class="c-webComponentTestWrapper-slot">
-                    <slot></slot>
-                </div>
-            </div>`;
-    }
-}
-
-const componentSelector = 'web-component-test-wrapper';
-
-if (!customElements.get(componentSelector)) {
-    customElements.define(componentSelector, WebComponentTestWrapper);
-}
-
-declare global {
-    interface HTMLElementTagNameMap {
-        [componentSelector]: WebComponentTestWrapper;
-    }
-}

package/src/test-helpers/components/web-component-test-wrapper/webComponentTestWrapper.scss

@@ -1,20 +0,0 @@
-.c-webComponentTestWrapper {
-    padding-block: var(--dt-spacing-c);
-    padding-inline: var(--dt-spacing-e);
-    font-family: var(--dt-font-interactive-m-family);
-    font-size: calc(var(--dt-font-size-20) * 1px);
-    border: 1px solid var(--dt-color-background-dark);
-    display: grid;
-    grid-template-columns: 1fr 1fr;
-}
-
-.c-webComponentTestWrapper-label {
-    margin-block: var(--dt-spacing-c);
-}
-
-.c-webComponentTestWrapper-slot {
-    padding: var(--dt-spacing-c);
-    border: 1px dashed var(--dt-color-background-dark);
-    grid-column: 1 / 3;
-    margin-block-start: var(--dt-spacing-c);
-}

package/src/test-helpers/defs.ts

@@ -1,15 +0,0 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-export type PropObject = {
-    [key: string]: any;
-};
-
-export type WebComponentPropValues = {
-    [key: string]: any;
-};
-
-export type WebComponentTestInput = {
-    propValues: WebComponentPropValues;
-    renderedString: string;
-};
-
-export type WebComponentRenderFn = (propVals: WebComponentPropValues) => string;

package/src/test-helpers/get-all-prop-combos.ts

@@ -1,83 +0,0 @@
-import { PropObject, WebComponentPropValues } from './defs';
-
-/**
- * Generate all possible combinations of properties for a given object.
- *
- * @param {PropObject} obj - The object containing properties for which combinations are to be generated.
- * Each property value can any data type.
- *
- * @returns {WebComponentPropValues[]} An array of objects, where each object is a unique combination of web component property values.
- */
-export const getAllPropCombinations = (obj: PropObject): WebComponentPropValues[] => {
-    const propertyKeys = Object.keys(obj);
-    const combinationsOfPropValues: WebComponentPropValues[] = [];
-
-    // This function generates combinations of properties from a given object.
-    // It does this by recursively concatenating each property value to an 'accumulatedPropertyValues' array,
-    // and adding the resulting combination to a 'WebComponentPropValues' array when it reaches the end of the keys.
-    function generatePropCombinations (accumulatedPropertyValues: any[], i: number): void {
-    // When 'i' equals the length of 'keys', we've reached the end of the keys.
-    // This means we've formed a complete combination.
-        if (i === propertyKeys.length) {
-            // Create an empty object to hold the current WebComponentPropValues.
-            const combo: WebComponentPropValues = {};
-            // Loop over the 'accumulatedPropertyValues' array, which contains the property values for this combination.
-            for (let j = 0; j < accumulatedPropertyValues.length; j++) {
-            // Assign each value to the corresponding key in the 'combo' object.
-                combo[propertyKeys[j]] = accumulatedPropertyValues[j];
-            }
-            // Add this combination to the 'combinationsOfPropValues' array.
-            combinationsOfPropValues.push(combo);
-            // End the recursion for this branch.
-            return;
-        }
-
-        // Get the current key and its values from the input object.
-        const propertyKey = propertyKeys[i];
-        const propertyValues = obj[propertyKey];
-
-        if (typeof propertyValues === 'boolean') {
-            // If the values for this key are a boolean, we generate two combinations:
-            // one with the value 'true', and one with the value 'false'.
-            generatePropCombinations([...accumulatedPropertyValues, true], i + 1);
-            generatePropCombinations([...accumulatedPropertyValues, false], i + 1);
-        } else if (Array.isArray(propertyValues)) {
-            // If the values for this key are an array, we generate a combination for each value in the array.
-            for (let j = 0; j < propertyValues.length; j++) {
-                generatePropCombinations([...accumulatedPropertyValues, propertyValues[j]], i + 1);
-            }
-        } else {
-            // If the values for this key are neither a boolean nor an array,
-            // we simply generate a single combination with the value as is.
-            generatePropCombinations([...accumulatedPropertyValues, propertyValues], i + 1);
-        }
-    }
-
-    generatePropCombinations([], 0);
-
-    return combinationsOfPropValues;
-};
-
-/**
- * Splits an array of component prop combinations by a particular property value.
- *
- * @param {WebComponentPropValues[]} propValueCombinations - The array of combinations to split.
- * @param {string} property - The property to split by.
- *
- * @returns {Record<string, WebComponentPropValues[]>} An object mapping each unique property value to the combinations that have it.
- */
-export const splitCombinationsByPropertyValue = (propValueCombinations: WebComponentPropValues[], property: string): Record<string, WebComponentPropValues[]> => propValueCombinations
-    .reduce((splitCombinations: Record<string, WebComponentPropValues[]>, combination: WebComponentPropValues) => {
-        const propertyValue = combination[property];
-        const propertyValueKey = String(propertyValue);
-
-        if (!(propertyValueKey in splitCombinations)) {
-            splitCombinations[propertyValueKey] = [];
-        }
-
-        // Add the current combination to the array for its property value
-        splitCombinations[propertyValueKey].push(combination);
-
-        return splitCombinations;
-    }, {});
-

package/src/test-helpers/index.ts

@@ -1,5 +0,0 @@
-export * from './get-all-prop-combos';
-export * from './defs';
-export * from './rendering';
-export * from './components';
-export * from './percy-lit-options';

package/src/test-helpers/percy-lit-options.ts

@@ -1,37 +0,0 @@
-///*
-///* This code snippet was provided by Percy as a way to get our Lit components working correctly when running against the Safari browser.
-///* Safari blocks requests coming from localhost, resulting in our CSS not loading when requested.
-///* This function is passed to Percy and executed against the serialised DOM to rewrite all 'localhost' urls to 'render.percy.local'.
-///* This is a temporary workaround, and a long-term solution will be implemented by Percy at a later date.
-///*
-const percyOptions = {
-    domTransformation: (documentElement: any) => {
-        function updateLinks(root : any) {
-        root.querySelectorAll('[data-percy-adopted-stylesheets-serialized]').forEach((link : any) => {
-            console.log(link);
-            let href = link.getAttribute('data-percy-serialized-attribute-href');
-            href = href.replace(/localhost[:\d+]*/, 'render.percy.local');
-            link.setAttribute('data-percy-serialized-attribute-href', href);
-        });
-
-        root.querySelectorAll('[data-percy-shadow-host]')
-            .forEach((shadowHost : any) => {
-                console.log(shadowHost);
-                if (shadowHost?.shadowRoot)
-                updateLinks(shadowHost.shadowRoot);
-            }
-        );
-        }
-        updateLinks(documentElement);
-    }
-}
-
-const getLitPercyOptions = () => {
-    const options = {
-        domTransformation: percyOptions.domTransformation.toString()
-    }
-
-    return options;
-}
-
-export { getLitPercyOptions }

package/src/test-helpers/rendering.ts

@@ -1,10 +0,0 @@
-import { WebComponentPropValues, WebComponentTestInput, WebComponentRenderFn } from './defs';
-
-export function createTestWebComponent (propVals: WebComponentPropValues, componentRenderFn: WebComponentRenderFn): WebComponentTestInput {
-    const testComponent: WebComponentTestInput = {
-        propValues: propVals,
-        renderedString: componentRenderFn(propVals),
-    };
-
-    return testComponent;
-}