@justeattakeaway/pie-webc-core 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## 0.3.0
+
+### Minor Changes
+
+- [Added] - new WebComponentTestWrapper test component for adding labels to visual tests ([#519](https://github.com/justeattakeaway/pie/pull/519)) by [@jamieomaguire](https://github.com/jamieomaguire)
+
+- [Added] - a helper module to generate all prop variants of a given component ([#499](https://github.com/justeattakeaway/pie/pull/499)) by [@jamieomaguire](https://github.com/jamieomaguire)
+
+- [Added] - `required` property decorator ([#530](https://github.com/justeattakeaway/pie/pull/530)) by [@raoufswe](https://github.com/raoufswe)
+
+- [Changed] - Make pie-webc-core public ([#523](https://github.com/justeattakeaway/pie/pull/523)) by [@jamieomaguire](https://github.com/jamieomaguire)
+
+## 0.2.0
+
+### Minor Changes
+
+- [Added] - Property validation decorator ([#491](https://github.com/justeattakeaway/pie/pull/491)) by [@jamieomaguire](https://github.com/jamieomaguire)
+
+## 0.1.0
+
+### Minor Changes
+
+- [Added] - RTL Mixin and base project ([#478](https://github.com/justeattakeaway/pie/pull/478)) by [@jamieomaguire](https://github.com/jamieomaguire)

package/LICENSE

@@ -0,0 +1,17 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+Copyright (c) Just Eat Takeaway.com
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,7 @@
+<p align="center">
+  <img align="center" src="../../../readme_image.png" height="200" alt="">
+</p>
+
+# pie-webc-core
+
+A core library containing classes, mixins, utilities and anything else to be reused in our web components library.

package/index.ts

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

package/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@justeattakeaway/pie-webc-core",
+  "version": "0.3.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",
+  "volta": {
+    "extends": "../../../package.json"
+  }
+}

package/src/decorators/index.ts

@@ -0,0 +1,3 @@
+export * from './valid-property-values';
+export * from './required-property';
+

package/src/decorators/required-property.ts

@@ -0,0 +1,24 @@
+/**
+ * A decorator for marking a property as required.
+ * 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 {
+    const privatePropertyKey = `#${propertyKey}`;
+
+    Object.defineProperty(target, propertyKey, {
+        get () : any {
+            return this[privatePropertyKey];
+        },
+        set (value: any) : void {
+            const oldValue = this[privatePropertyKey];
+
+            if (value === undefined || value === null || value === '') {
+                console.error(`<${componentName}> Missing required attribute "${propertyKey}"`);
+            }
+            this[privatePropertyKey] = value;
+
+            this.requestUpdate(propertyKey, oldValue);
+        },
+    });
+};

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

@@ -0,0 +1,32 @@
+/**
+ * A decorator for specifying a list of valid values for a property.
+ * If this property's setter is called with an invalid value, an error is logged and the default value will be assigned instead.
+ * @param validValues - The array of valid values
+ * @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 {
+    const privatePropertyKey = `#${propertyKey}`;
+
+    Object.defineProperty(target, propertyKey, {
+        get () : any {
+            return this[privatePropertyKey];
+        },
+        set (value: any) : void {
+            const oldValue = this[privatePropertyKey];
+
+            if (!validValues.includes(value)) {
+                console.error(
+                        `<${componentName}> Invalid value "${value}" provided for property "${propertyKey}".`,
+                        `Must be one of: ${validValues.join(' | ')}.`,
+                        `Falling back to default value: "${defaultValue}"`,
+                );
+                this[privatePropertyKey] = defaultValue;
+            } else {
+                this[privatePropertyKey] = value;
+            }
+
+            this.requestUpdate(propertyKey, oldValue);
+        },
+    });
+};

package/src/index.ts

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

package/src/mixins/index.ts

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

package/src/mixins/rtl/rtlMixin.ts

@@ -0,0 +1,41 @@
+/* eslint-disable max-classes-per-file */
+import { LitElement } from 'lit';
+import { property } from 'lit/decorators/property.js';
+
+type Constructor<T> = new (...args: any[]) => T;
+
+declare class RTLInterface {
+    dir: string;
+    isRTL: boolean;
+}
+
+export const RtlMixin =
+    <T extends Constructor<LitElement>>(superClass: T) => {
+        class RTLElement extends superClass {
+            @property({ type: String })
+                dir = '';
+
+            /**
+             * Returns true if the element is in Right to Left mode.
+             * If a dir attribute is not explicitly set on the web component
+             * then it falls back to the nearest parent with a dir attribute set.
+             *
+             * A dir attribute being set will result in a reactive property.
+             * If the component falls back to a parent dir attribute then the value
+             * will not be reactive and is only computed once
+             */
+            get isRTL () : boolean {
+                if (this.dir === 'ltr') {
+                    return false;
+                }
+
+                if (this.dir === 'rtl' || window?.getComputedStyle(this)?.direction === 'rtl') {
+                    return true;
+                }
+
+                return false;
+            }
+        }
+
+        return RTLElement as Constructor<RTLInterface> & T;
+    };

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

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

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

@@ -0,0 +1,58 @@
+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

@@ -0,0 +1,20 @@
+.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

@@ -0,0 +1,15 @@
+/* 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

@@ -0,0 +1,83 @@
+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

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

package/src/test-helpers/rendering.ts

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

package/tsconfig.json

@@ -0,0 +1,30 @@
+{
+  "compilerOptions": {
+      "target": "ES6",
+      "module": "ES2022",
+      "lib": ["es2020", "DOM", "DOM.Iterable"],
+      "declaration": true,
+      "declarationMap": true,
+      "sourceMap": true,
+      "inlineSources": true,
+      "outDir": "./compiled",
+      "baseUrl": ".",
+      "paths": {
+        "@/*": ["./src/*"]
+      },
+      "rootDir": ".",
+      "strict": true,
+      "noUnusedLocals": true,
+      "noUnusedParameters": true,
+      "noImplicitReturns": true,
+      "noFallthroughCasesInSwitch": true,
+      "noImplicitAny": true,
+      "noImplicitThis": true,
+      "moduleResolution": "node",
+      "allowSyntheticDefaultImports": true,
+      "experimentalDecorators": true,
+      "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*.ts","./declaration.d.ts", "test/**/*.ts"],
+  "exclude": []
+}