@justeattakeaway/pie-webc-core 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justeattakeaway/pie-webc-core",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "PIE design system base classes, mixins and utilities for web components",
   "type": "module",
   "main": "index.ts",

package/src/index.ts

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

package/src/mixins/rtl/rtlMixin.ts

@@ -1,55 +1,96 @@
 /* eslint-disable max-classes-per-file */
-import { LitElement } from 'lit';
-import { property } from 'lit/decorators/property.js';
+import { LitElement, isServer } from 'lit';
 
-// According to TS, "A mixin class must have a constructor with a single rest parameter of type 'any[]'."
+/**
+ * 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;
 
-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.
+ * An interface representing the structure of RTL related class.
+ * @interface
  */
-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;
+    /** A boolean indicating whether the text direction is right-to-left. */
     isRTL: boolean;
 }
 
 /**
- * This RTL mixin is used with Lit Web components to add programmatic Right-to-Left (RTL) support.
- * It is only required if your component either:
- * - Needs RTL awareness in its TypeScript logic.
- * - Its CSS requires a [dir='rtl'] attribute to be present.
- *
- * By default, components will infer the 'dir' property from the document's root 'dir' attribute.
- * If needed, it's possible to override specific components direction by setting the 'dir' property
- * value. The 'dir' property value is reflected in the DOM, making it queryable. The 'isRTL'
- * internal property returns true or false depending on whether or not the 'dir' property is 'rtl' or not.
+ * 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 {Constructor<LitElement>} superClass - The LitElement class to extend with RTL functionality.
+ * @returns {Constructor<_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 Constructor<LitElement>>(superClass: T) => {
+        /**
+       * Class representing a LitElement with RTL handling.
+       * @extends {LitElement}
+       * @implements {_RTLInterface}
+       */
         class RTLElement extends superClass implements _RTLInterface {
-            @property({ type: String, reflect: true })
-                dir : htmlDirAttribute = document?.documentElement?.dir as htmlDirAttribute ?? 'ltr';
-
             /**
-             * 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 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.
              *
-             * 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
+             * @returns {boolean} - Returns `true` if the text direction is RTL, otherwise `false`.
              */
-            get isRTL () : boolean {
-                return this.dir === 'rtl';
+            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;
             }
         }
 

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

@@ -1,72 +0,0 @@
-import { LitElement, html, nothing } from 'lit';
-import {
-    describe,
-    it,
-    expect,
-} from 'vitest';
-import { RTLComponentProps, RtlMixin } from '../index';
-
-const scenarios = [
-    { dir: 'ltr', isRTL: false },
-    { dir: 'rtl', isRTL: true },
-    { dir: 'auto', isRTL: false }
-];
-
-describe('RtlMixin', () => {
-    const componentSelector = 'rtl-mixin-mock';
-    class MockComponent extends RtlMixin(LitElement) implements RTLComponentProps {
-        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 the dir attribute is set via the component', () => {
-        scenarios.forEach(({ dir, isRTL }) => {
-            it(`should default to ${dir} 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.dir).toEqual(dir);
-                expect(component.isRTL).toBe(isRTL);
-            });
-        });
-    });
-
-    describe('when the dir attribute is set via the root document', () => {
-        scenarios.forEach(({ dir, isRTL }) => {
-            it(`should default to ${dir} 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.dir).toEqual(dir);
-                expect(component.isRTL).toBe(isRTL);
-            });
-        });
-    });
-
-    it('should default to dir value of the component if the root document and component dir attribute 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.dir).toEqual(componentDir);
-        expect(component.dir).not.toEqual(rootDir);
-        expect(component.isRTL).toBeTruthy();
-    });
-});

package/src/type-helpers/DependentMap.ts

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

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