improve readme

.gitignore

@@ -5,3 +5,5 @@ node_modules
 docs
 inst/doc
 wiki
+
+/.quarto/

README.Rmd

@@ -15,6 +15,7 @@ knitr::opts_chunk$set(
 
 library(blockr)
 library(bslib)
+library(DiagrammeR)
 ```
 
 # blockr
@@ -26,29 +27,114 @@ library(bslib)
 
 Building blocks for data manipulation and visualization operations.
 
-`{blockr}` has been built for webR (wasm) and is available for download with 
-`webr::install("blockr", repos = c("https://blockr-org.github.io/webr-repos", "https://repo.r-wasm.org"))`.
+```{r, echo=FALSE}
+mermaid("
+  flowchart TD
+  subgraph LR workspace[Workspace]
+    subgraph stack1[Stack]
+      direction LR
+      subgraph input_block[Block 1]
+        input(Data: dataset, browser, ...)
+      end
+      subgraph transform_block[Block 2]
+        transform(Transform block: filter, select ...)
+      end
+      subgraph output_block[Block 3]
+        output(Result/transform: plot, filter, ...)
+      end
+      input_block --> |data| transform_block --> |data| output_block
+    end
+    subgraph stack2[Stack 2]
+      stack1_data[Stack 1 data] --> |data| transform2[Transform]
+    end
+    stack1 --> |data| stack2
+    subgraph stackn[Stack n]
+      stacki_data[Stack i data] --> |data| transformn[Transform] --> |data| Visualize
+    end
+    stack2 ---> |... data| stackn
+  end
+  ",
+  height = "500px"
+) |>
+  htmlwidgets::onRender(
+    "function(el, x) {
+      el.classList.add('text-center')
+    }
+    "
+  )
+```
+
+Key features:
+
+1. **User-Friendly Interface**: Build data pipelines with intuitive interface.
+2. **Flexibility**: Easily add, remove, or rearrange blocks in your pipeline.
+3. **Extensibility**: Developers can create custom blocks to extend functionality.
+4. **Reproducibility**: Pipelines created with `blockr` are easily shareable and reproducible, with exportable code.
+5. **Interactivity**: Real-time feedback as you build and modify your pipeline.
+
+## Installation
+
+You can install the development version of blockr from [GitHub](https://github.com/) with:
 
 ```r
-library(blockr)
-library(blockr.data)
+pak::pak("blockr-org/blockr")
+```
 
-data_block <- new_dataset_block(selected = "lab", package = "blockr.data")
+## Example: palmer penguins case study
+
+Below is a simple case study involving `{blockr}`. We use the palmerpenguins dataset to find out which
+femal species has the largest flippers. We create 2 custom blocks allowing to create our plot block (see the plot vignette for more details). Note that the `{blockr.ggplot2}` package exposes some ready to use blocks.
+
+```r
+library(blockr)
+library(palmerpenguins)
+library(ggplot2)
+
+new_ggplot_block <- function(col_x = character(), col_y = character(), ...) {
+
+  data_cols <- function(data) colnames(data)
+
+  new_block(
+    fields = list(
+      x = new_select_field(col_x, data_cols, type = "name"),
+      y = new_select_field(col_y, data_cols, type = "name")
+    ),
+    expr = quote(
+      ggplot(mapping = aes(x = .(x), y = .(y)))
+    ),
+    class = c("ggplot_block", "plot_block"),
+    ...
+  )
+}
+
+new_geompoint_block <- function(color = character(), shape = character(), ...) {
+
+  data_cols <- function(data) colnames(data$data)
+
+  new_block(
+    fields = list(
+      color = new_select_field(color, data_cols, type = "name"),
+      shape = new_select_field(shape, data_cols, type = "name")
+    ),
+    expr = quote(
+      geom_point(aes(color = .(color), shape = .(shape)), size = 2)
+    ),
+    class = c("plot_layer_block", "plot_block"),
+    ...
+  )
+}
 
 stack <- new_stack(
-  data_block,
-  new_select_block
+  data_block = new_dataset_block("penguins", "palmerpenguins"),
+  filter_block = new_filter_block("sex", "female"), 
+  plot_block = new_ggplot_block("flipper_length_mm", "body_mass_g"),
+  layer_block = new_geompoint_block("species", "species")
 )
 serve_stack(stack)
 ```
 
-## Installation
-
-You can install the development version of blockr from [GitHub](https://github.com/) with:
-
-```r
-# install.packages("devtools")
-pak::pkg_install("blockr-org/blockr")
+```{r blockr-penguins-stack, echo=FALSE, fig.cap='Penguins app demo', fig.align = 'center', out.width='100%'}
+knitr::include_graphics("vignettes/figures/blockr-penguins-stack.png")
 ```
 
 ## Contribute

README.md

@@ -11,31 +11,87 @@
 
 Building blocks for data manipulation and visualization operations.
 
