From 8c3b6840a34452160baa1dc987ebdaf163f27d9a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=9B=B7=E7=94=B5=E8=8A=BD=E8=A1=A3?= Date: Thu, 1 Oct 2026 13:07:03 -0400 Subject: [PATCH] =?UTF-8?q?T48i=20Docs=20=C2=B7=20Overlays:=20drawing=20ov?= =?UTF-8?q?er=20the=20page,=20dialogs,=20popovers,=20toasts;=20the=20overl?= =?UTF-8?q?ays=20example=20compiles?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Cargo.toml | 4 ++ examples/docs/overlays.rs | 96 +++++++++++++++++++++++++++++++++++ frontend/src/docs/guides.ts | 2 +- frontend/src/docs/overlays.md | 45 ++++++++++++++++ 4 files changed, 146 insertions(+), 1 deletion(-) create mode 100644 examples/docs/overlays.rs create mode 100644 frontend/src/docs/overlays.md diff --git a/Cargo.toml b/Cargo.toml index 5423cbb..bb2ba4a 100644 --- a/Cargo.toml +++ b/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" diff --git a/examples/docs/overlays.rs b/examples/docs/overlays.rs new file mode 100644 index 0000000..9ca4b64 --- /dev/null +++ b/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, + open: bool, +} + +impl Render for Layers { + fn render(&mut self, _: &mut Window, cx: &mut Context) -> 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); + }); +} diff --git a/frontend/src/docs/guides.ts b/frontend/src/docs/guides.ts index 3cff0f8..1150337 100644 --- a/frontend/src/docs/guides.ts +++ b/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. */ diff --git a/frontend/src/docs/overlays.md b/frontend/src/docs/overlays.md new file mode 100644 index 0000000..505547a --- /dev/null +++ b/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 +```