updated docs and added custom type example

maccesch · maccesch · commit 747811bfa0e3 · 2024-02-07T22:31:48.000Z
diff --git a/.idea/leptos-struct-table.iml b/.idea/leptos-struct-table.iml
diff --git a/examples/custom_renderers_svg/src/renderers.rs b/examples/custom_renderers_svg/src/renderers.rs
@@ -20,7 +20,7 @@ pub fn SvgRowRenderer<Row>(
     on_change: EventHandler<ChangeEvent<Row>>,
 ) -> impl IntoView
 where
-    Row: RowRenderer + Clone + 'static,
+    Row: TableRow + Clone + 'static,
 {
     let transform = format!("translate(0, {})", (index + 1) * ROW_HEIGHT);
 
diff --git a/examples/custom_type/Cargo.toml b/examples/custom_type/Cargo.toml
@@ -0,0 +1,19 @@
+[package]
+name = "custom_type"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+leptos = { version = "0.6", features = ["nightly", "csr"] }
+leptos-struct-table = { path = "../..", features = ["chrono"] }
+chrono = { version = "0.4", features = ["serde"] }
+console_error_panic_hook = "0.1"
+console_log = "1"
+log = "0.4"
+async-trait = "0.1"
+derive_more = { version = "0.99" }
+
+[dev-dependencies]
+wasm-bindgen = "0.2"
+wasm-bindgen-test = "0.3.0"
+web-sys = "0.3"
diff --git a/examples/custom_type/README.md b/examples/custom_type/README.md
@@ -0,0 +1,16 @@
+A table example with custom local data stored as `Vec<Rc<Book>>`.
+
+If you don't have it installed already, install [Trunk](https://trunkrs.dev/) 
+as well as the nightly toolchain for Rust and the wasm32-unknown-unknown target:
+
+```bash
+cargo install trunk
+rustup toolchain install nightly
+rustup target add wasm32-unknown-unknown
+```
+
+Then, to run this example, execute in a terminal:
+
+```bash
+trunk serve --open
+```
diff --git a/examples/custom_type/index.html b/examples/custom_type/index.html
@@ -0,0 +1,5 @@
+<!DOCTYPE html>
+<html>
+  <head></head>
+  <body></body>
+</html>
diff --git a/examples/custom_type/rust-toolchain.toml b/examples/custom_type/rust-toolchain.toml
@@ -0,0 +1,2 @@
+[toolchain]
+channel = "nightly"
diff --git a/examples/custom_type/src/main.rs b/examples/custom_type/src/main.rs
@@ -0,0 +1,69 @@
+#![deny(missing_docs)]
+//! Simple showcase example.
+
+use chrono::NaiveDate;
+use derive_more::{Deref, DerefMut};
+use leptos::*;
+use leptos_struct_table::*;
+use std::rc::Rc;
+
+/// This generates the component BookTable
+#[derive(TableRow)]
+#[table(sortable, impl_vec_data_provider, row_type = "RcBook")]
+pub struct Book {
+    /// Title of the book.
+    pub title: String,
+    /// Author of the book.
+    pub author: String,
+    /// Date when book has been published.
+    pub publish_date: Option<NaiveDate>,
+    /// Description of the book. Optional.
+    #[table(none_value = "-")]
+    pub description: Option<String>,
+}
+
+/// New-type pattern because otherwise the impl TableRow doesn't work because of orphan rules.
+#[derive(Deref, DerefMut, Clone)]
+pub struct RcBook(Rc<Book>);
+
+fn main() {
+    _ = console_log::init_with_level(log::Level::Debug);
+    console_error_panic_hook::set_once();
+
+    mount_to_body(|| {
+        let rows = vec![
+            RcBook(Rc::new(Book {
+                title: "The Great Gatsby".to_string(),
+                author: "F. Scott Fitzgerald".to_string(),
+                publish_date: Some(NaiveDate::from_ymd_opt(1925, 4, 10).unwrap()),
+                description: Some(
+                    "A story of wealth, love, and the American Dream in the 1920s.".to_string(),
+                ),
+            })),
+            RcBook(Rc::new(Book {
+                title: "The Grapes of Wrath".to_string(),
+                author: "John Steinbeck".to_string(),
+                publish_date: Some(NaiveDate::from_ymd_opt(1939, 4, 14).unwrap()),
+                description: None,
+            })),
+            RcBook(Rc::new(Book {
+                title: "Nineteen Eighty-Four".to_string(),
+                author: "George Orwell".to_string(),
+                publish_date: Some(NaiveDate::from_ymd_opt(1949, 6, 8).unwrap()),
+                description: None,
+            })),
+            RcBook(Rc::new(Book {
+                title: "Ulysses".to_string(),
+                author: "James Joyce".to_string(),
+                publish_date: Some(NaiveDate::from_ymd_opt(1922, 2, 2).unwrap()),
+                description: None,
+            })),
+        ];
+
+        view! {
+            <table>
+                <TableContent rows/>
+            </table>
+        }
+    })
+}
diff --git a/src/class_providers/bootstrap.rs b/src/class_providers/bootstrap.rs
@@ -13,4 +13,6 @@ impl TableClassesProvider for BootstrapClassesPreset {
 
         format!("{} {}", active, template_classes)
     }
+
+    // TODO : skeleton loading
 }
