zeyn 0.0.7

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,
    /// Seconds a shared cache may keep the page of a public screen opened without a session
    /// (`cache = N`, at most [`MAX_SCREEN_CACHE`]); 0 sends no public cache headers.
    pub cache: u32,
}

/// Longest `cache = N` a screen may ask for: one day.
pub const MAX_SCREEN_CACHE: u32 = 86_400;

/// 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>>;

    /// Reads path segment `field` of the route (`{id}` in `/orders/{id}`) as the JSON value of
    /// that params field, or `None` when it does not parse (the request answers 404). Generated
    /// by `#[screen]` for routes with segments.
    fn path_value(field: &str, raw: &str) -> Option<serde_json::Value> {
        let _ = (field, raw);
        None
    }
}

/// A params field type that can be a path segment of a route, such as `id` in `/orders/{id}`.
/// A segment only parses in the one form the framework writes it in (`7`, not `+7` or `007`),
/// so each record has one address.
///
/// A field whose type cannot be a segment does not compile:
///
/// ```compile_fail
/// use zeyn::prelude::*;
///
/// #[params]
/// pub struct DayParams {
///     pub day: Vec<String>,
/// }
///
/// #[screen(route = "/days/{day}", public)]
/// pub fn day(_p: DayParams) -> Screen {
///     Screen::new("Day")
/// }
/// ```
#[diagnostic::on_unimplemented(
    message = "`{Self}` cannot be a route path segment",
    label = "this route names a params field of type `{Self}`",
    note = "path segments take integers (`i64`, `u32`, ...), entity keys (`ProductId`), `String` or `zeyn::Slug`; take the field out of the route and it travels in the JSON `params` query instead"
)]
pub trait PathValue: Serialize + Sized {
    /// Parses a decoded segment. `None` answers 404.
    fn from_segment(raw: &str) -> Option<Self>;
}

macro_rules! path_ints {
    ($($t:ty),*) => {$(
        impl PathValue for $t {
            fn from_segment(raw: &str) -> Option<Self> {
                raw.parse::<$t>().ok().filter(|v| v.to_string() == raw)
            }
        }
    )*};
}

path_ints!(i8, i16, i32, i64, u8, u16, u32, u64, usize);

impl PathValue for String {
    fn from_segment(raw: &str) -> Option<Self> {
        (!raw.is_empty() && raw != "." && raw != ".." && raw.len() <= MAX_SEGMENT)
            .then(|| raw.to_string())
    }
}

/// Longest path segment value read or written, in bytes.
pub const MAX_SEGMENT: usize = 256;

#[doc(hidden)]
/// Reads a segment as the type of the params field `field` points to. The closure is never
/// called; it only names the field, so a missing field is a compile error at the route.
pub fn __path_value<P, T: PathValue>(
    raw: &str,
    field: impl Fn(&P) -> &T,
) -> Option<serde_json::Value> {
    let _ = field;
    T::from_segment(raw).and_then(|v| serde_json::to_value(v).ok())
}

/// Names of the path segments of a route: `["slug", "n"]` for `/catalog/{slug}/{n}`.
pub(crate) fn route_segments(route: &str) -> impl Iterator<Item = &str> {
    route.split('/').filter_map(|s| {
        s.strip_prefix('{')
            .and_then(|s| s.strip_suffix('}'))
    })
}

/// Whether a route has path segments. Usable in constant checks.
pub const fn route_has_segments(route: Option<&str>) -> bool {
    let Some(route) = route else { return false };
    let bytes = route.as_bytes();
    let mut i = 0;
    while i < bytes.len() {
        if bytes[i] == b'{' {
            return true;
        }
        i += 1;
    }
    false
}

