zeyn 0.0.3

use crate::action::{Access, ActionMeta, Cursor, DataQuery, Result};
use crate::ctx::{BoxFuture, Ctx, Dep};
use crate::i18n::Text;
use crate::render::{Render, attr, slug};
use serde::Serialize;
use serde::de::DeserializeOwned;
use serde_json::json;
use std::any::Any;
use std::collections::HashMap;

/// Screen params. Implemented by `#[params]`; screens without params use `()`.
#[diagnostic::on_unimplemented(
    message = "`{Self}` is not a screen params type",
    label = "the first argument of a screen is its params",
    note = "mark the type with `#[params]`, or use `_: ()` as the first argument when the screen has no params"
)]
pub trait Params: Serialize + DeserializeOwned + Clone + Send + Sync + 'static {}

impl Params for () {}

/// Screen definition generated by `#[screen]`.
#[derive(Clone, Copy, Debug, Serialize)]
pub struct ScreenMeta {
    pub name: &'static str,
    pub route: Option<&'static str>,
    pub access: Access,
    /// Opening the screen is audited as a read, with its params.
    pub sensitive: bool,
    /// The user must give a reason before the screen's data is shown. Implies `sensitive`.
    pub reason: bool,
    /// First paragraph of the screen's `///` doc comment, added to its AI tool descriptions.
    pub doc: &'static str,
    /// AI policy from `ai = "..."` or `ai = false`. A hidden screen offers no tools and models
    /// cannot navigate to it.
    pub ai: crate::action::Ai,
}

/// A screen. Implemented by `#[screen]`, never written by hand.
pub trait ScreenDef: Copy + Send + Sync + 'static {
    type Params: Params;
    const META: ScreenMeta;

    /// Services the screen needs; checked when the app starts.
    fn deps() -> Vec<Dep>;

    /// Builds the screen with injected arguments. Access is checked by the caller.
    fn build(ctx: Ctx, params: Self::Params) -> BoxFuture<Result<Screen>>;
}

/// What the client does after a user interaction.
#[derive(Clone, Debug, PartialEq, Serialize)]
#[serde(tag = "effect", rename_all = "snake_case")]
pub enum Effect {
    OpenWindow {
        screen: &'static str,
        params: serde_json::Value,
    },
    Navigate {
        screen: &'static str,
        params: serde_json::Value,
    },
    Toast {
        message: Text,
    },
    CloseAndRefresh,
    /// Asks the user to confirm `message`, then runs `then`. Built with [`Effect::confirm`].
    Confirm {
        message: Text,
        then: Box<Effect>,
    },
    /// A toast with a tone and an optional action button. Built with [`Toast`] and
    /// [`UiCtx::notify`]. Danger toasts are announced at once (assertive), the others politely.
    Notice {
        message: Text,
        tone: crate::grid::Tone,
        action: Option<(Text, Box<Effect>)>,
    },
    /// Goes to a local path of the app. With `frame` the whole app frame (menu, title, session
    /// settings) is loaded again, as after signing in or out; still without a page load.
    Go {
        url: String,
        frame: bool,
    },
}

impl Effect {
    /// Goes to a local path of the app (see [`Effect::Go`]). Anything that is not a local path
    /// goes to the start page, so a `return_to` from a request can never leave the app.
    ///
    /// ```
    /// use zeyn::Effect;
    /// assert_eq!(Effect::go("/orders?x=1", false), Effect::Go { url: "/orders?x=1".into(), frame: false });
    /// assert_eq!(Effect::go("//evil.example", true), Effect::Go { url: "/".into(), frame: true });
    /// ```
    pub fn go(url: &str, frame: bool) -> Effect {
        let local = url.starts_with('/')
            && !url.starts_with("//")
            && !url.contains('\\')
            && !url.chars().any(char::is_control)
            && url.len() <= 2048;
        Effect::Go { url: if local { url.to_string() } else { "/".into() }, frame }
    }

