| 1 | /**
|
| 2 | * Welcome to @reach/dialog!
|
| 3 | *
|
| 4 | * An accessible dialog or "modal" window.
|
| 5 | *
|
| 6 | * @see Docs https://reach.tech/dialog
|
| 7 | * @see Source https://github.com/reach/reach-ui/tree/main/packages/dialog
|
| 8 | * @see WAI-ARIA https://www.w3.org/TR/wai-aria-practices-1.2/#dialog_modal
|
| 9 | */
|
| 10 | import * as React from "react";
|
| 11 | import type * as Polymorphic from "@reach/utils/polymorphic";
|
| 12 | /**
|
| 13 | * DialogOverlay
|
| 14 | *
|
| 15 | * Low-level component if you need more control over the styles or rendering of
|
| 16 | * the dialog overlay.
|
| 17 | *
|
| 18 | * Note: You must render a `DialogContent` inside.
|
| 19 | *
|
| 20 | * @see Docs https://reach.tech/dialog#dialogoverlay
|
| 21 | */
|
| 22 | declare const DialogOverlay: Polymorphic.ForwardRefComponent<"div", DialogOverlayProps>;
|
| 23 | interface DialogOverlayProps extends DialogProps {
|
| 24 | /**
|
| 25 | * By default the dialog locks the focus inside it. Normally this is what you
|
| 26 | * want. This prop is provided so that this feature can be disabled. This,
|
| 27 | * however, is strongly discouraged.
|
| 28 | *
|
| 29 | * The reason it is provided is not to disable the focus lock entirely.
|
| 30 | * Rather, there are certain situations where you may need more control on how
|
| 31 | * the focus lock works. This should be complemented by setting up a focus
|
| 32 | * lock yourself that would allow more flexibility for your specific use case.
|
| 33 | *
|
| 34 | * If you do set this prop to `true`, make sure you set up your own
|
| 35 | * `FocusLock` component. You can likely use
|
| 36 | * `react-focus-lock`, which is what Reach uses internally by default. It has
|
| 37 | * various settings to allow more customization, but it takes care of a lot of
|
| 38 | * hard work that you probably don't want or need to do.
|
| 39 | *
|
| 40 | * @see Docs https://reach.tech/dialog#dialogoverlay-dangerouslybypassfocuslock
|
| 41 | * @see https://github.com/theKashey/react-focus-lock
|
| 42 | * @see https://github.com/reach/reach-ui/issues/615
|
| 43 | */
|
| 44 | dangerouslyBypassFocusLock?: boolean;
|
| 45 | /**
|
| 46 | * By default the dialog locks scrolling with `react-remove-scroll`, which
|
| 47 | * also injects some styles on the body element to remove the scrollbar while
|
| 48 | * maintaining its gap to prevent jank when the dialog's open state is
|
| 49 | * toggled. This is almost always what you want in a dialog, but in some cases
|
| 50 | * you may have the need to customize this behavior further.
|
| 51 | *
|
| 52 | * This prop will disable `react-remove-scroll` and allow you to compose your
|
| 53 | * own scroll lock component to meet your needs. Like the
|
| 54 | * `dangerouslyBypassFocusLock` prop, this is generally discouraged and should
|
| 55 | * only be used if a proper fallback for managing scroll behavior is provided.
|
| 56 | *
|
| 57 | * @see Docs https://reach.tech/dialog#dialogoverlay-dangerouslybypassscrolllock
|
| 58 | * @see https://github.com/theKashey/react-remove-scroll
|
| 59 | */
|
| 60 | dangerouslyBypassScrollLock?: boolean;
|
| 61 | }
|
| 62 | /**
|
| 63 | * DialogContent
|
| 64 | *
|
| 65 | * Low-level component if you need more control over the styles or rendering of
|
| 66 | * the dialog content.
|
| 67 | *
|
| 68 | * Note: Must be a child of `DialogOverlay`.
|
| 69 | *
|
| 70 | * Note: You only need to use this when you are also styling `DialogOverlay`,
|
| 71 | * otherwise you can use the high-level `Dialog` component and pass the props
|
| 72 | * to it. Any props passed to `Dialog` component (besides `isOpen` and
|
| 73 | * `onDismiss`) will be spread onto `DialogContent`.
|
| 74 | *
|
| 75 | * @see Docs https://reach.tech/dialog#dialogcontent
|
| 76 | */
|
| 77 | declare const DialogContent: Polymorphic.ForwardRefComponent<"div", DialogContentProps>;
|
| 78 | /**
|
| 79 | * @see Docs https://reach.tech/dialog#dialogcontent-props
|
| 80 | */
|
| 81 | interface DialogContentProps {
|
| 82 | /**
|
| 83 | * Accepts any renderable content.
|
| 84 | *
|
| 85 | * @see Docs https://reach.tech/dialog#dialogcontent-children
|
| 86 | */
|
| 87 | children?: React.ReactNode;
|
| 88 | }
|
| 89 | /**
|
| 90 | * Dialog
|
| 91 | *
|
| 92 | * High-level component to render a modal dialog window over the top of the page
|
| 93 | * (or another dialog).
|
| 94 | *
|
| 95 | * @see Docs https://reach.tech/dialog#dialog
|
| 96 | */
|
| 97 | declare const Dialog: Polymorphic.ForwardRefComponent<"div", DialogProps>;
|
| 98 | /**
|
| 99 | * @see Docs https://reach.tech/dialog#dialog-props
|
| 100 | */
|
| 101 | interface DialogProps {
|
| 102 | /**
|
| 103 | * Handle zoom/pinch gestures on iOS devices when scroll locking is enabled.
|
| 104 | * Defaults to `false`.
|
| 105 | *
|
| 106 | * @see Docs https://reach.tech/dialog#dialog-allowpinchzoom
|
| 107 | */
|
| 108 | allowPinchZoom?: boolean;
|
| 109 | /**
|
| 110 | * Accepts any renderable content.
|
| 111 | *
|
| 112 | * @see Docs https://reach.tech/dialog#dialog-children
|
| 113 | */
|
| 114 | children?: React.ReactNode;
|
| 115 | /**
|
| 116 | * By default the first focusable element will receive focus when the dialog
|
| 117 | * opens but you can provide a ref to focus instead.
|
| 118 | *
|
| 119 | * @see Docs https://reach.tech/dialog#dialog-initialfocusref
|
| 120 | */
|
| 121 | initialFocusRef?: React.RefObject<any>;
|
| 122 | /**
|
| 123 | * Controls whether or not the dialog is open.
|
| 124 | *
|
| 125 | * @see Docs https://reach.tech/dialog#dialog-isopen
|
| 126 | */
|
| 127 | isOpen?: boolean;
|
| 128 | /**
|
| 129 | * This function is called whenever the user hits "Escape" or clicks outside
|
| 130 | * the dialog. _It's important to close the dialog `onDismiss`_.
|
| 131 | *
|
| 132 | * The only time you shouldn't close the dialog on dismiss is when the dialog
|
| 133 | * requires a choice and none of them are "cancel". For example, perhaps two
|
| 134 | * records need to be merged and the user needs to pick the surviving record.
|
| 135 | * Neither choice is less destructive than the other, so in these cases you
|
| 136 | * may want to alert the user they need to a make a choice on dismiss instead
|
| 137 | * of closing the dialog.
|
| 138 | *
|
| 139 | * @see Docs https://reach.tech/dialog#dialog-ondismiss
|
| 140 | */
|
| 141 | onDismiss?(event: React.MouseEvent | React.KeyboardEvent): void;
|
| 142 | /**
|
| 143 | * By default, React Focus Lock prevents focus from being moved outside of the
|
| 144 | * locked element even if the thing trying to take focus is in another frame.
|
| 145 | * Normally this is what you want, as an iframe is typically going to be a
|
| 146 | * part of your page content. But in some situations, like when using Code
|
| 147 | * Sandbox, you can't use any of the controls or the editor in the sandbox
|
| 148 | * while dialog is open because of the focus lock.
|
| 149 | *
|
| 150 | * This prop may have some negative side effects and unintended consequences,
|
| 151 | * and it opens questions about how we might distinguish frames that *should*
|
| 152 | * steal focus from those that shouldn't. Perhaps it's best for app devs to
|
| 153 | * decide, and if they use this prop we should advise them to imperatively
|
| 154 | * assign a -1 tabIndex to other iframes that are a part of the page content
|
| 155 | * when the dialog is open.
|
| 156 | *
|
| 157 | * https://github.com/reach/reach-ui/issues/536
|
| 158 | *
|
| 159 | * @deprecated
|
| 160 | */
|
| 161 | unstable_lockFocusAcrossFrames?: boolean;
|
| 162 | }
|
| 163 | export type { DialogContentProps, DialogOverlayProps, DialogProps };
|
| 164 | export { Dialog, DialogContent, DialogOverlay };
|
| 165 | export default Dialog;
|