import * as React from "react"; import type { Props } from "./types"; /** * @orbit-doc-start * README * ---------- * # Dialog * * To implement Dialog component into your project you'll need to add the import: * * ```jsx * import Dialog from "@kiwicom/orbit-components/lib/Dialog"; * ``` * * After adding import into your project you can use it simply like: * * ```jsx * Log out} * /> * ``` * * ## Props * * Table below contains all types of the props available in Dialog component. * * | Name | Type | Default | Description | * | :---------------- | :------------------------------------------------------ | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- | * | dataTest | `string` | | Optional prop for testing purposes. | * | id | `string` | | Set `id` for `Dialog`. | * | renderInPortal | `boolean` | `true` | Optional prop, set it to `false` if you're rendering Dialog inside a custom portal. | * | description | `React.Node` | | Optional description of the main action that Dialog performs. | * | illustration | `React.Node` | | Optional illustration of the Dialog. | * | **primaryAction** | `React.Node` | | Primary and required action that user can do with the Dialog. | * | secondaryAction | `React.Node` | | Optional, secondary action that user can perform - possibility to close the Dialog most of the time. | * | lockScrolling | `boolean` | `true` | Whether to prevent scrolling of the rest of the page while Dialog is open. This is on by default to provide a better user experience. | * | onClose | `() => void \| Promise` | | Callback that is triggered when the dialog is closed. | * | **title** | `React.Node` | | The title of the Dialog - preferably the purpose of the main action. | * | titleAs | `"h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6" \| "div"` | | The HTML tag of the title. It **does not** change the visual style of the title. If undefined, it will render as a `div`. | * | maxWidth | `number` (>540) | | Specifies the maximum width in pixels of the Dialog component. This property only affects the display on larger screen sizes and and widths greater than 540px. | * | triggerRef | `React.RefObject` | | The ref to the element which triggers the Dialog. | * * * Accessibility * ------------- * ## Accessibility * * The Dialog component has been designed with accessibility in mind, providing features that enhance the experience for users of assistive technologies. * * ### Accessibility props * * The following props are available to improve the accessibility of your Dialog component: * * | Name | Type | Description | * | :---------- | :------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------ | * | title | `React.Node` | Provides a visible title that is associated with the dialog as its accessible name. | * | titleAs | `"h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6" \| "div"` | Defines the semantic HTML element for the title while maintaining its visual appearance. | * | description | `React.Node` | Provides additional context about the dialog's purpose, which is automatically associated with the dialog via aria-describedby. | * | triggerRef | `React.RefObject` | References the element that triggered the dialog, allowing focus to return to it when the dialog closes. | * * ### Automatic Accessibility Features * * The Dialog component automatically implements the following accessibility features: * * - `role="dialog"`: Identifies the element as a dialog to assistive technologies. * * - `aria-modal="true"`: Indicates that the dialog is modal, meaning it blocks interaction with page content. * * - `aria-labelledby`: Automatically associates the dialog with its title for screen readers using a generated ID. * * - `aria-describedby`: When a description is provided, it's automatically associated with the dialog using a generated ID. * * - The Dialog's animations respect the user's reduced motion preferences. * * ### Focus Management * * - When opened, focus is automatically moved to the first focusable element within the dialog. * * - When closed, focus returns to the element that triggered the dialog (when `triggerRef` is provided). * * ### Best practices * * - Always provide a descriptive `title` that clearly indicates the purpose of the dialog. * * - Use the `description` prop to provide additional context when needed, especially for complex interactions. * * - Ensure that primary and secondary actions have clear, descriptive labels that indicate their purpose. * * - Use semantic heading levels (`titleAs` prop) that fit within your page's heading hierarchy. For example, if your dialog appears within a page section that uses `h2`, consider using `titleAs="h3"` for proper document structure. * * - Test keyboard navigation within the dialog to ensure all interactive elements are accessible. * * - When creating a dialog trigger, help screen reader users understand the relationship between the trigger and the dialog: * 1. Apply `aria-expanded="true"` to the trigger element when the dialog is open and `aria-expanded="false"` when it's closed. * 2. Use `aria-controls` on the trigger element to associate it with the dialog via Dialog component's `id`. * * ### Keyboard Navigation * * The Dialog component supports the following keyboard interactions: * * - **Escape** key closes the dialog * - **Tab** key navigates through focusable elements within the dialog, with focus being contained within the dialog while it's open * - **Enter/Space** keys activate buttons and other interactive elements within the dialog * * ### Examples * * #### Basic Dialog with accessible title and semantic heading level * * ```jsx * Save changes} * secondaryAction={} * onClose={() => handleClose()} * /> * ``` * * #### Dialog with proper trigger * * ```jsx * function ExampleComponent() { * const [isOpen, setIsOpen] = React.useState(false); * const buttonRef = React.useRef(null); * * return ( * <> * * * {isOpen && ( * { * savePreferences(); * setIsOpen(false); * }} * > * Save preferences * * } * secondaryAction={ * * } * onClose={() => setIsOpen(false)} * triggerRef={buttonRef} * /> * )} * * ); * } * ``` * * * @orbit-doc-end */ declare const Dialog: ({ dataTest, id, title, titleAs, description, primaryAction, secondaryAction, onClose, maxWidth, renderInPortal, illustration, lockScrolling, triggerRef, }: Props) => React.JSX.Element; export default Dialog; //# sourceMappingURL=index.d.ts.map