    /// Runs `then` only after the user confirms `message` in a dialog.
    ///
    /// ```
    /// use zeyn::Effect;
    /// let e = Effect::confirm("Close without saving?", Effect::CloseAndRefresh);
    /// assert!(matches!(e, Effect::Confirm { .. }));
    /// ```
    pub fn confirm(message: impl Into<Text>, then: Effect) -> Effect {
        Effect::Confirm { message: message.into(), then: Box::new(then) }
    }

    /// Goes to a screen in place, like a link. Params of the wrong type do not compile.
    pub fn navigate<S: ScreenDef>(_screen: S, params: S::Params) -> Effect {
        Effect::Navigate { screen: S::META.name, params: params_json(&params) }
    }

    /// JSON sent to the client, with texts resolved in the user's language.
    pub fn to_json(&self, r: &Render) -> serde_json::Value {
        match self {
            Effect::Toast { message } => {
                json!({ "effect": "toast", "message": r.i18n.text(r.locale, message) })
            }
            Effect::Notice { message, tone, action } => {
                let mut j = json!({ "effect": "toast", "message": r.i18n.text(r.locale, message), "tone": tone });
                if let Some((label, then)) = action {
                    j["action"] = json!({ "label": r.i18n.text(r.locale, label), "effect": then.to_json(r) });
                }
                j
            }
            Effect::Confirm { message, then } => json!({
                "effect": "confirm",
                "message": r.i18n.text(r.locale, message),
                "title": r.i18n.text(r.locale, &Text::key("zeyn.ui.confirm.title")),
                "ok": r.i18n.text(r.locale, &Text::key("zeyn.ui.confirm.ok")),
                "cancel": r.i18n.text(r.locale, &Text::key("zeyn.ui.confirm.cancel")),
                "then": then.to_json(r),
            }),
            other => serde_json::to_value(other).unwrap_or(serde_json::Value::Null),
        }
    }
}

/// Serializes params. Cannot fail for types marked with `#[params]`.
fn params_json<P: Params>(params: &P) -> serde_json::Value {
    serde_json::to_value(params).expect("screen params must serialize to JSON")
}

/// Most toasts the runtime shows at once; older ones make room for new ones.
pub const MAX_TOASTS: usize = 3;

/// A toast with a tone and an optional action button, for [`UiCtx::notify`].
///
/// ```
/// use zeyn::{Effect, Toast};
/// let e: Effect = Toast::success("Order saved").action("Undo", Effect::CloseAndRefresh).into();
/// assert!(matches!(e, Effect::Notice { .. }));
/// ```
#[derive(Clone, Debug, PartialEq)]
pub struct Toast {
    message: Text,
    tone: crate::grid::Tone,
    action: Option<(Text, Box<Effect>)>,
}

impl Toast {
    fn of(tone: crate::grid::Tone, message: impl Into<Text>) -> Self {
        Toast { message: message.into(), tone, action: None }
    }

    pub fn info(message: impl Into<Text>) -> Self {
        Self::of(crate::grid::Tone::Info, message)
    }

    pub fn success(message: impl Into<Text>) -> Self {
        Self::of(crate::grid::Tone::Success, message)
    }

    pub fn warning(message: impl Into<Text>) -> Self {
        Self::of(crate::grid::Tone::Warning, message)
    }

    /// An error or a loss the user must notice: announced at once and shown twice as long.
    pub fn danger(message: impl Into<Text>) -> Self {
        Self::of(crate::grid::Tone::Danger, message)
    }

    /// A button on the toast that runs `effect`, such as undo or opening the saved record. The
    /// toast stays while it is hovered or holds focus, so the button can be reached.
    pub fn action(mut self, label: impl Into<Text>, effect: Effect) -> Self {
        self.action = Some((label.into(), Box::new(effect)));
        self
    }
}