/// URL of a screen at `path` (its route with the feature prefix) with these params: path segments
/// filled from the params fields of the same name, the other fields in the JSON `params` query.
/// `None` when a segment's field is missing or not a number or a usable string.
///
/// ```
/// use serde_json::json;
/// use zeyn::screen_url;
/// assert_eq!(screen_url("/orders/{id}", &json!({ "id": 42, "tab": "lines" })).unwrap(), "/orders/42?params=%7B%22tab%22%3A%22lines%22%7D");
/// assert_eq!(screen_url("/catalog/{slug}/{n}", &json!({ "slug": "cay-bardagi", "n": 2 })).unwrap(), "/catalog/cay-bardagi/2");
/// assert_eq!(screen_url("/orders", &json!({ "q": 1 })).unwrap(), "/orders?params=%7B%22q%22%3A1%7D");
/// assert_eq!(screen_url("/orders/{id}", &json!({})), None);
/// ```
pub fn screen_url(path: &str, params: &serde_json::Value) -> Option<String> {
    if !route_has_segments(Some(path)) {
        return Some(if params.is_null() {
            path.to_string()
        } else {
            format!("{path}?params={}", encode(&params.to_string()))
        });
    }
    let fields = params.as_object()?;
    let mut out = String::with_capacity(path.len() + 16);
    for (i, part) in path.split('/').enumerate() {
        if i > 0 {
            out.push('/');
        }
        match part
            .strip_prefix('{')
            .and_then(|p| p.strip_suffix('}'))
        {
            Some(name) => {
                let value = match fields.get(name)? {
                    serde_json::Value::Number(n) => n.to_string(),
                    serde_json::Value::String(s) => String::from_segment(s)?,
                    _ => return None,
                };
                out.push_str(&encode(&value));
            }
            None => out.push_str(part),
        }
    }
    let segments: Vec<&str> = route_segments(path).collect();
    let rest: serde_json::Map<String, serde_json::Value> = fields
        .iter()
        .filter(|(k, _)| !segments.contains(&k.as_str()))
        .map(|(k, v)| (k.clone(), v.clone()))
        .collect();
    if !rest.is_empty() {
        out.push_str("?params=");
        out.push_str(&encode(&serde_json::Value::Object(rest).to_string()));
    }
    Some(out)
}

/// Full paths (feature prefix, no base path) of the routed screens of a running app, so links
/// rendered for a request use the path form. Kept by the server as a service on every request.
#[derive(Clone, Default)]
pub(crate) struct Routes(
    pub(crate) std::sync::Arc<HashMap<&'static str, String>>,
    /// The default language when the app keeps the language in the URL (`App::locale_paths`):
    /// links in another language get its segment in front, so they stay in that language.
    pub(crate) Option<std::sync::Arc<str>>,
);

impl crate::ctx::Service for Routes {}

impl Routes {
    /// App path of `screen` with `params`, without the base path; see [`screen_url`].
    pub(crate) fn href(r: &Render, screen: &str, params: &serde_json::Value) -> Option<String> {
        let ctx = r.ctx?;
        let routes = ctx.service::<Routes>()?;
        let url = screen_url(routes.0.get(screen)?, params)?;
        Some(match routes.1.as_deref() {
            Some(default) if ctx.locale() != default && url == "/" => format!("/{}/", ctx.locale()),
            Some(default) if ctx.locale() != default => format!("/{}{url}", ctx.locale()),
            _ => url,
        })
    }
}

/// Percent encodes a path segment or query value. Dots are encoded too, so a segment never looks
/// like a file name to the browser runtime.
fn encode(s: &str) -> String {
    let mut out = String::with_capacity(s.len());
    for b in s.bytes() {
        match b {
            b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'~' => out.push(b as char),
            _ => out.push_str(&format!("%{b:02X}")),
        }
    }
    out
}

