tablo-core 0.9.0

//! [`Page`] — a panel page that is not a resource: a dashboard, a report, a
//! settings screen, a media library — and the [`PageDef`] it declares.

use std::{any::TypeId, future::Future, sync::Arc};

use topcoat::{
    Result,
    context::Cx,
    icon::IconData,
    view::{BoxView, View, ViewExt},
};

pub use self::filters::{PageFilter, PageFilters};
use crate::{
    HeaderAction, HeaderActions, Widget,
    naming::{kebab_case, sentence_case, type_stem},
    navigation::NavigationItem,
    widget::WidgetGrid,
};

/// A panel page that is not a resource, mounted at `{prefix}/{slug}` with a
/// sidebar entry; the panel owns the route and entry while the page owns its
/// markup.
///
/// ```rust
/// # use tablo_core::{Page, Panel};
/// struct ReportsPage;
///
/// impl Page for ReportsPage {}
///
/// Panel::new("admin").page::<ReportsPage>(); // GET /admin/reports
/// ```
///
/// A page serves one `GET` with a sidebar entry, which [`PageDef::access`] limits
/// to the users it admits. A form it renders posts to an app-declared route the
/// auth gate covers; that route asks [`can_open`](crate::can_open) itself.
pub trait Page: Sized + Send + Sync + 'static {
    /// The page's slug, sidebar entry, access and header actions. Defaults to
    /// [`PageDef::new`]: every default.
    ///
    /// [`Panel::page_with`](crate::Panel::page_with) adjusts it for one panel.
    fn declare() -> PageDef {
        PageDef::new()
    }

    /// Render the page body. The panel checks for a resolved user and
    /// [`PageDef::access`] before calling it.
    ///
    /// Defaults to the page its [`PageDef`] declares: the [`title`](PageDef::title) and
    /// [`description`](PageDef::description), the buttons of its
    /// [`header_action`](PageDef::header_action)s, and the grid of its
    /// [`widget`](PageDef::widget)s. A page that renders more places those parts itself, through
    /// [`header_action_buttons`](crate::header_action_buttons) and [`widgets`](crate::widgets):
    ///
    /// ```rust
    /// # use tablo_core::Page;
    /// # use topcoat::{Result, context::Cx, view::{View, view}};
    /// struct ReportsPage;
    ///
    /// impl Page for ReportsPage {
    ///     async fn render(cx: &Cx) -> Result<impl View> {
    ///         Ok(view! {
    ///             tablo_ui::page(
    ///                 tablo_ui::page_header(tablo_ui::page_title("Reports"))
    ///                 tablo_ui::page_content((tablo_core::widgets::<Self>(cx)) "…")
    ///             )
    ///         })
    ///     }
    /// }
    /// ```
    fn render(cx: &Cx) -> impl Future<Output = Result<impl View>> + Send {
        async move { Ok(declared_body(cx, TypeId::of::<Self>())) }
    }
}

/// Renders the page of type `page` as its [`PageDef`] declares it. The panel installs it: a page's
/// header and grid are the serving layer's markup.
pub(crate) struct PageBody(pub(crate) for<'a> fn(&'a Cx, TypeId) -> BoxView<'a>);

/// The body [`Page::render`] defaults to; nothing on a router that mounts no panel.
fn declared_body(cx: &Cx, page: TypeId) -> BoxView<'_> {
    match topcoat::context::try_context::<PageBody>(cx) {
        Some(PageBody(render)) => render(cx, page),
        None => ().boxed(),
    }
}

/// Whether the request's user may open a page.
type AccessFn = dyn Fn(&Cx) -> bool + Send + Sync;

