@justeattakeaway/pie-modal 0.16.0 → 0.18.0

package/README.md

@@ -15,6 +15,7 @@
 3. [Importing the component](#importing-the-component)
 4. [Props](#props)
 5. [Testing](#testing)
+5. [Legacy browser support](#legacy-browser-support)
 
 # pie-modal
 
@@ -118,3 +119,16 @@ Under scripts `test:visual` replace the environment variable with the below:
 ```bash
 PERCY_TOKEN_PIE_MODAL=abcde
 ```
+
+## 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.

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

@@ -1,126 +1,241 @@
-import { LitElement, TemplateResult } from 'lit';
-import type { DependentMap } from '@justeattakeaway/pie-webc-core';
-import { type AriaProps, type ActionProps, type ModalProps, headingLevels, sizes } from './defs';
-export { type ModalProps, headingLevels, sizes };
-declare const componentSelector = "pie-modal";
-declare const PieModal_base: (new (...args: any[]) => {
-    dir: "ltr" | "rtl" | "auto";
-    isRTL: boolean;
-}) & typeof LitElement;
-/**
- * @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.
- */
-export declare class PieModal extends PieModal_base implements ModalProps {
-    aria: AriaProps;
-    heading: string;
-    headingLevel: ModalProps['headingLevel'];
-    hasBackButton: boolean;
-    hasStackedActions: boolean;
-    isDismissible: boolean;
-    isFooterPinned: boolean;
-    isFullWidthBelowMid: boolean;
-    isLoading: boolean;
-    isOpen: boolean;
-    leadingAction: ActionProps;
-    position: ModalProps['position'];
-    returnFocusAfterCloseSelector?: string;
-    size: ModalProps['size'];
-    supportingAction: ActionProps;
-    private _dialog?;
-    private _backButtonClicked;
-    static styles: import("lit").CSSResult;
-    constructor();
-    connectedCallback(): void;
-    disconnectedCallback(): void;
-    firstUpdated(changedProperties: DependentMap<ModalProps>): void;
-    updated(changedProperties: DependentMap<ModalProps>): void;
-    /**
-     * Opens the dialog element and disables page scrolling
-     */
-    private _handleModalOpened;
-    /**
-     * Closes the dialog element and re-enables page scrolling
-     */
-    private _handleModalClosed;
-    /**
-     * 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;
-    private _handleModalOpenStateOnFirstRender;
-    private _handleModalOpenStateChanged;
-    /**
-     * Return focus to the specified element, providing the selector is valid
-     * and the chosen element can be found.
-     */
-    private _returnFocus;
-    /**
-     * Template for the close button element. Called within the
-     * main render function.
-     *
-     * @private
-     */
-    private renderCloseButton;
-    /**
-     * Template for the back button element. Called within the
-     * main render function.
-     *
-     * @private
-     */
-    private renderBackButton;
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * Renders the modal inner content and footer of the modal.
-     * @private
-     */
-    private renderModalContentAndFooter;
-    render(): TemplateResult;
-    /**
-     * Dismisses the modal on backdrop click if `isDismissible` is `true`.
-     * @param {MouseEvent} event - the click event targetting the modal/backdrop
-     */
-    private _handleDialogLightDismiss;
-    /**
-     * 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;
-}
-declare global {
-    interface HTMLElementTagNameMap {
-        [componentSelector]: PieModal;
-    }
-}
-//# sourceMappingURL=index.d.ts.map
+import type { CSSResult } from 'lit';
+import type { DependentMap } from '@justeattakeaway/pie-webc-core';
+import type { LitElement } from 'lit';
+import { RTLComponentProps } from '@justeattakeaway/pie-webc-core';
+import type { TemplateResult } from 'lit';
+import { Variant } from '@justeattakeaway/pie-button/src/defs.ts';
+
+export declare 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 declare type AriaProps = {
+    close?: string;
+    back?: string;
+    loading?: string;
+};
+
+export declare const headingLevels: readonly ["h1", "h2", "h3", "h4", "h5", "h6"];
+
+export declare type ModalProps = RTLComponentProps & {
+    /**
+     * 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;
+    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 back button is clicked.
+ *
+ * @constant
+ */
+export declare const ON_MODAL_BACK_EVENT = "pie-modal-back";
+
+/**
+ * Event name for when the modal is closed.
+ *
+ * @constant
+ */
+export declare const ON_MODAL_CLOSE_EVENT = "pie-modal-close";
+
+/**
+ * Event name for when the modal is opened.
+ *
+ * @constant
+ */
+export declare const ON_MODAL_OPEN_EVENT = "pie-modal-open";
+
+/**
+ * @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.
+ */
+export declare class PieModal extends PieModal_base implements ModalProps {
+    aria: AriaProps;
+    heading: string;
+    headingLevel: ModalProps['headingLevel'];
+    hasBackButton: boolean;
+    hasStackedActions: boolean;
+    isDismissible: boolean;
+    isFooterPinned: boolean;
+    isFullWidthBelowMid: boolean;
+    isLoading: boolean;
+    isOpen: boolean;
+    leadingAction: ActionProps;
+    position: ModalProps['position'];
+    returnFocusAfterCloseSelector?: string;
+    size: ModalProps['size'];
+    supportingAction: ActionProps;
+    private _dialog?;
+    private _backButtonClicked;
+    static styles: CSSResult;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    firstUpdated(changedProperties: DependentMap<ModalProps>): void;
+    updated(changedProperties: DependentMap<ModalProps>): void;
+    /**
+     * Opens the dialog element and disables page scrolling
+     */
+    private _handleModalOpened;
+    /**
+     * Closes the dialog element and re-enables page scrolling
+     */
+    private _handleModalClosed;
+    /**
+     * 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;
+    private _handleModalOpenStateOnFirstRender;
+    private _handleModalOpenStateChanged;
+    /**
+     * Return focus to the specified element, providing the selector is valid
+     * and the chosen element can be found.
+     */
+    private _returnFocus;
+    /**
+     * Template for the close button element. Called within the
+     * main render function.
+     *
+     * @private
+     */
+    private renderCloseButton;
+    /**
+     * Template for the back button element. Called within the
+     * main render function.
+     *
+     * @private
+     */
+    private renderBackButton;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Renders the modal inner content and footer of the modal.
+     * @private
+     */
+    private renderModalContentAndFooter;
+    render(): TemplateResult;
+    /**
+     * Dismisses the modal on backdrop click if `isDismissible` is `true`.
+     * @param {MouseEvent} event - the click event targetting the modal/backdrop
+     */
+    private _handleDialogLightDismiss;
+    /**
+     * 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;
+}
+
+declare const PieModal_base: (new (...args: any[]) => {
+    dir: "ltr" | "rtl" | "auto";
+    isRTL: boolean;
+}) & typeof LitElement;
+
+export declare const positions: readonly ["top", "center"];
+
+export declare const sizes: readonly ["small", "medium", "large"];
+
+export { }