impl From<Toast> for Effect {
    fn from(t: Toast) -> Self {
        Effect::Notice { message: t.message, tone: t.tone, action: t.action }
    }
}

/// Window helpers.
pub struct Window;

impl Window {
    /// Effect that opens a screen as a window. Params of the wrong type do not compile.
    pub fn open<S: ScreenDef>(_screen: S, params: S::Params) -> Effect {
        Effect::OpenWindow { screen: S::META.name, params: params_json(&params) }
    }
}

/// Context given to event handlers. Collects the effects they ask for.
#[derive(Debug, Default)]
pub struct UiCtx {
    effects: Vec<Effect>,
}

impl UiCtx {
    pub fn toast(&mut self, message: impl Into<Text>) {
        self.effects.push(Effect::Toast { message: message.into() });
    }

    /// A toast with a tone and maybe an action button: `ui.notify(Toast::success(t!("saved")))`.
    pub fn notify(&mut self, toast: Toast) {
        self.effects.push(toast.into());
    }

    /// Closes the window and refreshes the screen that opened it.
    pub fn close_and_refresh(&mut self) {
        self.effects.push(Effect::CloseAndRefresh);
    }

    pub fn navigate<S: ScreenDef>(&mut self, _screen: S, params: S::Params) {
        self.effects.push(Effect::Navigate { screen: S::META.name, params: params_json(&params) });
    }

    /// Any effect, such as `Effect::confirm(...)`.
    pub fn effect(&mut self, effect: Effect) {
        self.effects.push(effect);
    }

    pub fn into_effects(self) -> Vec<Effect> {
        self.effects
    }
}

/// One loaded page of grid rows, type erased.
pub struct LoadedPage {
    pub items: Box<dyn Any + Send + Sync>,
    pub count: usize,
    pub total: Option<u64>,
    pub next: Option<Cursor>,
    pub offset: u64,
    /// Column totals over the whole filtered result.
    pub totals: Vec<crate::action::Total>,
    /// Column layout the rows are rendered in; `None` is the grid's own layout.
    pub view: Option<crate::grid::DataGridView>,
    /// Whether the user's view changes are saved on the server.
    pub saved_views: bool,
    /// How deep these rows sit in a grouped or tree grid; 0 at the top.
    pub depth: usize,
    /// Group values or ancestor keys leading to these rows, in the fixed machine form.
    pub path: Vec<Option<String>>,
    /// Groups instead of rows, when the grid groups at this depth.
    pub groups: Option<Vec<crate::action::Group>>,
    /// Keys of the rows that have children, in a tree grid.
    pub parents: Vec<String>,
}

/// An action call built on the server for one row or menu item, ready to run.
pub struct RowCall {
    pub meta: ActionMeta,
    pub run: Box<dyn FnOnce(Ctx) -> BoxFuture<Result<()>> + Send>,
}

/// A component that loads rows through an action. Implemented by `DataGrid`.
pub trait GridSource: Send + Sync {
    fn action(&self) -> ActionMeta;

    /// Query for the first page, as the grid's paging asks for it, with the sort and filters of
    /// a saved view.
    fn first_query(&self, view: Option<&crate::grid::DataGridView>) -> DataQuery;

    /// Cleans a view sent by a client so only the grid's own columns, sort keys and filters remain.
    fn clean_view(&self, view: crate::grid::DataGridView) -> crate::grid::DataGridView;

    /// Header row for a view.
    fn head_html(&self, r: &Render, view: Option<&crate::grid::DataGridView>) -> String;

    fn fetch(&self, ctx: Ctx, query: DataQuery) -> BoxFuture<Result<LoadedPage>>;

    /// Loads rows as the user sees them: in a grouped or tree grid, the groups or rows under
    /// `path` (group values or ancestor keys from the client, checked here). Flat grids ignore
    /// `path`. Exports and bulk actions use [`GridSource::fetch`], which never groups.
    fn fetch_at(&self, ctx: Ctx, query: DataQuery, path: Vec<Option<String>>) -> BoxFuture<Result<LoadedPage>> {
        let _ = path;
        self.fetch(ctx, query)
    }

