@justeattakeaway/pie-modal 0.17.0 → 0.19.0

package/dist/react.d.ts

@@ -0,0 +1,270 @@
+import type { CSSResult } from 'lit';
+import type { DependentMap } from '@justeattakeaway/pie-webc-core';
+import type { EventName } from '@lit-labs/react';
+import type { LitElement } from 'lit';
+import type { ReactWebComponent } from '@lit-labs/react';
+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 ModalActionType = 'leading' | 'supporting';
+
+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 leading action is clicked.
+ *
+ * @constant
+ */
+export declare const ON_MODAL_LEADING_ACTION_CLICK = "pie-modal-leading-action-click";
+
+/**
+ * Event name for when the modal is opened.
+ *
+ * @constant
+ */
+export declare const ON_MODAL_OPEN_EVENT = "pie-modal-open";
+
+/**
+ * Event name for when the modal supporting action is clicked.
+ *
+ * @constant
+ */
+export declare const ON_MODAL_SUPPORTING_ACTION_CLICK = "pie-modal-supporting-action-click";
+
+export declare const PieModal: ReactWebComponent<PieModal_2, {
+    onPieModalOpen: EventName<CustomEvent<any>>;
+    onPieModalClose: EventName<CustomEvent<any>>;
+    onPieModalBack: EventName<CustomEvent<any>>;
+    onPieModalLeadingActionClick: EventName<CustomEvent<any>>;
+    onPieModalSupportingActionClick: EventName<CustomEvent<any>>;
+}>;
+
+/**
+ * @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.
+ */
+declare class PieModal_2 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;
+    private _handleActionClick;
+    /**
+     * 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 { }