-`{blockr}` has been built for webR (wasm) and is available for download
-with
-`webr::install("blockr", repos = c("https://blockr-org.github.io/webr-repos", "https://repo.r-wasm.org"))`.
+Key features:
+
+1.  **User-Friendly Interface**: Build data pipelines with intuitive
+    interface.
+2.  **Flexibility**: Easily add, remove, or rearrange blocks in your
+    pipeline.
+3.  **Extensibility**: Developers can create custom blocks to extend
+    functionality.
+4.  **Reproducibility**: Pipelines created with `blockr` are easily
+    shareable and reproducible, with exportable code.
+5.  **Interactivity**: Real-time feedback as you build and modify your
+    pipeline.
+
+## Installation
+
+You can install the development version of blockr from
+[GitHub](https://github.com/) with:
+
+``` r
+pak::pak("blockr-org/blockr")
+```
+
+## Example: palmer penguins case study
+
+Below is a simple case study involving `{blockr}`. We use the
+palmerpenguins dataset to find out which femal species has the largest
+flippers. We create 2 custom blocks allowing to create our plot block
+(see the plot vignette for more details). Note that the
+`{blockr.ggplot2}` package exposes some ready to use blocks.
 
 ``` r
 library(blockr)
-library(blockr.data)
+library(palmerpenguins)
+library(ggplot2)
 
-data_block <- new_dataset_block(selected = "lab", package = "blockr.data")
+new_ggplot_block <- function(col_x = character(), col_y = character(), ...) {
+
+  data_cols <- function(data) colnames(data)
+
+  new_block(
+    fields = list(
+      x = new_select_field(col_x, data_cols, type = "name"),
+      y = new_select_field(col_y, data_cols, type = "name")
+    ),
+    expr = quote(
+      ggplot(mapping = aes(x = .(x), y = .(y)))
+    ),
+    class = c("ggplot_block", "plot_block"),
+    ...
+  )
+}
+
+new_geompoint_block <- function(color = character(), shape = character(), ...) {
+
+  data_cols <- function(data) colnames(data$data)
+
+  new_block(
+    fields = list(
+      color = new_select_field(color, data_cols, type = "name"),
+      shape = new_select_field(shape, data_cols, type = "name")
+    ),
+    expr = quote(
+      geom_point(aes(color = .(color), shape = .(shape)), size = 2)
+    ),
+    class = c("plot_layer_block", "plot_block"),
+    ...
+  )
+}
 
 stack <- new_stack(
-  data_block,
-  new_select_block
+  data_block = new_dataset_block("penguins", "palmerpenguins"),
+  filter_block = new_filter_block("sex", "female"), 
+  plot_block = new_ggplot_block("flipper_length_mm", "body_mass_g"),
+  layer_block = new_geompoint_block("species", "species")
 )
 serve_stack(stack)
 ```
 
-## Installation
-
-You can install the development version of blockr from
-[GitHub](https://github.com/) with:
-
 ``` r
-# install.packages("devtools")
-pak::pkg_install("blockr-org/blockr")
+appdir <- system.file("examples", "penguins", package = "blockr")
+appshot(appdir, delay = 3)
 ```
 
 ## Contribute

_pkgdown.yml

@@ -24,6 +24,7 @@ articles:
   desc: ~
   navbar: User Guide
   contents:
+  - "`blockr_examples`"
   - "`data-blocks`"
   - "`registry`"
   - "`plot-block`"

vignettes/blockr_examples.Rmd

@@ -1,7 +1,10 @@
 ---
-title: "blockr: Flexible Data Pipeline Building for Everyone"
-output: html_document
-date: "2024-07-07"
+title: "blockr: case studies"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{blockr: case studies}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
 ---
 
 ```{r setup, include=FALSE}
@@ -41,8 +44,6 @@ new_slider_field <- function(value = 5L, min = 0L, max = 10L, step = 1L, ...) {
 #' @method ui_input slider_field
 #' @export
 ui_input.slider_field <- function(x, id, name) {
-  ns <- NS(input_ids(x, id))
-
   shiny::sliderInput(
     blockr:::input_ids(x, id),
     name,
@@ -741,6 +742,7 @@ serve_stack(marketing_impact_stack)
 
 ### 5. Dynamical systems
 
+In the below example, we implemented the Lorenz attractor and solve it with the `{pracma}` R package (technically, the reason using `{pracma}` over `{deSolve}` or `{diffeqr}` is because only `{pracma}` is available for shinylive required by the embeded demo).
 
 ```{r, eval=TRUE, echo=FALSE}
 card(

vignettes/new-field.Rmd

@@ -1,8 +1,8 @@
 ---
-title: "new-field"
+title: "4. Case study: create a new field"
 output: rmarkdown::html_vignette
 vignette: >
-  %\VignetteIndexEntry{new-field}
+  %\VignetteIndexEntry{4. Case study: create a new field}
   %\VignetteEngine{knitr::rmarkdown}
   %\VignetteEncoding{UTF-8}
 ---