    /// Rows of a loaded page as HTML.
    fn rows_html(&self, page: &LoadedPage, r: &Render) -> String;

    /// Footer row with the totals of a loaded page, or `None` when the grid has no totals or the
    /// page carries none (the client keeps the footer it has).
    fn foot_html(&self, page: &LoadedPage, r: &Render) -> Option<String>;

    /// Renders the grid with its first page already in place.
    fn render_loaded(&self, out: &mut String, r: &Render, page: &LoadedPage);

    /// JSON Schema of the query, for agent tools.
    fn tool_schema(&self) -> serde_json::Value;

    /// Loads the row with this key through the grid's own action. The result holds at most the
    /// rows the action returned for a key filter; [`GridSource::row_call`] picks the matching one.
    fn find_row(&self, ctx: Ctx, key: String) -> BoxFuture<Result<LoadedPage>> {
        let _ = (ctx, key);
        Box::pin(async { Err(crate::action::Error::NotFound) })
    }

    /// Call of bulk action `index` with these keys; `None` when there is no such action or a key
    /// does not read as the key type.
    fn bulk_call(&self, index: usize, keys: Vec<serde_json::Value>) -> Option<RowCall> {
        let _ = (index, keys);
        None
    }

    /// Access rule of bulk action `index`.
    fn bulk_meta(&self, index: usize) -> Option<ActionMeta> {
        let _ = index;
        None
    }

    /// A row key from the client as JSON of the key's type; `None` when it cannot be read.
    fn key_json(&self, key: &str) -> Option<serde_json::Value> {
        let _ = key;
        None
    }

    /// Keys of the rows of a loaded page, in order.
    fn page_keys(&self, page: &LoadedPage) -> Vec<serde_json::Value> {
        let _ = page;
        Vec::new()
    }

    /// Builds the save of an inline edit of the row with this key from the loaded page: only
    /// editable columns and the row version may be in `values`, otherwise `Forbidden`; values are
    /// read and validated as a form would (`Validation` errors name the fields).
    fn edit_call(
        &self,
        page: &LoadedPage,
        key: &str,
        values: &serde_json::Map<String, serde_json::Value>,
        locale: &str,
        tz: crate::time::TimeZone,
    ) -> Result<RowCall> {
        let _ = (page, key, values, locale, tz);
        Err(crate::action::Error::NotFound)
    }

    /// The row with this key from a loaded page as HTML, in the page's view.
    fn row_html(&self, page: &LoadedPage, key: &str, r: &Render) -> Option<String> {
        let _ = (page, key, r);
        None
    }

    /// Who may export the whole filtered result; `None` when the grid offers no export.
    fn export_access(&self) -> Option<crate::action::Access> {
        None
    }

    /// Most rows one export may hold.
    fn export_limit(&self) -> usize {
        0
    }

    /// Header line of a CSV export in a view, with the user's labels.
    fn csv_head(&self, r: &Render, view: Option<&crate::grid::DataGridView>) -> String {
        let _ = (r, view);
        String::new()
    }

    /// CSV lines of a loaded page in its view: values as the user reads them, in the user's
    /// language, with spreadsheet formulas defused.
    fn csv_rows(&self, page: &LoadedPage, r: &Render) -> String {
        let _ = (page, r);
        String::new()
    }

    /// Columns of a typed export (XLSX) in a view: labels in the user's language and widths.
    fn export_columns(&self, r: &Render, view: Option<&crate::grid::DataGridView>) -> Vec<crate::grid::ExportColumn> {
        let _ = (r, view);
        Vec::new()
    }

    /// Typed values of a loaded page in its view, one row per item: choices as the user's labels
    /// and exact moments as wall clock time in the user's time zone. Everything else keeps its type.
    fn export_values(&self, page: &LoadedPage, r: &Render) -> Vec<Vec<crate::value::Value>> {
        let _ = (page, r);
        Vec::new()
    }