/// What a [`Page`] declares: its slug, sidebar entry, title, access, header actions and widgets.
///
/// [`Page::declare`] returns one, and [`Panel::page_with`](crate::Panel::page_with) adjusts it for
/// one panel. Every setting has a default, so a page sets only what differs:
///
/// ```rust
/// # use tablo_core::{Page, PageDef};
/// # use topcoat::{Result, context::Cx, view::View};
/// struct MediaLibraryPage;
///
/// impl Page for MediaLibraryPage {
///     fn declare() -> PageDef {
///         PageDef::new().slug("media").icon(tablo_ui::icons::IMAGE)
///     }
///
///     async fn render(_cx: &Cx) -> Result<impl View> {
///         Ok(())
///     }
/// }
/// ```
///
/// The panel builds the def once when it mounts and serves the result to every request.
pub struct PageDef {
    slug: Option<String>,
    label: Option<crate::Text>,
    icon: Option<IconData>,
    navigation_order: Option<i32>,
    navigation_group: Option<crate::Text>,
    navigation: Option<NavigationItem>,
    navigation_hidden: bool,
    title: Option<crate::Text>,
    description: Option<crate::Text>,
    access: Arc<AccessFn>,
    access_declared: bool,
    header_actions: HeaderActions,
    widgets: WidgetGrid,
    filters: Vec<PageFilter>,
}

impl PageDef {
    /// A def with every default: the slug and label from the page's type name, and access for
    /// every signed-in user.
    pub fn new() -> Self {
        Self::default()
    }

    /// The URL segment under the panel prefix: `"media"` mounts the page at
    /// `{panel prefix}/media`.
    ///
    /// Defaults to the page type's name without a trailing `Page`, kebab-cased:
    /// `MediaLibraryPage` → `media-library`. [`Panel::home`](crate::Panel::home) mounts the page
    /// at the prefix and does not read it.
    #[must_use]
    pub fn slug(mut self, slug: impl Into<String>) -> Self {
        self.slug = Some(slug.into());
        self
    }

    /// The sidebar label.
    ///
    /// Defaults to the message `page-{name}` of the panel's catalogs, else the page type's name
    /// without a trailing `Page`, in sentence case: `MediaLibraryPage` reads `page-media-library`,
    /// else `Media library`.
    #[must_use]
    pub fn label(mut self, label: impl Into<crate::Text>) -> Self {
        self.label = Some(label.into());
        self
    }

    /// The icon of the page's sidebar entry, replacing the icon of a
    /// [`navigation`](Self::navigation) item.
    #[must_use]
    pub fn icon(mut self, icon: IconData) -> Self {
        self.icon = Some(icon);
        self
    }

    /// Where the sidebar entry sorts among the panel's entries, lowest first; defaults to `0`, and
    /// entries of equal order keep their registration order. It replaces the order of a
    /// [`navigation`](Self::navigation) item.
    #[must_use]
    pub fn navigation_order(mut self, order: i32) -> Self {
        self.navigation_order = Some(order);
        self
    }

    /// The labelled sidebar group the entry renders in, such as `"Reports"`; defaults to none,
    /// above every group. It replaces the group of a [`navigation`](Self::navigation) item.
    #[must_use]
    pub fn navigation_group(mut self, group: impl Into<crate::Text>) -> Self {
        self.navigation_group = Some(group.into());
        self
    }

    /// Replaces the sidebar entry, for one that links somewhere other than the page:
    /// `NavigationItem::at("Exports", "/admin/reports?tab=exports")`. [`icon`](Self::icon),
    /// [`navigation_order`](Self::navigation_order) and
    /// [`navigation_group`](Self::navigation_group) still apply to it.
    #[must_use]
    pub fn navigation(mut self, item: NavigationItem) -> Self {
        self.navigation = Some(item);
        self
    }

    /// Keeps the page out of the sidebar. It stays mounted at its URL, and
    /// [`access`](Self::access) still decides who may open it: link it from a
    /// [user menu item](crate::Panel::user_menu_item), another page or a notification.
    #[must_use]
    pub fn without_navigation(mut self) -> Self {
        self.navigation_hidden = true;
        self
    }

    /// The heading the default [`render`](Page::render) shows. Defaults to the
    /// [`label`](Self::label) when one is given, else the label of the
    /// [`navigation`](Self::navigation) item, else the label's default.
    #[must_use]
    pub fn title(mut self, title: impl Into<crate::Text>) -> Self {
        self.title = Some(title.into());
        self
    }

    /// The line the default [`render`](Page::render) shows under the title; defaults to none.
    #[must_use]
    pub fn description(mut self, description: impl Into<crate::Text>) -> Self {
        self.description = Some(description.into());
        self
    }

