@ui5/webcomponents-react

import '@ui5/webcomponents/dist/Dialog.js'; import type { PopupBeforeCloseEventDetail } from '@ui5/webcomponents/dist/Popup.js'; import type PopupAccessibleRole from '@ui5/webcomponents/dist/types/PopupAccessibleRole.js'; import type ValueState from '@ui5/webcomponents-base/dist/types/ValueState.js'; import type { CommonProps, Ui5CustomEvent, Ui5DomRef, UI5WCSlotsNode } from '@ui5/webcomponents-react-base'; import type { ReactNode } from 'react'; interface DialogAttributes { /** * Defines the accessible description of the component. * * **Note:** Available since [v2.11.0](https://github.com/UI5/webcomponents/releases/tag/v2.11.0) of **@ui5/webcomponents**. * @default undefined */ accessibleDescription?: string | undefined; /** * Receives id(or many ids) of the elements that describe the component. * * **Note:** Available since [v2.11.0](https://github.com/UI5/webcomponents/releases/tag/v2.11.0) of **@ui5/webcomponents**. * @default undefined */ accessibleDescriptionRef?: string | undefined; /** * Defines the accessible name of the component. * @default undefined */ accessibleName?: string | undefined; /** * Defines the IDs of the elements that label the component. * * **Note:** Available since [v1.1.0](https://github.com/UI5/webcomponents/releases/tag/v1.1.0) of **@ui5/webcomponents**. * @default undefined */ accessibleNameRef?: string | undefined; /** * Allows setting a custom role. * * **Note:** Available since [v1.10.0](https://github.com/UI5/webcomponents/releases/tag/v1.10.0) of **@ui5/webcomponents**. * @default "Dialog" */ accessibleRole?: PopupAccessibleRole | keyof typeof PopupAccessibleRole; /** * Determines whether the component is draggable. * If this property is set to true, the Dialog will be draggable by its header. * * **Note:** The component can be draggable only in desktop mode. * * **Note:** This property overrides the default HTML "draggable" attribute native behavior. * When "draggable" is set to true, the native browser "draggable" * behavior is prevented and only the Dialog custom logic ("draggable by its header") works. * @default false */ draggable?: boolean; /** * Defines the header text. * * **Note:** If `header` slot is provided, the `headerText` is ignored. * @default undefined */ headerText?: string | undefined; /** * Defines the ID of the HTML Element, which will get the initial focus. * * **Note:** If an element with `autofocus` attribute is added inside the component, * `initialFocus` won't take effect. * @default undefined */ initialFocus?: string | undefined; /** * Indicates if the element is open * * **Note:** Available since [v1.2.0](https://github.com/UI5/webcomponents/releases/tag/v1.2.0) of **@ui5/webcomponents**. * @default false */ open?: boolean; /** * Defines if the focus should be returned to the previously focused element, * when the popup closes. * @default false */ preventFocusRestore?: boolean; /** * Indicates whether initial focus should be prevented. * * **Note:** Available since [v2.0.0](https://github.com/UI5/webcomponents/releases/tag/v2.0.0) of **@ui5/webcomponents**. * @default false */ preventInitialFocus?: boolean; /** * Configures the component to be resizable. * If this property is set to true, the Dialog will have a resize handle in its bottom right corner in LTR languages. * In RTL languages, the resize handle will be placed in the bottom left corner. * * **Note:** The component can be resizable only in desktop mode. * * **Note:** Upon resizing, externally defined height and width styling will be ignored. * @default false */ resizable?: boolean; /** * Defines whether a fullscreen toggle button is shown in the dialog header. * When pressed, it toggles the `stretch` property. * The fullscreen button is not available on phone devices. * * **Note:** The fullscreen button is not available on phone devices, * nor when a custom header slot is provided — the application is expected * to render its own toggle inside the custom header in those cases. * * **Note:** Available since [v2.25.0](https://github.com/UI5/webcomponents/releases/tag/v2.25.0) of **@ui5/webcomponents**. * @default false */ showFullscreenButton?: boolean; /** * Defines the state of the `Dialog`. * * **Note:** If `"Negative"` and `"Critical"` states is set, it will change the * accessibility role to "alertdialog", if the accessibleRole property is set to `"Dialog"`. * @default "None" */ state?: ValueState | keyof typeof ValueState; /** * Determines if the dialog will be stretched to full screen on mobile. On desktop, * the dialog will be stretched to approximately 90% of the viewport. * * **Note:** For better usability of the component it is recommended to set this property to "true" when the dialog is opened on phone. * @default false */ stretch?: boolean; } interface DialogDomRef extends Required<DialogAttributes>, Ui5DomRef { /** * Focuses the element denoted by `initialFocus`, if provided, * or the first focusable element otherwise. * @returns {Promise<void>} - Promise that resolves when the focus is applied */ applyFocus: () => Promise<void>; } interface DialogPropTypes extends DialogAttributes, Omit<CommonProps, keyof DialogAttributes | 'children' | 'footer' | 'header' | 'onBeforeClose' | 'onBeforeOpen' | 'onClose' | 'onOpen'> { /** * Defines the content of the Popup. * * __Supported Node Type/s:__ `Array<HTMLElement>` */ children?: ReactNode | ReactNode[]; /** * Defines the footer HTML Element. * * __Note:__ The content of the prop will be rendered into a [<slot>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot) by assigning the respective [slot](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/slot) attribute (`slot="footer"`). * Since you can't change the DOM order of slots when declaring them within a prop, it might prove beneficial to manually mount them as part of the component's children, especially when facing problems with the reading order of screen readers. * * __Note:__ When passing a custom React component to this prop, you have to make sure your component reads the `slot` prop and appends it to the most outer element of your component. * Learn more about it [here](https://ui5.github.io/webcomponents-react/v2/?path=/docs/knowledge-base-handling-slots--docs). * * __Supported Node Type/s:__ `Array<HTMLElement>` */ footer?: UI5WCSlotsNode; /** * Defines the header HTML Element. * * **Note:** If `header` slot is provided, the labelling of the dialog is a responsibility of the application developer. * `accessibleName` should be used. * * __Note:__ The content of the prop will be rendered into a [<slot>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot) by assigning the respective [slot](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/slot) attribute (`slot="header"`). * Since you can't change the DOM order of slots when declaring them within a prop, it might prove beneficial to manually mount them as part of the component's children, especially when facing problems with the reading order of screen readers. * * __Note:__ When passing a custom React component to this prop, you have to make sure your component reads the `slot` prop and appends it to the most outer element of your component. * Learn more about it [here](https://ui5.github.io/webcomponents-react/v2/?path=/docs/knowledge-base-handling-slots--docs). * * __Supported Node Type/s:__ `Array<HTMLElement>` */ header?: UI5WCSlotsNode; /** * Fired before the component is closed. This event can be cancelled, which will prevent the popup from closing. * * **Note:** Call `event.preventDefault()` inside the handler of this event to prevent its default action/s. * * | cancelable | bubbles | * | :--------: | :-----: | * | ✅|❌| */ onBeforeClose?: (event: Ui5CustomEvent<DialogDomRef, PopupBeforeCloseEventDetail>) => void; /** * Fired before the component is opened. This event can be cancelled, which will prevent the popup from opening. * * **Note:** Call `event.preventDefault()` inside the handler of this event to prevent its default action/s. * * | cancelable | bubbles | * | :--------: | :-----: | * | ✅|❌| */ onBeforeOpen?: (event: Ui5CustomEvent<DialogDomRef>) => void; /** * Fired after the component is closed. * * | cancelable | bubbles | * | :--------: | :-----: | * | ❌|❌| */ onClose?: (event: Ui5CustomEvent<DialogDomRef>) => void; /** * Fired after the component is opened. * * | cancelable | bubbles | * | :--------: | :-----: | * | ❌|❌| */ onOpen?: (event: Ui5CustomEvent<DialogDomRef>) => void; } /** * The `Dialog` component is used to temporarily display some information in a * size-limited window in front of the regular app screen. * It is used to prompt the user for an action or a confirmation. * The `Dialog` interrupts the current app processing as it is the only focused UI element and * the main screen is dimmed/blocked. * The dialog combines concepts known from other technologies where the windows have * names such as dialog box, dialog window, pop-up, pop-up window, alert box, or message box. * * The `Dialog` is modal, which means that a user action is required before it is possible to return to the parent window. * To open multiple dialogs, each dialog element should be separate in the markup. This will ensure the correct modal behavior. Avoid nesting dialogs within each other. * The content of the `Dialog` is fully customizable. * * ### Structure * A `Dialog` consists of a header, content, and a footer for action buttons. * The `Dialog` is usually displayed at the center of the screen. * Its position can be changed by the user. To enable this, you need to set the property `draggable` accordingly. * * * ### Responsive Behavior * The `stretch` property can be used to stretch the `Dialog` to full screen. For better usability, it's recommended to stretch the dialog to full screen on phone devices. * * **Note:** When a `Bar` is used in the header or in the footer, you should remove the default dialog's paddings. * * For more information see the sample "Bar in Header/Footer". * * ### Keyboard Handling * * #### Basic Navigation * When the `Dialog` has the `draggable` property set to `true`, the user can move the dialog * with the following keyboard shortcuts: * * - [Up] or [Down] arrow keys - Move the dialog up/down. * - [Left] or [Right] arrow keys - Move the dialog left/right. * * #### Resizing * When the `Dialog` has the `resizable` property set to `true`, the user can change the size of the dialog * with the following keyboard shortcuts: * * - [Shift] + [Up] or [Down] - Decrease/Increase the height of the dialog. * - [Shift] + [Left] or [Right] - Decrease/Increase the width of the dialog. * * #### Fullscreen * When the `Dialog` has the `showFullscreenButton` property set to `true`, the user can toggle fullscreen mode * with the following keyboard shortcut: * * - [Shift] + [Ctrl] + [F] - Toggle fullscreen mode. * * * * __Note:__ This is a UI5 Web Component! [Dialog UI5 Web Component Documentation](https://ui5.github.io/webcomponents/components/Dialog) | [Repository](https://github.com/UI5/webcomponents) */ declare const Dialog: import("react").ForwardRefExoticComponent<DialogPropTypes & import("@ui5/webcomponents-react-base").WithWebComponentPropTypes & import("react").RefAttributes<DialogDomRef>>; export { Dialog }; export type { DialogDomRef, DialogPropTypes };