    /// Cells of a loaded page in its view as the user reads them, for printed exports (PDF).
    fn export_text(&self, page: &LoadedPage, r: &Render) -> Vec<Vec<String>> {
        let _ = (page, r);
        Vec::new()
    }

    /// Builds the call of a row item (`a0` for the first row action) from the loaded row with
    /// this key. `None` when the row is not there or the item does not exist for it.
    fn row_call(&self, page: &LoadedPage, key: &str, item: &str) -> Option<RowCall> {
        let _ = (page, key, item);
        None
    }

    /// Fields of the row model. Used to keep searches off masked fields.
    fn fields(&self) -> &'static [crate::model::FieldMeta] {
        &[]
    }

    /// Name of the row model when it is `#[sensitive]`, so exports are audited.
    fn sensitive_model(&self) -> Option<&'static str> {
        None
    }

    /// The raw value of a masked field of the row with this key, for an audited reveal.
    fn reveal(&self, _ctx: Ctx, _key: String, _field: String) -> BoxFuture<Result<Option<crate::privacy::Revealed>>> {
        Box::pin(async { Ok(None) })
    }
}

/// A component that saves data through an action. Implemented by forms with `submit`.
pub trait FormSource: Send + Sync {
    fn action(&self) -> ActionMeta;

    /// Parses submitted values, validates and runs the action. `values` holds what the user typed.
    fn submit(&self, ctx: Ctx, values: serde_json::Map<String, serde_json::Value>) -> BoxFuture<Result<Vec<Effect>>>;

    /// JSON Schema of the values, for agent tools.
    fn tool_schema(&self) -> serde_json::Value;
}

/// Anything that can be placed on a screen. This is the extension point for third party components.
///
/// A component writes its own HTML and describes itself in the schema. It must escape user data
/// with [`crate::render::escape`] (or [`Render::text`] and [`Render::value`]) and give interactive
/// parts a `data-testid` that starts with `r.scope`.
pub trait Component: Send + Sync {
    fn render(&self, out: &mut String, r: &Render);

    /// Schema used by MCP tools and test generation. Include a `"type"` key.
    fn schema(&self) -> serde_json::Value;

    fn grid(&self) -> Option<&dyn GridSource> {
        None
    }

    fn form(&self) -> Option<&dyn FormSource> {
        None
    }

    /// The raw value of a masked field this component shows, for an audited reveal. The server
    /// checks the unmask permission before sending it.
    fn reveal(&self, _field: &str) -> Option<crate::privacy::Revealed> {
        None
    }

    /// CSV import, for components that import rows (see [`crate::Import`]).
    fn import(&self) -> Option<&dyn crate::import::ImportSource> {
        None
    }

    /// A PDF document, for components that download one (see [`crate::PdfLink`]).
    #[cfg(feature = "pdf")]
    fn pdf(&self) -> Option<&dyn crate::pdf::PdfSource> {
        None
    }

    /// Nodes held by a container. Child `i` of the node at path `p` has the path `p.i`.
    fn children(&self) -> &[Node] {
        &[]
    }

    /// Children rendered with the page. Others, such as closed lazy tabs, load when first shown.
    fn eager_children(&self) -> &[Node] {
        self.children()
    }

    /// Data the component fetches through an action, by key (a field name for lookups).
    fn source(&self, _key: &str) -> Option<&dyn crate::ui::DataSource> {
        None
    }
}

/// Type erased component: a node of the screen tree.
pub struct Node(Box<dyn Component>);

impl Node {
    pub fn new(component: impl Component + 'static) -> Self {
        Self(Box::new(component))
    }

    pub fn render(&self, out: &mut String, r: &Render) {
        self.0.render(out, r);
    }

    pub fn schema(&self) -> serde_json::Value {
        self.0.schema()
    }

