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

Cargo.toml

@@ -111,3 +111,7 @@ path = "examples/docs/motion.rs"
 [[example]]
 name = "docs_icons"
 path = "examples/docs/icons.rs"
+
+[[example]]
+name = "docs_overlays"
+path = "examples/docs/overlays.rs"

examples/docs/overlays.rs

@@ -0,0 +1,96 @@
+use ely_gpui_component::{
+    Assets,
+    buttons::Button,
+    feedback::{Toast, ToastViewport, Toaster},
+    overlays::{Dialog, Popover},
+    primitives::{FocusScope, Severity},
+    theme::ActiveTheme,
+};
+use gpui::{
+    App, AppContext, Context, Entity, FocusHandle, IntoElement, ParentElement, Render, Styled,
+    Window, WindowOptions, div,
+};
+
+struct Layers {
+    focus: FocusHandle,
+    toaster: Entity<Toaster>,
+    open: bool,
+}
+
+impl Render for Layers {
+    fn render(&mut self, _: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
+        let theme = cx.theme();
+        let (opener, closer) = (cx.entity(), cx.entity());
+        let toaster = self.toaster.clone();
+        let dialog = self.open.then(|| {
+            Dialog::new("delete", "Delete notes.txt?", move |_, cx| {
+                closer.update(cx, |layers, cx| {
+                    layers.open = false;
+                    cx.notify();
+                })
+            })
+            .detail("It leaves the trash after 30 days.")
+            .action(|close| {
+                Button::new("cancel", "Cancel").on_click(move |_, window, cx| close(window, cx))
+            })
+            .action(move |close| {
+                Button::new("confirm", "Delete")
+                    .primary()
+                    .on_click(move |_, window, cx| {
+                        close(window, cx);
+                        toaster.update(cx, |toaster, cx| {
+                            toaster.push(Toast::new("Deleted").severity(Severity::Success), cx);
+                        });
+                    })
+            })
+        });
+        FocusScope::new(&self.focus)
+            .root()
+            .size_full()
+            .flex()
+            .flex_col()
+            .gap_4()
+            .p_8()
+            .bg(theme.colors.bg)
+            .text_color(theme.colors.fg)
+            .child(
+                div()
+                    .flex()
+                    .gap_2()
+                    .child(Popover::new("details", "Details", |_, _| {
+                        div().p_3().child("Size 4 KB · Edited today")
+                    }))
+                    .child(
+                        Button::new("delete-open", "Delete…").on_click(move |_, _, cx| {
+                            opener.update(cx, |layers, cx| {
+                                layers.open = true;
+                                cx.notify();
+                            })
+                        }),
+                    ),
+            )
+            .children(dialog)
+            .child(ToastViewport::new("toasts", &self.toaster))
+    }
+}
+
+fn main() {
+    gpui_platform::application()
+        .with_assets(Assets)
+        .run(|cx: &mut App| {
+            ely_gpui_component::init(cx);
+            cx.open_window(WindowOptions::default(), |window, cx| {
+                cx.new(|cx| {
+                    let focus = cx.focus_handle();
+                    window.focus(&focus, cx);
+                    Layers {
+                        focus,
+                        toaster: cx.new(|_| Toaster::default()),
+                        open: false,
+                    }
+                })
+            })
+            .expect("window failed to open");
+            cx.activate(true);
+        });
+}

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
+```