T48i Docs · Overlays: drawing over the page, dialogs, popovers, toasts; the overlays example compiles

frontend/src/docs/guides.ts

@@ -6,7 +6,7 @@ import { Marked, type Tokens } from "marked";
 const at = (relative: string) => fileURLToPath(new URL(relative, import.meta.url));
 
 /** The guides in reading order, by file name. */
-const ORDER = ["introduction", "installation", "getting-started", "theme", "focus", "motion", "icons"];
+const ORDER = ["introduction", "installation", "getting-started", "theme", "focus", "motion", "icons", "overlays"];
 
 export interface Guide {
   /** The path segment; the introduction has none. */

frontend/src/docs/overlays.md

@@ -0,0 +1,45 @@
+# Overlays
+
+Dialogs, popovers, menus, tooltips and toasts draw over the page. Each takes focus while it is open and hands it back when it closes.
+
+## Drawing over the page
+
+`primitives::raise(id, child)` draws `child` over the page. At the top of the tree it draws after everything else. Inside something raised, it lays out on its own and draws last there, so a list opened in a dialog lies over the dialog. Ely's overlays raise themselves; an app calls `raise` only for an overlay of its own.
+
+## Dialogs
+
+`Dialog::new(id, title, on_close)` is a card over a scrim. Render it while it is open, and set the open flag false in `on_close`.
+
+| Call | Does |
+| --- | --- |
+| `.detail(text)` | A line under the title. |
+| `.child(..)` | The owner's content. |
+| `.action(\|close\| ..)` | A button in the row at the bottom, in the order given. `build` gets the dialog's close; a button that ends the dialog calls it. |
+| `.fullscreen()` | Fills the window below its title bar. |
+
+Escape, a press on the scrim and the close button all run `on_close`. Tab stays inside the dialog, and focus returns to what held it before, on every way out. The card fits the window; its body scrolls and its actions stay. `AlertDialog`, `ConfirmDialog` and `PromptDialog` build on `Dialog`.
+
+## Popovers
+
+`Popover::new(id, label, content)` is a button that opens a panel under it, or over it when only above has room. A press outside or Escape closes it, and Tab stays inside. `content` runs only while the panel is open. `Popover::with_opener` opens the panel from an element of the app's own.
+
+## Toasts
+
+A window keeps one `Toaster`, an entity, and renders one `ToastViewport::new(id, &toaster)`. Anything that holds the entity pushes to it.
+
+| Call | Does |
+| --- | --- |
+| `toaster.push(toast, cx)` | Shows the toast and returns its id. Past four toasts, the oldest leaves. |
+| `toaster.dismiss(id, cx)` | Sends a toast away early. |
+| `Toast::new(title)` | Stays 5 seconds. |
+| `.body(text)`, `.severity(Severity::Success)` | A line of detail; a color and icon for info, success, warning or danger. |
+| `.action(label, handler)` | A button that runs `handler`, then sends the toast away. |
+| `.undo(handler)` | An Undo button and a line that runs out with the time left. |
+| `.stay(None)` | Stays until closed. `Some(Duration::ZERO)` panics. |
+
+## A popover, a dialog and a toast
+
+The example opens a popover of details and a dialog that asks before it deletes. Its Delete button closes the dialog and pushes a toast.
+
+```rust example=overlays
+```