    pub fn grid(&self) -> Option<&dyn GridSource> {
        self.0.grid()
    }

    pub fn form(&self) -> Option<&dyn FormSource> {
        self.0.form()
    }

    pub fn reveal(&self, field: &str) -> Option<crate::privacy::Revealed> {
        self.0.reveal(field)
    }

    pub fn import(&self) -> Option<&dyn crate::import::ImportSource> {
        self.0.import()
    }

    #[cfg(feature = "pdf")]
    pub fn pdf(&self) -> Option<&dyn crate::pdf::PdfSource> {
        self.0.pdf()
    }

    pub fn children(&self) -> &[Node] {
        self.0.children()
    }

    pub fn eager_children(&self) -> &[Node] {
        self.0.eager_children()
    }

    pub fn source(&self, key: &str) -> Option<&dyn crate::ui::DataSource> {
        self.0.source(key)
    }
}

/// Icons.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum Icon {
    Plus,
    Edit,
    Delete,
    Save,
    Search,
    Box,
    Cart,
    Table,
    Home,
    Chart,
}

impl Icon {
    fn css(self) -> &'static str {
        match self {
            Icon::Plus => "plus",
            Icon::Edit => "edit",
            Icon::Delete => "delete",
            Icon::Save => "save",
            Icon::Search => "search",
            Icon::Box => "box",
            Icon::Cart => "cart",
            Icon::Table => "table",
            Icon::Home => "home",
            Icon::Chart => "chart",
        }
    }

    /// Icon markup, hidden from screen readers.
    pub fn html(self) -> String {
        format!(r#"<span class="z-icon z-icon-{}" aria-hidden="true"></span>"#, self.css())
    }
}

/// Export format.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum Export {
    Xlsx,
    Csv,
    /// A list report, with the `pdf` Cargo feature.
    Pdf,
}

impl Export {
    fn code(self) -> &'static str {
        match self {
            Export::Xlsx => "xlsx",
            Export::Csv => "csv",
            Export::Pdf => "pdf",
        }
    }
}

#[derive(Debug)]
struct ButtonSpec {
    label: Text,
    icon: Option<Icon>,
    shortcut: Option<String>,
    override_browser: bool,
    effect: Option<Effect>,
    tip: Option<Text>,
}

#[derive(Debug)]
enum ToolItem {
    Button(ButtonSpec),
    Export(Export),
}

/// Screen toolbar.
#[derive(Debug, Default)]
pub struct Toolbar {
    items: Vec<ToolItem>,
}

impl Toolbar {
    pub fn button(self, label: impl Into<Text>) -> ToolButton {
        ToolButton {
            bar: self,
            spec: ButtonSpec {
                label: label.into(),
                icon: None,
                shortcut: None,
                override_browser: false,
                effect: None,
                tip: None,
            },
        }
    }

    /// Export button for the grid on this screen.
    pub fn export(mut self, format: Export) -> Toolbar {
        self.items.push(ToolItem::Export(format));
        self
    }

