@videojs/react 10.0.0-beta.30 → 10.0.0-beta.32

package/docs/reference/alert-dialog.md

@@ -0,0 +1,649 @@
+# AlertDialog
+
+A modal alert dialog for urgent messages that require acknowledgement
+
+## Import
+
+tsx
+
+```
+import { AlertDialog } from '@videojs/react';
+```
+
+## Anatomy
+
+tsx
+
+```
+<AlertDialog.Root>
+  <AlertDialog.Backdrop />
+  <AlertDialog.Popup>
+    <AlertDialog.Title />
+    <AlertDialog.Description />
+    <AlertDialog.Close />
+  </AlertDialog.Popup>
+</AlertDialog.Root>
+```
+
+## Behavior
+
+Use an alert dialog for an urgent message that interrupts the user and requires acknowledgement. Your application controls when it opens and supplies its content. `AlertDialog.Root` adds alert semantics, while the other `AlertDialog` parts are re-exported from [`Dialog`](./dialog.md). For general modal content, including a player opened from a thumbnail, use `Dialog.Root` instead.
+
+Use `open` with `onOpenChange` for controlled state, or `defaultOpen` for uncontrolled state. `Root` provides state without rendering an element, while `Popup` renders only while the dialog is open.
+
+The close part and Escape close the dialog. The dialog stays rendered during a closing transition, then restores focus to the element that was focused before it opened.
+
+## Styling
+
+Use the open and transition data attributes to style visibility and animations:
+
+Attribute
+
+Description
+
+`data-open`
+
+Present while the dialog is open, including its closing transition
+
+`data-starting-style`
+
+Present at the start of the opening transition
+
+`data-ending-style`
+
+Present during the closing transition
+
+React renders separate backdrop and popup elements. Add a `className` to each part and style them independently:
+
+css
+
+```
+.alert-dialog-backdrop[data-starting-style],
+.alert-dialog-backdrop[data-ending-style],
+.alert-dialog-popup[data-starting-style],
+.alert-dialog-popup[data-ending-style] {
+  opacity: 0;
+}
+```
+
+## Accessibility
+
+The dialog uses `role="alertdialog"` and `aria-modal="true"`. The title and description receive generated IDs that are connected with `aria-labelledby` and `aria-describedby`. Focus moves into the dialog when it opens, stays within it while open, and returns to the previously focused element when it closes. Content outside the dialog is inert while it is open. Pressing Escape closes the dialog.
+
+## Examples
+
+### Basic usage
+
+Open alert dialog
+
+App.tsx
+
+App.css
+
+```
+import { AlertDialog } from '@videojs/react';
+import { useState } from 'react';
+
+export default function BasicUsage() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <div className="react-alert-dialog-basic">
+      <button className="react-alert-dialog-basic__trigger" type="button" onClick={() => setOpen(true)}>
+        Open alert dialog
+      </button>
+      <AlertDialog.Root open={open} onOpenChange={setOpen}>
+        <AlertDialog.Backdrop className="react-alert-dialog-basic__backdrop" />
+        <AlertDialog.Popup className="react-alert-dialog-basic__dialog">
+          <AlertDialog.Title className="react-alert-dialog-basic__title">Stop playback?</AlertDialog.Title>
+          <AlertDialog.Description className="react-alert-dialog-basic__description">
+            Your current playback position will be lost.
+          </AlertDialog.Description>
+          <AlertDialog.Close className="react-alert-dialog-basic__close">Continue</AlertDialog.Close>
+        </AlertDialog.Popup>
+      </AlertDialog.Root>
+    </div>
+  );
+}
+```
+```
+.react-alert-dialog-basic {
+  position: relative;
+  display: grid;
+  place-items: center;
+  min-height: 240px;
+  overflow: hidden;
+  background: #111827;
+  border-radius: 12px;
+}
+
+.react-alert-dialog-basic__trigger,
+.react-alert-dialog-basic__close {
+  padding: 8px 16px;
+  color: #111827;
+  cursor: pointer;
+  background: #fff;
+  border: 0;
+  border-radius: 9999px;
+}
+
+.react-alert-dialog-basic__backdrop {
+  position: absolute;
+  inset: 0;
+  background: rgb(3 7 18 / 92%);
+  transition: opacity 150ms ease;
+}
+
+.react-alert-dialog-basic__dialog {
+  position: absolute;
+  inset: 0;
+  z-index: 1;
+  display: grid;
+  gap: 12px;
+  place-content: center;
+  padding: 32px;
+  color: #fff;
+  text-align: center;
+  transition: opacity 150ms ease;
+}
+
+.react-alert-dialog-basic__backdrop[data-starting-style],
+.react-alert-dialog-basic__backdrop[data-ending-style],
+.react-alert-dialog-basic__dialog[data-starting-style],
+.react-alert-dialog-basic__dialog[data-ending-style] {
+  opacity: 0;
+}
+
+.react-alert-dialog-basic__title {
+  font-size: 20px;
+  font-weight: 600;
+}
+
+.react-alert-dialog-basic__description {
+  color: #d1d5db;
+}
+
+.react-alert-dialog-basic__close {
+  justify-self: center;
+}
+```
+
+## API Reference
+
+### 
+
+Root
+
+Manages alert dialog state and provides it to the shared dialog parts.
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`closeOnEscape`
+
+`boolean`
+
+`—`
+
+▸
+
+Description
+
+Whether pressing Escape closes the dialog.
+
+`defaultOpen`
+
+`boolean`
+
+`—`
+
+▸
+
+Description
+
+Initial open state for uncontrolled usage.
+
+`open`
+
+`boolean`
+
+`—`
+
+▸
+
+Description
+
+Controlled open state. When set, the consumer is responsible for toggling.
+
+#### State
+
+State is accessible via the `render`, `className`, and `style` props.
+
+Property
+
+Type
+
+Details
+
+`transitionStarting`
+
+`boolean`
+
+▸
+
+Description
+
+Whether the open transition is in progress.
+
+`transitionEnding`
+
+`boolean`
+
+▸
+
+Description
+
+Whether the close transition is in progress.
+
+`open`
+
+`boolean`
+
+▸
+
+Description
+
+Whether the dialog is currently open.
+
+`status`
+
+`'idle' | 'starting' | 'ending'`
+
+▸
+
+Description
+
+Current phase of the transition lifecycle.
+
+`titleId`
+
+`string | undefined`
+
+▸
+
+Description
+
+Element ID of the dialog title, used for `aria-labelledby`.
+
+`descriptionId`
+
+`string | undefined`
+
+▸
+
+Description
+
+Element ID of the dialog description, used for `aria-describedby`.
+
+### 
+
+Backdrop
+
+Presentational layer behind a dialog while it is rendered, including its exit transition.
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`className`
+
+`string | ((state: DialogCore.State) => string | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Class name or function returning class name from state.
+
+`render`
+
+`ReactElement | ((props: HTMLProps, state: DialogCore.State) => ReactElement | null)`
+
+`—`
+
+▸
+
+Description
+
+Render prop for custom element.
+
+`style`
+
+`CSSProperties | ((state: DialogCore.State) => CSSProperties | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Style or function returning style from state.
+
+#### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-open`
+
+▸
+
+Description
+
+Present when the dialog is open.
+
+`data-starting-style`
+
+▸
+
+Description
+
+Present during the open transition.
+
+`data-ending-style`
+
+▸
+
+Description
+
+Present during the close transition.
+
+### 
+
+Close
+
+Renders a button that closes the dialog.
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`className`
+
+`string | ((state: DialogCore.State) => string | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Class name or function returning class name from state.
+
+`render`
+
+`ReactElement | ((props: HTMLProps, state: DialogCore.State) => ReactElement | null)`
+
+`—`
+
+▸
+
+Description
+
+Render prop for custom element.
+
+`style`
+
+`CSSProperties | ((state: DialogCore.State) => CSSProperties | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Style or function returning style from state.
+
+#### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-open`
+
+▸
+
+Description
+
+Present when the dialog is open.
+
+`data-starting-style`
+
+▸
+
+Description
+
+Present during the open transition.
+
+`data-ending-style`
+
+▸
+
+Description
+
+Present during the close transition.
+
+### 
+
+Description
+
+Renders the description announced with the dialog.
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`className`
+
+`string | ((state: DialogCore.State) => string | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Class name or function returning class name from state.
+
+`render`
+
+`ReactElement | ((props: HTMLProps, state: DialogCore.State) => ReactElement | null)`
+
+`—`
+
+▸
+
+Description
+
+Render prop for custom element.
+
+`style`
+
+`CSSProperties | ((state: DialogCore.State) => CSSProperties | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Style or function returning style from state.
+
+### 
+
+Popup
+
+Renders the modal dialog while it is open.
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`className`
+
+`string | ((state: DialogCore.State) => string | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Class name or function returning class name from state.
+
+`render`
+
+`ReactElement | ((props: HTMLProps, state: DialogCore.State) => ReactElement | null)`
+
+`—`
+
+▸
+
+Description
+
+Render prop for custom element.
+
+`style`
+
+`CSSProperties | ((state: DialogCore.State) => CSSProperties | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Style or function returning style from state.
+
+#### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-open`
+
+▸
+
+Description
+
+Present when the dialog is open.
+
+`data-starting-style`
+
+▸
+
+Description
+
+Present during the open transition.
+
+`data-ending-style`
+
+▸
+
+Description
+
+Present during the close transition.
+
+### 
+
+Title
+
+Renders the heading that labels the dialog.
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`className`
+
+`string | ((state: DialogCore.State) => string | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Class name or function returning class name from state.
+
+`render`
+
+`ReactElement | ((props: HTMLProps, state: DialogCore.State) => ReactElement | null)`
+
+`—`
+
+▸
+
+Description
+
+Render prop for custom element.
+
+`style`
+
+`CSSProperties | ((state: DialogCore.State) => CSSProperties | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Style or function returning style from state.