@justeattakeaway/pie-modal 0.0.0-snapshot-release-20231123112917

package/README.md

@@ -0,0 +1,121 @@
+<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-modal">
+    <img alt="GitHub Workflow Status" src="https://img.shields.io/npm/v/@justeattakeaway/pie-modal.svg">
+  </a>
+</p>
+
+# Table of Contents
+
+1. [Introduction](#pie-modal)
+2. [Installation](#installation)
+3. [Importing the component](#importing-the-component)
+4. [Peer Dependencies](#peer-dependencies)
+5. [Props](#props)
+6. [Legacy browser support](#legacy-browser-support)
+7. [Contributing](#contributing)
+
+
+## pie-modal
+
+`pie-modal` is a Web Component built using the Lit library. It offers a simple and accessible modal component for web applications, which uses the native HTML `dialog` element under the hood.
+
+This component can be easily integrated into various frontend frameworks and customized through a set of properties.
+
+
+## Installation
+
+To install `pie-modal` in your application, run the following on your command line:
+
+```bash
+# npm
+$ npm i @justeattakeaway/pie-modal
+
+# yarn
+$ yarn add @justeattakeaway/pie-modal
+```
+
+For full information on using PIE components as part of an application, check out the [Getting Started Guide](https://github.com/justeattakeaway/pie/wiki/Getting-started-with-PIE-Web-Components).
+
+
+### Importing the component
+
+#### JavaScript
+```js
+// Default – for Native JS Applications, Vue, Angular, Svelte, etc.
+import { PieModal } from '@justeattakeaway/pie-modal';
+
+// If you don't need to reference the imported object, you can simply
+// import the module which registers the component as a custom element.
+import '@justeattakeaway/pie-modal';
+```
+
+#### React
+```js
+// React
+// For React, you will need to import our React-specific component build
+// which wraps the web component using ​@lit/react
+import { PieModal } from '@justeattakeaway/pie-modal/dist/react';
+```
+
+> [!NOTE]
+> When using the React version of the component, please make sure to also
+> include React as a [peer dependency](#peer-dependencies) in your project.
+
+
+## Peer Dependencies
+
+> [!IMPORTANT]
+> When using `pie-modal`, you will also need to include a couple of dependencies to ensure the component renders as expected. See [the PIE Wiki](https://github.com/justeattakeaway/pie/wiki/Getting-started-with-PIE-Web-Components#expected-dependencies) for more information and how to include these in your application.
+
+
+## Props
+
+| Property                      | Type      | Default        | Description |
+|-------------------------------|-----------|----------------|-------------|
+| aria                          | `Object`  | `undefined`    | An object representing the aria labels for the `close` & `back` buttons within the modal as well as the `isLoading` state labels (`aria-label` & `aria-busy`). |
+| hasBackButton                 | `Boolean` | `false`        | If true, the modal includes a back button which closes the modal when clicked. |
+| hasStackedActions             | `Boolean` | `false`        | If true, the action buttons will be stacked (full width) at narrow breakpoints. |
+| heading                       | `String`  | n/a (Required) | The heading text of the modal. |
+| headingLevel                  | `String`  | `h2`           | The HTML tag to use for the modal's heading (can be `h1`-`h6`). |
+| isDismissible                 | `Boolean` | `false`        | If true, the modal includes a close button and can be dismissed by clicking on the backdrop or pressing the `Esc` key. |
+| isFooterPinned                | `Boolean` | `true` | When false, the modal footer will scroll with the content inside the modal body. |
+| isFullWidthBelowMid           | `Boolean` | `false`        | If true and the page is narrower than the mid breakpoint, a **medium-sized** modal will take up the full width of the screen. |
+| isLoading                     | `Boolean` | `false`        | When true, displays a loading spinner in the modal |
+| isOpen                        | `Boolean` | `false`        | Controls if the modal element is open or closed |
+| leadingAction                 | `Object`  | `undefined`    | An object representing the leading action of the modal. It has the following properties:<br>- text (required): The text to display on the leading action button.<br>- variant: The variant of the leading action button. Please see [pie-button](https://github.com/justeattakeaway/pie/blob/main/packages/components/pie-button/README.md#props) for options. Defaults to primary if not provided.<br>- ariaLabel: The ARIA label for the leading action button. Example: `leadingAction = { text: "Example Text", variant: "secondary", ariaLabel: "Example Aria Label" }` |
+| position                      | `String`  | `center`       | The position of the modal; this controls where it will appear on the page. Can be `top` or `center`. |
+| returnFocusAfterCloseSelector | `String`  | `undefined`    | If provided, focus will be sent to the first element that matches this selector when the modal is closed. If not provided, the `dialog` element will return focus to the element that opened the modal. |
+| size                          | `String`  | `medium`       | Determines the maximum width of the modal. Large modals will expand to fill the entire page width at narrow viewports. Can be `small`, `medium` or `large`. |
+| supportingAction              | `Object`  | `undefined`    | An object representing the supporting action of the modal. It has the following properties:<br>- text (required): The text to display on the supporting action button.<br>- variant: The variant of the supporting action button. Please see [pie-button](https://github.com/justeattakeaway/pie/blob/main/packages/components/pie-button/README.md#props) for options. Defaults to ghost if not provided.<br>- ariaLabel: The ARIA label for the supporting action button. Example: `supportingAction = { text: "Example Text", variant: "ghost", ariaLabel: "Example Aria Label" }` |
+
+In your markup or JSX, you can then use these to set the properties for the `pie-modal` component:
+
+```html
+<!-- Native HTML -->
+<pie-modal heading='My Awesome Heading' headingLevel='h3'>Click me!</pie-modal>
+
+<!-- JSX -->
+<PieModal heading='My Awesome Heading' headingLevel='h3'>Click me!</PieModal>
+```
+
+## Legacy browser support
+
+`pie-modal` uses the Dialog element which might not be supported by legacy browsers.
+
+To support them, `pie-modal` uses the [dialog-polyfill](https://github.com/GoogleChrome/dialog-polyfill) package. It works automatically and doesn't need any setup.
+
+The polyfill comes with a few limitations, as noted on its [documentation page](https://github.com/GoogleChrome/dialog-polyfill#limitations):
+- Dialogs should not be contained by parents that create a stacking context
+- The browser's chrome may not always be accessible via the tab key
+- Changes to the CSS top/bottom values while open aren't retained
+
+For more details, check the package documentation mentioned above.
+
+
+## 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) and how to run specific [component tests](https://github.com/justeattakeaway/pie/wiki/Contributing-Guide#testing).

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/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@justeattakeaway/pie-modal",
+  "version": "0.0.0-snapshot-release-20231123112917",
+  "description": "PIE design system modal built using web components",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "src",
+    "dist",
+    "**/*.d.ts"
+  ],
+  "scripts": {
+    "build": "yarn build:wrapper pie-modal && run -T vite build",
+    "lint:scripts": "run -T eslint .",
+    "lint:scripts:fix": "run -T eslint . --fix",
+    "lint:style": "run -T stylelint ./src/**/*.{css,scss}",
+    "lint:style:fix": "yarn lint:style --fix",
+    "watch": "run -T vite build --watch",
+    "test": "echo \"Error: no test specified\" && exit 0",
+    "test:ci": "yarn test",
+    "test:browsers": "npx playwright test -c ./playwright-lit.config.ts",
+    "test:browsers:ci": "yarn test:browsers",
+    "test:visual": "run -T cross-env-shell PERCY_TOKEN=${PERCY_TOKEN_PIE_MODAL} percy exec --allowed-hostname cloudfront.net -- npx playwright test -c ./playwright-lit-visual.config.ts",
+    "test:visual:ci": "yarn test:visual"
+  },
+  "author": "Just Eat Takeaway.com - Design System Team",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@justeat/pie-design-tokens": "5.9.0",
+    "@justeattakeaway/pie-components-config": "0.6.0",
+    "@types/body-scroll-lock": "3.1.2"
+  },
+  "volta": {
+    "extends": "../../../package.json"
+  },
+  "dependencies": {
+    "@justeattakeaway/pie-button": "0.40.0",
+    "@justeattakeaway/pie-icon-button": "0.22.0",
+    "@justeattakeaway/pie-icons-webc": "0.11.1",
+    "@justeattakeaway/pie-spinner": "0.3.0",
+    "@justeattakeaway/pie-webc-core": "0.12.0",
+    "body-scroll-lock": "3.1.5",
+    "dialog-polyfill": "0.5.6"
+  },
+  "sideEffects": [
+    "dist/*.js"
+  ]
+}

package/src/defs.ts

@@ -0,0 +1,150 @@
+import { Variant } from '@justeattakeaway/pie-button/src/defs.ts';
+
+export const headingLevels = ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'] as const;
+export const sizes = ['small', 'medium', 'large'] as const;
+export const positions = ['top', 'center'] as const;
+
+export type AriaProps = {
+    close?: string;
+    back?: string;
+    loading?: string;
+};
+
+export type ActionProps = {
+        /**
+         * The text to display inside the button.
+         */
+        text: string;
+
+        /**
+         * The button variant.
+         */
+        variant?: Variant;
+
+        /**
+         * The ARIA label for the button.
+         */
+        ariaLabel?: string;
+};
+
+export type ModalProps = {
+    /**
+     * The ARIA labels used for the modal close and back buttons, as well as loading state.
+     */
+    aria?: AriaProps;
+
+    /**
+     * When true, the modal will have a back button. This currently behaves the same as the close button.
+     */
+    hasBackButton: boolean;
+
+    /**
+     * When true, the modal will have a back button. This currently behaves the same as the close button.
+     */
+    hasStackedActions: boolean;
+
+    /**
+     * 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;
+
+    /**
+     * When false, the modal footer will scroll with the content inside the modal body.
+     */
+    isFooterPinned: boolean;
+
+    /**
+     * This controls whether a *medium-sized* modal will cover the full width of the page when below the mid breakpoint.
+     */
+    isFullWidthBelowMid: boolean;
+
+    /**
+     * When true, displays a loading spinner in the modal.
+     */
+    isLoading: boolean;
+
+    /**
+     * The leading action configuration for the modal.
+     */
+    leadingAction: ActionProps;
+
+    /*
+     * The position of the modal; this controls where it will appear on the page.
+     */
+    position: typeof positions[number];
+
+    /**
+     * 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.
+     */
+    size: typeof sizes[number];
+
+    /**
+     * The supporting action configuration for the modal.
+     */
+    supportingAction: ActionProps;
+};
+
+/**
+ * Event name for when the modal is closed.
+ *
+ * @constant
+ */
+export const ON_MODAL_CLOSE_EVENT = 'pie-modal-close';
+
+/**
+ * Event name for when the modal is opened.
+ *
+ * @constant
+ */
+export const ON_MODAL_OPEN_EVENT = 'pie-modal-open';
+
+/**
+ * Event name for when the modal back button is clicked.
+ *
+ * @constant
+ */
+export const ON_MODAL_BACK_EVENT = 'pie-modal-back';
+
+/**
+ * Event name for when the modal leading action is clicked.
+ *
+ * @constant
+ */
+export const ON_MODAL_LEADING_ACTION_CLICK = 'pie-modal-leading-action-click';
+
+/**
+ * Event name for when the modal supporting action is clicked.
+ *
+ * @constant
+ */
+export const ON_MODAL_SUPPORTING_ACTION_CLICK = 'pie-modal-supporting-action-click';
+
+export type ModalActionType = 'leading' | 'supporting';

package/src/index.ts

@@ -0,0 +1,481 @@
+import {
+    LitElement, nothing, TemplateResult, unsafeCSS, PropertyValues,
+} from 'lit';
+import { html, unsafeStatic } from 'lit/static-html.js';
+import { property, query } from 'lit/decorators.js';
+import { disableBodyScroll, enableBodyScroll } from 'body-scroll-lock';
+
+import '@justeattakeaway/pie-button';
+import '@justeattakeaway/pie-icon-button';
+import {
+    requiredProperty, RtlMixin, validPropertyValues, defineCustomElement,
+} from '@justeattakeaway/pie-webc-core';
+import '@justeattakeaway/pie-icons-webc/IconClose';
+import '@justeattakeaway/pie-icons-webc/IconChevronLeft';
+import '@justeattakeaway/pie-icons-webc/IconChevronRight';
+import '@justeattakeaway/pie-spinner';
+
+import styles from './modal.scss?inline';
+import {
+    type AriaProps,
+    type ActionProps,
+    type ModalProps,
+    type ModalActionType,
+    headingLevels,
+    positions,
+    sizes,
+    ON_MODAL_BACK_EVENT,
+    ON_MODAL_CLOSE_EVENT,
+    ON_MODAL_OPEN_EVENT,
+    ON_MODAL_LEADING_ACTION_CLICK,
+    ON_MODAL_SUPPORTING_ACTION_CLICK,
+} from './defs';
+
+// Valid values available to consumers
+export * from './defs';
+
+const componentSelector = 'pie-modal';
+
+export interface ModalEventDetail {
+    targetModal: PieModal;
+}
+
+/**
+ * @tagname pie-modal
+ * @event {CustomEvent} pie-modal-open - when the modal is opened.
+ * @event {CustomEvent} pie-modal-close - when the modal is closed.
+ * @event {CustomEvent} pie-modal-back - when the modal back button is clicked.
+ * @event {CustomEvent} pie-modal-leading-action-click - when the modal leading action is clicked.
+ * @event {CustomEvent} pie-modal-supporting-action-click - when the modal supporting action is clicked.
+ */
+export class PieModal extends RtlMixin(LitElement) implements ModalProps {
+    @property({ type: Object })
+    public aria!: AriaProps;
+
+    @property({ type: String })
+    @requiredProperty(componentSelector)
+    public heading!: string;
+
+    @property()
+    @validPropertyValues(componentSelector, headingLevels, 'h2')
+    public headingLevel: ModalProps['headingLevel'] = 'h2';
+
+    @property({ type: Boolean })
+    public hasBackButton = false;
+
+    @property({ type: Boolean })
+    public hasStackedActions = false;
+
+    @property({ type: Boolean, reflect: true })
+    public isDismissible = false;
+
+    @property({ type: Boolean })
+    public isFooterPinned = true;
+
+    @property({ type: Boolean })
+    public isFullWidthBelowMid = false;
+
+    @property({ type: Boolean, reflect: true })
+    public isLoading = false;
+
+    @property({ type: Boolean })
+    public isOpen = false;
+
+    @property({ type: Object })
+    public leadingAction!: ActionProps;
+
+    @property()
+    @validPropertyValues(componentSelector, positions, 'center')
+    public position: ModalProps['position'] = 'center';
+
+    @property()
+    public returnFocusAfterCloseSelector?: string;
+
+    @property()
+    @validPropertyValues(componentSelector, sizes, 'medium')
+    public size: ModalProps['size'] = 'medium';
+
+    @property({ type: Object })
+    public supportingAction!: ActionProps;
+
+    @query('dialog')
+    private _dialog?: HTMLDialogElement;
+
+    private _backButtonClicked = false;
+
+    // Renders a `CSSResult` generated from SCSS by Vite
+    static styles = unsafeCSS(styles);
+
+    connectedCallback () : void {
+        super.connectedCallback();
+        this.addEventListener('click', (event) => this._handleDialogLightDismiss(event));
+        document.addEventListener(ON_MODAL_OPEN_EVENT, (event) => this._handleModalOpened(<CustomEvent>event));
+        document.addEventListener(ON_MODAL_CLOSE_EVENT, (event) => this._handleModalClosed(<CustomEvent>event));
+        document.addEventListener(ON_MODAL_BACK_EVENT, (event) => this._handleModalClosed(<CustomEvent>event));
+    }
+
+    disconnectedCallback () : void {
+        document.removeEventListener(ON_MODAL_OPEN_EVENT, (event) => this._handleModalOpened(<CustomEvent>event));
+        document.removeEventListener(ON_MODAL_CLOSE_EVENT, (event) => this._handleModalClosed(<CustomEvent>event));
+        document.removeEventListener(ON_MODAL_BACK_EVENT, (event) => this._handleModalClosed(<CustomEvent>event));
+        super.disconnectedCallback();
+    }
+
+    async firstUpdated (changedProperties: PropertyValues<this>) : Promise<void> {
+        super.firstUpdated(changedProperties);
+
+        if (this._dialog) {
+            const dialogPolyfill = await import('dialog-polyfill').then((module) => module.default);
+            dialogPolyfill.registerDialog(this._dialog);
+            this._dialog.addEventListener('cancel', (event) => this._handleDialogCancelEvent(event));
+            this._dialog.addEventListener('close', () => {
+                this.isOpen = false;
+            });
+        }
+
+        this._handleModalOpenStateOnFirstRender(changedProperties);
+    }
+
+    updated (changedProperties: PropertyValues<this>) : void {
+        super.updated(changedProperties);
+        this._handleModalOpenStateChanged(changedProperties);
+    }
+
+    /**
+     * Opens the dialog element and disables page scrolling
+     */
+    private _handleModalOpened (event: CustomEvent): void {
+        const { targetModal } = event.detail;
+
+        if (targetModal === this) {
+            const modalScrollContainer = this._dialog?.querySelector('.c-modal-scrollContainer');
+
+            if (modalScrollContainer) {
+                disableBodyScroll(modalScrollContainer);
+            }
+
+            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();
+        }
+    }
+
+    /**
+     * Closes the dialog element and re-enables page scrolling
+     */
+    private _handleModalClosed (event: CustomEvent): void {
+        const { targetModal } = event.detail;
+
+        if (targetModal === this) {
+            const modalScrollContainer = this._dialog?.querySelector('.c-modal-scrollContainer');
+
+            if (modalScrollContainer) {
+                enableBodyScroll(modalScrollContainer);
+            }
+
+            this._dialog?.close();
+            this._returnFocus();
+        }
+    }
+
+    /**
+     * 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 _handleDialogCancelEvent = (event: Event) : void => {
+        if (!this.isDismissible) {
+            event.preventDefault();
+        }
+    };
+
+    // Handles the value of the isOpen property on first render of the component
+    private _handleModalOpenStateOnFirstRender (changedProperties: PropertyValues<this>) : 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._dispatchModalCustomEvent(ON_MODAL_OPEN_EVENT);
+        }
+    }
+
+    // Handles changes to the modal isOpen property by dispatching any appropriate events
+    private _handleModalOpenStateChanged (changedProperties: PropertyValues<this>) : void {
+        const wasPreviouslyOpen = changedProperties.get('isOpen');
+
+        if (wasPreviouslyOpen !== undefined) {
+            if (wasPreviouslyOpen) {
+                if (this._backButtonClicked) {
+                    // Reset the flag
+                    this._backButtonClicked = false;
+                    this._dispatchModalCustomEvent(ON_MODAL_BACK_EVENT);
+                } else {
+                    this._dispatchModalCustomEvent(ON_MODAL_CLOSE_EVENT);
+                }
+            } else {
+                this._dispatchModalCustomEvent(ON_MODAL_OPEN_EVENT);
+            }
+        }
+    }
+
+    private _handleActionClick (actionType: ModalActionType) : void {
+        if (actionType === 'leading') {
+            this._dialog?.close('leading');
+            this._dispatchModalCustomEvent(ON_MODAL_LEADING_ACTION_CLICK);
+        } else if (actionType === 'supporting') {
+            this._dialog?.close('supporting');
+            this._dispatchModalCustomEvent(ON_MODAL_SUPPORTING_ACTION_CLICK);
+        }
+    }
+
+    /**
+     * Return focus to the specified element, providing the selector is valid
+     * and the chosen element can be found.
+     */
+    private _returnFocus () : void {
+        const selector = this.returnFocusAfterCloseSelector?.trim();
+
+        if (selector) {
+            (document.querySelector(selector) as HTMLElement)?.focus();
+        }
+    }
+
+    /**
+     * Template for the close button element. Called within the
+     * main render function.
+     *
+     * @private
+     */
+    private renderCloseButton (): TemplateResult {
+        return html`
+            <pie-icon-button
+                @click="${() => { this.isOpen = false; }}"
+                variant="ghost-secondary"
+                class="c-modal-closeBtn"
+                aria-label="${this.aria?.close || nothing}"
+                data-test-id="modal-close-button">
+                <icon-close></icon-close>
+            </pie-icon-button>`;
+    }
+
+    /**
+     * Template for the back button element. Called within the
+     * main render function.
+     *
+     * @private
+     */
+    private renderBackButton () : TemplateResult {
+        return html`
+            <pie-icon-button
+                @click="${() => { this._backButtonClicked = true; this.isOpen = false; }}"
+                variant="ghost-secondary"
+                class="c-modal-backBtn"
+                aria-label="${this.aria?.back || nothing}"
+                data-test-id="modal-back-button">
+                ${this.isRTL ? html`<icon-chevron-right></icon-chevron-right>` : html`<icon-chevron-left></icon-chevron-left>`}
+            </pie-icon-button>
+        `;
+    }
+
+    /**
+     * Render leadingAction button depending on prop availability.
+     *
+     * 1. If the prop `leadingAction` is not provided, the button is not rendered.
+     * 2. If the prop `leadingAction` is provided but any of the optional properties
+     * are not provided, they fall back to their default values.
+     *
+     * @private
+     */
+    private renderLeadingAction () : TemplateResult | typeof nothing {
+        const { text, variant = 'primary', ariaLabel } = this.leadingAction;
+
+        if (!text) {
+            return nothing;
+        }
+
+        return html`
+            <pie-button
+                variant="${variant}"
+                aria-label="${ariaLabel || nothing}"
+                type="submit"
+                ?isFullWidth="${this.hasStackedActions}"
+                @click="${() => this._handleActionClick('leading')}"
+                data-test-id="modal-leading-action">
+                ${text}
+            </pie-button>
+        `;
+    }
+
+    /**
+     * Render supportingAction button depending on prop availability.
+     *
+     * 1. If the prop `supportingAction` is not provided, the button is not rendered.
+     * 2. If the prop `supportingAction` is provided but any of the optional properties
+     * are not provided, they fall back to their default values.
+     * 3. If `supportingAction` is provided but not `leadingAction`, log a warning and do
+     * not render `supportingAction`.
+     *
+     * @private
+     */
+    private renderSupportingAction (): TemplateResult | typeof nothing {
+        const { text, variant = 'ghost', ariaLabel } = this.supportingAction;
+
+        if (!text) {
+            return nothing;
+        }
+
+        if (!this.leadingAction) {
+            console.warn('Use `leadingAction` instead of `supportingAction`. `supportingAction` is being ignored.');
+            return nothing;
+        }
+
+        return html`
+            <pie-button
+                variant="${variant}"
+                aria-label="${ariaLabel || nothing}"
+                type="reset"
+                ?isFullWidth="${this.hasStackedActions}"
+                @click="${() => this._handleActionClick('supporting')}"
+                data-test-id="modal-supporting-action">
+                ${text}
+            </pie-button>
+        `;
+    }
+
+    /**
+     * Renders the modal inner content and footer of the modal.
+     * @private
+     */
+    private renderModalContentAndFooter (): TemplateResult {
+        return html`
+        <article class="c-modal-scrollContainer c-modal-content c-modal-content--scrollable">
+            <div class="c-modal-contentInner">
+                <slot></slot>
+            </div>
+            ${this.isLoading ? html`<pie-spinner size="xlarge" variant="secondary"></pie-spinner>` : nothing}
+        </article>
+        <footer class="c-modal-footer">
+            ${this.leadingAction ? this.renderLeadingAction() : nothing}
+            ${this.supportingAction ? this.renderSupportingAction() : nothing}
+        </footer>`;
+    }
+
+    public render () {
+        const {
+            aria,
+            hasBackButton,
+            hasStackedActions,
+            heading,
+            headingLevel = 'h2',
+            isDismissible,
+            isFooterPinned,
+            isFullWidthBelowMid,
+            isLoading,
+            leadingAction,
+            position,
+            size,
+            supportingAction,
+        } = this;
+
+        const headingTag = unsafeStatic(headingLevel);
+
+        return html`
+        <dialog
+            id="dialog"
+            class="c-modal"
+            size="${size}"
+            position="${position}"
+            ?hasActions=${leadingAction || supportingAction}
+            ?hasBackButton=${hasBackButton}
+            ?hasStackedActions=${hasStackedActions}
+            ?isDismissible=${isDismissible}
+            ?isFooterPinned=${isFooterPinned}
+            ?isFullWidthBelowMid=${isFullWidthBelowMid}
+            ?isLoading=${isLoading}
+            aria-busy="${isLoading ? 'true' : 'false'}"
+            aria-label="${(isLoading && aria?.loading) || nothing}"
+            data-test-id="pie-modal">
+            <header class="c-modal-header">
+                ${hasBackButton ? this.renderBackButton() : nothing}
+                <${headingTag} class="c-modal-heading">
+                    ${heading}
+                </${headingTag}>
+                ${isDismissible ? this.renderCloseButton() : nothing}
+            </header>
+            ${
+            // We need to wrap the remaining content in a shared scrollable container if the footer is not pinned
+            isFooterPinned
+                ? this.renderModalContentAndFooter()
+                : html`
+                        <div class="c-modal-scrollContainer">
+                            ${this.renderModalContentAndFooter()}
+                        </div>
+                        `
+            }
+        </dialog>`;
+    }
+
+    /**
+     * 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 {
+            top = 0, bottom = 0, left = 0, right = 0,
+        } = rect || {};
+
+        // This means the dialog is not open due to clicking the close button so
+        // we want to escape early
+        if (top === 0 && bottom === 0 && left === 0 && right === 0) {
+            return;
+        }
+
+        const isClickOutsideDialog = event.clientY < top ||
+            event.clientY > bottom ||
+            event.clientX < left ||
+            event.clientX > right;
+
+        if (isClickOutsideDialog) {
+            this.isOpen = false;
+        }
+    };
+
+    /**
+     * 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.
+     *
+     * @param {string} eventType
+     */
+    private _dispatchModalCustomEvent (eventType: string): void {
+        const event = new CustomEvent<ModalEventDetail>(eventType, {
+            bubbles: true,
+            composed: true,
+            detail: { targetModal: this },
+        });
+
+        this.dispatchEvent(event);
+    }
+}
+
+defineCustomElement(componentSelector, PieModal);
+
+declare global {
+    interface HTMLElementTagNameMap {
+        [componentSelector]: PieModal;
+    }
+}

package/src/modal.scss

@@ -0,0 +1,321 @@
+@use '@justeattakeaway/pie-css/scss' as p;
+@use '@justeat/pie-design-tokens/dist/jet.scss' as dt;
+@use 'dialog-polyfill/dist/dialog-polyfill.css';
+
+*,
+*:before,
+*:after {
+    box-sizing: border-box;
+}
+
+.c-modal {
+    // Custom Property Declarations
+    // These are defined here instead of :host to encapsulate them inside Shadow DOM
+    $breakpoint-wide: 768px;
+
+    --modal-size-s: 450px;
+    --modal-size-m: 600px;
+    --modal-size-l: 1080px;
+
+    // The base modal defaults
+    --modal-border-radius: var(--dt-radius-rounded-d);
+    --modal-font: var(--dt-font-interactive-m-family);
+    --modal-bg-color: var(--dt-color-container-default);
+    --modal-elevation: var(--dt-elevation-04);
+
+    &:focus-visible {
+        outline: none;
+    }
+
+    // We need to override the icon sizes at different screen sizes regardless of size prop passed in
+    pie-icon-button {
+        @media (max-width: calc($breakpoint-wide - 1px)) {
+            --btn-dimension: 40px;
+        }
+    }
+
+
+    &[open] {
+        // We only apply this when the modal is open,
+        // otherwise it interferes with the native
+        // `display: none;` on the dialog element.
+        display: flex;
+        flex-direction: column;
+    }
+
+    border-radius: var(--modal-border-radius);
+    border: none;
+    box-shadow: var(--modal-elevation);
+    font-family: var(--modal-font);
+    background-color: var(--modal-bg-color);
+
+    padding: 0;
+
+    --modal-margin-none: var(--dt-spacing-none);
+    --modal-margin-small: var(--dt-spacing-g);
+    --modal-margin-large: var(--dt-spacing-j);
+    --modal-margin-block: var(--modal-margin-small);
+
+    @media (min-width: $breakpoint-wide) {
+        --modal-margin-block: var(--modal-margin-large);
+    }
+
+    // The initial values for these variables apply to the medium-sized modal
+    // Other sizes will update the variables as needed
+    --modal-block-size: fit-content;
+    --modal-inline-size: 75%;
+    --modal-max-block-size: calc(100vh - calc(var(--modal-margin-block) * 2));
+    --modal-max-inline-size: var(--modal-size-m);
+
+    block-size: var(--modal-block-size);
+    inline-size: var(--modal-inline-size);
+    max-block-size: var(--modal-max-block-size);
+    max-inline-size: var(--modal-max-inline-size);
+
+    &[size='small'] {
+        --modal-max-inline-size: var(--modal-size-s);
+
+        @media (min-width: $breakpoint-wide) {
+            --modal-margin-block: var(--modal-margin-large);
+        }
+    }
+
+    &[size='medium'] {
+        /* Same as default styles */
+        &[isfullwidthbelowmid] {
+            @media (max-width: calc($breakpoint-wide - 1px)) {
+                --modal-margin-block: var(--modal-margin-none);
+                --modal-border-radius: var(--dt-radius-rounded-none);
+                --modal-block-size: 100%;
+                --modal-inline-size: 100%;
+
+                // In this case, the modal must exceed the previous maximum width
+                --modal-max-inline-size: 100%;
+
+                // this ensures the content container spans the full height
+                > .c-modal-scrollContainer {
+                    block-size: 100%;
+                }
+            }
+        }
+    }
+
+    &[size='large'] {
+        --modal-inline-size: 75%;
+        --modal-max-inline-size: var(--modal-size-l);
+        --modal-margin-block: var(--modal-margin-large);
+
+        @media (max-width: calc($breakpoint-wide - 1px)) {
+            --modal-margin-block: var(--modal-margin-none);
+            --modal-border-radius: var(--dt-radius-rounded-none);
+            --modal-block-size: 100%;
+            --modal-inline-size: 100%;
+        }
+    }
+
+    &[position='top'] {
+        margin-block-start: var(--dt-spacing-j);
+        max-block-size: calc(100% - var(--dt-spacing-j) * 2);
+
+        &[size='large'],
+        &[isfullwidthbelowmid][size='medium'] {
+            @media (max-width: calc($breakpoint-wide - 1px)) {
+                margin-block-start: var(--dt-spacing-none);
+                max-block-size: 100%;
+            }
+        }
+    }
+
+    // We need to pull in the token directly here because the
+    // pseudo element `::backdrop` doesn't seem to pick up custom css properties.
+    &::backdrop {
+        background: #{dt.$color-overlay};
+    }
+
+    & .c-modal-footer {
+        --modal-button-spacing: var(--dt-spacing-d);
+        --modal-footer-padding: var(--dt-spacing-d);
+
+        display: flex;
+        flex-flow: row-reverse;
+        flex-wrap: wrap;
+        gap: var(--modal-button-spacing);
+        padding: var(--modal-footer-padding);
+
+        @media (min-width: $breakpoint-wide) {
+            --modal-footer-padding: var(--dt-spacing-e);
+        }
+    }
+
+    // When hasStackedActions is set
+    // change the direction of the footer flex container so buttons are full width of modal
+    &[hasstackedactions] {
+        & .c-modal-footer {
+            // TODO: Move breakpoint sizes into shared CSS component utilities
+            @media (max-width: calc($breakpoint-wide - 1px)) {
+                flex-direction: column;
+            }
+        }
+    }
+
+    & .c-modal-header {
+        display: grid;
+        grid-template-areas: 'back heading close';
+        grid-template-columns: minmax(0, max-content) minmax(0, 1fr) minmax(0, max-content);
+        align-items: start;
+    }
+
+    & .c-modal-heading {
+        --modal-header-font-size: calc(var(--dt-font-heading-m-size--narrow) * 1px);
+        --modal-header-font-line-height: calc(var(--dt-font-heading-m-line-height--narrow) * 1px);
+        --modal-header-font-weight: var(--dt-font-heading-m-weight);
+
+        font-size: var(--modal-header-font-size);
+        line-height: var(--modal-header-font-line-height);
+        font-weight: var(--modal-header-font-weight);
+        margin: 0;
+        grid-area: heading;
+
+        margin-inline: var(--dt-spacing-d);
+        margin-block: 14px; // This is deliberately not a custom property
+
+        @media (min-width: $breakpoint-wide) {
+            --modal-header-font-size: calc(var(--dt-font-heading-m-size--wide) * 1px);
+            --modal-header-font-line-height: calc(var(--dt-font-heading-m-line-height--wide) * 1px);
+            margin-inline: var(--dt-spacing-e);
+            margin-block: 20px; // This is deliberately not a custom property
+        }
+    }
+
+    // Ensure correct padding when there is a back button in front of the heading
+    &[hasbackbutton] .c-modal-heading {
+        margin-inline-start: var(--dt-spacing-b);
+
+        @media (min-width: $breakpoint-wide) {
+            margin-inline-start: var(--dt-spacing-c);
+        }
+    }
+
+    // Ensure correct padding when there is a close button behind the heading
+    &[isdismissible] .c-modal-heading {
+        margin-inline-end: var(--dt-spacing-d);
+
+        @media (min-width: $breakpoint-wide) {
+            margin-inline-end: var(--dt-spacing-e);
+        }
+    }
+
+    & .c-modal-backBtn {
+        grid-area: back;
+        margin-block: var(--dt-spacing-b);
+        margin-inline: var(--dt-spacing-b) var(--dt-spacing-none);
+
+        @media (min-width: $breakpoint-wide) {
+            margin-block: var(--dt-spacing-c);
+            margin-inline: var(--dt-spacing-c) var(--dt-spacing-none);
+        }
+    }
+
+    & .c-modal-closeBtn {
+        grid-area: close;
+        margin-block: var(--dt-spacing-b);
+        margin-inline: var(--dt-spacing-none) var(--dt-spacing-b);
+
+        @media (min-width: $breakpoint-wide) {
+            margin-block: var(--dt-spacing-c);
+            margin-inline: var(--dt-spacing-none) var(--dt-spacing-c);
+        }
+    }
+
+    & .c-modal-content {
+        // Modal content Custom Props
+        --modal-content-font-size: calc(var(--dt-font-size-16) * 1px);
+        --modal-content-font-weight: var(--dt-font-weight-regular);
+        --modal-content-line-height: calc(var(--dt-font-size-16-line-height) * 1px);
+        --modal-content-padding-block: var(--dt-spacing-a);
+        --modal-content-padding-inline: var(--dt-spacing-d);
+
+        @media (min-width: $breakpoint-wide) {
+            --modal-content-padding-inline: var(--dt-spacing-e);
+        }
+
+        position: relative;
+        min-block-size: var(--dt-spacing-j);
+
+        font-size: var(--modal-content-font-size);
+        line-height: var(--modal-content-line-height);
+        font-weight: var(--modal-content-font-weight);
+
+        padding-inline: var(--modal-content-padding-inline);
+        padding-block: var(--modal-content-padding-block);
+        flex-grow: 1;
+
+        &--scrollable {
+            background:
+                // Scroll shadow cover
+                // A top-to-bottom opacity gradient from transparent to the component background colour
+                linear-gradient(to bottom, transparent, var(--dt-color-container-default) 75%) center bottom,
+                // Scroll shadow
+                linear-gradient(transparent, var(--dt-color-border-strong)) center bottom;
+            background-repeat: no-repeat;
+            background-size: 100% 48px, 100% 12px;
+
+            // The shadow cover is an opacity gradient which is attached to the bottom of the scrollable element
+            // and scrolls with it, so as you reach the bottom of the content the more opaque portion covers
+            // (and therefore hides) the shadow. This gives the effect of the shadow fading away.
+            // The shadow itself does not move as you scroll.
+            background-attachment: local, scroll;
+        }
+    }
+
+    & > .c-modal-scrollContainer {
+        display: flex;
+        flex-direction: column;
+        block-size: auto;
+        overflow-y: auto;
+
+        // These are the shadows used to indicate scrolling above and below content
+        --bg-scroll-end: linear-gradient(rgba(255, 255, 255, 0), var(--dt-color-container-default) 70%) 0 100%;
+        --bg-scroll-bottom: radial-gradient(farthest-corner at 50% 100%, rgba(0, 0, 0, 0.3), rgba(0, 0, 0, 0)) 0 100%;
+
+        // Sizes of the scroll shadows
+        --bg-size-scroll-end: 100% 40px;
+        --bg-size-scroll-bottom: 100% 8px;
+
+        background: var(--bg-scroll-end), var(--bg-scroll-bottom);
+        background-repeat: no-repeat;
+        background-size: var(--bg-size-scroll-end), var(--bg-size-scroll-bottom);
+
+        background-attachment: local, scroll;
+
+        .c-modal-content {
+            flex-shrink: 0;
+        }
+    }
+
+    &[isfooterpinned] .c-modal-content {
+        overflow-y: auto;
+    }
+
+    &[isLoading] .c-modal-content {
+        pie-spinner {
+            position: absolute;
+            left: 50%;
+            top: 50%;
+            transform: translate(-50%, -50%);
+        }
+
+        & .c-modal-contentInner {
+            display: none;
+        }
+    }
+
+    // removes the scroll shadow effect if "background-attachment" isn't supported.
+    // @supports (background-attachment: local) isn't used as Safari 14 recognizes the property but it has no effect.
+    // thus, "aspect-ratio" is used instead as it's only supported in Safari>=15
+    @supports not (aspect-ratio: 1 / 1) {
+        .c-modal-scrollContainer {
+            background: none;
+        }
+    }
+}