@justeattakeaway/pie-webc-core 0.0.0-snapshot-release-20240104162246

package/.eslintignore

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

package/.turbo/turbo-build.log

@@ -0,0 +1,7 @@
+vite v4.3.9 building for production...
+transforming...
+✓ 10 modules transformed.
+rendering chunks...
+computing gzip size...
+dist/index.js  2.23 kB │ gzip: 1.03 kB
+✓ built in 127ms

package/CHANGELOG.md

@@ -0,0 +1,119 @@
+# Changelog
+
+## 0.0.0-snapshot-release-20240104162246
+
+### Minor Changes
+
+- [Removed] - unused LitElementMixin type as we do not need it anywhere ([#1145](https://github.com/justeattakeaway/pie/pull/1145)) by [@jamieomaguire](https://github.com/jamieomaguire)
+
+- [Changed] - Updated LitElement imports where it is only used as a type to include the 'type' keyword (fixes a TS error in some consumers) ([#1143](https://github.com/justeattakeaway/pie/pull/1143)) by [@jamieomaguire](https://github.com/jamieomaguire)
+
+- [Changed] - Use proper interface keyword for RTLmixin interface. Was using a class before which is incorrect. ([#1145](https://github.com/justeattakeaway/pie/pull/1145)) by [@jamieomaguire](https://github.com/jamieomaguire)
+
+## 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
+
+- [Added] - Build webc-core using vite ([#1037](https://github.com/justeattakeaway/pie/pull/1037)) by [@xander-marjoram](https://github.com/xander-marjoram)
+
+- [Changed] - Move lit dependency from storybook to webc-core ([#1037](https://github.com/justeattakeaway/pie/pull/1037)) by [@xander-marjoram](https://github.com/xander-marjoram)
+
+## 0.12.0
+
+### Minor Changes
+
+- [Changed] - `@validPropertyValues` and `@requiredProperty` decorators to support Lit 3. ([#1027](https://github.com/justeattakeaway/pie/pull/1027)) by [@raoufswe](https://github.com/raoufswe)
+
+## 0.12.0-next.0
+
+### Minor Changes
+
+- [Changed] - `@validPropertyValues` and `@requiredProperty` decorators to support Lit 3. ([#1025](https://github.com/justeattakeaway/pie/pull/1025)) by [@raoufswe](https://github.com/raoufswe)
+
+## 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
+
+- [Fixed] - License removed from packages ([#869](https://github.com/justeattakeaway/pie/pull/869)) by [@kevinrodrigues](https://github.com/kevinrodrigues)
+
+## 0.9.1
+
+### Patch Changes
+
+- [Changed] - Align author field for all packages ([#852](https://github.com/justeattakeaway/pie/pull/852)) by [@xander-marjoram](https://github.com/xander-marjoram)
+
+## 0.9.0
+
+### Minor Changes
+
+- [Changed] - Rewrite RTL mixin to remove the dir property. The LitElement base class is a subclass of HTMLElement, so a Lit component inherits all of the standard HTMLElement properties and methods. This means that the dir property is already available on the component and we don't need to add it again. [Reference](https://lit.dev/docs/components/defining/#a-lit-component-is-an-html-element). During SSR, if no dir is provided, it will be inferred from the document.documentElement once it's instantiated on the client. ([#818](https://github.com/justeattakeaway/pie/pull/818)) by [@jamieomaguire](https://github.com/jamieomaguire)
+
+- [Changed] - Removed the DependantMap type and replaced all references with Lit's own PropertyValues helper. This provides exactly the same strongly typed map for a component's properties which makes our own type a little redundant. [Reference](https://lit.dev/docs/components/lifecycle/#typescript-types-for-changedproperties) ([#818](https://github.com/justeattakeaway/pie/pull/818)) by [@jamieomaguire](https://github.com/jamieomaguire)
+
+## 0.8.0
+
+### Minor Changes
+
+- [Changed] - Update RTL mixin to infer dir by default and document ([#745](https://github.com/justeattakeaway/pie/pull/745)) by [@raoufswe](https://github.com/raoufswe)
+
+## 0.7.0
+
+### Minor Changes
+
+- [Changed] - Add js/ts linting and fix errors ([#653](https://github.com/justeattakeaway/pie/pull/653)) by [@jamieomaguire](https://github.com/jamieomaguire)
+
+## 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
+
+- [Added] - New function to fix CSS loading in Safari Percy tests ([#534](https://github.com/justeattakeaway/pie/pull/534)) by [@siggerzz](https://github.com/siggerzz)
+
+## 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/README.md

@@ -0,0 +1,74 @@
+<p align="center">
+  <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
+
+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/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/dist/index.js

@@ -0,0 +1,65 @@
+import { isServer as u } from "lit";
+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.
+     * If running on the client-side (not SSR) and the `dir` property is not present, the text direction will be inferred
+     * from the document's root element. This inference is not available during SSR.
+     * In all other cases, it will return `false`, indicating a left-to-right (LTR) text direction.
+     *
+     * @returns {boolean} - Returns `true` if the text direction is RTL, otherwise `false`.
+     */
+    get isRTL() {
+      return this.dir ? this.dir === "rtl" : !u && !this.dir ? document.documentElement.getAttribute("dir") === "rtl" : !1;
+    }
+  }
+  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(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
+  });
+}, m = (e) => function(n, i) {
+  const o = `#${i}`;
+  Object.defineProperty(n, i, {
+    get() {
+      return this[o];
+    },
+    set(r) {
+      (r == null || typeof r == "string" && r.trim() === "") && console.error(`<${e}> Missing required attribute "${i}"`), this[o] = r;
+    },
+    configurable: !0
+  });
+};
+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 {
+  a as FormControlMixin,
+  l as RtlMixin,
+  h as defineCustomElement,
+  m as requiredProperty,
+  f as validPropertyValues
+};

package/index.ts

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

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@justeattakeaway/pie-webc-core",
+  "version": "0.0.0-snapshot-release-20240104162246",
+  "description": "PIE design system base classes, mixins and utilities for web components",
+  "type": "module",
+  "main": "dist/index.js",
+  "author": "Just Eat Takeaway.com - Design System Team",
+  "license": "Apache-2.0",
+  "scripts": {
+    "build": "run -T vite build",
+    "lint:scripts": "run -T eslint .",
+    "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/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,21 @@
+/**
+ * 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 = <T>(componentName: string) => function validateRequiredProperty (target: object, propertyKey: string): void {
+    const privatePropertyKey = `#${propertyKey}`;
+
+    Object.defineProperty(target, propertyKey, {
+        get (): T {
+            return this[privatePropertyKey];
+        },
+        set (value: T): void {
+            if (value === undefined || value === null || (typeof value === 'string' && value.trim() === '')) {
+                console.error(`<${componentName}> Missing required attribute "${propertyKey}"`);
+            }
+            this[privatePropertyKey] = value;
+        },
+        configurable: true,
+    });
+};

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

@@ -0,0 +1,29 @@
+/**
+ * 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 = <T>(componentName: string, validValues: readonly T[], defaultValue: T) => function validatePropertyValues (target: object, propertyKey: string) : void {
+    const privatePropertyKey = `#${propertyKey}`;
+
+    Object.defineProperty(target, propertyKey, {
+        get (): T {
+            return this[privatePropertyKey];
+        },
+        set (value: T): void {
+            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;
+            }
+        },
+        configurable: true,
+    });
+};

package/src/functions/defineCustomElement.ts

@@ -0,0 +1,47 @@
+import type { 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/index.ts

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

package/src/mixins/formControl/formControlMixin.ts

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

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

package/src/mixins/rtl/rtlMixin.ts

@@ -0,0 +1,91 @@
+/* eslint-disable max-classes-per-file */
+import { LitElement, isServer } from 'lit';
+import type { GenericConstructor } from '../types/GenericConstructor';
+
+/**
+ * An interface representing the structure of RTL related class.
+ * @interface
+ */
+export interface RTLInterface {
+    /** A boolean indicating whether the text direction is right-to-left. */
+    isRTL: boolean;
+}
+
+/**
+ * A mixin to extend LitElement with right-to-left (RTL) text direction handling.
+ * This mixin adds a read-only `isRTL` property to the class it's applied to,
+ * allowing you to easily determine the text direction within your component.
+ *
+ * @function
+ * @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
+ * import { LitElement, html } from 'lit';
+ * import { RtlMixin } from './RtlMixin'; // Adjust the import path as needed
+ *
+ * class MyElement extends RtlMixin(LitElement) {
+ *   render() {
+ *     return html`<p>Text direction is ${this.isRTL ? 'right-to-left' : 'left-to-right'}</p>`;
+ *   }
+ * }
+ *
+ * customElements.define('my-element', MyElement);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { LitElement, html } from 'lit';
+ * import { RtlMixin } from './RtlMixin'; // Adjust the import path as needed
+ *
+ * class MyStyledElement extends RtlMixin(LitElement) {
+ *   render() {
+ *     return html`<div class="foo" ?isRTL=${this.isRTL}>Content</div>`;
+ *   }
+ * }
+ *
+ * customElements.define('my-styled-element', MyStyledElement);
+ * ```
+ *
+ * The corresponding SCSS to leverage the `isRTL` attribute:
+ * ```scss
+ * .foo[isRTL] {
+ *   background-color: red;
+ *   text-align: right;
+ * }
+ * ```
+ */
+export const RtlMixin =
+    <T extends GenericConstructor<LitElement>>(superClass: T) => {
+        /**
+       * Class representing a LitElement with RTL handling.
+       * @extends {LitElement}
+       * @implements {RTLInterface}
+       */
+        class RTLElement extends superClass implements RTLInterface {
+            /**
+             * 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.
+             * If running on the client-side (not SSR) and the `dir` property is not present, the text direction will be inferred
+             * from the document's root element. This inference is not available during SSR.
+             * In all other cases, it will return `false`, indicating a left-to-right (LTR) text direction.
+             *
+             * @returns {boolean} - Returns `true` if the text direction is RTL, otherwise `false`.
+             */
+            get isRTL (): boolean {
+                if (this.dir) {
+                    return this.dir === 'rtl';
+                }
+
+                // If running on client-side and `dir` is not present, infer from the document's root element.
+                if (!isServer && !this.dir) {
+                    return document.documentElement.getAttribute('dir') === 'rtl';
+                }
+
+                return false;
+            }
+        }
+
+        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/test/decorators/required-property.spec.ts

@@ -0,0 +1,73 @@
+import {
+    beforeEach,
+    afterEach,
+    describe,
+    it,
+    expect,
+    vi,
+} from 'vitest';
+
+import { requiredProperty } from '../../decorators/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;
+    }
+
+    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();
+    });
+});

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

@@ -0,0 +1,68 @@
+import {
+    beforeEach,
+    afterEach,
+    describe,
+    it,
+    expect,
+    vi,
+} from 'vitest';
+
+import { validPropertyValues } from '../../decorators/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';
+    }
+
+    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"',
+        );
+    });
+});

package/src/test/functions/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 '../../functions/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/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/test/mixins/rtlMixin/rtlMixin.client.spec.ts

@@ -0,0 +1,92 @@
+import {
+    LitElement, html, nothing,
+} from 'lit';
+
+import {
+    describe,
+    it,
+    expect,
+    vi,
+} from 'vitest';
+
+import { RtlMixin } from '../../../index';
+
+const scenarios = [
+    { dir: 'ltr', isRTL: false },
+    { dir: 'rtl', isRTL: true },
+    { dir: 'auto', isRTL: false }
+];
+
+vi.mock('lit', async () => ({
+    ...((await vi.importActual('lit')) as Array<unknown>),
+    isServer: false,
+}));
+
+describe('RtlMixin', () => {
+    const componentSelector = 'rtl-mixin-mock';
+
+    class MockComponent extends RtlMixin(LitElement) {
+        render () {
+            const { isRTL, dir } = this;
+            return html`<div dir="${dir || nothing}">${isRTL ? 'RTL Mode' : 'LTR Mode'}</div>`;
+        }
+    }
+
+    customElements.define(componentSelector, MockComponent);
+
+    function getMockInstance (): MockComponent {
+        return document.body.querySelector(componentSelector) as MockComponent;
+    }
+
+    describe('when running in the browser', () => {
+        describe('when the dir attribute is set via the component', () => {
+            scenarios.forEach(({ dir, isRTL }) => {
+                it(`should reflect ${isRTL ? 'RTL' : 'LTR'} if the component dir attribute is set to ${dir}`, () => {
+                    // Arrange
+                    document.body.innerHTML = `<rtl-mixin-mock dir="${dir}"></rtl-mixin-mock>`;
+                    const component = getMockInstance();
+
+                    // Assert
+                    expect(component.isRTL).toBe(isRTL);
+                });
+            });
+        });
+
+        describe('when the dir attribute is set via the root document and no attribute provided to the component', () => {
+            scenarios.forEach(({ dir, isRTL }) => {
+                it(`should reflect ${isRTL ? 'RTL' : 'LTR'} if the root document dir attribute is set to ${dir}`, () => {
+                    // Arrange
+                    document.documentElement.setAttribute('dir', dir);
+                    document.body.innerHTML = '<rtl-mixin-mock></rtl-mixin-mock>'; // component doesn't set dir
+                    const component = getMockInstance();
+
+                    // Assert
+                    expect(component.isRTL).toBe(isRTL);
+                });
+            });
+        });
+
+        it('should prefer the dir value of the component over the root document when both are set', () => {
+            // Arrange
+            const rootDir = 'ltr';
+            const componentDir = 'rtl';
+            document.documentElement.setAttribute('dir', rootDir);
+            document.body.innerHTML = `<rtl-mixin-mock dir="${componentDir}"></rtl-mixin-mock>`;
+            const component = getMockInstance();
+
+            // Assert
+            expect(component.isRTL).toBeTruthy();
+        });
+
+        it('should reflect the root document dir attribute if `auto` is provided to the component', () => {
+            // Arrange
+            const rootDir = 'ltr';
+            document.documentElement.setAttribute('dir', rootDir);
+            document.body.innerHTML = '<rtl-mixin-mock dir="auto"></rtl-mixin-mock>';
+            const component = getMockInstance();
+
+            // Assert
+            expect(component.isRTL).toBeFalsy();
+        });
+    });
+});

package/src/test/mixins/rtlMixin/rtlMixin.server.spec.ts

@@ -0,0 +1,62 @@
+import {
+    LitElement, html, nothing,
+} from 'lit';
+
+import {
+    describe,
+    it,
+    expect,
+    vi,
+} from 'vitest';
+
+import { RtlMixin } from '../../../index';
+
+const scenarios = [
+    { dir: 'ltr', isRTL: false },
+    { dir: 'rtl', isRTL: true },
+    { dir: 'auto', isRTL: false }
+];
+
+vi.mock('lit', async () => ({
+    ...((await vi.importActual('lit')) as Array<unknown>),
+    isServer: true,
+}));
+
+describe('RtlMixin', () => {
+    const componentSelector = 'rtl-mixin-mock';
+
+    class MockComponent extends RtlMixin(LitElement) {
+        render () {
+            const { isRTL, dir } = this;
+            return html`<div dir="${dir || nothing}">${isRTL ? 'RTL Mode' : 'LTR Mode'}</div>`;
+        }
+    }
+
+    customElements.define(componentSelector, MockComponent);
+
+    function getMockInstance (): MockComponent {
+        return document.body.querySelector(componentSelector) as MockComponent;
+    }
+
+    describe('when running on the server', () => {
+        it('should return false for isRTL when dir is not set', () => {
+            // Arrange
+            document.body.innerHTML = '<rtl-mixin-mock></rtl-mixin-mock>';
+            const component = getMockInstance();
+
+            // Assert
+            expect(component.isRTL).toBeFalsy();
+        });
+
+        scenarios.forEach(({ dir, isRTL }) => {
+            it(`should reflect ${isRTL ? 'RTL' : 'LTR'} if the component dir attribute is set to ${dir} when running on the server`, () => {
+                // Arrange
+                document.body.innerHTML = `<rtl-mixin-mock dir="${dir}"></rtl-mixin-mock>`;
+                const component = getMockInstance();
+
+                // Assert
+                expect(component.isRTL).toBe(isRTL);
+            });
+        });
+    });
+});

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../../configs/pie-components-config/tsconfig.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "rootDir": ".",
+  },
+  "include": ["src/**/*.ts", "./declaration.d.ts", "test/**/*.ts", "index.ts", "playwright-lit.config.ts"],
+}

package/vite.config.js

@@ -0,0 +1,19 @@
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+    build: {
+        lib: {
+            entry: {
+                index: 'src/index.ts',
+            },
+            formats: ['es'],
+        },
+        rollupOptions: {
+            external: (id) => /^lit/.test(id),
+        },
+    },
+    test: {
+        environment: 'jsdom',
+        exclude: ['**/*.browser.spec.ts'],
+    },
+});