    /// Whether the request's user may open the page. The panel answers 403 and leaves the page
    /// out of the sidebar when it answers `false`. Defaults to every signed-in user.
    ///
    /// ```rust
    /// # use tablo_core::{Page, PageDef, auth};
    /// # use topcoat::{Result, context::Cx, view::{View, view}};
    /// # #[derive(Clone)]
    /// # struct Staff { admin: bool }
    /// # impl tablo_core::PanelUser for Staff {
    /// #     fn user_id(&self) -> String { String::new() }
    /// #     fn display_name(&self) -> &str { "" }
    /// #     fn can_access_panel(&self, _panel: &str) -> bool { true }
    /// # }
    /// struct BillingPage;
    ///
    /// impl Page for BillingPage {
    ///     fn declare() -> PageDef {
    ///         PageDef::new().access(|cx| auth::user::<Staff>(cx).is_some_and(|staff| staff.admin))
    ///     }
    ///
    ///     async fn render(cx: &Cx) -> Result<impl View> {
    ///         Ok(view! { tablo_ui::page(tablo_ui::page_title("Billing")) })
    ///     }
    /// }
    /// ```
    #[must_use]
    pub fn access(mut self, access: impl Fn(&Cx) -> bool + Send + Sync + 'static) -> Self {
        self.access = Arc::new(access);
        self.access_declared = true;
        self
    }

    /// Adds the [`HeaderAction`] `A` after the ones already declared, served at
    /// `{url}/-/actions/{NAME}`. The default [`render`](Page::render) shows their buttons in the
    /// page's header; a page that renders itself places
    /// [`header_action_buttons`](crate::header_action_buttons). An `A::NAME` that is not a
    /// single URL path segment does not compile.
    ///
    /// The actions run for whoever may open the page: a page has no policy. An action that writes
    /// a resource's records asks that resource's policy in its own
    /// [`can_run`](crate::HeaderAction::can_run).
    #[must_use]
    pub fn header_action<A: HeaderAction>(mut self) -> Self {
        self.header_actions = self.header_actions.add::<A>();
        self
    }

    /// Adds the [`Widget`] `W` after the ones already declared, to the grid the default
    /// [`render`](Page::render) shows under the header; a page that renders itself places
    /// [`widgets`](crate::widgets).
    #[must_use]
    pub fn widget<W: Widget>(mut self) -> Self {
        self.widgets.push::<W>();
        self
    }

    /// Offers `filter` above the widgets, after the filters already declared: a value the page
    /// keeps in its query string, which its widgets read through
    /// [`page_filters`](crate::page_filters). The default [`render`](Page::render) shows the
    /// filters' bar under the header; a page that renders itself places
    /// [`page_filter_bar`](crate::page_filter_bar). Mounting refuses two filters sharing a key,
    /// and a key that is not ASCII letters, digits, `-` and `_`.
    #[must_use]
    pub fn filter(mut self, filter: PageFilter) -> Self {
        self.filters.push(filter);
        self
    }

    /// How many columns the widget grid has on a wide screen, from 1 to 4; defaults to 2. A
    /// medium screen shows at most two, a narrow one one.
    #[must_use]
    pub fn widget_columns(mut self, columns: u8) -> Self {
        self.widgets.set_columns(columns);
        self
    }
}

impl Default for PageDef {
    fn default() -> Self {
        Self {
            slug: None,
            label: None,
            icon: None,
            navigation_order: None,
            navigation_group: None,
            navigation: None,
            navigation_hidden: false,
            title: None,
            description: None,
            access: Arc::new(|_| true),
            access_declared: false,
            header_actions: HeaderActions::new(),
            widgets: WidgetGrid::default(),
            filters: Vec::new(),
        }
    }
}

impl std::fmt::Debug for PageDef {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("PageDef")
            .field("slug", &self.slug)
            .field("label", &self.label)
            .field("navigation_order", &self.navigation_order)
            .field("navigation_group", &self.navigation_group)
            .field("navigation", &self.navigation)
            .field("navigation_hidden", &self.navigation_hidden)
            .field("title", &self.title)
            .field("description", &self.description)
            .field("header_actions", &self.header_actions)
            .field("widgets", &self.widgets)
            .finish_non_exhaustive()
    }
}