/// 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)]
#[allow(
    clippy::large_enum_variant,
    reason = "nearly every entry of the list is the large variant, so boxing it would add an allocation per entry and save no memory"
)]
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>,
    moved: Option<(&'static str, serde_json::Value)>,
    head: Option<Box<crate::seo::Head>>,
}

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,
            moved: None,
            head: None,
        }
    }

    /// Answers that this page lives at another screen's address now: the browser gets a permanent
    /// redirect (301) there, such as from an old slug to the current one. Params of the wrong type
    /// do not compile. To answer that nothing is there, return `Err(Error::NotFound)` instead.
    ///
    /// ```ignore
    /// if p.slug != product.slug {
    ///     return Ok(Screen::moved_to(product_page, ProductParams { slug: product.slug, n: p.n }));
    /// }
    /// ```
    pub fn moved_to<S: ScreenDef>(_screen: S, params: S::Params) -> Self {
        Self {
            moved: Some((S::META.name, params_json(&params))),
            ..Self::new("")
        }
    }

    /// Screen and params of [`Screen::moved_to`], if this screen moved.
    pub(crate) fn take_moved(&mut self) -> Option<(&'static str, serde_json::Value)> {
        self.moved.take()
    }

    fn head_mut(&mut self) -> &mut crate::seo::Head {
        self.head
            .get_or_insert_with(Default::default)
    }

    /// Summary for search results and link previews: `<meta name="description">` and
    /// `og:description`.
    pub fn description(mut self, text: impl Into<Text>) -> Self {
        self.head_mut().description = Some(text.into());
        self
    }

    /// The URL search engines should index for this page: an `https` URL, or an app path written
    /// behind `App::site_url` and the base path. Other URLs are ignored with a warning.
    pub fn canonical(mut self, url: impl Into<String>) -> Self {
        self.head_mut().canonical = crate::seo::checked(url.into(), "a canonical URL");
        self
    }

    /// The same page in another language, sent as `<link rel="alternate" hreflang="..">`:
    /// `hreflang` is a language tag such as `tr` or `zh-Hans`, or `x-default` for the page shown
    /// when no language matches, and `url` an `https` URL or an app path. List every language
    /// the page has, including its own. Bad tags or URLs are ignored with a warning, and at most
    /// [`crate::seo::MAX_ALTERNATES`] are kept.
    ///
    /// ```
    /// use zeyn::Screen;
    /// let s = Screen::new("Orders").alternate("en", "/orders").alternate("tr", "/tr/orders").alternate("x-default", "/orders");
    /// ```
    pub fn alternate(mut self, hreflang: &str, url: impl Into<String>) -> Self {
        let tag = crate::seo::valid_hreflang(hreflang);
        let url = crate::seo::checked(url.into(), "an alternate URL");
        let head = self.head_mut();
        match (tag, url) {
            (true, Some(url)) if head.alternates.len() < crate::seo::MAX_ALTERNATES => {
                head.alternates
                    .push((hreflang.to_string(), url));
            }
            (false, _) => {
                tracing::warn!("hreflang `{hreflang}` is not a language tag or x-default; ignored")
            }
            _ => {}
        }
        self
    }

    /// Image of link previews (`og:image`): an `https` URL or an app path.
    pub fn og_image(mut self, url: impl Into<String>) -> Self {
        self.head_mut().og_image = crate::seo::checked(url.into(), "an og:image URL");
        self
    }

    /// Structured data for search engines, sent as `<script type="application/ld+json">`. The
    /// browser never runs it, and the JSON is escaped so it cannot end the script element.
    pub fn json_ld(mut self, data: serde_json::Value) -> Self {
        self.head_mut().json_ld = Some(data);
        self
    }

    /// Whether search engines may index the page.
    pub fn robots(mut self, robots: crate::seo::Robots) -> Self {
        self.head_mut().robots = Some(robots);
        self
    }

    /// Head tags of the page (description, canonical, alternates, preview image, robots, JSON-LD), empty
    /// when the screen sets none.
    pub fn head_html(&self, r: &Render, site: &str, prefix: &str) -> String {
        self.head
            .as_ref()
            .map(|h| h.render(r, site, prefix))
            .unwrap_or_default()
    }

    /// 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<_>>(),
        })
    }
}