tablo_core/

lib.rs

//! Tablo: a server-rendered admin toolkit on [Topcoat](topcoat) and [Toasty](toasty).
//!
//! A [`Panel`] serves one [`Resource`] per Toasty model. A resource names the model, whose
//! [`ModelColumns`](derive@ModelColumns) give its default table and detail page, and the record
//! form its create and edit submissions parse into, which [`ModelForm`](derive@ModelForm) derives
//! from the model or [`RecordForm`](derive@RecordForm) from a struct of its own. It declares the
//! rest as one [`ResourceDef`] value: its [`Policy`], which denies by default, and any [`Table`],
//! [`Schema`] or [`Detail`] that replaces or extends the defaults.
//! The app mounts the panel on its own Topcoat router with [`RouterBuilderPanelExt::panel`], which
//! builds each def once, binds it to the database schema and checks it first; one router mounts any
//! number of panels at distinct prefixes.
//!
//! ```rust,no_run
//! # use tablo_core::{Allow, Panel, Resource, ResourceDef, RouterBuilderPanelExt};
//! # use toasty::Db;
//! # use topcoat::router::{Router, RouterBuilderDiscoverExt};
//! # fn main() -> topcoat::Result<()> {
//! #[derive(Debug, Clone, toasty::Model, tablo_core::ModelColumns, tablo_core::ModelForm)]
//! pub struct Book {
//!     #[key]
//!     #[auto]
//!     pub id: uuid::Uuid,
//!     pub title: String,
//! }
//!
//! pub struct BookResource;
//!
//! impl Resource for BookResource {
//!     type Model = Book;
//!     type Form = BookForm;
//!
//!     fn declare() -> ResourceDef<Self> {
//!         ResourceDef::new().policy(Allow)
//!     }
//! }
//!
//! # let db: Db = todo!();
//! let router = Router::builder()
//!     .discover()
//!     .app_context(db)
//!     .panel(Panel::new("admin").resource::<BookResource>())?
//!     .build();
//! # let _ = router;
//! # Ok(())
//! # }
//! ```
//!
//! The [user guide](https://y-l.fr/tablo/nightly/guide/) walks through a complete panel and each
//! part of it. [`ResourceDef`] lists everything a resource declares, [`Resource`] the hooks it
//! overrides, and [`Panel`] every builder call.

// The derives emit `tablo_core::` paths; this lets them expand inside this
// crate's own tests too.
extern crate self as tablo_core;

#[doc(hidden)]
pub mod __macro {
    pub use toasty::{
        Executor, Result as DbResult,
        schema::{Embed, Model},
        stmt,
        stmt::{List, Path},
    };
    pub use topcoat::context::Cx;

    pub use crate::{
        Lens,
        detail::Detail,
        extend::{Includes, OptionSource},
        form::{
            FieldError, FormField, FormScalar, FormValues, NullableScalar, RecordForm,
            assert_form_scalar, links_include, links_key, parse_list, parse_password, parse_scalar,
            write_links,
        },
        resource::{ActionInput, required_input},
        schema::{
            ChoiceField, CustomField, EmbeddedForm, Field, FieldResolver, FileField, IntoSchema,
            Options, RepeaterField, RepeaterItem, Schema, TextField,
            embedded::{
                Embedded, EmbeddedBuilder, embedded_field, embedded_form, take_leaf, take_value,
            },
            form_key, parse_items,
            tree::Retype,
            write_items,
        },
        table::{ModelColumns, Table, column::model::pick},
        toasty_compat::VariantId,
    };
}
// The toolkit surface: Panel, Resource, Table, Schema, Notification,
// Tenancy, CSRF, and the `Db` glue.
pub mod auth;
pub mod csrf;
pub mod db;
mod declaration;
pub mod detail;
mod error;
pub mod extend;
pub mod form;
mod lens;
mod naming;
pub mod navigation;
pub mod notification;
mod page;
pub mod panel;
pub mod policy;
pub mod resource;
pub mod schema;
pub mod table;
pub mod tenancy;
#[cfg(test)]
mod test_support;
mod toasty_compat;
mod topcoat_compat;
pub mod upload;