/// A [`PageDef`] with its defaults filled in for the page `P`, as a panel mounted it.
pub(crate) struct MountedPage {
    pub(crate) slug: String,
    /// The sidebar entry, its target not yet resolved to the page's URL.
    pub(crate) navigation: NavigationItem,
    /// Whether the sidebar leaves the page out: [`PageDef::without_navigation`].
    pub(crate) navigation_hidden: bool,
    /// The heading the default [`Page::render`] shows.
    pub(crate) title: crate::Text,
    pub(crate) description: Option<crate::Text>,
    access: Arc<AccessFn>,
    /// Whether the def declared [`PageDef::access`] rather than keep the default.
    pub(crate) access_declared: bool,
    pub(crate) header_actions: HeaderActions,
    pub(crate) widgets: WidgetGrid,
    /// The [`PageDef::filter`]s, in declaration order.
    pub(crate) filters: Vec<PageFilter>,
}

impl MountedPage {
    pub(crate) fn new<P: Page>(def: PageDef) -> Self {
        let stem = type_stem::<P>("Page");
        let noun = sentence_case(stem);
        let label = crate::Text::derived(
            crate::naming::derived_id("page", &crate::naming::slug_case(&noun)),
            noun,
        );
        Self::declared(def, kebab_case(stem), label)
    }

    /// `def` with its defaults filled in: `slug` and `label` where it names none.
    pub(crate) fn declared(def: PageDef, slug: String, label: crate::Text) -> Self {
        let title = def
            .title
            .or_else(|| def.label.clone())
            .or_else(|| def.navigation.as_ref().map(|item| item.label.clone()));
        let label = def.label.unwrap_or(label);
        let title = title.unwrap_or_else(|| label.clone());
        let mut navigation = def.navigation.unwrap_or_else(|| NavigationItem {
            label,
            ..NavigationItem::default()
        });
        if let Some(order) = def.navigation_order {
            navigation.order = order;
        }
        if let Some(icon) = def.icon {
            navigation.icon = Some(icon);
        }
        if let Some(group) = def.navigation_group {
            navigation.group = Some(group);
        }
        Self {
            slug: def.slug.unwrap_or(slug),
            navigation,
            navigation_hidden: def.navigation_hidden,
            title,
            description: def.description,
            access: def.access,
            access_declared: def.access_declared,
            header_actions: def.header_actions,
            widgets: def.widgets,
            filters: def.filters,
        }
    }

    /// Whether the request's user may open the page.
    pub(crate) fn admits(&self, cx: &Cx) -> bool {
        (self.access)(cx)
    }

    /// The page behind `access` in place of its def's: an auth page placed in an area, which
    /// declares none, opens to whom auth offers it.
    pub(crate) fn with_access(
        mut self,
        access: impl Fn(&Cx) -> bool + Send + Sync + 'static,
    ) -> Self {
        self.access = Arc::new(access);
        self
    }

    /// The page's access check, shared with its sidebar entry.
    pub(crate) fn access(&self) -> Arc<AccessFn> {
        Arc::clone(&self.access)
    }
}

/// A page's declaration check, run by
/// [`RouterBuilderPanelExt::panel`](crate::RouterBuilderPanelExt::panel) as a resource's is.
pub(crate) type PageCheck = Box<dyn Fn(&Cx, &mut Vec<crate::DeclarationError>) + Send>;

/// Checks the header actions of `page`, the page `P` as the panel mounted it, as a resource's are,
/// that no two of its widgets share a name, and that its filters' keys are distinct query words.
pub(crate) fn check_page<P: Page>(page: Arc<MountedPage>) -> PageCheck {
    Box::new(move |cx, errors| {
        page.widgets.check::<P>(errors);
        let mut keys = std::collections::HashSet::new();
        for filter in &page.filters {
            if !filter.has_valid_key() || !keys.insert(filter.key()) {
                errors.push(crate::DeclarationError::of::<P>(
                    crate::declaration::Site::Registration,
                    crate::DeclarationErrorKind::MisdeclaredPageFilter {
                        key: filter.key().to_string(),
                    },
                ));
            }
        }
        crate::resource::check_inputs::<P>(
            cx,
            page.header_actions
                .entries()
                .iter()
                .map(|action| (action.name, action.input)),
            errors,
        );
    })
}

pub(crate) mod filters;
#[cfg(test)]
mod tests;