@primer/react/lib/Dialog/Dialog.d.ts

An implementation of GitHub's Primer Design System using React

import React from 'react';
import type { ButtonProps } from '../Button';
import type { SxProp } from '../sx';
import type { ResponsiveValue } from '../hooks/useResponsiveValue';
import type { ForwardRefComponent as PolymorphicForwardRefComponent } from '../utils/polymorphic';
/**
 * Props that characterize a button to be rendered into the footer of
 * a Dialog.
 */
export type DialogButtonProps = Omit<ButtonProps, 'content'> & {
    /**
     * The variant of Button to use
     */
    buttonType?: 'default' | 'primary' | 'danger' | 'normal';
    /**
     * The Button's inner text
     */
    content: React.ReactNode;
    /**
     * If true, and if this is the only button with autoFocus set to true,
     * focus this button automatically when the dialog appears.
     */
    autoFocus?: boolean;
    /**
     * A reference to the rendered Button’s DOM node, used together with
     * `autoFocus` for `focusTrap`’s `initialFocus`.
     */
    ref?: React.RefObject<HTMLButtonElement>;
};
/**
 * Props to customize the rendering of the Dialog.
 */
export interface DialogProps extends SxProp {
    /**
     * Title of the Dialog. Also serves as the aria-label for this Dialog.
     */
    title?: React.ReactNode;
    /**
     * The Dialog's subtitle. Optional. Rendered below the title in smaller
     * type with less contrast. Also serves as the aria-describedby for this
     * Dialog.
     */
    subtitle?: React.ReactNode;
    /**
     * Provide a custom renderer for the dialog header. This content is
     * rendered directly into the dialog body area, full bleed from edge
     * to edge, top to the start of the body element.
     *
     * Warning: using a custom renderer may violate Primer UX principles.
     */
    renderHeader?: React.FunctionComponent<React.PropsWithChildren<DialogHeaderProps>>;
    /**
     * Provide a custom render function for the dialog body. This content is
     * rendered directly into the dialog body area, full bleed from edge to
     * edge, header to footer.
     *
     * Warning: using a custom renderer may violate Primer UX principles.
     */
    renderBody?: React.FunctionComponent<React.PropsWithChildren<DialogProps>>;
    /**
     * Provide a custom render function for the dialog footer. This content is
     * rendered directly into the dialog footer area, full bleed from edge to
     * edge, end of the body element to bottom.
     *
     * Warning: using a custom renderer may violate Primer UX principles.
     */
    renderFooter?: React.FunctionComponent<React.PropsWithChildren<DialogProps>>;
    /**
     * Specifies the buttons to be rendered in the Dialog footer.
     */
    footerButtons?: DialogButtonProps[];
    /**
     * This method is invoked when a gesture to close the dialog is used (either
     * an Escape key press, clicking the backdrop, or clicking the "X" in the top-right corner). The
     * gesture argument indicates the gesture that was used to close the dialog
     * ('close-button' or 'escape').
     */
    onClose: (gesture: 'close-button' | 'escape') => void;
    /**
     * Default: "dialog". The ARIA role to assign to this dialog.
     * @see https://www.w3.org/TR/wai-aria-practices-1.1/#dialog_modal
     * @see https://www.w3.org/TR/wai-aria-practices-1.1/#alertdialog
     */
    role?: 'dialog' | 'alertdialog';
    /**
     * The width of the dialog.
     * small: 296px
     * medium: 320px
     * large: 480px
     * xlarge: 640px
     */
    width?: DialogWidth;
    /**
     * The height of the dialog.
     * small: 296x480
     * large: 480x640
     * auto: variable based on contents
     */
    height?: DialogHeight;
    /**
     * The position of the dialog
     */
    position?: 'center' | 'left' | 'right' | ResponsiveValue<'left' | 'right' | 'bottom' | 'fullscreen' | 'center'>;
    /**
     * Return focus to this element when the Dialog closes,
     * instead of the element that had focus immediately before the Dialog opened
     */
    returnFocusRef?: React.RefObject<HTMLElement>;
    /**
     * The element to focus when the Dialog opens
     */
    initialFocusRef?: React.RefObject<HTMLElement>;
    /**
     * Additional class names to apply to the dialog
     */
    className?: string;
}
/**
 * Props that are passed to a component that serves as a dialog header
 */
export interface DialogHeaderProps extends DialogProps {
    /**
     * ID of the element that will be used as the `aria-labelledby` attribute on the
     * dialog. This ID should be set to the element that renders the dialog's title.
     */
    dialogLabelId: string;
    /**
     * ID of the element that will be used as the `aria-describedby` attribute on the
     * dialog. This ID should be set to the element that renders the dialog's subtitle.
     */
    dialogDescriptionId: string;
}
declare const heightMap: {
    readonly small: "480px";
    readonly large: "640px";
    readonly auto: "auto";
};
declare const widthMap: {
    readonly small: "296px";
    readonly medium: "320px";
    readonly large: "480px";
    readonly xlarge: "640px";
};
export type DialogWidth = keyof typeof widthMap;
export type DialogHeight = keyof typeof heightMap;
type StyledHeaderProps = React.ComponentProps<'div'> & SxProp;
type StyledTitleProps = React.ComponentProps<'h1'> & SxProp;
type StyledSubtitleProps = React.ComponentProps<'h2'> & SxProp;
type StyledBodyProps = React.ComponentProps<'div'> & SxProp;
type StyledFooterProps = React.ComponentProps<'div'> & SxProp;
/**
 * A dialog is a type of overlay that can be used for confirming actions, asking
 * for disambiguation, and presenting small forms. They generally allow the user
 * to focus on a quick task without having to navigate to a different page.
 *
 * Dialogs appear in the page after a direct user interaction. Don't show dialogs
 * on page load or as system alerts.
 *
 * Dialogs appear centered in the page, with a visible backdrop that dims the rest
 * of the window for focus.
 *
 * All dialogs have a title and a close button.
 *
 * Dialogs are modal. Dialogs can be dismissed by clicking on the close button,
 * pressing the escape key, or by interacting with another button in the dialog.
 * To avoid losing information and missing important messages, clicking outside
 * of the dialog will not close it.
 *
 * The sub components provided (e.g. Header, Title, etc.) are available for custom
 * renderers only. They are not intended to be used otherwise.
 */
export declare const Dialog: React.ForwardRefExoticComponent<DialogProps & {
    children?: React.ReactNode | undefined;
} & React.RefAttributes<HTMLDivElement>> & {
    Header: React.ForwardRefExoticComponent<Omit<StyledHeaderProps, "ref"> & React.RefAttributes<HTMLElement>>;
    Title: React.ForwardRefExoticComponent<Omit<StyledTitleProps, "ref"> & React.RefAttributes<HTMLElement>>;
    Subtitle: React.ForwardRefExoticComponent<Omit<StyledSubtitleProps, "ref"> & React.RefAttributes<HTMLElement>>;
    Body: PolymorphicForwardRefComponent<"div", StyledBodyProps>;
    Footer: React.ForwardRefExoticComponent<Omit<StyledFooterProps, "ref"> & React.RefAttributes<HTMLElement>>;
    Buttons: React.FC<React.PropsWithChildren<{
        buttons: DialogButtonProps[];
    }>>;
    CloseButton: React.FC<React.PropsWithChildren<{
        onClose: () => void;
    }>>;
};
export {};
//# sourceMappingURL=Dialog.d.ts.map