/// The future a type-erased, dyn-compatible method returns.
pub(crate) type BoxFuture<'a, T> = std::pin::Pin<Box<dyn Future<Output = T> + Send + 'a>>;

pub use auth::{
    Auth, Authenticator, LoginThrottle, PanelUser, PasswordAuth, Registrar, SignUp, membership,
};
pub use declaration::{
    ActionInputFault, DeclarationError, DeclarationErrorKind, ManyToManyFault, MountError,
    SegmentFault, SignUpFault, Site,
};
pub use detail::{Detail, IntoDetail};
pub use form::{
    FieldError, FieldErrorKind, FieldErrors, FormField, FormScalar, FormValue, FormValues, NoForm,
    Posted, RecordForm,
};
pub use lens::Lens;
pub use navigation::{NavTarget, NavigationItem};
pub use notification::{Notification, NotificationStatus};
pub use page::{Page, PageDef, header_action_buttons};
pub use panel::{Brand, Panel, PanelHandle, RouterBuilderPanelExt, can_list, can_open, url};
pub use policy::{Ability, Allow, Deny, Policy, ReadOnly, when};
pub use resource::{
    Action, ActionInput, Committed, ForeignKey, HeaderAction, HeaderActions, Mutation, Places,
    PublicLink, Relation, Resource, ResourceDef, can, scoped_query, write_create, write_update,
};
pub use schema::{
    ChoiceField, CustomField, EmbeddedForm, Field, FieldResolver, FileField, Grid, Group,
    IntoFormValue, IntoOptions, IntoSchema, Options, RepeaterField, RepeaterItem, Schema, Section,
    Source, TextField, Toggle, Watched,
};
pub use table::{
    BooleanColumn, ColumnWidth, ComputedColumn, CountColumn, Cursor, DateColumn, DateFilter,
    DateValue, EmbeddedColumn, FileColumn, FilterValue, IntoColumns, IntoFilters, ModelColumns,
    QueryFilter, RelationColumn, RelationLens, RepeaterColumn, SelectFilter, Sort, Table,
    TablePage, TableState, TernaryFilter, TextColumn, ToOneRelation, WiredTable, contains_expr,
};
/// Derives [`ActionInput`](trait@ActionInput) for the typed value an [`Action`] asks for
/// before it runs.
///
/// ```rust
/// # #[derive(Debug, Clone, toasty::Model, tablo_core::ModelColumns)]
/// # struct Post { #[key] #[auto] id: uuid::Uuid, status: String }
/// # use tablo_core::{Action, ActionInput, NoForm, Resource};
/// # use topcoat::{Result, context::Cx};
/// # struct PostResource;
/// # impl Resource for PostResource {
/// #     type Model = Post;
/// #     type Form = NoForm<Post>;
/// # }
/// #[derive(tablo_core::ActionInput)]
/// pub struct Rejection {
///     #[form(multiline = 4)]
///     pub reason: String,
///     pub notify_author: bool,
/// }
///
/// struct Reject;
///
/// impl Action<PostResource> for Reject {
///     type Input = Rejection;
///     const NAME: &'static str = "reject";
///
///     async fn run(
///         _cx: &Cx,
///         posts: &[Post],
///         rejection: Rejection,
///         ex: &mut dyn toasty::Executor,
///     ) -> Result<()> {
///         // Store `rejection.reason`, notify when `rejection.notify_author` holds…
///         # let _ = (posts, rejection.reason, rejection.notify_author, ex);
///         Ok(())
///     }
/// }
/// ```
///
/// Each field posts its own name, which no column binds, and renders the control its type
/// picks: a `bool` a checkbox, `#[form(options)]` a choice over the field type's
/// [`Options`](derive@Options), `#[form(options = T)]` one over `T`'s, and any other
/// [`FormScalar`] a text input of the type's input type.
///
/// A field's **blank answer** is its `#[form(blank = ..)]`, `""` for an `#[form(optional)]`
/// `String`, `None` for an `Option`, or `false` for a `bool`. A field with none is required:
/// its control renders required and the parse refuses an empty submission.
///
/// # Per-field attributes
///
/// - `#[form(label = "Reason")]` — the control's label (default: the field name in sentence
///   case).
/// - `#[form(multiline = 4)]` — a `<textarea>` of 4 rows.
/// - `#[form(placeholder = "rust, async")]` — a text input's placeholder.
/// - `#[form(email)]` — a text input that refuses a malformed email address.
/// - `#[form(password)]` — a masked text input on a `String`, read untrimmed, that a refused
///   form renders empty.
/// - `#[form(blank = ..)]`, `#[form(optional)]` — the blank answer.
/// - `#[form(options)]`, `#[form(options = T)]` — a choice. An `Option<T>` field names its
///   options type: `#[form(options = T)]`.
///
/// A generic struct, a tuple struct, an empty struct (name `()` instead), an unknown key, a
/// text input's key with `options` or on a `bool`, `password` with `multiline`, and a field
/// that is not a `FormScalar` are compile errors.
/// [`RouterBuilderPanelExt::panel`] refuses a field named `csrf_token`, `confirm` or `ids`,
/// the keys an action's POST carries besides its input.
///
/// A hand-written impl builds its fields with [`Field::text_input`], [`Field::choice_input`]
/// and [`Field::toggle_input`]; its controls render without the `required` mark, though its
/// `parse` still refuses what it requires.
pub use tablo_macros::ActionInput;
/// Derives `EmbeddedForm` for an embedded struct or enum.
///
/// Builds the schema node and converts the value through that node's keys.
///
/// ```rust,no_run
/// # #[derive(Debug, Clone, toasty::Model, tablo_core::ModelColumns)]
/// # struct Post {
/// #     #[key] #[auto] id: uuid::Uuid,
/// #     publication: Publication,
/// # }
/// # use tablo_core::Section;
/// #[derive(Debug, Clone, toasty::Embed, tablo_core::EmbeddedForm)]
/// pub enum Publication {
///     #[column(variant = 1)]
///     Scheduled {
///         #[shared(timestamp)]
///         #[form(label = "Publication timestamp")]
///         scheduled_at: String,
///         scheduled_for: String,
///     },
///     #[column(variant = 2)]
///     Published {
///         #[shared(timestamp)]
///         published_at: String,
///         canonical_url: String,
///     },
/// }
///
/// // form declaration — no field bindings written by hand
/// Section::new("Publication").schema(Publication::form(Post::fields().publication()));
/// ```
///
/// # How a field is classified
///
/// A field marked `#[form(embed)]` is another **embedded value**, delegated to
/// its own `EmbeddedForm`. Every other field is a **scalar**: one column, read
/// and written through `FormScalar` (`String`, a `TypedValue` type, an
/// `Options` enum, or an `Option` of one). A scalar of another type fails to compile at the
/// field, naming the trait. An empty scalar is its blank answer — its declared
/// `#[form(blank = ..)]`, `None` for an `Option`, `false` for a `bool`, `""`
/// for an `#[form(optional)]` `String` — and a scalar with none is required:
/// its control renders required and the parse refuses its key.
///
/// # Which variant an enum reads
///
/// A named discriminant always wins, and an undeclared one is refused;
/// otherwise the first variant, in declaration order, with a **payload of its
/// own** submitted — a `#[shared(..)]` column belongs to several variants and
/// never selects one; otherwise the first variant.
///
/// A `#[shared(..)]` column renders once, and a variant that does not declare it
/// neither shows nor submits it: it is a conditional field there, so a variant
/// that omits it needs the column to have a blank answer.
///
/// # Per-field attributes
///
/// - `#[form(embed)]` — a nested `EmbeddedForm` value.
/// - `#[form(label = "Canonical URL")]` — the control's label (default: the field name in
///   sentence case, `canonical_url` → "Canonical url").
/// - `#[form(multiline = 3)]` — a `<textarea>` of 3 rows.
/// - `#[form(blank = ..)]` — what an empty submission reads as.
/// - `#[form(optional)]` on a `String` — an empty submission reads as `""`.
///
/// Anything else in `#[form(..)]` is a compile error, as are `label`, `multiline`, `blank` and
/// `optional` on an embedded value, `blank` or `optional` on an `Option`, and `optional` on a
/// type other than `String`.
pub use tablo_macros::EmbeddedForm;
/// Derive a model's [`ModelColumns`](trait@ModelColumns): the table a resource lists it in and
/// the detail page it shows it on, when the resource declares neither.
///
/// ```rust
/// # #[derive(Debug, Clone, Copy, PartialEq, Eq, toasty::Embed, tablo_core::Options)]
/// # pub enum Role { Admin, Member }
/// #[derive(Debug, Clone, toasty::Model, tablo_core::ModelColumns)]
/// pub struct User {
///     #[key]
///     #[auto]
///     pub id: uuid::Uuid,
///     pub name: String,
///     pub role: Role,
///     pub active: bool,
///     #[columns(skip)]
///     pub password_hash: String,
///     #[default(jiff::Timestamp::now())]
///     pub created_at: jiff::Timestamp,
/// }
///
/// // Lists `name`, `role`, `active` and `created_at`, and shows them on the detail page.
/// let table = <User as tablo_core::ModelColumns>::table();
/// # let _ = table;
/// ```
///
/// Each field shows whoever writes it, the person through a form or Toasty through a
/// `#[default]` or an `#[update]`, in a column its type picks:
///
/// - a `bool`: a sortable [`BooleanColumn`], yes or no;
/// - a `String` or `Option<String>`: a sortable, searchable [`TextColumn`];
/// - any other [`FormScalar`]: a sortable [`TextColumn`], an [`Options`](derive@Options) enum
///   by its label;
/// - an [`EmbeddedForm`](derive@EmbeddedForm) value: an [`EmbeddedColumn`], leaf by leaf, on
///   the detail page only;
/// - a list of [`RepeaterItem`](derive@RepeaterItem) values: a [`RepeaterColumn`], on the
///   detail page only;
/// - any other type: no column.
///
/// No column shows a key Toasty generates, a `#[version]` field, a relation or its foreign
/// key, which only a declared [`RelationColumn`] shows, by the related record's title, or a
/// `TenantId` or `Option<TenantId>` field, which belongs to the resource's [`Tenancy`]. An
/// `#[auto]` `created_at` or `updated_at` shows like any timestamp.
///
/// Every other field shows, a secret such as a password hash or an API token included, to
/// anyone the policy lets view the list: mark it `#[columns(skip)]`, which leaves it out of
/// the table, its search and export, and the detail page. On a field already left out it is a
/// compile error, as are an unknown key and a generic model.
///
/// The derive reads the model, not a form: a file path shows as text and a `String` an
/// `#[form(options = ..)]` key labels shows its stored value. Declare a [`FileColumn`] or a
/// formatted [`TextColumn`] for them.
///
/// A resource replaces either default with [`ResourceDef::table`] or [`ResourceDef::detail`],
/// and extends one by starting from it: `User::table().filters(..)`, with
/// [`ModelColumns`](trait@ModelColumns) in scope.
pub use tablo_macros::ModelColumns;
/// Derive a model's [`RecordForm`](derive@RecordForm) struct from the model: the fields a
/// person fills, named and typed as the model declares them.
///
/// ```rust
/// #[derive(Debug, Clone, toasty::Model, tablo_core::ModelColumns, tablo_core::ModelForm)]
/// pub struct Book {
///     #[key]
///     #[auto]
///     pub id: uuid::Uuid,
///     pub title: String,
///     #[form(optional)]
///     pub subtitle: String,
///     #[default(jiff::Timestamp::now())]
///     pub created_at: jiff::Timestamp,
/// }
///
/// // The derive wrote `BookForm { title, subtitle }`, with `BookFormField` and
/// // `BookFormControls`, as `#[derive(RecordForm)]` would.
/// let form = BookForm {
///     title: "Dune".into(),
///     subtitle: String::new(),
/// };
/// # let _ = form;
/// ```
///
/// The form leaves out what no person fills: a key, so an edit never rewrites it, an
/// `#[auto]`, `#[update]` or `#[version]` field, a relation, and a `TenantId` or
/// `Option<TenantId>` field, which belongs to the resource's [`Tenancy`]. A form key on one of
/// those is a compile error naming the fix. A `#[default]` field and a `#[belongs_to]` foreign
/// key are left out unless a form key opts them in, such as `#[form(repeat)]` on a defaulted
/// list or `#[form(relationship = AuthorResource)]` on a foreign key. `#[form(skip)]` leaves
/// out any other field. When the policy allows `Create`, mounting refuses a non-nullable
/// column left out, such as a key a person picks, unless an overridden `create_record` names
/// it with `create_column`.
///
/// Each field keeps the model field's visibility and docs. A field's `#[form(..)]` keys are
/// [`RecordForm`](derive@RecordForm)'s, as are the form's checks and defaults.
/// `#[form(name = BookEditor)]` on the model names the form, `BookForm` otherwise. A form
/// whose fields differ from the model's, such as a many-to-many field's keys, is a
/// `#[derive(RecordForm)]` struct.
pub use tablo_macros::ModelForm;
/// Derive `Options` for a unit-variant enum: the `(value, label)` list a
/// choice field, a select filter and a column share, and the `FormScalar`
/// that posts a variant as its value and reads it as its label.
///
/// ```rust
/// # use tablo_core::Options;
/// #[derive(Debug, Clone, Copy, PartialEq, Eq, toasty::Embed, tablo_core::Options)]
/// pub enum Status {
///     Draft,
///     #[option(label = "Live")]
///     Published,
/// }
///
/// assert_eq!(Status::Published.value(), "published");
/// assert_eq!(Status::Published.label(), "Live");
/// assert_eq!(Status::from_value("draft"), Some(Status::Draft));
/// ```
///
/// Each variant's value is its `snake_case` name and its label that name in
/// sentence case. `#[option(value = "..")]` and `#[option(label = "..")]`
/// override either. A generic enum, a variant with fields, two variants
/// sharing one value or one label, and an unknown key are compile errors.
///
/// The enum, and an `Option` of it, is a form scalar through this derive, so
/// it cannot also implement `TypedValue` or `FormScalar` itself.
pub use tablo_macros::Options;
/// Derive `RecordForm` for the typed value a resource's form writes.
///
/// One field per model column the form writes, named and typed like the
/// model's field. A scalar (`String`, a `TypedValue` type, an `Options` enum,
/// or an `Option` of one) binds the key its control posts; a `#[form(embed)]` field binds
/// every key of an `EmbeddedForm` value and is written whole.
///
/// ```rust
/// # #[derive(Debug, Clone, toasty::Model, tablo_core::ModelColumns)]
/// # pub struct User {
/// #     #[key] #[auto] id: uuid::Uuid,
/// #     name: String,
/// #     role: String,
/// #     age: i64,
/// # }
/// #[derive(tablo_core::RecordForm)]
/// #[form(model = User)]
/// pub struct UserForm {
///     pub name: String,
///     #[form(blank = "member")]
///     pub role: String,
///     #[form(blank = 0)]
///     pub age: i64,
/// }
/// ```
///
/// The derive also emits `UserFormField`, one variant per field, which
/// `Posted` and `Resource::validate_record`'s `FieldErrors` key on and
/// `RecordForm::fields` answers with each variant's keys.
/// It emits `UserFormControls`, one control per field chosen from the field —
/// a `bool` is a toggle, `#[form(options = T)]` a choice over `T`'s options,
/// `#[form(options)]` a choice over the field type's options,
/// `#[form(relationship = R)]` a choice over `R`'s records (a multiple choice over a `Vec` of
/// their keys), `#[form(file)]` a file field, `#[form(embed)]` the embedded value's schema,
/// `#[form(repeat)]` a repeater, and any
/// other field a text field — with `controls()` handing them over, typed by the form so only a
/// `Schema<UserForm>` places them, and `RecordForm::control` answering one
/// field's. A resource's `ResourceDef` defaults its form to them; `ResourceDef::form` arranges
/// or extends them instead, and a form renders the controls it does not place after the ones
/// it does. The table and detail page read the model, not the form: see
/// [`ModelColumns`](derive@ModelColumns).
///
/// # Attributes
///
/// - `#[form(model = User)]` on the struct: the model the form writes.
/// - `#[form(blank = <expr>)]` on a scalar: the value an empty submission reads as.
/// - `#[form(optional)]` on a `String`: an empty submission reads as `""`.
/// - `#[form(options)]` on an `Options` enum or an `Option` of one: a choice over its options.
///   Without it, the field is a text field.
/// - `#[form(options = Status)]`: a choice over `Status::options()`.
/// - `#[form(relationship = AuthorResource)]` on a foreign key: a choice over the source's
///   records, each labelled by its `record_title`. The source is any `OptionSource`, which
///   every `Resource` is.
/// - `#[form(relationship = TagResource)]` on a `Vec` of the source's keys, named like the
///   model's `#[has_many(via = joins.target)]` field: a many-to-many field, a multiple choice
///   whose records the write links through the join model, one row each. No record is its
///   blank answer; an edit that does not post it keeps the record's links.
/// - `#[form(file)]` on a `String`: a file field.
/// - `#[form(embed)]` on an `EmbeddedForm` value.
/// - `#[form(repeat)]` on a `#[document]` list of [`RepeaterItem`](derive@RepeaterItem)
///   values: a repeater, a row per item, which the browser adds, removes and moves. No rows is
///   its blank answer.
///
/// A scalar's **blank answer** is its `blank`, `""` for an `optional` `String`, `None` for an
/// `Option`, or `false` for a `bool`. A field with none is required: the panel renders its
/// control required and the parse refuses an empty submission. No control declares presence.
///
/// A generic struct, a tuple struct, an empty struct, a `Deferred<_>` field,
/// `blank` or `optional` on an `Option`, an embedded value or a many-to-many field, `optional`
/// on a type other than `String`, and an unknown key are compile errors. So are a field the
/// model lacks, a type the model's field does not have, a scalar that is not a `FormScalar`,
/// and a many-to-many field whose keys are not its source's primary key.
pub use tablo_macros::RecordForm;
/// Derives [`RepeaterItem`](trait@RepeaterItem) for one item of a repeater: an embedded struct
/// a `#[document]` list stores.
///
/// ```rust
/// #[derive(Debug, Clone, toasty::Embed, tablo_core::RepeaterItem)]
/// pub struct Link {
///     pub label: String,
///     #[form(label = "URL")]
///     pub url: String,
/// }
///
/// #[derive(Debug, Clone, toasty::Model, tablo_core::ModelColumns)]
/// pub struct Post {
///     #[key]
///     #[auto]
///     id: uuid::Uuid,
///     #[document]
///     #[default(Vec::<Link>::new())]
///     links: Vec<Link>,
/// }
///
/// #[derive(tablo_core::RecordForm)]
/// #[form(model = Post)]
/// pub struct PostForm {
///     #[form(repeat)]
///     pub links: Vec<Link>,
/// }
/// ```
///
/// Its fields, controls and attributes are an [`ActionInput`](derive@ActionInput)'s: each row
/// posts them under its own prefix (`links.0.url`). An item's blank answers and required
/// fields work the same way, and each row answers to its controls' own rules, such as a choice
/// offering only its options. A repeater takes at most [`MAX_ROWS`](schema::MAX_ROWS) rows.
pub use tablo_macros::RepeaterItem;
pub use tenancy::{Membership, Tenancy, Tenant, TenantColumn, TenantId, require_tenant, tenant_id};
pub use upload::{DirUploader, Uploader};