@justeattakeaway/pie-webc-core 0.13.0 → 0.14.0

package/.eslintignore

@@ -1,3 +1,5 @@
 .turbo
 dist
 node_modules
+test-results
+lit-browsers-report

package/.turbo/turbo-build.log

@@ -1,7 +1,7 @@
 vite v4.3.9 building for production...
 transforming...
-✓ 8 modules transformed.
+✓ 11 modules transformed.
 rendering chunks...
 computing gzip size...
-dist/index.js  1.91 kB │ gzip: 0.90 kB
-✓ built in 135ms
+dist/index.js  2.23 kB │ gzip: 1.02 kB
+✓ built in 117ms

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.14.0
+
+### Minor Changes
+
+- [Added] - Form Control Mixin for adding native form association behaviour to web components ([#1142](https://github.com/justeattakeaway/pie/pull/1142)) by [@jamieomaguire](https://github.com/jamieomaguire)
+
+- [Changed] - Re organised test structure and added playwright testing ([#1142](https://github.com/justeattakeaway/pie/pull/1142)) by [@jamieomaguire](https://github.com/jamieomaguire)
+
 ## 0.13.0
 
 ### Minor Changes

package/README.md

@@ -2,6 +2,73 @@
   <img align="center" src="../../../readme_image.png" height="200" alt="">
 </p>
 
+<p align="center">
+  <a href="https://www.npmjs.com/@justeattakeaway/pie-webc-core">
+    <img alt="GitHub Workflow Status" src="https://img.shields.io/npm/v/@justeattakeaway/pie-webc-core.svg">
+  </a>
+</p>
+
 # pie-webc-core
 
-A core library containing classes, mixins, utilities and anything else to be reused in our web components library.
+1. [Introduction](#introduction)
+2. [Installation](#installation)
+3. [Importing the package](#importing-the-package)
+4. [Dependencies](#dependencies)
+5. [Contributing](#contributing)
+6. [Testing](#testing)
+
+## Introduction
+
+A core library for PIE web components which contains classes, mixins, utilities and anything other functionality that can be shared across web components.
+
+
+## Installation
+
+To add `pie-webc-core` to your component, run the following on your command line:
+
+```bash
+$ yarn add @justeattakeaway/pie-webc-core
+```
+
+## Importing the package
+
+```js
+import { RequiredProperty, RtlMixin } from '@justeattakeaway/pie-webc-core';
+
+export class MyComponent extends RtlMixin(LitElement) implements MyComponentProps {
+  // ...
+
+  @property({ type: String })
+  @requiredProperty('my-component')
+  public value!: string;
+
+  // ...
+}
+```
+
+## Dependencies
+
+This package provides `lit` as a dependency which means the package that depends on `@justeattakeaway/pie-webc-core` will automatically install `lit` into the `node_modules` folder of its consuming application.
+
+Other dependencies may be added in future to make it easier for people to install and use our components.
+
+## Contributing
+
+Check out our [contributing guide](https://github.com/justeattakeaway/pie/wiki/Contributing-Guide) for more information on [local development](https://github.com/justeattakeaway/pie/wiki/Contributing-Guide#local-development).
+
+To run the unit tests, simply run `yarn test --filter=pie-webc-core` from the root of the monorepo.
+
+## Testing
+
+- Currently we have two methods of testing our core utilities:
+  - Unit tests using Vitest
+  - Browser tests using Playwright
+
+### Unit tests
+We write unit tests for small pieces of functionality that can be tested in isolation. These could be things such as class decorators or utility functions. However, sometimes testing in an isolated node environment is not enough. This is where Browser tests come in.
+
+### Browser tests
+We write browser tests for functionality that requires a browser environment to test. This could be things such as component class mixins. For these, we run our tests using Playwright. This allows us to run our tests in a real browser environment and test things such as DOM manipulation and events. A useful pattern for this kind of testing is to write a mock component that uses the mixin you want to test. This allows you to test the mixin in isolation without having to worry about the implementation of the component itself.
+
+### Naming and running tests
+Currently, for writing unit tests we simply name the file `**/*.spec.ts`. To write browser tests, we name the file `**/*.browser.spec.ts`. This allows us to run all unit tests using `yarn test --filter=pie-webc-core` and all browser tests using `yarn test:browsers --filter=pie-webc-core`.

package/dist/index.js

@@ -1,6 +1,6 @@
 import { isServer as u } from "lit";
-const f = (e) => {
-  class r extends e {
+const l = (e) => {
+  class t extends e {
     /**
      * A getter to determine whether the text direction is right-to-left (RTL).
      * If the `dir` property is present on the component, it will be used to determine the text direction.
@@ -14,40 +14,52 @@ const f = (e) => {
       return this.dir ? this.dir === "rtl" : !u && !this.dir ? document.documentElement.getAttribute("dir") === "rtl" : !1;
     }
   }
-  return r;
-}, l = (e, r, i) => function(o, t) {
-  const s = `#${t}`;
-  Object.defineProperty(o, t, {
+  return t;
+}, a = (e) => {
+  class t extends e {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    constructor(...i) {
+      super(...i), this._internals = this.attachInternals();
+    }
+    get form() {
+      return this._internals.form;
+    }
+  }
+  return t.formAssociated = !0, t;
+}, f = (e, t, n) => function(o, r) {
+  const s = `#${r}`;
+  Object.defineProperty(o, r, {
     get() {
       return this[s];
     },
-    set(d) {
-      r.includes(d) ? this[s] = d : (console.error(
-        `<${e}> Invalid value "${d}" provided for property "${t}".`,
-        `Must be one of: ${r.join(" | ")}.`,
-        `Falling back to default value: "${i}"`
-      ), this[s] = i);
+    set(c) {
+      t.includes(c) ? this[s] = c : (console.error(
+        `<${e}> Invalid value "${c}" provided for property "${r}".`,
+        `Must be one of: ${t.join(" | ")}.`,
+        `Falling back to default value: "${n}"`
+      ), this[s] = n);
     },
     configurable: !0
   });
-}, a = (e) => function(i, n) {
-  const o = `#${n}`;
-  Object.defineProperty(i, n, {
+}, m = (e) => function(n, i) {
+  const o = `#${i}`;
+  Object.defineProperty(n, i, {
     get() {
       return this[o];
     },
-    set(t) {
-      (t == null || typeof t == "string" && t.trim() === "") && console.error(`<${e}> Missing required attribute "${n}"`), this[o] = t;
+    set(r) {
+      (r == null || typeof r == "string" && r.trim() === "") && console.error(`<${e}> Missing required attribute "${i}"`), this[o] = r;
     },
     configurable: !0
   });
 };
-function m(e, r) {
-  customElements.get(e) ? console.warn(`PIE Web Component: "${e}" has already been defined. Please ensure the component is only being defined once in your application.`) : customElements.define(e, r);
+function h(e, t) {
+  customElements.get(e) ? console.warn(`PIE Web Component: "${e}" has already been defined. Please ensure the component is only being defined once in your application.`) : customElements.define(e, t);
 }
 export {
-  f as RtlMixin,
-  m as defineCustomElement,
-  a as requiredProperty,
-  l as validPropertyValues
+  a as FormControlMixin,
+  l as RtlMixin,
+  h as defineCustomElement,
+  m as requiredProperty,
+  f as validPropertyValues
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justeattakeaway/pie-webc-core",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "PIE design system base classes, mixins and utilities for web components",
   "type": "module",
   "main": "dist/index.js",
@@ -12,11 +12,16 @@
     "lint:scripts:fix": "run -T eslint . --fix",
     "test": "run -T vitest run",
     "test:ci": "yarn test",
+    "test:browsers": "npx playwright test -c ./playwright-lit.config.ts",
+    "test:browsers:ci": "yarn test:browsers",
     "test:watch": "run -T vitest"
   },
   "dependencies": {
     "lit": "3.1.0"
   },
+  "devDependencies": {
+    "@justeattakeaway/pie-components-config": "0.7.0"
+  },
   "volta": {
     "extends": "../../../package.json"
   }

package/playwright/index.html

@@ -0,0 +1,56 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="preload" href="https://d30v2pzvrfyzpo.cloudfront.net/fonts/JETSansDigital-Regular-optimised.woff2" as="font" type="font/woff2" crossorigin>
+    <link rel="preload" href="https://d30v2pzvrfyzpo.cloudfront.net/fonts/JETSansDigital-Bold-optimised.woff2" as="font" type="font/woff2" crossorigin>
+    <link rel="preload" href="https://d30v2pzvrfyzpo.cloudfront.net/fonts/JETSansDigital-ExtraBold-optimised.woff2" as="font" type="font/woff2" crossorigin>
+    <style>
+        @font-face {
+            font-family: JETSansDigital;
+            src: url('https://d30v2pzvrfyzpo.cloudfront.net/fonts/JETSansDigital-Regular-optimised.woff2') format("woff2"),
+            url('https://d30v2pzvrfyzpo.cloudfront.net/fonts/JETSansDigital-Regular-optimised.woff') format("woff");
+            font-weight: 400;
+            font-display: swap;
+        }
+        @font-face {
+            font-family: JETSansDigital;
+            src: url('https://d30v2pzvrfyzpo.cloudfront.net/fonts/JETSansDigital-Bold-optimised.woff2') format("woff2"),
+            url('https://d30v2pzvrfyzpo.cloudfront.net/fonts/JETSansDigital-Bold-optimised.woff') format("woff");
+            font-weight: 700;
+            font-display: swap;
+        }
+        @font-face {
+            font-family: JETSansDigital;
+            src: url('https://d30v2pzvrfyzpo.cloudfront.net/fonts/JETSansDigital-ExtraBold-optimised.woff2') format("woff2"),
+            url('https://d30v2pzvrfyzpo.cloudfront.net/fonts/JETSansDigital-ExtraBold-optimised.woff') format("woff");
+            font-weight: 800;
+            font-display: swap;
+        }
+        body {
+            font-feature-settings: "tnum"; /* Enable tabular numbers */
+        }
+        /* basic styles to center align components and give them some spacing */
+        #root {
+            padding: 1em;
+        }
+
+        #root > * {
+            display: block;
+            margin-inline: auto;
+        }
+
+        #root > * + * {
+            margin-top: 1em;
+        }
+    </style>
+    <title>Testing Page</title>
+    <link rel="stylesheet" type="text/css" href="https://unpkg.com/@justeat/pie-design-tokens/dist/jet.css" />
+    <link rel="stylesheet" type="text/css" href="https://unpkg.com/@justeat/pie-design-tokens/dist/jet-hsl-colors.css" />
+</head>
+<body>
+    <div id="root"></div>
+    <script type="module" src="./index.ts"></script>
+</body>
+</html>

package/playwright/index.ts

@@ -0,0 +1 @@
+// Import common styles here

package/playwright-lit.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig, devices } from '@sand4rt/experimental-ct-web';
+import { getPlaywrightConfig as getPlaywrightConfigOG } from '@justeattakeaway/pie-components-config';
+import type { PlaywrightTestConfig } from '@playwright/test';
+
+const getPlaywrightConfig = () : PlaywrightTestConfig => ({
+    ...getPlaywrightConfigOG(),
+    projects: [
+        {
+            name: 'component:chrome',
+            use: {
+                ...devices['Desktop Chrome'],
+            },
+            testMatch: ['**/test/**/*.browser.spec.ts'],
+        },
+    ],
+});
+
+export default defineConfig(getPlaywrightConfig());

package/src/mixins/formControl/formControlMixin.ts

@@ -0,0 +1,58 @@
+import { LitElement } from 'lit';
+import type { GenericConstructor } from '../types/GenericConstructor';
+
+/**
+ * Interface for FormControl behavior.
+ */
+export interface FormControlInterface {
+    _internals: ElementInternals;
+    get form(): HTMLFormElement | null;
+}
+
+/**
+ * Mixin to add form control behaviors to a LitElement.
+ * This mixin adds properties and methods to handle form-associated custom elements.
+ *
+ * @param superClass - The LitElement class to extend with form control functionality.
+ * @returns A class extending both the provided LitElement and _FormControlInterface.
+ *
+ * @example
+ * ```typescript
+ * import { LitElement, html } from 'lit';
+ * import { FormControlMixin } from './path-to-FormControlMixin'; // Update the import path
+ *
+ * // Create a new component using the FormControlMixin
+ * class MyFormElement extends FormControlMixin(LitElement) {
+ *   render() {
+ *     return html`<div>Form-associated element with form: ${this.form ? 'attached' : 'detached'}</div>`;
+ *   }
+ * }
+ *
+ * customElements.define('my-form-element', MyFormElement);
+ * ```
+ */
+export const FormControlMixin =
+    <T extends GenericConstructor<LitElement>>(superClass: T) => {
+        /**
+       * Class representing a LitElement that behaves like a native HTML form control element.
+       * @extends {LitElement}
+       * @implements {_FormControlInterface}
+       */
+        class FormControlElement extends superClass implements FormControlInterface {
+            static formAssociated = true;
+
+            _internals: ElementInternals;
+
+            get form () {
+                return this._internals.form;
+            }
+
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            constructor (...args: any[]) {
+                super(...args);
+                this._internals = this.attachInternals();
+            }
+        }
+
+        return FormControlElement as GenericConstructor<FormControlInterface> & T;
+    };

package/src/mixins/index.ts

@@ -1 +1,5 @@
 export * from './rtl/rtlMixin';
+export * from './formControl/formControlMixin';
+
+export * from './types/GenericConstructor';
+export * from './types/LitElementMixin';

package/src/mixins/rtl/rtlMixin.ts

@@ -1,13 +1,6 @@
 /* eslint-disable max-classes-per-file */
 import { LitElement, isServer } from 'lit';
-
-/**
- * A type representing a constructor of any class.
- * @typedef {new (...args: any[]) => T} Constructor
- * @template T
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-type Constructor<T> = new (...args: any[]) => T;
+import type { GenericConstructor } from '../types/GenericConstructor';
 
 /**
  * An interface representing the structure of RTL related class.
@@ -24,8 +17,8 @@ declare class _RTLInterface {
  * allowing you to easily determine the text direction within your component.
  *
  * @function
- * @param {Constructor<LitElement>} superClass - The LitElement class to extend with RTL functionality.
- * @returns {Constructor<_RTLInterface> & T} - A new class extending both LitElement and _RTLInterface.
+ * @param {GenericConstructor<LitElement>} superClass - The LitElement class to extend with RTL functionality.
+ * @returns {GenericConstructor<_RTLInterface> & T} - A new class extending both LitElement and _RTLInterface.
  *
  * @example
  * ```typescript
@@ -64,7 +57,7 @@ declare class _RTLInterface {
  * ```
  */
 export const RtlMixin =
-    <T extends Constructor<LitElement>>(superClass: T) => {
+    <T extends GenericConstructor<LitElement>>(superClass: T) => {
         /**
        * Class representing a LitElement with RTL handling.
        * @extends {LitElement}
@@ -94,5 +87,5 @@ export const RtlMixin =
             }
         }
 
-        return RTLElement as Constructor<_RTLInterface> & T;
+        return RTLElement as GenericConstructor<_RTLInterface> & T;
     };

package/src/mixins/types/GenericConstructor.ts

@@ -0,0 +1,7 @@
+/**
+ * A type representing a constructor of any class.
+ * @typedef {new (...args: any[]) => T} Constructor
+ * @template T
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type GenericConstructor<T> = new (...args: any[]) => T;

package/src/mixins/types/LitElementMixin.ts

@@ -0,0 +1,7 @@
+import { LitElement } from 'lit';
+import type { GenericConstructor } from './GenericConstructor';
+
+/**
+ * A type representing a mixin that is compatible with classes that extend LitElement.
+ */
+export type LitElementMixin<T extends GenericConstructor<LitElement>> = (base: T) => T;

package/src/{decorators/test → test/decorators}/required-property.spec.ts

@@ -7,7 +7,7 @@ import {
     vi,
 } from 'vitest';
 
-import { requiredProperty } from '../required-property';
+import { requiredProperty } from '../../decorators/required-property';
 
 describe('requiredProperty', () => {
     let consoleErrorSpy: unknown;

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

@@ -7,7 +7,7 @@ import {
     vi,
 } from 'vitest';
 
-import { validPropertyValues } from '../valid-property-values';
+import { validPropertyValues } from '../../decorators/valid-property-values';
 
 describe('validPropertyValues', () => {
     let consoleErrorSpy: unknown;

package/src/{functions/test → test/functions}/defineCustomElement.spec.ts

@@ -3,7 +3,7 @@ import { LitElement } from 'lit';
 import {
     vi, expect, it,
 } from 'vitest';
-import { defineCustomElement } from '../defineCustomElement';
+import { defineCustomElement } from '../../functions/defineCustomElement';
 
 it('should call console.warn when a component is defined twice', () => {
     // Arrange

package/src/test/mixins/formControlMixin/MockComponent.ts

@@ -0,0 +1,19 @@
+import { LitElement, html } from 'lit';
+import { FormControlMixin } from '../../../mixins/formControl/formControlMixin.ts';
+import { defineCustomElement } from '../../../functions/defineCustomElement.ts';
+
+const componentSelector = 'form-control-mixin-mock';
+
+export class MockComponent extends FormControlMixin(LitElement) {
+    render () {
+        return html`<div>Form Control Component</div>`;
+    }
+}
+
+declare global {
+    interface HTMLElementTagNameMap {
+        [componentSelector]: MockComponent;
+    }
+}
+
+defineCustomElement(componentSelector, MockComponent);

package/src/test/mixins/formControlMixin/formControlMixin.browser.spec.ts

@@ -0,0 +1,76 @@
+import { test, expect } from '@sand4rt/experimental-ct-web';
+import { MockComponent } from './MockComponent.ts';
+
+test.describe('FormControlMixin', () => {
+    // IMPORTANT: Mounting and Unmounting the component before each test ensures that any tests that do not explicitly
+    // mount the component will still have it available in Playwright's cache (loaded and registered in the test browser)
+    test.beforeEach(async ({ mount }) => {
+        const component = await mount(MockComponent);
+        await component.unmount();
+    });
+
+    test.describe('form property', () => {
+        test.describe('when no form exists', () => {
+            test('should not have an associated form', async ({ page, mount }) => {
+                // Arrange
+                await mount(MockComponent);
+
+                const isFormAssociated = await page.evaluate(() => {
+                    const component = document.querySelector('form-control-mixin-mock');
+                    const form = component?.form;
+
+                    return !!form;
+                });
+
+                // Assert
+                expect(isFormAssociated).toBe(false);
+            });
+        });
+
+        test.describe('when inside of a form', () => {
+            test('should return the associated form', async ({ page }) => {
+                // Arrange
+                await page.setContent(`
+                    <form id="testForm" action="/foo" method="POST">
+                        <input type="text" id="username" name="username" required>
+                        <input type="password" id="password" name="password" required>
+                        <form-control-mixin-mock></form-control-mixin-mock>
+                    </form>
+                `);
+
+                const formId = await page.evaluate(() => {
+                    const component = document.querySelector('form-control-mixin-mock');
+                    const form = component?.form;
+
+                    return form?.id;
+                });
+
+                // Assert
+                expect(formId).toContain('testForm');
+            });
+        });
+
+        test.describe('when not inside of an existing form', () => {
+            test('should not have an associated form', async ({ page }) => {
+                // Arrange
+                await page.setContent(`
+                    <form id="siblingForm" action="/foo" method="POST">
+                        <input type="text" id="username" name="username" required>
+                        <input type="password" id="password" name="password" required>
+                    </form>
+                    <form-control-mixin-mock></form-control-mixin-mock>
+                `);
+
+                const isFormAssociated = await page.evaluate(() => {
+                    const component = document.querySelector('form-control-mixin-mock');
+                    const form = component?.form;
+
+                    return !!form;
+                });
+
+                // Assert
+                expect(isFormAssociated).toBe(false);
+            });
+        });
+    });
+});

package/src/{mixins/test → test/mixins/rtlMixin}/rtlMixin.client.spec.ts

@@ -9,7 +9,7 @@ import {
     vi,
 } from 'vitest';
 
-import { RtlMixin } from '../index';
+import { RtlMixin } from '../../../index';
 
 const scenarios = [
     { dir: 'ltr', isRTL: false },

package/src/{mixins/test → test/mixins/rtlMixin}/rtlMixin.server.spec.ts

@@ -9,7 +9,7 @@ import {
     vi,
 } from 'vitest';
 
-import { RtlMixin } from '../index';
+import { RtlMixin } from '../../../index';
 
 const scenarios = [
     { dir: 'ltr', isRTL: false },

package/tsconfig.json

@@ -1,30 +1,8 @@
 {
+  "extends": "../../../configs/pie-components-config/tsconfig.json",
   "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
+    "baseUrl": ".",
+    "rootDir": ".",
   },
-  "include": ["src/**/*.ts","./declaration.d.ts", "test/**/*.ts", "index.ts"],
-  "exclude": []
+  "include": ["src/**/*.ts", "./declaration.d.ts", "test/**/*.ts", "index.ts", "playwright-lit.config.ts"],
 }

package/vite.config.js

@@ -14,5 +14,6 @@ export default defineConfig({
     },
     test: {
         environment: 'jsdom',
+        exclude: ['**/*.browser.spec.ts'],
     },
 });