finish update vignettes, update news.md, readme, ...

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: blockr
 Title: A block-based framework for data manipulation and visualization
-Version: 0.0.1.9000
+Version: 0.0.2
 Authors@R: 
     c(person(given = "Nicolas",
              family = "Bennett",

NEWS.md

@@ -1,3 +1,39 @@
+# blockr 0.0.2
+
+## Breaking changes
+- Change blocks and fields constructor names to `new_*_block` and `new_*_field`. For instance, for the select block,
+users are now supposed to use `new_select_block()` and not `select_block`.
+- Remove `data` from block constructor:
+
+```r
+new_select_block <- function(columns = character(), ...) {
+  ...
+}
+```
+
+## New features
+- New validation functions: `validate_field()` and `validate_block()` to check that
+values are consistent with data. These are used to then propagate any error to the user via JavaScript.
+- Evaluation stops whenever a block isn't valid and the app should not crash.
+- We can now instantiate block outside the stack with default parameter values (or use the old way with constructors):
+
+```r
+# New way
+data_blk <- new_dataset_block(selected = "lab", package = "blockr.data")
+select_blk <- new_select_block("STUDYID")
+
+stack <- new_stack(
+  data_blk,
+  select_blk
+)
+
+# Old way
+stack <- new_stack(
+  new_ data_block,
+  new_select_block
+)
+```
+
 # blockr 0.0.1.9000
 
 * First prototype:

README.Rmd

@@ -27,15 +27,17 @@ 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 = "https://blockr-org.github.io/webr-repos")`.
+`webr::install("blockr", repos = c("https://blockr-org.github.io/webr-repos", "https://repo.r-wasm.org"))`.
 
 ```r
 library(blockr)
 library(blockr.data)
 
+data_block <- new_dataset_block(selected = "lab", package = "blockr.data")
+
 stack <- new_stack(
-  dataset_block,
-  select_block
+  data_block,
+  new_select_block
 )
 serve_stack(stack)
 ```
@@ -46,7 +48,7 @@ You can install the development version of blockr from [GitHub](https://github.c
 
 ```r
 # install.packages("devtools")
-devtools::install_github("blockr-org/blockr")
+pak::pkg_install("blockr-org/blockr")
 ```
 
 ## Contribute

README.md

@@ -13,15 +13,17 @@ 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 = "https://blockr-org.github.io/webr-repos")`.
+`webr::install("blockr", repos = c("https://blockr-org.github.io/webr-repos", "https://repo.r-wasm.org"))`.
 
 ``` r
 library(blockr)
 library(blockr.data)
 
+data_block <- new_dataset_block(selected = "lab", package = "blockr.data")
+
 stack <- new_stack(
-  dataset_block,
-  select_block
+  data_block,
+  new_select_block
 )
 serve_stack(stack)
 ```
@@ -33,7 +35,7 @@ You can install the development version of blockr from
 
 ``` r
 # install.packages("devtools")
-devtools::install_github("blockr-org/blockr")
+pak::pkg_install("blockr-org/blockr")
 ```
 
 ## Contribute

_pkgdown.yml

@@ -46,19 +46,19 @@ reference:
 - title: Fields elements
   desc: Fields are translated into shiny inputs. They are part of blocks.
   contents:
-  - "`string_field`"
-  - "`select_field`"
-  - "`switch_field`"
-  - "`numeric_field`"
-  - "`submit_field`"
-  - "`upload_field`"
-  - "`filesbrowser_field`"
-  - "`variable_field`"
-  - "`range_field`"
-  - "`hidden_field`"
-  - "`list_field`"
-  - "`result_field`"
-  - "`keyvalue_field`"
+  - "`new_string_field`"
+  - "`new_select_field`"
+  - "`new_switch_field`"
+  - "`new_numeric_field`"
+  - "`new_submit_field`"
+  - "`new_upload_field`"
+  - "`new_filesbrowser_field`"
+  - "`new_variable_field`"
+  - "`new_range_field`"
+  - "`new_hidden_field`"
+  - "`new_list_field`"
+  - "`new_result_field`"
+  - "`new_keyvalue_field`"
 
 - title: Blocks core elements
   desc: Functions to build blocks
@@ -76,24 +76,23 @@ reference:
 - title: Blocks
   desc: Blocks contain field. They return a dataframe
   contents: 
-  - "`dataset_block`"
-  - "`upload_block`"
-  - "`filesbrowser_block`"
+  - "`new_dataset_block`"
+  - "`new_upload_block`"
+  - "`new_filesbrowser_block`"
   - "`new_parser_block`"
-  - "`csv_block`"
-  - "`rds_block`"
-  - "`json_block`"
-  - "`sas_block`"
-  - "`xpt_block`"
-  - "`result_block`"
-  - "`filter_block`"
-  - "`select_block`"
-  - "`summarize_block`"
-  - "`arrange_block`"
-  - "`group_by_block`"
-  - "`join_block`"
-  - "`head_block`"
-  - "`mutate_block`"
+  - "`new_csv_block`"
+  - "`new_rds_block`"
+  - "`new_json_block`"
+  - "`new_xpt_block`"
+  - "`new_result_block`"
+  - "`new_filter_block`"
+  - "`new_select_block`"
+  - "`new_summarize_block`"
+  - "`new_arrange_block`"
+  - "`new_group_by_block`"
+  - "`new_join_block`"
+  - "`new_head_block`"
+  - "`new_mutate_block`"
 
 - title: Stack
   desc: Stack contains multiple block.
@@ -197,3 +196,9 @@ reference:
   - "`as_log_level`"
   - "`cnd_logger`"
   - "`cat_logger`"
+
+news:
+ releases:
+ - text: "blockr 0.0.2"
+ - text: "blockr 0.0.1.9000"
+

index.md

@@ -13,7 +13,7 @@ Building blocks for data manipulation and visualization operations.
 
 <div class="card bslib-card bslib-mb-spacing html-fill-item html-fill-container" data-bslib-card-init data-full-screen="false" data-require-bs-caller="card()" data-require-bs-version="5">
 <div class="card-body bslib-gap-spacing html-fill-item html-fill-container" style="margin-top:auto;margin-bottom:auto;flex:1 1 auto;">
-<iframe class="html-fill-item" src="https://shinylive.io/r/editor/#code=NobwRAdghgtgpmAXGKAHVA6ASmANGAYwHsIAXOMpMAdzgCMAnRRASwgGdSoAbbgCgA6YOtyIEA1gyG4ABAzioi7GQF4ZQgBalSqdogD0+kWMkBaIgwDmGSy1IaArnQwsi+2o1PzF7IQEoBCG4WRigGAE8+YwkGAI4uCRkAHlMZCDhqAH1OKAlBCBlCmQATKC5M6PFcQKKZdjhuOAJSCtEJQLjA+oYANzhshPE+HIk-MABfAF0gA" height="700" width="100%" style="border: 1px solid rgba(0,0,0,0.175); border-radius: .375rem;" allowfullscreen="" allow="autoplay" data-external="1"></iframe>
+<iframe class="html-fill-item" src="https://shinylive.io/r/editor/#code=NobwRAdghgtgpmAXGKAHVA6ASmANGAYwHsIAXOMpMAdzgCMAnRRASwgGdSoAbbgCgA6YOtyIEA1gyG4ABAzioi7GQF4ZBQWAAWpUqnaIA9IZFjJAWiIMA5hmstSWgK50MLIodqNz8xe2kyQjp6Bsa+RBgM5tRQ7DAYVtZCAJTJAhDcLIxQDACefKYSDGkZWQw5+YWSGAAmUFwl6XVcAPpVMgA85jIQcNQtzbFwpG2iEnzscNxwBOQ1qoFg3FB0AahQElDWcAtCVQy19VAp6emcG+Kd3b395+ODo2YlkwwAbnAtd+ITXBLJYABfAC6QA" height="700" width="100%" style="border: 1px solid rgba(0,0,0,0.175); border-radius: .375rem;" allowfullscreen="" allow="autoplay" data-external="1"></iframe>
 </div>
 <bslib-tooltip placement="auto" bsOptions="[]" data-require-bs-version="5" data-require-bs-caller="tooltip()">
 <template>Expand</template>
@@ -30,10 +30,9 @@ with
 library(blockr)
 library(blockr.data)
 
-stack <- new_stack(
-  dataset_block,
-  select_block
-)
+data_block <- new_dataset_block(selected = "lab", package = "blockr.data")
+
+stack <- new_stack(data_block)
 serve_stack(stack)
 ```
 

vignettes/data-blocks.Rmd

@@ -185,18 +185,23 @@ output as input of the second stack (it appears in the result block select input
 
 ```r
 library(blockr)
+library(blockr.data)
 
 serve_workspace(
-  stack1 = new_stack(new_dataset_block, new_select_block),
+  stack1 = new_stack(
+    new_dataset_block("lab", "blockr.data"),
+    new_select_block(c("STUDYID", "USUBJID"))
+  ),
   stack2 = new_stack(new_result_block),
+  stack3 = new_stack(new_dataset_block("ae", "blockr.data")),
   title = "My workspace"
 )
 ```
 
 ```{r, eval=TRUE, echo=FALSE}
 card(
   create_app_link(
-    "NobwRAdghgtgpmAXGKAHVA6ASmANGAYwHsIAXOMpMAdzgCMAnRRASwgGdSoAbbgCgA6YOtyIEA1gyG4ABAzioi7GQF4ZBQWAAWpUqnaIA9IZFjJAWiIMA5hmstSWgK50MLIodqNz8xe2kyQjp6Bsa+RBgM5tRQ7DAYVtZCAJTJAhDcLIxQDACefKYSDGkQ6exwDABucAD61Fbi7KhQBHCCEDIynC3iAIyqMhBw1DXdEnxDIwAmUFzlpDWF4rKTo3DccAQLS8m46Z1j4gBMA6uHE8M18uxO3NuiErv7MqQOGwNCALK5MvUMjc1WkJ0skwABfAC6QA", # nolint
+    "NobwRAdghgtgpmAXGKAHVA6ASmANGAYwHsIAXOMpMAdzgCMAnRRASwgGdSoAbbgCgA6YOtyIEA1gyG4ABAzioi7GQF4ZBQWAAWpUqnaIA9IZFjJAWiIMA5hmstSWgK50MLIodqNz8xe2kyQjp6Bsa+RBgM5tRQ7DAYVtZCAJTJAhDcLIxQDACefKYSDGkZWQw5+YWSGAAmUFwl6exwDABucAD61Fbi7KhQBHCCEDIynAPiAIyqMhBw1B3jEsOjo3MLdVzNpB1VmtxQdAFCVQy19VApuOmrs-OLcNxwBDt7GkIAygAqAKoAIgBNACSf2OYB+Hx+ACEAFIglIlUbJa4jMZcCQAJhm60W6PEfBx8nYTm4r1EEmRNzREwAzNj7kt8TjNrE4GSzJooHAwadzlwESjRqQHE8ZkIALK5GTdBi9fqDITpZJgAC+AF0gA", # nolint
     "app",
     header = FALSE
   ),

vignettes/developer-guide.Rmd

@@ -117,64 +117,51 @@ classDiagram
 
 The `validate_field` generic ensures each field has revelant values. For instance, for a string field,
 which ultimately becomes a shiny text input, the method `validate_field.string_field` is responsible
-for checking that the value is a character string and modifies it if not (I BELIEVE WE'RE DOING
-TOO MUCH HERE SINCE THE VALIDATION SHOULD HAPPEN ON THE SHINY SIDE).
+for checking that the value is a character string and modifies it if not.
 
 ### More complex fields
 
-With basic fields, we can't handle __dependencies__ between 2 fields. This is typically what happens
-in a join block. To join datasets, we need 2 datasets and some columns for the join. Assuming, 
-the dataset choice is managed by a field, changing the datasets may update the possible
-choices for the `join_by` field. Below shows the definition of 2 simple fields, one for selecting
-the join function (static set of choices) and another for selecting the second dataset.
-
-```r
-fields <- list(
-  join_func = new_select_field(
-    paste(type, "join", sep = "_"),
-    paste(join_types, "join", sep = "_")
-  ),
-  y = new_select_field(y[[1]], y),
-  by = ...
-)
-```
-
-How do we handle the `by` field as it depends on `y`?
-
-This is where we introduce `list_field`. `list_field` accepts a function generating 
-the choices with a dependency on other existing fields:
+TBD
 
-```r
-by_choices <- function(data, y) {
-    # DEPENDENCY on y
-    choices <- intersect(
-      colnames(data),
-      colnames(eval(as.name(y)))
-    )
-
-    ...
-
-    # Return nested field
-    list(
-      val = new_select_field(
-        default,
-        choices,
-        multiple = TRUE
-      )
-    )
-  }
-```
+## Validation and evaluation
 
-`by_choices` can then be injected inside `new_list_field`:
+That's currently how {blockr} validate blocks and fields. Each block is validated, meaning that each field that compose it should have valid values according to the input data. Only when everything is valid, the block expression is evaluated and the result computed and passed to the next block. Any error is catched by R and forwarded to JavaScript so that users are notified about what went wrong and where.
 
-```r
-fields <- list(
-  join_func = new_select_field(
-    paste(type, "join", sep = "_"),
-    paste(join_types, "join", sep = "_")
-  ),
-  y = new_select_field(y[[1]], y),
-  by = new_list_field(sub_fields = by_choices) # HERE
+```{r, echo=FALSE}
+mermaid("
+flowchart TD;
+    subgraph stack
+        subgraph blk1
+            block1[Block 1] --> |check fields| validate_block1[Validation] --> validate_block1_ok[OK]
+            validate_block1 --> validate_block1_fail[Fail]
+            validate_block1_ok --> |evaluate| try_eval[Try] --> eval_block1_ok[OK] --> data_block1[Data]
+            eval_block1_ok[Success]
+            try_eval --> eval_block1_fail[Fail]
+        end
+        data_block1 -.-> block2
+        subgraph blk2
+        block2[Block2] --> |check fields| validate_block2[Validation] --> validate_block2_ok[OK]
+        
+        validate_block2 --> validate_block2_fail[Fail]
+        validate_block2_ok --> |evaluate| try_eval2[Try] --> eval_block2_ok[OK] --> data_block2[Data]
+        eval_block2_ok[Success]
+        try_eval2 --> eval_block2_fail[Fail]
+        end
+        data_block2 -.-> stack_result[Stack result]
+    end
+    eval_block1_fail -.-x |notification| gui
+    eval_block2_fail -.-x |notification| gui
+    validate_block1_fail -.-x |notification| gui
+    validate_block2_fail -.-x |notification| gui
+    subgraph ui
+        gui[User interface]
+    end
+", height = "1200px") |>
+  htmlwidgets::onRender(
+    "function(el, x) {
+      el.classList.add('text-center')
+    }
+    "
 )
 ```