    pub(crate) fn render(&self, out: &mut String, r: &Render, title: &str) {
        let scope = r.scope;
        out.push_str(&format!(r#"<div class="z-toolbar" role="toolbar" aria-label="{title}">"#));
        for (n, item) in self.items.iter().enumerate() {
            match item {
                ToolItem::Button(b) => {
                    let tip = b.tip.as_ref().map(|t| crate::ui::tip(r, &format!("{scope}-tooltip-{n}"), t));
                    if tip.is_some() {
                        out.push_str(r#"<span class="z-tip-host">"#);
                    }
                    let english = b.label.english();
                    out.push_str(&format!(
                        r#"<button type="button" class="z-button" data-testid="{scope}.toolbar.{}""#,
                        slug(&english)
                    ));
                    if let Some(keys) = b.shortcut.as_deref().and_then(|s| crate::command::usable_shortcut(s, b.override_browser)) {
                        out.push_str(&format!(r#" aria-keyshortcuts="{}""#, crate::render::escape(&keys)));
                    }
                    if let Some(e) = &b.effect {
                        out.push_str(&format!(r#" data-zeyn-effect="{}""#, attr(e)));
                    }
                    if let Some((attrs, _)) = &tip {
                        out.push_str(attrs);
                    }
                    out.push('>');
                    if let Some(i) = b.icon {
                        out.push_str(&i.html());
                    }
                    out.push_str(&r.text(&b.label));
                    out.push_str("</button>");
                    if let Some((_, html)) = &tip {
                        out.push_str(html);
                        out.push_str("</span>");
                    }
                }
                ToolItem::Export(e) => out.push_str(&format!(
                    r#"<button type="button" class="z-button" data-testid="{scope}.toolbar.export-{code}" data-zeyn-export="{code}">{}</button>"#,
                    r.text(&Text::key(format!("zeyn.export.{}", e.code()))),
                    code = e.code()
                )),
            }
        }
        out.push_str("</div>");
    }

    pub(crate) fn schema(&self) -> serde_json::Value {
        self.items
            .iter()
            .map(|item| match item {
                ToolItem::Button(b) => json!({
                    "type": "button",
                    "label": b.label,
                    "icon": b.icon,
                    "shortcut": b.shortcut,
                    "effect": b.effect,
                }),
                ToolItem::Export(e) => json!({ "type": "export", "format": e }),
            })
            .collect()
    }
}

/// Toolbar button being configured.
pub struct ToolButton {
    bar: Toolbar,
    spec: ButtonSpec,
}

impl ToolButton {
    pub fn icon(mut self, icon: Icon) -> Self {
        self.spec.icon = Some(icon);
        self
    }

    /// Keyboard shortcut such as `"Alt+N"`. Shortcuts the browser uses (`Ctrl+P`, `Ctrl+S`,
    /// `F5`, ...) are not bound unless the button calls [`ToolButton::override_browser`]; ones the
    /// browser never passes on (`Ctrl+N`, `Ctrl+T`, `Ctrl+W`) are never bound. Both are logged.
    pub fn shortcut(mut self, keys: impl Into<String>) -> Self {
        self.spec.shortcut = Some(keys.into());
        self
    }

    /// Takes over a shortcut the browser uses, on purpose.
    pub fn override_browser(mut self) -> Self {
        self.spec.override_browser = true;
        self
    }

    /// A tooltip for the button: shown on hover, focus and long press, read as its description.
    pub fn tip(mut self, text: impl Into<Text>) -> Self {
        self.spec.tip = Some(text.into());
        self
    }

    /// Opens the screen as a window when the button is pressed.
    pub fn opens<S: ScreenDef>(mut self, screen: S, params: S::Params) -> Self {
        self.spec.effect = Some(Window::open(screen, params));
        self
    }

    pub fn button(self, label: impl Into<Text>) -> ToolButton {
        self.finish().button(label)
    }

    pub fn export(self, format: Export) -> Toolbar {
        self.finish().export(format)
    }

    fn finish(mut self) -> Toolbar {
        self.bar.items.push(ToolItem::Button(self.spec));
        self.bar
    }
}

impl From<ToolButton> for Toolbar {
    fn from(b: ToolButton) -> Self {
        b.finish()
    }
}

#[derive(Clone, Copy, Debug)]
enum ScreenKind {
    Page,
    Window { width: u32 },
}

/// Content of a screen. Screen functions return this.
pub struct Screen {
    title: Text,
    kind: ScreenKind,
    toolbar: Option<Toolbar>,
    body: Vec<Node>,
    menu: Option<crate::menu::ContextMenu>,
}

impl Screen {
    /// Full page screen.
    pub fn new(title: impl Into<Text>) -> Self {
        Self { title: title.into(), kind: ScreenKind::Page, toolbar: None, body: Vec::new(), menu: None }
    }

    /// Screen opened as a window.
    pub fn window(title: impl Into<Text>) -> Self {
        Self { kind: ScreenKind::Window { width: 560 }, ..Self::new(title) }
    }

    /// Window width in pixels. No effect on full page screens.
    pub fn width(mut self, px: u32) -> Self {
        if let ScreenKind::Window { width } = &mut self.kind {
            *width = px;
        }
        self
    }

    pub fn toolbar<F, R>(mut self, build: F) -> Self
    where
        F: FnOnce(Toolbar) -> R,
        R: Into<Toolbar>,
    {
        self.toolbar = Some(build(Toolbar::default()).into());
        self
    }

    pub fn body(mut self, node: impl Into<Node>) -> Self {
        self.body.push(node.into());
        self
    }

    /// Context menu for the empty space of the screen (not over rows, headers or inputs).
    pub fn context_menu(mut self, menu: crate::menu::ContextMenu) -> Self {
        self.menu = Some(menu);
        self
    }

    /// Takes the action item at `path` of the screen's context menu, to run it.
    pub fn menu_call(&self, path: &str) -> Option<RowCall> {
        self.menu.as_ref()?.take(path)
    }

    pub fn title(&self) -> &Text {
        &self.title
    }

    pub fn nodes(&self) -> &[Node] {
        &self.body
    }

    /// Renders the screen in English with no params and no preloaded rows. For tests and tools.
    pub fn html(&self, meta: &ScreenMeta) -> String {
        self.render(&Render::english(meta.name), meta, &serde_json::Value::Null, &HashMap::new())
    }

    /// Renders the screen. `loaded` holds the first page of grids by node path (`"0"`, `"1.2"`).
    pub fn render(
        &self,
        r: &Render,
        meta: &ScreenMeta,
        params: &serde_json::Value,
        loaded: &HashMap<String, LoadedPage>,
    ) -> String {
        let scope = meta.name;
        let r = Render { scope, loaded: Some(loaded), ..*r };
        let title = r.text(&self.title);
        let params = match self.menu.as_ref().map(|m| m.to_json(&r)) {
            Some(items) if items.as_array().is_some_and(|a| !a.is_empty()) => {
                format!(r#"{}" data-zeyn-menu="{}"#, attr(params), attr(&items))
            }
            _ => attr(params),
        };
        let mut out = String::new();
        let close = match self.kind {
            ScreenKind::Page => {
                out.push_str(&format!(
                    r#"<section class="z-screen" data-zeyn-screen="{scope}" data-zeyn-params="{params}" aria-labelledby="{scope}-title"><h1 id="{scope}-title">{title}</h1>"#
                ));
                "</section>"
            }
            ScreenKind::Window { width } => {
                out.push_str(&format!(
                    r#"<div class="z-window" role="dialog" aria-modal="true" data-zeyn-screen="{scope}" data-zeyn-params="{params}" aria-labelledby="{scope}-title" style="--z-width:{width}px"><h2 id="{scope}-title">{title}</h2>"#
                ));
                "</div>"
            }
        };
        if let Some(t) = &self.toolbar {
            t.render(&mut out, &r, &title);
        }
        for (i, node) in self.body.iter().enumerate() {
            crate::ui::render_node(&mut out, &r, &i.to_string(), node);
        }
        out.push_str(close);
        out
    }

    /// Screen schema used by MCP tools, test generation and validation.
    pub fn schema(&self, meta: &ScreenMeta) -> serde_json::Value {
        let (kind, width) = match self.kind {
            ScreenKind::Page => ("page", None),
            ScreenKind::Window { width } => ("window", Some(width)),
        };
        json!({
            "screen": meta,
            "title": self.title,
            "kind": kind,
            "width": width,
            "toolbar": self.toolbar.as_ref().map(Toolbar::schema),
            "body": self.body.iter().map(Node::schema).collect::<Vec<_>>(),
        })
    }
}