@justeattakeaway/pie-modal 0.9.0 → 0.11.0

package/dist/types/packages/components/pie-modal/src/index.d.ts

@@ -1,4 +1,4 @@
-import { LitElement } from 'lit';
+import { LitElement, TemplateResult } from 'lit';
 import type { DependentMap } from '@justeattakeaway/pie-webc-core';
 import { ModalProps, headingLevels, sizes } from './defs';
 export { type ModalProps, headingLevels, sizes };
@@ -7,13 +7,18 @@ declare const PieModal_base: (new (...args: any[]) => {
     dir: string;
     isRTL: boolean;
 }) & typeof LitElement;
-export declare class PieModal extends PieModal_base {
-    isOpen: boolean;
+export declare class PieModal extends PieModal_base implements ModalProps {
     heading: string;
     headingLevel: ModalProps['headingLevel'];
+    isDismissible: boolean;
+    isFullWidthBelowMid: boolean;
+    isOpen: boolean;
+    returnFocusAfterCloseSelector?: string;
     size: ModalProps['size'];
     _dialog?: HTMLDialogElement;
     constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
     firstUpdated(changedProperties: DependentMap<ModalProps>): void;
     updated(changedProperties: DependentMap<ModalProps>): void;
     /**
@@ -25,34 +30,45 @@ export declare class PieModal extends PieModal_base {
      */
     private _handleModalClosed;
     /**
-     * This is only to be used inside the component template as direct property
-     * reassignment is not allowed.
+     * Prevents the user from dismissing the dialog via the `cancel`
+     * event (ESC key) when `isDismissible` is set to false.
+     *
+     * @param {Event} event - The event object.
      */
-    private _triggerCloseModal;
-    connectedCallback(): void;
-    disconnectedCallback(): void;
+    private _handleDialogCancelEvent;
     private _handleModalOpenStateOnFirstRender;
     private _handleModalOpenStateChanged;
-    render(): import("lit-html").TemplateResult;
     /**
-     * Dismisses the modal on backdrop click
-     *
+     * Return focus to the specified element, providing the selector is valid
+     * and the chosen element can be found.
+     * Fails silently.
+     */
+    private _returnFocus;
+    render(): TemplateResult;
+    /**
+     * Dismisses the modal on backdrop click if `isDismissible` is `true`.
+     * @param {MouseEvent} event - the click event targetting the modal/backdrop
      */
     private _handleDialogLightDismiss;
     /**
-     * Dispatch `ON_MODAL_CLOSE_EVENT` event.
-     * To be used whenever we close the modal.
+     * Note: We should aim to have a shareable event helper system to allow
+     * us to share this across components in-future.
+     *
+     * Dispatch a custom event.
+     *
+     * To be used whenever we have behavioural events we want to
+     * bubble up through the modal.
      *
-     * @event
+     * @param {string} eventType
      */
-    private _dispatchModalCloseEvent;
+    private _dispatchModalCustomEvent;
     /**
-     * Dispatch `ON_MODAL_OPEN_EVENT` event.
-     * To be used whenever we open the modal.
+     * Template for the close button element. Called within the
+     * main render function.
      *
-     * @event
+     * @private
      */
-    private _dispatchModalOpenEvent;
+    private renderCloseButton;
     static styles: import("lit").CSSResult;
 }
 declare global {

package/dist/types/packages/components/pie-modal/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAa,MAAM,KAAK,CAAC;AAM5C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAGnE,OAAO,EACH,UAAU,EACV,aAAa,EAGb,KAAK,EACR,MAAM,QAAQ,CAAC;AAGhB,OAAO,EAAE,KAAK,UAAU,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC;AAEjD,QAAA,MAAM,iBAAiB,cAAc,CAAC;;;;;AAEtC,qBAAa,QAAS,SAAQ,aAAoB;IAEvC,MAAM,UAAS;IAIf,OAAO,EAAG,MAAM,CAAC;IAIjB,YAAY,EAAE,UAAU,CAAC,cAAc,CAAC,CAAQ;IAIhD,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,CAAY;IAGvC,OAAO,CAAC,EAAE,iBAAiB,CAAC;;IAOhC,YAAY,CAAE,iBAAiB,EAAE,YAAY,CAAC,UAAU,CAAC,GAAI,IAAI;IAIjE,OAAO,CAAE,iBAAiB,EAAE,YAAY,CAAC,UAAU,CAAC,GAAI,IAAI;IAI5D;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAQ1B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAM1B;;;OAGG;IACH,OAAO,CAAC,kBAAkB,CAExB;IAEF,iBAAiB,IAAM,IAAI;IAM3B,oBAAoB,IAAM,IAAI;IAO9B,OAAO,CAAC,kCAAkC;IAU1C,OAAO,CAAC,4BAA4B;IAYpC,MAAM;IA4BN;;;OAGG;IACH,OAAO,CAAC,yBAAyB,CAqB/B;IAEF;;;;;OAKG;IACH,OAAO,CAAC,wBAAwB,CAO9B;IAEF;;;;;OAKG;IACH,OAAO,CAAC,uBAAuB,CAO7B;IAGF,MAAM,CAAC,MAAM,0BAAqB;CACrC;AAID,OAAO,CAAC,MAAM,CAAC;IACX,UAAU,qBAAqB;QAC3B,CAAC,iBAAiB,CAAC,EAAE,QAAQ,CAAC;KACjC;CACJ"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,UAAU,EAAW,cAAc,EACtC,MAAM,KAAK,CAAC;AAMb,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAEnE,OAAO,iDAAiD,CAAC;AAEzD,OAAO,EACH,UAAU,EACV,aAAa,EAGb,KAAK,EACR,MAAM,QAAQ,CAAC;AAGhB,OAAO,EAAE,KAAK,UAAU,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC;AAEjD,QAAA,MAAM,iBAAiB,cAAc,CAAC;;;;;AAEtC,qBAAa,QAAS,SAAQ,aAAqB,YAAW,UAAU;IAG7D,OAAO,EAAG,MAAM,CAAC;IAIjB,YAAY,EAAE,UAAU,CAAC,cAAc,CAAC,CAAQ;IAGhD,aAAa,UAAS;IAGtB,mBAAmB,UAAS;IAG5B,MAAM,UAAS;IAGf,6BAA6B,CAAC,EAAE,MAAM,CAAC;IAIvC,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,CAAY;IAGvC,OAAO,CAAC,EAAE,iBAAiB,CAAC;;IAOhC,iBAAiB,IAAM,IAAI;IAM3B,oBAAoB,IAAM,IAAI;IAM9B,YAAY,CAAE,iBAAiB,EAAE,YAAY,CAAC,UAAU,CAAC,GAAI,IAAI;IASjE,OAAO,CAAE,iBAAiB,EAAE,YAAY,CAAC,UAAU,CAAC,GAAI,IAAI;IAI5D;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAS1B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAM1B;;;;;OAKG;IACH,OAAO,CAAC,wBAAwB,CAI9B;IAGF,OAAO,CAAC,kCAAkC;IAU1C,OAAO,CAAC,4BAA4B;IAYpC;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAQpB,MAAM;IA2BN;;;OAGG;IACH,OAAO,CAAC,yBAAyB,CAyB/B;IAEF;;;;;;;;;;OAUG;IACH,OAAO,CAAC,yBAAyB,CAO/B;IAEF;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;IAWzB,MAAM,CAAC,MAAM,0BAAqB;CACrC;AAID,OAAO,CAAC,MAAM,CAAC;IACX,UAAU,qBAAqB;QAC3B,CAAC,iBAAiB,CAAC,EAAE,QAAQ,CAAC;KACjC;CACJ"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justeattakeaway/pie-modal",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "PIE design system modal built using web components",
   "type": "module",
   "main": "dist/index.js",
@@ -23,6 +23,7 @@
   "devDependencies": {
     "@justeattakeaway/pie-components-config": "workspace:*",
     "@justeattakeaway/pie-icon-button": "workspace:*",
+    "@justeattakeaway/pie-icons-webc": "workspace:*",
     "@justeattakeaway/pie-webc-core": "workspace:*",
     "@types/body-scroll-lock": "3.1.0"
   },

package/src/defs.ts

@@ -6,14 +6,40 @@ export interface ModalProps {
      * The text to display in the modal's heading.
      */
     heading: string;
+
     /**
      * The HTML heading tag to use for the modal's heading. Can be h1-h6.
      */
     headingLevel: typeof headingLevels[number];
+
     /**
      * When true, the modal will be open.
      */
     isOpen: boolean;
+
+    /**
+     * When set to `true`:
+     *  1. The close button within the modal will be visible.
+     *  2. The user can dismiss the modal via the ESCAPE key, clicking the backdrop
+     *     or via a close button.
+     *
+     * When set to `false`:
+     *  1. The close button within the modal will be hidden.
+     *  2. The user can NOT dismiss the modal via the ESCAPE key or clicking the backdrop.
+     *
+     */
+    isDismissible: boolean;
+
+    /**
+     * This controls whether a *medium-sized* modal will cover the full width of the page when below the mid breakpoint.
+     */
+    isFullWidthBelowMid: boolean;
+
+    /**
+     * The selector for the element that you would like focus to be returned to when the modal is closed, e.g., #skipToMain
+     */
+    returnFocusAfterCloseSelector?: string;
+
     /**
      * The size of the modal; this controls how wide it will appear on the page.
      */

package/src/index.ts

@@ -1,4 +1,6 @@
-import { LitElement, unsafeCSS } from 'lit';
+import {
+    LitElement, nothing, TemplateResult, unsafeCSS,
+} from 'lit';
 import { html, unsafeStatic } from 'lit/static-html.js';
 import { property, query } from 'lit/decorators.js';
 import {
@@ -6,6 +8,7 @@ import {
 } from '@justeattakeaway/pie-webc-core';
 import type { DependentMap } from '@justeattakeaway/pie-webc-core';
 import { disableBodyScroll, enableBodyScroll } from 'body-scroll-lock';
+import '@justeattakeaway/pie-icons-webc/icons/IconClose';
 import styles from './modal.scss?inline';
 import {
     ModalProps,
@@ -20,10 +23,7 @@ export { type ModalProps, headingLevels, sizes };
 
 const componentSelector = 'pie-modal';
 
-export class PieModal extends RtlMixin(LitElement) {
-    @property({ type: Boolean })
-    public isOpen = false;
-
+export class PieModal extends RtlMixin(LitElement) implements ModalProps {
     @property({ type: String })
     @requiredProperty(componentSelector)
     public heading!: string;
@@ -32,6 +32,18 @@ export class PieModal extends RtlMixin(LitElement) {
     @validPropertyValues(componentSelector, headingLevels, 'h2')
     public headingLevel: ModalProps['headingLevel'] = 'h2';
 
+    @property({ type: Boolean, reflect: true })
+    public isDismissible = false;
+
+    @property({ type: Boolean })
+    public isFullWidthBelowMid = false;
+
+    @property({ type: Boolean })
+    public isOpen = false;
+
+    @property()
+    public returnFocusAfterCloseSelector?: string;
+
     @property()
     @validPropertyValues(componentSelector, sizes, 'medium')
     public size: ModalProps['size'] = 'medium';
@@ -44,8 +56,25 @@ export class PieModal extends RtlMixin(LitElement) {
         this.addEventListener('click', (event) => this._handleDialogLightDismiss(event));
     }
 
+    connectedCallback () : void {
+        super.connectedCallback();
+        document.addEventListener(ON_MODAL_OPEN_EVENT, this._handleModalOpened.bind(this));
+        document.addEventListener(ON_MODAL_CLOSE_EVENT, this._handleModalClosed.bind(this));
+    }
+
+    disconnectedCallback () : void {
+        document.removeEventListener(ON_MODAL_OPEN_EVENT, this._handleModalOpened.bind(this));
+        document.removeEventListener(ON_MODAL_CLOSE_EVENT, this._handleModalClosed.bind(this));
+        super.disconnectedCallback();
+    }
+
     firstUpdated (changedProperties: DependentMap<ModalProps>) : void {
+        this._dialog?.addEventListener('cancel', (event) => this._handleDialogCancelEvent(event));
         this._handleModalOpenStateOnFirstRender(changedProperties);
+
+        this._dialog?.addEventListener('close', () => {
+            this.isOpen = false;
+        });
     }
 
     updated (changedProperties: DependentMap<ModalProps>) : void {
@@ -57,9 +86,10 @@ export class PieModal extends RtlMixin(LitElement) {
      */
     private _handleModalOpened () : void {
         disableBodyScroll(this);
-        //  We require this because toggling the prop `isOpen` itself won't
-        //  allow the dialog to open in the correct way (with the default background),
-        //  the method `showModal()` needs to be invoked.
+        if (this._dialog?.hasAttribute('open') || !this._dialog?.isConnected) {
+            return;
+        }
+        // The ::backdrop pseudoelement is only shown if the modal is opened via JS
         this._dialog?.showModal();
     }
 
@@ -68,37 +98,29 @@ export class PieModal extends RtlMixin(LitElement) {
      */
     private _handleModalClosed () : void {
         enableBodyScroll(this);
-        //  Closes the native dialog element
         this._dialog?.close();
+        this._returnFocus();
     }
 
     /**
-     * This is only to be used inside the component template as direct property
-     * reassignment is not allowed.
+     * Prevents the user from dismissing the dialog via the `cancel`
+     * event (ESC key) when `isDismissible` is set to false.
+     *
+     * @param {Event} event - The event object.
      */
-    private _triggerCloseModal = () : void => {
-        this.isOpen = false;
+    private _handleDialogCancelEvent = (event: Event) : void => {
+        if (!this.isDismissible) {
+            event.preventDefault();
+        }
     };
 
-    connectedCallback () : void {
-        super.connectedCallback();
-        document.addEventListener(ON_MODAL_OPEN_EVENT, this._handleModalOpened.bind(this));
-        document.addEventListener(ON_MODAL_CLOSE_EVENT, this._handleModalClosed.bind(this));
-    }
-
-    disconnectedCallback () : void {
-        document.removeEventListener(ON_MODAL_OPEN_EVENT, this._handleModalOpened.bind(this));
-        document.removeEventListener(ON_MODAL_CLOSE_EVENT, this._handleModalClosed.bind(this));
-        super.disconnectedCallback();
-    }
-
     // Handles the value of the isOpen property on first render of the component
     private _handleModalOpenStateOnFirstRender (changedProperties: DependentMap<ModalProps>) : void {
         // This ensures if the modal is open on first render, the scroll lock and backdrop are applied
         const previousValue = changedProperties.get('isOpen');
 
         if (previousValue === undefined && this.isOpen) {
-            this._dispatchModalOpenEvent();
+            this._dispatchModalCustomEvent(ON_MODAL_OPEN_EVENT);
         }
     }
 
@@ -108,18 +130,32 @@ export class PieModal extends RtlMixin(LitElement) {
 
         if (previousValue !== undefined) {
             if (previousValue) {
-                this._dispatchModalCloseEvent();
+                this._dispatchModalCustomEvent(ON_MODAL_CLOSE_EVENT);
             } else {
-                this._dispatchModalOpenEvent();
+                this._dispatchModalCustomEvent(ON_MODAL_OPEN_EVENT);
             }
         }
     }
 
+    /**
+     * Return focus to the specified element, providing the selector is valid
+     * and the chosen element can be found.
+     * Fails silently.
+     */
+    private _returnFocus () : void {
+        const selector = this.returnFocusAfterCloseSelector?.trim();
+
+        if (selector) {
+            (document.querySelector(selector) as HTMLElement)?.focus();
+        }
+    }
+
     render () {
         const {
             heading,
             headingLevel = 'h2',
             size,
+            isFullWidthBelowMid,
         } = this;
 
         const headingTag = unsafeStatic(headingLevel);
@@ -127,14 +163,12 @@ export class PieModal extends RtlMixin(LitElement) {
         return html`
             <dialog
                 id="dialog"
+                class="c-modal"
                 size="${size}"
-                class="c-modal">
+                ?isFullWidthBelowMid=${isFullWidthBelowMid}>
                 <header>
                     <${headingTag} class="c-modal-heading">${heading}</${headingTag}>
-                    <pie-icon-button
-                        @click="${this._triggerCloseModal}"
-                        variant="ghost-secondary"
-                        class="c-modal-closeBtn"></pie-icon-button>
+                     ${this.isDismissible ? this.renderCloseButton() : nothing}
                 </header>
                 <article class="c-modal-content">
                     <slot></slot>
@@ -144,10 +178,14 @@ export class PieModal extends RtlMixin(LitElement) {
     }
 
     /**
-     * Dismisses the modal on backdrop click
-     *
+     * Dismisses the modal on backdrop click if `isDismissible` is `true`.
+     * @param {MouseEvent} event - the click event targetting the modal/backdrop
      */
     private _handleDialogLightDismiss = (event: MouseEvent) : void => {
+        if (!this.isDismissible) {
+            return;
+        }
+
         const rect = this._dialog?.getBoundingClientRect();
 
         const {
@@ -161,9 +199,9 @@ export class PieModal extends RtlMixin(LitElement) {
         }
 
         const isClickOutsideDialog = event.clientY < top ||
-            event.clientY > bottom ||
-            event.clientX < left ||
-            event.clientX > right;
+                event.clientY > bottom ||
+                event.clientX < left ||
+                event.clientX > right;
 
         if (isClickOutsideDialog) {
             this.isOpen = false;
@@ -171,13 +209,18 @@ export class PieModal extends RtlMixin(LitElement) {
     };
 
     /**
-     * Dispatch `ON_MODAL_CLOSE_EVENT` event.
-     * To be used whenever we close the modal.
+     * Note: We should aim to have a shareable event helper system to allow
+     * us to share this across components in-future.
+     *
+     * Dispatch a custom event.
      *
-     * @event
+     * To be used whenever we have behavioural events we want to
+     * bubble up through the modal.
+     *
+     * @param {string} eventType
      */
-    private _dispatchModalCloseEvent = () : void => {
-        const event = new CustomEvent(ON_MODAL_CLOSE_EVENT, {
+    private _dispatchModalCustomEvent = (eventType: string) : void => {
+        const event = new CustomEvent(eventType, {
             bubbles: true,
             composed: true,
         });
@@ -186,19 +229,20 @@ export class PieModal extends RtlMixin(LitElement) {
     };
 
     /**
-     * Dispatch `ON_MODAL_OPEN_EVENT` event.
-     * To be used whenever we open the modal.
+     * Template for the close button element. Called within the
+     * main render function.
      *
-     * @event
+     * @private
      */
-    private _dispatchModalOpenEvent = () : void => {
-        const event = new CustomEvent(ON_MODAL_OPEN_EVENT, {
-            bubbles: true,
-            composed: true,
-        });
-
-        this.dispatchEvent(event);
-    };
+    private renderCloseButton (): TemplateResult {
+        return html`
+            <pie-icon-button
+                @click="${() => { this.isOpen = false; }}"
+                variant="ghost-secondary"
+                class="c-modal-closeBtn"
+                data-test-id="modal-close-button"><icon-close /></pie-icon-button>
+        `;
+    }
 
     // Renders a `CSSResult` generated from SCSS by Vite
     static styles = unsafeCSS(styles);

package/src/modal.scss

@@ -35,6 +35,11 @@
 
     &[size='medium'] {
         /* Same as default styles */
+        &[isfullwidthbelowmid] {
+            @media (max-width: $breakpoint-wide) {
+                --modal-inline-size: 100%;
+            }
+        }
     }
 
     &[size='large'] {