diff --git a/change/@fluentui-react-components-bbc25942-e688-4a93-9fc5-b8aeb8947518.json b/change/@fluentui-react-components-bbc25942-e688-4a93-9fc5-b8aeb8947518.json
new file mode 100644
index 00000000000000..85d71b0379caa8
--- /dev/null
+++ b/change/@fluentui-react-components-bbc25942-e688-4a93-9fc5-b8aeb8947518.json
@@ -0,0 +1,7 @@
+{
+ "type": "none",
+ "comment": "Spec creation",
+ "packageName": "@fluentui/react-components",
+ "email": "bernardo.sunderhus@gmail.com",
+ "dependentChangeType": "none"
+}
diff --git a/packages/react-components/react-components/assets/alert-keyboard.png b/packages/react-components/react-components/assets/alert-keyboard.png
new file mode 100644
index 00000000000000..b3d5d783264bc0
Binary files /dev/null and b/packages/react-components/react-components/assets/alert-keyboard.png differ
diff --git a/packages/react-components/react-components/assets/alert-mouse-touch.png b/packages/react-components/react-components/assets/alert-mouse-touch.png
new file mode 100644
index 00000000000000..83768538b9b165
Binary files /dev/null and b/packages/react-components/react-components/assets/alert-mouse-touch.png differ
diff --git a/packages/react-components/react-components/assets/dialog-anatomy.png b/packages/react-components/react-components/assets/dialog-anatomy.png
new file mode 100644
index 00000000000000..d116d2d5cc8e18
Binary files /dev/null and b/packages/react-components/react-components/assets/dialog-anatomy.png differ
diff --git a/packages/react-components/react-components/assets/modal-keyboard.png b/packages/react-components/react-components/assets/modal-keyboard.png
new file mode 100644
index 00000000000000..3b6f2cc6684ad6
Binary files /dev/null and b/packages/react-components/react-components/assets/modal-keyboard.png differ
diff --git a/packages/react-components/react-components/assets/modal-mouse-touch.png b/packages/react-components/react-components/assets/modal-mouse-touch.png
new file mode 100644
index 00000000000000..038b28d45d95a1
Binary files /dev/null and b/packages/react-components/react-components/assets/modal-mouse-touch.png differ
diff --git a/packages/react-components/react-components/assets/non-modal-keyboard.png b/packages/react-components/react-components/assets/non-modal-keyboard.png
new file mode 100644
index 00000000000000..2fafc43c5fcf3a
Binary files /dev/null and b/packages/react-components/react-components/assets/non-modal-keyboard.png differ
diff --git a/packages/react-components/react-components/assets/non-modal-mouse-touch.png b/packages/react-components/react-components/assets/non-modal-mouse-touch.png
new file mode 100644
index 00000000000000..234638d2bc7604
Binary files /dev/null and b/packages/react-components/react-components/assets/non-modal-mouse-touch.png differ
diff --git a/packages/react-components/react-dialog/Spec.md b/packages/react-components/react-dialog/Spec.md
index 4f87703faa967b..3164c5dc923ea9 100644
--- a/packages/react-components/react-dialog/Spec.md
+++ b/packages/react-components/react-dialog/Spec.md
@@ -1,63 +1,524 @@
-# @fluentui/react-dialog Spec
+# Dialog
## Background
-_Description and use cases of this component_
+This spec defines the default function of a `Dialog` a window overlaid on either the primary window or another dialog window. Windows under a modal dialog are inert. That is, users cannot interact with content outside an active dialog window. Inert content outside an active dialog is typically visually obscured or dimmed so it is difficult to discern, and in some implementations, attempts to interact with the inert content cause the dialog to close.
+
+The interactions that result in the opening/closing of the `Dialog` component should be configurable.
## Prior Art
-_Include background research done for this component_
+- All mentions of v7 or v8 refer to Fabric - `@fluentui/react` ([docsite](https://developer.microsoft.com/en-us/fluentui#/))
+- All mentions of v0 refer to Northstar - `@fluentui/react-northstar` ([docsite](https://fluentsite.z22.web.core.windows.net/))
-- _Link to Open UI research_
-- _Link to comparison of v7 and v0_
-- _Link to GitHub epic issue for the converged component_
+- [Github epic](https://github.com/microsoft/fluentui/issues/20953)
+- [Open UI Research](https://open-ui.org/components/dialog.research)
+- Dialogs in 3rd party UI systems:
+ - [Carbon](https://react.carbondesignsystem.com/?path=/docs/components-modal--default)
+ - [Chakra UI](https://chakra-ui.com/docs/overlay/modal)
+ - [FAST](https://explore.fast.design/components/fast-dialog)
+ - [Material UI](https://mui.com/components/dialogs/)
+ - [Radix](https://www.radix-ui.com/docs/primitives/components/dialog)
+ - [Reach UI](https://reach.tech/dialog/)
+ - [Reakit](https://reakit.io/docs/dialog/)
+ - [Ariakit](https://github.com/reakit/reakit/tree/v2)
+ - [Spectrum](https://react-spectrum.adobe.com/react-spectrum/Dialog.html)
-## Sample Code
+### Comparison between v0 and v8
+
+Note that the below code samples are not meant to be complete, but to highlight differences between the two libraries. Please refer to official docsites for actual API references.
+
+#### v8
+
+In v8 there are Dialog and Modal components which are relevant to the Dialog component for v9. The Dialog component was intended to be used primarily for confirming actions, whereas Modal component was intended to be used for lengthy content that may contain forms and other controls. This spec will only cover the comparison to the Dialog component.
+
+The visibility of the dialog is controlled through the `hidden` prop whose its value should be a react state boolean provided from the consumer.
+
+[Documentation for v8 Dialog](https://developer.microsoft.com/en-us/fluentui#/controls/web/dialog)
+
+Sample code:
+
+```jsx
+
+
+
+
+```
-_Provide some representative example code that uses the proposed API for the component_
+#### v0
-## Variants
+In v0, the Dialog component expects all the content through props, including the content, actions etc. The dialog component uses the `trigger` prop that expects a React component to control its visibility. The element passed to this prop will be rendered in-place where the dialog is defined.
-_Describe visual or functional variants of this control, if applicable. For example, a slider could have a 2D variant._
+[Documentation for v0 Dialog](https://fluentsite.z22.web.core.windows.net/components/dialog/definition)
+
+```jsx
+}
+/>
+```
## API
-_List the **Props** and **Slots** proposed for the component. Ideally this would just be a link to the component's `.types.ts` file_
+The `Dialog` should implement a `children` based API as is one of the standards across all the surveyed alternatives as a part of Open UI research in [Prior Art](#prior-art). The component will leverage the use of `context` in the interaction and data flows of child compound components.
-## Structure
+Sample usages will be give in the following section of this document [Sample code](#sample-code)
-- _**Public**_
-- _**Internal**_
-- _**DOM** - how the component will be rendered as HTML elements_
+### Dialog
-## Migration
+The root level component serves as an interface for interaction with all possible behaviors exposed. It provides context down the hierarchy to `children` compound components to allow functionality. This component expects to receive as children either a `DialogContent` or a `DialogTrigger` and a `DialogContent` (or some component that will eventually render one of those compound components) in this specific order
+
+```tsx
+type DialogSlots = {
+ /**
+ * The dialog element itself
+ */
+ root: Slot<'div'>;
+ /**
+ * Dimmed background of dialog.
+ * The default overlay is rendered as a `
` with styling.
+ * This slot expects a `
` element which will replace the default overlay.
+ * The overlay should have `aria-hidden="true"`.
+ */
+ overlay?: Slot<'div'>;
+ /**
+ * The root element of the Dialog right after Portal.
+ */
+ root: Slot<'div'>;
+};
+
+type DialogProps = ComponentProps & {
+ /**
+ * Dialog variations.
+ *
+ * `modal`: When this type of dialog is open, the rest of the page is dimmed out and cannot be interacted with. The tab sequence is kept within the dialog and moving the focus outside the dialog will imply closing it. This is the default type of the component.
+ *
+ * `non-modal`: When a non-modal dialog is open, the rest of the page is not dimmed out and users can interact with the rest of the page. This also implies that the tab focus can move outside the dialog when it reaches the last focusable element.
+ *
+ * `alert`: is a special type of modal dialogs that interrupts the user's workflow to communicate an important message or ask for a decision. Unlike a typical modal dialog, the user must take an action through the options given to dismiss the dialog, and it cannot be dismissed through the dimmed background or escape key.
+ */
+ type?: 'modal' | 'non-modal' | 'alert';
+ /**
+ * Controls the open state of the dialog
+ * @default undefined
+ */
+ open?: boolean;
+ /**
+ * Default value for the uncontrolled open state of the dialog.
+ * @default false
+ */
+ defaultOpen?: boolean;
+ /**
+ * Callback fired when the component changes value from open state.
+ * @default undefined
+ */
+ onOpenChange?(event: MouseEvent | KeyboardEvent, data: DialogOpenChangeData): void;
+};
+
+type DialogOpenChangeData = {
+ /**
+ * The event source of the callback invocation
+ */
+ type: 'escapeKeyDown' | 'overlayClick' | 'triggerClick';
+ /**
+ * The next value for the internal state of the dialog
+ */
+ open: boolean;
+};
+```
+
+### DialogTrigger
+
+A non-visual component that wraps its child and configures them to be the trigger that will open or close a `Dialog`. This component should only accept one child.
+
+In case the trigger is used outside `Dialog` component it'll still provide basic [ARIA related attributes](#aria-roles-and-states) to it's wrapped child, but it won't be able to alter the dialog `open` state anymore, in that case the user must provide a [`controlled state`](#controlled-dialog)
+
+```typescript
+export type DialogTriggerProps = {
+ /**
+ * Explicitly declare if the trigger is responsible for opening,
+ * closing or toggling a Dialog visibility state.
+ * @default 'toggle'
+ */
+ type?: 'open' | 'close' | 'toggle';
+ /**
+ * Explicitly require single child or render function
+ * to inject properties
+ */
+ children: (React.ReactElement & { ref?: React.Ref }) | (() => React.ReactElement | null);
+};
+```
+
+### DialogContent
+
+The `DialogContent` component represents the visual part of a `Dialog` as a whole, it contains everything that should be visible.
+By itself it has no style, but it's responsible of showing/hiding content when `Dialog` visibility state changes, also it'll ensure a `Portal` is properly created for the content being provided as well as for the `overlay` element provided by `Dialog`
+
+```tsx
+type DialogTitleSlots = {
+ /**
+ * By default this is a div.
+ */
+ root: Slot<'div', 'main'>;
+};
+
+type DialogTitleProps = ComponentProps;
+```
+
+### DialogTitle
+
+The DialogTitle component will expect to have a dialog title/header and will show the close (X icon) button if specified so. Apart from styling and presenting `closeButton`, this component does not have other behavior.
+
+```tsx
+type DialogTitleSlots = {
+ /**
+ * By default this is a div, but can be a heading.
+ */
+ root: Slot<'div', 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'>;
+ closeButton?: Slot<'button'>;
+};
+
+type DialogTitleProps = ComponentProps;
+```
+
+### DialogBody
+
+The `DialogBody` is a container where the content of the dialog is rendered. Apart from styling, this component does not have other behavior.
+
+```tsx
+type DialogBodySlots = {
+ root: Slot<'div'>;
+};
+
+type DialogBodyProps = ComponentProps;
+```
+
+### DialogActions
+
+`DialogActions` is a container for the actions of the dialog. Apart from styling, this component does not have other behavior.
+
+```tsx
+type DialogActionsSlots = {
+ root: Slot<'div'>;
+};
+
+type DialogActionsProps = ComponentProps;
+```
+
+## Sample Code
+
+The below samples do not represent the definitive props of the final implemented component, but represent the ideal final implementations. Can be subject to change during the implementation phase.
+
+### Basic Dialog
+
+```tsx
+const dialog =
+```
-_Describe what will need to be done to upgrade from the existing implementations:_
+```html
+
+
+
+
+
This is as basic as it gets
+```
-- _Migration from v8_
-- _Migration from v0_
+### Alert Dialog
+
+An alert dialog is a modal dialog that interrupts the user's workflow to communicate an important message and acquire a response. Examples include action confirmation prompts and error message confirmations. The alertdialog role enables assistive technologies and browsers to distinguish alert dialogs from other dialogs so they have the option of giving alert dialogs special treatment, such as playing a system alert sound.
+
+```tsx
+const dialog =
+```
+
+```html
+
+
+
+
+
+ Title
+
+
+
This is going to be inside the dialog
+
+
+
+
+
+
+```
+
+### Controlled Dialog
+
+```tsx
+const CustomDialog = () => {
+ const [isOpen, setIsOpen] = React.useState(false);
+ const handleOpenChange = (ev, { open }) => setIsOpen(open);
+ const handleOpen = () => setIsOpen(true);
+ return (
+ <>
+ {/*
+ the trigger component is still useful outside of the Dialog,
+ to provide ARIA attributes, but it will no longer speak with the dialog.
+ A controlled state is required in this case
+ */}
+
+
+
+
+
+ );
+};
+```
+
+```html
+
+
+
+
+
+ Title
+
+
+
This is going to be inside the dialog
+
+
+
+
+
+
+```
+
+### Async Input submission dialog
+
+```tsx
+function AsyncConfirmDialog() {
+ const [input, setInput] = useState('');
+ const [state, sendInput] = useSendInput();
+ const [isOpen, setIsOpen] = useState(false);
+ const handleInputChange = ev => {
+ setInput(ev.target.value.trim());
+ };
+ const handleOpenChange = (ev, { open }) => {
+ setIsOpen(open);
+ setInput(''); // clean up on cancel/close
+ };
+ const handleSubmit = async ev => {
+ ev.preventDefault();
+ await sendInput(input); // sending data on confirm
+ setIsOpen(false);
+ };
+ return (
+ <>
+
+
+ );
+}
+```
+
+## Migration
+
+_TBA: Link to migration guide doc_
## Behaviors
-_Explain how the component will behave in use, including:_
+Dialog will use **Tabster** to handle the keyboard navigation and ensure focus trapping.
+
+The below references were used to decide appropriate keyboard interaction from an a11y perspective.
+
+- https://www.w3.org/WAI/ARIA/apg/patterns/dialogmodal/
+- https://www.w3.org/WAI/ARIA/apg/example-index/dialog-modal/dialog.html
+- https://www.w3.org/WAI/ARIA/apg/example-index/dialog-modal/alertdialog.html
+
+### Modal
+
+#### Mouse & Touch
+
+
+
+1. Clicking on the trigger (element / button component) a Dialog is displayed with a dimmed background.
+2. Clicking on the dimmed background dismisses the dialog.
+3. The dialog can be dismissed also when confirmation button is clicked (footer).
+
+#### Keyboard
+
+
+
+1. **(1)** TabKey to set focus on Trigger, use EnterKey to open.
+2. **(2-6)** Focus is moved to the first focusable control inside the dialog.
+3. **(5-6)** After the dialog is dismissed, keyboard focus should be moved back to where it was before it moved into the dialog. Otherwise the focus can be dropped to the beginning of the page. Or if the item is no longer available it can be moved to the next logical location in that region i.e. next / previous item.
+4. **TabKey** Moves focus to next focusable element inside the dialog. When focus is on the last focusable element in the dialog, moves focus to the next focusable action in the browser window.
+5. **Shift+Tab** Moves focus to previous focusable element inside the dialog. When focus is on the first focusable element in the dialog, moves focus to the last focusable action within the browser window.
+6. **EscKey** Closes the dialog, returning focus to the trigger, in case the trigger is gone or not possible to focus, the use might require to setup focus manually.
+
+### Non-Modal
-- _Component States_
-- _Interaction_
- - _Keyboard_
- - _Cursor_
- - _Touch_
- - _Screen readers_
+#### Mouse & touch
+
+
+
+1. Clicking on the trigger (element / button component) a Dialog is displayed without a dimmed background.
+2. A user can continue to interact with elements on the page behind the dialog.
+3. Clicking the dismiss button (X icon in header), or cancel/dismiss buttons (footer) will close the dialog.
+
+#### Keyboard
+
+
+
+1. **(1)** **TabKey** to set focus on Trigger, use **EnterKey** to open.
+2. - **(2a)** Focus is moved to the default focusable control inside the dialog.
+ - **(2b)** **EnterKey** on dismiss action to close dialog,
+3. After the dialog is dismissed, keyboard focus should be moved back to where it was before it moved into the dialog. Otherwise the focus can be dropped to the beginning of the page.
+4. **TabKey** Moves focus to next focusable element inside the dialog, once you get to the end of the focusable items within the dialog focus moves to next actionable item outside of the dialog container.
+5. **Shift+Tab** Moves focus to previous focusable element inside the dialog and back to the trigger control.
+6. **EscKey** Closes the dialog when the focus is on the dialog.
+
+### Alert dialog
+
+#### Mouse & Touch
+
+
+
+1. Clicking on the trigger (element / button component) a Dialog is displayed with a dimmed background.
+2. Windows under the dialog are are inert, their scrolling is blocked and clicking on the dimmed background will not close the dialog.
+3. Clicking the dismiss button (X icon in header), or cancel/dismiss buttons (footer) will dismiss the dialog.
+
+#### Keyboard
+
+
+
+1. **(1)** **TabKey** to set focus on Trigger, use **EnterKey** to open.
+2. **(2 & 3)** Focus is automatically set to the first focusable element inside the dialog
+3. **EnterKey** Confirms or cancels the alert message and dialog is dismissed.
+4. **TabKey** Moves focus to next focusable element inside the dialog. When focus is on the last focusable element in the dialog, moves focus to the next focusable action in the browser window.
+5. **Shift+Tab** Moves focus to previous focusable element inside the dialog. When focus is on the first focusable element in the dialog, moves focus to the last focusable action within the browser window.
## Accessibility
-Base accessibility information is included in the design document. After the spec is filled and review, outcomes from it need to be communicated to design and incorporated in the design document.
-
-- Decide whether to use **native element** or folow **ARIA** and provide reasons
-- Identify the **[ARIA](https://www.w3.org/TR/wai-aria-practices-1.2/) pattern** and, if the component is listed there, follow its specification as possible.
-- Identify accessibility **variants**, the `role` ([ARIA roles](https://www.w3.org/TR/wai-aria-1.1/#role_definitions)) of the component, its `slots` and `aria-*` props.
-- Describe the **keyboard navigation**: Tab Oder and Arrow Key Navigation. Describe any other keyboard **shortcuts** used
-- Specify texts for **state change announcements** - [ARIA live regions
- ](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) (number of available items in dropdown, error messages, confirmations, ...)
-- Identify UI parts that appear on **hover or focus** and specify keyboard and screen reader interaction with them
-- List cases when **focus** needs to be **trapped** in sections of the UI (for dialogs and popups or for hierarchical navigation)
-- List cases when **focus** needs to be **moved programatically** (if parts of the UI are appearing/disappearing or other cases)
+> ⚠️ _Note: All other accessibility information, not covered in this section, is provided throughout the spec._
+
+The dialog component follows the [Dialog WAI-Aria design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialogmodal/).
+
+### Aria roles and states
+
+#### Modal
+
+- Trigger button
+ - [`aria-haspopup="dialog"`](https://w3c.github.io/aria/#aria-haspopup)
+- Dialog
+ - [`role="dialog"`](https://w3c.github.io/aria/#dialog)
+ - [`aria-modal=true`](https://w3c.github.io/aria/#aria-modal)
+ - [`aria-labelledby={dialog-title-idref}`](https://w3c.github.io/aria/#aria-labelledby)
+ - [`aria-describedby={dialog-body-idref}`](https://w3c.github.io/aria/#aria-describedby)
+ - [`aria-label="some label"`](https://w3c.github.io/aria/#aria-label)
+
+#### Non-modal
+
+- Trigger button
+ - [`aria-haspopup="dialog"`](https://w3c.github.io/aria/#aria-haspopup)
+- Dialog
+ - [`role="dialog"`](https://w3c.github.io/aria/#dialog)
+ - [`aria-modal=false`](https://w3c.github.io/aria/#aria-modal)
+ - [`aria-labelledby={dialog-title-idref}`](https://w3c.github.io/aria/#aria-labelledby)
+ - [`aria-describedby={dialog-body-idref}`](https://w3c.github.io/aria/#aria-describedby)
+ - [`aria-label="some label"`](https://w3c.github.io/aria/#aria-label)
+
+#### Alert dialog
+
+- Trigger button
+ - [`aria-haspopup="dialog"`](https://w3c.github.io/aria/#aria-haspopup)
+ > ⚠️ This is deprecated, the proper attribute should be [`aria-expanded=true`](https://w3c.github.io/aria/#aria-expanded)
+- Dialog
+ - [`role="alertdialog"`](https://w3c.github.io/aria/#dialog)
+ - [`aria-modal=false`](https://w3c.github.io/aria/#aria-modal)
+ - [`aria-labelledby={dialog-title-idref}`](https://w3c.github.io/aria/#aria-labelledby)
+ - [`aria-describedby={dialog-body-idref}`](https://w3c.github.io/aria/#aria-describedby)
+ - [`aria-label="some label"`](https://w3c.github.io/aria/#aria-label)
diff --git a/packages/react-components/react-dialog/assets/AlertDialogKeyboardInteraction.png b/packages/react-components/react-dialog/assets/AlertDialogKeyboardInteraction.png
new file mode 100644
index 00000000000000..8359c2cab37798
Binary files /dev/null and b/packages/react-components/react-dialog/assets/AlertDialogKeyboardInteraction.png differ
diff --git a/packages/react-components/react-dialog/assets/AlertDialogMouseInteraction.png b/packages/react-components/react-dialog/assets/AlertDialogMouseInteraction.png
new file mode 100644
index 00000000000000..0d365326efd4bb
Binary files /dev/null and b/packages/react-components/react-dialog/assets/AlertDialogMouseInteraction.png differ
diff --git a/packages/react-components/react-dialog/assets/ModalDialogKeyboardInteraction.png b/packages/react-components/react-dialog/assets/ModalDialogKeyboardInteraction.png
new file mode 100644
index 00000000000000..496e716f114b09
Binary files /dev/null and b/packages/react-components/react-dialog/assets/ModalDialogKeyboardInteraction.png differ
diff --git a/packages/react-components/react-dialog/assets/ModalDialogMouseInteraction.png b/packages/react-components/react-dialog/assets/ModalDialogMouseInteraction.png
new file mode 100644
index 00000000000000..94d5b2d5d19cc5
Binary files /dev/null and b/packages/react-components/react-dialog/assets/ModalDialogMouseInteraction.png differ
diff --git a/packages/react-components/react-dialog/assets/NonModalDialogKeyboardInteraction.png b/packages/react-components/react-dialog/assets/NonModalDialogKeyboardInteraction.png
new file mode 100644
index 00000000000000..24c8e14cc3b64e
Binary files /dev/null and b/packages/react-components/react-dialog/assets/NonModalDialogKeyboardInteraction.png differ
diff --git a/packages/react-components/react-dialog/assets/NonModalDialogMouseInteraction.png b/packages/react-components/react-dialog/assets/NonModalDialogMouseInteraction.png
new file mode 100644
index 00000000000000..ff0c1483a96e57
Binary files /dev/null and b/packages/react-components/react-dialog/assets/NonModalDialogMouseInteraction.png differ