diff --git a/src/class_providers/mod.rs b/src/class_providers/mod.rs
@@ -61,6 +61,7 @@ pub trait TableClassesProvider {
         prop_class.to_string()
     }
 
+    #[allow(unused_variables)]
     /// Get the classes for the elements inside of the cells of rows that are currently
     /// being loaded. Usually this will be some loading indicator like a sceleton bar.
     /// The `prop_class` parameter contains the classes specified in the
diff --git a/src/components/mod.rs b/src/components/mod.rs
@@ -22,6 +22,11 @@ macro_rules! wrapper_render_fn {
         /// Default
         #[$doc_name]
         /// renderer. Please note that this is **NOT** a `#[component]`.
+        ///
+        /// # Arguments
+        ///
+        /// * `content` - The content of the renderer. It's like the children of this view.
+        /// * `class` - The class attribute that is passed to the root element
         $(#[$additional_doc])*
         #[allow(non_snake_case)]
         pub fn $name(content: View, class: Signal<String>) -> impl IntoView {
diff --git a/src/components/row.rs b/src/components/row.rs
@@ -1,4 +1,4 @@
-use crate::row_renderer::RowRenderer;
+use crate::table_row::TableRow;
 use crate::{ChangeEvent, EventHandler};
 use leptos::*;
 
@@ -20,7 +20,7 @@ pub fn DefaultTableRowRenderer<Row>(
     on_change: EventHandler<ChangeEvent<Row>>,
 ) -> impl IntoView
 where
-    Row: RowRenderer + Clone + 'static,
+    Row: TableRow + Clone + 'static,
 {
     view! {
         <tr class=class on:click=move |mouse_event| on_select.run(mouse_event)>
diff --git a/src/components/table_content.rs b/src/components/table_content.rs
@@ -1,7 +1,7 @@
 use crate::components::renderer_fn::renderer_fn;
 use crate::loaded_rows::{LoadedRows, RowState};
-use crate::row_renderer::RowRenderer;
 use crate::selection::Selection;
+use crate::table_row::TableRow;
 use crate::{
     ChangeEvent, ColumnSort, DefaultErrorRowRenderer, DefaultLoadingRowRenderer,
     DefaultRowPlaceholderRenderer, DefaultTableBodyRenderer, DefaultTableHeadRenderer,
@@ -31,7 +31,7 @@ renderer_fn!(
         on_change: EventHandler<ChangeEvent<Row>>
     )
     default DefaultTableRowRenderer
-    where Row: RowRenderer + Clone + 'static
+    where Row: TableRow + Clone + 'static
 );
 
 renderer_fn!(
@@ -56,28 +56,101 @@ renderer_fn!(
 /// Render the content of a table. This is the main component of this crate.
 #[component]
 pub fn TableContent<Row, DataP, ClsP>(
+    /// The data to be rendered in this table.
+    /// This must implement [`TableDataProvider`] or [`PaginatedTableDataProvider`].
     rows: DataP,
-    #[prop(optional, into)] scroll_container: ScrollContainer,
-    #[prop(optional, into)] on_change: EventHandler<ChangeEvent<Row>>,
-    #[prop(optional, into)] selection: Selection,
-    #[prop(optional, into)] on_selection_change: EventHandler<SelectionChangeEvent<Row>>,
-    #[prop(default = DefaultTableHeadRenderer.into(), into)] thead_renderer: WrapperRendererFn,
-    #[prop(default = DefaultTableBodyRenderer.into(), into)] tbody_renderer: WrapperRendererFn,
+
+    /// The container element which has scrolling capabilities. By default this is the `body` element.
+    #[prop(optional, into)]
+    scroll_container: ScrollContainer,
+
+    /// Event handler for when a row is edited.
+    /// Check out the [editable example](https://github.com/Synphonyte/leptos-struct-table/blob/master/examples/editable/src/main.rs).
+    #[prop(optional, into)]
+    on_change: EventHandler<ChangeEvent<Row>>,
+
+    /// Selection mode together with the `RwSignal` to hold the selection. Available modes are
+    /// - `None` - No selection (default)
+    /// - `Single` - Single selection
+    /// - `Multiple` - Multiple selection
+    ///
+    /// Please see [`Selection`] for more information and check out the
+    /// [selectable example](https://github.com/Synphonyte/leptos-struct-table/blob/master/examples/selectable/src/main.rs).
+    #[prop(optional, into)]
+    selection: Selection,
+
+    /// Event handler callback for when the selection changes.
+    /// See the [selectable example](https://github.com/Synphonyte/leptos-struct-table/blob/master/examples/selectable/src/main.rs) for details.
+    #[prop(optional, into)]
+    on_selection_change: EventHandler<SelectionChangeEvent<Row>>,
+
+    /// Renderer function for the table head. Defaults to [`DefaultTableHeadRenderer`]. For a full example see the
+    /// [custom_renderers_svg example](https://github.com/Synphonyte/leptos-struct-table/blob/master/examples/custom_renderers_svg/src/main.rs).
+    #[prop(default = DefaultTableHeadRenderer.into(), into)]
+    thead_renderer: WrapperRendererFn,
+
+    /// Renderer function for the table body. Defaults to [`DefaultTableBodyRenderer`]. For a full example see the
+    /// [custom_renderers_svg example](https://github.com/Synphonyte/leptos-struct-table/blob/master/examples/custom_renderers_svg/src/main.rs).
+    #[prop(default = DefaultTableBodyRenderer.into(), into)]
+    tbody_renderer: WrapperRendererFn,
+
+    /// Renderer function for the table head row. Defaults to [`DefaultTableHeadRowRenderer`]. For a full example see the
+    /// [custom_renderers_svg example](https://github.com/Synphonyte/leptos-struct-table/blob/master/examples/custom_renderers_svg/src/main.rs).
     #[prop(default = DefaultTableHeadRowRenderer.into(), into)]
     thead_row_renderer: WrapperRendererFn,
-    #[prop(optional, into)] row_renderer: RowRendererFn<Row>,
-    #[prop(optional, into)] loading_row_renderer: LoadingRowRendererFn,
-    #[prop(optional, into)] error_row_renderer: ErrorRowRendererFn,
-    #[prop(optional, into)] row_placeholder_renderer_fn: RowPlaceholderRendererFn,
-    #[prop(optional, into)] row_class: MaybeSignal<String>,
-    #[prop(optional, into)] thead_class: MaybeSignal<String>,
-    #[prop(optional, into)] thead_row_class: MaybeSignal<String>,
-    #[prop(optional, into)] tbody_class: MaybeSignal<String>,
-    #[prop(optional, into)] loading_cell_class: MaybeSignal<String>,
-    #[prop(optional, into)] loading_cell_inner_class: MaybeSignal<String>,
-    #[prop(default = create_rw_signal(VecDeque::new()), into)] sorting: RwSignal<
-        VecDeque<(usize, ColumnSort)>,
-    >,
+
+    /// The row renderer. Defaults to [`DefaultTableRowRenderer`]. For a full example see the
+    /// [custom_renderers_svg example](https://github.com/Synphonyte/leptos-struct-table/blob/master/examples/custom_renderers_svg/src/main.rs).
+    #[prop(optional, into)]
+    row_renderer: RowRendererFn<Row>,
+
+    /// The row renderer for when that row is currently being loaded.
+    /// Defaults to [`DefaultLoadingRowRenderer`]. For a full example see the
+    /// [custom_renderers_svg example](https://github.com/Synphonyte/leptos-struct-table/blob/master/examples/custom_renderers_svg/src/main.rs).
+    #[prop(optional, into)]
+    loading_row_renderer: LoadingRowRendererFn,
+
+    /// The row renderer for when that row failed to load.
+    /// Defaults to [`DefaultErrorRowRenderer`]. For a full example see the
+    /// [custom_renderers_svg example](https://github.com/Synphonyte/leptos-struct-table/blob/master/examples/custom_renderers_svg/src/main.rs).
+    #[prop(optional, into)]
+    error_row_renderer: ErrorRowRendererFn,
+
+    /// The row placeholder renderer. Defaults to [`DefaultRowPlaceholderRenderer`].
+    /// This is used in place of rows that are not shown
+    /// before and after the currently visible rows.
+    #[prop(optional, into)]
+    row_placeholder_renderer_fn: RowPlaceholderRendererFn,
+
+    /// Additional classes to add to rows
+    #[prop(optional, into)]
+    row_class: MaybeSignal<String>,
+
+    /// Additional classes to add to the thead
+    #[prop(optional, into)]
+    thead_class: MaybeSignal<String>,
+
+    /// Additional classes to add to the row inside the thead
+    #[prop(optional, into)]
+    thead_row_class: MaybeSignal<String>,
+
+    /// Additional classes to add to the tbody
+    #[prop(optional, into)]
+    tbody_class: MaybeSignal<String>,
+
+    /// Additional classes to add to the cell inside a row that is being loaded
+    #[prop(optional, into)]
+    loading_cell_class: MaybeSignal<String>,
+
+    /// Additional classes to add to the inner element inside a cell that is inside a row that is being loaded
+    #[prop(optional, into)]
+    loading_cell_inner_class: MaybeSignal<String>,
+
+    /// The sorting to apply to the table.
+    /// For this to work you have add `#[table(sortable)]` to your struct.
+    /// Please see the [simple example](https://github.com/Synphonyte/leptos-struct-table/blob/master/examples/simple/src/main.rs).
+    #[prop(default = create_rw_signal(VecDeque::new()), into)]
+    sorting: RwSignal<VecDeque<(usize, ColumnSort)>>,
 
     /// This is called once the number of rows is known.
     /// It will only be executed if [`TableDataProvider::row_count`] returns `Some(...)`.
@@ -96,16 +169,16 @@ pub fn TableContent<Row, DataP, ClsP>(
 
     /// The display strategy to use when rendering the table.
     /// Can be one of
-    ///  - `Virtualization`
-    ///  - `InfiniteScroll`
-    ///  - `Pagination`  
+    /// - `Virtualization`
+    /// - `InfiniteScroll`
+    /// - `Pagination`  
     ///
     /// Please check [`DisplayStrategy`] to see explanations of all available options.
     #[prop(optional)]
     display_strategy: DisplayStrategy,
 ) -> impl IntoView
 where
-    Row: RowRenderer<ClassesProvider = ClsP> + Clone + 'static,
+    Row: TableRow<ClassesProvider = ClsP> + Clone + 'static,
     DataP: TableDataProvider<Row> + 'static,
     ClsP: TableClassesProvider + Copy + 'static,
 {
@@ -487,7 +560,7 @@ fn compute_average_row_height_from_loaded<Row, ClsP>(
     placeholder_height_before: Signal<f64>,
     loaded_rows: RwSignal<LoadedRows<Row>>,
 ) where
-    Row: RowRenderer<ClassesProvider = ClsP> + Clone + 'static,
+    Row: TableRow<ClassesProvider = ClsP> + Clone + 'static,
 {
     if let Some(el) = tbody_el.get_untracked() {
         let el: &web_sys::Element = &el;
diff --git a/src/data_provider.rs b/src/data_provider.rs
@@ -59,6 +59,11 @@ pub trait TableDataProvider<Row> {
 /// of connecting to a paginated data source instead of implementing [`TableDataProvider`] directly.
 ///
 /// If you implement this for your struct, [`TableDataProvider`] is automatically implemented for you.
+///
+/// > Please note that this is independent from using [`DisplayStrategy::Pagination`] with [`TableContent`].
+/// > You do not have implement this trait if you're using pagination and you vice versa if you're not using pagination
+/// > you can still implement this trait. And in case if you use this trait together with pagination the
+/// > display row count can be different from the `PAGE_ROW_COUNT`.
 #[async_trait(?Send)]
 pub trait PaginatedTableDataProvider<Row> {
     /// How many rows per page
diff --git a/src/display_strategy.rs b/src/display_strategy.rs
@@ -23,6 +23,7 @@ pub enum DisplayStrategy {
     ///
     /// > Please note that this will work wether your data source implements
     /// > [`PaginatedTableDataProvider`] or [`TableDataProvider`] directly.
+    /// > Also `row_count` can be different from `PaginatedTableDataProvider::PAGE_ROW_COUNT`.
     Pagination {
         row_count: usize,
         controller: PaginationController,
diff --git a/src/lib.rs b/src/lib.rs
diff --git a/src/reload_controller.rs b/src/reload_controller.rs
diff --git a/src/table_row.rs b/src/table_row.rs

Original file line number	Diff line number	Diff line change
`@@ -20,7 +20,7 @@ pub fn SvgRowRenderer<Row>(`
`20`	`20`	`on_change: EventHandler<ChangeEvent<Row>>,`
`21`	`21`	`) -> impl IntoView`
`22`	`22`	`where`
`23`		`- Row: RowRenderer + Clone + 'static,`
	`23`	`+ Row: TableRow + Clone + 'static,`
`24`	`24`	`{`
`25`	`25`	`let transform = format!("translate(0, {})", (index + 1) * ROW_HEIGHT);`
`26`	`26`
Original file line number	Diff line number	Diff line change
`@@ -13,4 +13,6 @@ impl TableClassesProvider for BootstrapClassesPreset {`
`13`	`13`
`14`	`14`	`format!("{} {}", active, template_classes)`
`15`	`15`	`}`
	`16`	`+`
	`17`	`+ // TODO : skeleton loading`
`16`	`18`	`}`
Original file line number	Diff line number	Diff line change
`@@ -61,6 +61,7 @@ pub trait TableClassesProvider {`
`61`	`61`	`prop_class.to_string()`
`62`	`62`	`}`
`63`	`63`
	`64`	`+ #[allow(unused_variables)]`
`64`	`65`	`/// Get the classes for the elements inside of the cells of rows that are currently`
`65`	`66`	`/// being loaded. Usually this will be some loading indicator like a sceleton bar.`
`66`	`67`	/// The `prop_class` parameter contains the classes specified in the