Merge pull request #29 from BristolMyersSquibb/fix/maelle-review-issues

christophsax · web-flow · commit 981233104744 · 2026-03-24T16:22:38.000+01:00
Address review feedback from maelle
diff --git a/.vitepress/config.js b/.vitepress/config.js
@@ -17,10 +17,15 @@ module.exports = {
       { text: 'Examples', link: '/examples/' },
       { text: 'Playground', link: 'https://blockr.cloud/app/empty' }
     ],
+    editLink: {
+      pattern: 'https://github.com/BristolMyersSquibb/blockr-site/edit/main/:path',
+      text: 'Edit this page on GitHub'
+    },
     sidebar: {
       '/learn/': [{
         text: 'Learn',
         items: [
+          { text: 'Installation', link: '/learn/00-installation' },
           { text: 'Build your first app', link: '/learn/01-build-your-first-app' },
           { text: 'Build a dashboard', link: '/learn/02-build-a-dashboard' },
           { text: 'Create a custom block', link: '/learn/03-create-a-block' }
diff --git a/.vitepress/theme/custom.css b/.vitepress/theme/custom.css
@@ -3,7 +3,7 @@
   display: flex !important;
   align-items: center;
   gap: 8px;
-  color: #999;
+  color: #666;
   font-size: 0.85em;
 }
 
diff --git a/docs/blocks/01-wrangling.md b/docs/blocks/01-wrangling.md
@@ -14,7 +14,7 @@ Use the column selector to pick the columns you want. You can select multiple co
 
 The block includes a "distinct" option. When enabled, duplicate rows are removed from the result, keeping only unique combinations of the selected columns.
 
-![](01-select-block.png)
+![Select block interface showing column picker](01-select-block.png)
 
 ---
 
@@ -28,7 +28,7 @@ Add multiple conditions using the "+ Add Condition" button. Each condition can b
 
 For more elaborate filter conditions using comparisons or calculations, use the filter expression block instead.
 
-![](01-filter-block.png)
+![Filter block interface with value dropdowns](01-filter-block.png)
 
 ---
 
@@ -38,7 +38,7 @@ The filter expression block keeps only rows that meet specific conditions using
 
 Supported operators include `>`, `<`, `==`, `!=`, `>=`, `<=` for comparisons, and `%in%` for checking membership in a set of values. Combine multiple conditions using `&` (AND) to require all conditions to be true, or `|` (OR) to require at least one condition to be true. The expression editor provides syntax highlighting and validates your expressions. Examples: `mpg > 20`, `cyl == 4 | cyl == 6`, `hp > 100 & wt < 3`.
 
-![](01-filter-expr-block.png)
+![Filter expression block with R expression editor](01-filter-expr-block.png)
 
 ---
 
@@ -50,7 +50,7 @@ When sorting by multiple columns, the order matters. The first column is the pri
 
 Add columns using the "+" button and remove them using the "×" button. Toggle between ascending and descending order for each column independently.
 
-![](01-arrange-block.png)
+![Arrange block with sort column and direction controls](01-arrange-block.png)
 
 ---
 
@@ -62,7 +62,7 @@ For head and tail types, specify the number of rows using n (count) or prop (pro
 
 The custom type accepts a rows expression like "1:5" or "c(1, 3, 5, 10)". All slice types support grouping via the by parameter, which performs the slice operation within each group separately.
 
-![](01-slice-block.png)
+![Slice block interface with type selector](01-slice-block.png)
 
 ---
 
@@ -74,7 +74,7 @@ Use mathematical operators (`+`, `-`, `*`, `/`, `^`) and functions (`sqrt()`, `l
 
 Expression order matters: later expressions can reference columns created by earlier expressions in the same mutate block. The by parameter allows grouping, making column references operate within each group. Add expressions with the "+ Add Expression" button and remove them with the "×" button.
 
-![](01-mutate-expr-block.png)
+![Mutate expression block with column name and expression fields](01-mutate-expr-block.png)
 
 ---
 
@@ -86,7 +86,7 @@ Select the existing column from a dropdown to ensure valid column names. Type th
 
 The block validates that you don't rename the same column twice and ensures column names don't conflict with existing names.
 
-![](01-rename-block.png)
+![Rename block showing new name to old name mapping](01-rename-block.png)
 
 ---
 
@@ -100,7 +100,7 @@ Use the "Columns to group by" selector to group data before summarizing. When gr
 
 For more complex aggregations using custom R expressions, use the summarize expression block instead.
 
-![](01-summarize-block.png)
+![Summarize block with function dropdown and column selector](01-summarize-block.png)
 
 ---
 
@@ -112,7 +112,7 @@ Enter expressions like `mean(mpg)`, `sum(hp)`, `dplyr::n()`, or more complex cal
 
 Use the "Columns to group by" selector to group data before summarizing. The "Show advanced options" section provides additional settings like the unpack option for handling functions that return data frames.
 
-![](01-summarize-expr-block.png)
+![Summarize expression block with R expression editor](01-summarize-expr-block.png)
 
 ---
 
@@ -124,7 +124,7 @@ Join types: left_join keeps all rows from the left dataset and matching rows fro
 
 The "Custom Column Mappings" interface supports both same-name joins (when columns have identical names) and different-name joins (when the matching columns have different names in each dataset). Add multiple join keys to match on multiple columns simultaneously. Enable "Use natural join" to automatically join on all common columns.
 
-![](01-join-block.png)
+![Join block with join type selector and column mappings](01-join-block.png)
 
 ---
 
@@ -136,7 +136,7 @@ Columns are matched by name. If datasets have different columns, the result incl
 
 The "Show advanced options" section provides the id_name option which adds an identifier column that tracks which source dataset each row came from. This is useful when combining data from multiple sources and you need to maintain provenance.
 
-![](01-bind-rows-block.png)
+![Bind rows block interface](01-bind-rows-block.png)
 
 ---
 
@@ -148,7 +148,7 @@ All input datasets must have exactly the same number of rows. The rows are combi
 
 If datasets have columns with the same name, they are automatically renamed with numeric suffixes (e.g., "Sepal.Length...1", "Sepal.Length...6") to avoid conflicts.
 
-![](01-bind-cols-block.png)
+![Bind columns block interface](01-bind-cols-block.png)
 
 ---
 
@@ -166,7 +166,7 @@ Select which columns to pivot. These columns are transformed into two new column
 
 The "Show advanced options" section provides names_prefix (removes common prefixes from column names) and values_drop_na (removes rows where the value is NA). This is useful for reshaping time series data, survey responses, or preparing data for visualization.
 
-![](01-pivot-longer-block.png)
+![Pivot longer block with column selector and naming options](01-pivot-longer-block.png)
 
 ---
 
@@ -178,7 +178,7 @@ Select which column contains values for new column names (names_from) and which
 
 The "Show advanced options" section provides names_prefix (adds a prefix to new column names) and values_fill (provides a value for missing combinations). This is useful for creating crosstabs, pivot tables, or comparing values across categories.
 
-![](01-pivot-wider-block.png)
+![Pivot wider block with names_from and values_from selectors](01-pivot-wider-block.png)
 
 ---
 
@@ -190,7 +190,7 @@ Select the column to separate and specify the names for the new columns (comma-s
 
 The "Show advanced options" section provides remove (whether to remove the input column), convert (whether to convert new columns to appropriate types), and extra/fill options for handling rows with too many or too few pieces.
 
-![](01-separate-block.png)
+![Separate block with column selector and separator input](01-separate-block.png)
 
 ---
 
@@ -202,7 +202,7 @@ Select the columns to unite and specify the name for the new combined column. En
 
 The "Show advanced options" section provides the remove option (whether to remove the input columns after uniting) and na.rm (whether to remove NA values before uniting).
 
-![](01-unite-block.png)
+![Unite block with column selector and separator input](01-unite-block.png)
 
 ---
 
diff --git a/docs/blocks/02-visualisation.md b/docs/blocks/02-visualisation.md
@@ -12,7 +12,7 @@ Map columns to the x and y axes to show how variables relate to each other. Add
 
 Scatter plots support additional aesthetics including shape (for categorical distinctions) and alpha (transparency). Use alpha values between 0 and 1 to reduce overplotting in dense regions. The block automatically handles scale creation and legend generation for all mapped aesthetics.
 
-![](02-block-ggplot-scatter.png)
+![Scatter plot example](02-block-ggplot-scatter.png)
 
 ---
 
@@ -24,7 +24,7 @@ Select a categorical variable for the x axis to create bars for each category. T
 
 Bar charts work well for comparing discrete groups, showing distributions of categorical variables, or displaying summary statistics. The block handles count aggregation automatically when no y variable is specified.
 
-![](02-block-ggplot-bar.png)
+![Bar chart example](02-block-ggplot-bar.png)
 
 ---
 
@@ -36,7 +36,7 @@ Map a sequential variable (like time or age) to the x axis and a continuous vari
 
 Line charts support additional aesthetics including linetype for distinguishing groups with different line styles (solid, dashed, dotted) and size for varying line thickness. This visualization is ideal for temporal data, growth curves, and tracking changes over ordered sequences.
 
-![](02-block-ggplot-line.png)
+![Line chart example](02-block-ggplot-line.png)
 
 ---
 
@@ -48,7 +48,7 @@ Select a categorical variable for x and a continuous variable for y. The box sho
 
 Box plots provide a compact summary of distribution shape, central tendency, and variability. They're particularly effective when comparing multiple groups side-by-side, as the aligned boxes make differences in median, spread, and skewness immediately visible.
 
-![](02-block-ggplot-boxplot.png)
+![Box plot example](02-block-ggplot-boxplot.png)
 
 ---
 
@@ -60,7 +60,7 @@ Like box plots, violin plots require a categorical x variable and continuous y v
 
 Violin plots are superior to box plots when you need to see whether distributions are unimodal or multimodal, identify subtle differences in distribution shape, or understand the full data density rather than just quartiles. They're especially valuable with larger datasets where distribution details matter.
 
-![](02-block-ggplot-violin.png)
+![Violin plot example](02-block-ggplot-violin.png)
 
 ---
 
@@ -72,7 +72,7 @@ Map a continuous variable to x to create a density curve. The fill aesthetic cre
 
 Density plots work well for comparing distributions when you want smooth, continuous representations rather than binned histograms. They're particularly effective with the alpha aesthetic set to 0.5-0.7, which makes overlapping distributions easy to distinguish. Use them to compare distribution shapes, identify modes, or assess whether groups follow similar patterns.
 
-![](02-block-ggplot-density.png)
+![Density plot example](02-block-ggplot-density.png)
 
 ---
 
@@ -84,7 +84,7 @@ Like line charts, area charts map sequential data to x and continuous values to
 
 Area charts work best when the filled space has meaning, such as cumulative quantities, market shares, or resource allocation over time. The alpha aesthetic (0.6-0.8) is particularly important when comparing overlapping areas, as it allows all curves to remain visible while still emphasizing volume.
 
-![](02-block-ggplot-area.png)
+![Area chart example](02-block-ggplot-area.png)
 
 ---
 
@@ -96,7 +96,7 @@ Select a continuous variable for x. The block automatically creates bins and cou
 
 Histograms are fundamental for exploratory data analysis: assessing whether data follows a normal distribution, identifying skewness or multimodality, detecting outliers, and understanding data range. Experiment with bin counts to find the right level of detail for your data's density and range.
 
-![](02-block-ggplot-histogram.png)
+![Histogram example](02-block-ggplot-histogram.png)
 
 ---
 
@@ -108,7 +108,7 @@ Map a categorical variable to x and a numeric value to y. Each category becomes
 
 While controversial among data visualization experts who prefer bar charts for precise comparisons, pie charts remain intuitive for showing simple proportions, especially when one category dominates or when emphasizing that parts constitute a whole. Keep categories limited and consider using a donut chart variant for a modern aesthetic.
 
-![](02-block-ggplot-pie.png)
+![Pie chart example](02-block-ggplot-pie.png)
 
 ---
 
@@ -120,7 +120,7 @@ Configure exactly like pie charts, but set donut_hole to a value between 0.3 and
 
 The empty center draws attention and can be used strategically to display total values, titles, or key metrics. The ring shape also makes it slightly easier to compare arc lengths than full pie slices, as the curves are more linear. Use donut charts when aesthetics matter or when you want to emphasize the ring pattern over the center point.
 
-![](02-block-ggplot-donut.png)
+![Donut chart example](02-block-ggplot-donut.png)
 
 ---
 
@@ -132,7 +132,7 @@ Select a facet variable to create a separate panel for each unique value. The nc
 
 Facet wrap works well with 3-15 groups where you want to see each group's pattern separately while maintaining visual comparison. It automatically handles scales: by default all facets share the same x and y scales for easy comparison, though you can set scales to "free" for independent axes. Use this for comparing patterns across time periods, regions, or categories.
 
-![](02-block-facet.png)
+![Facet wrap layout example](02-block-facet.png)
 
 ---
 
@@ -144,7 +144,7 @@ Select variables for facet_rows and facet_cols to create a rows × columns layou
 
 Facet grid is powerful for experimental designs with multiple factors, comparing subgroups across time periods, or any situation where data is naturally organized by two categorical variables. The grid structure reveals interaction effects and makes systematic comparisons straightforward. Keep factor levels reasonable (typically 2-5 levels per dimension) to maintain readability.
 
-![](02-block-facet-grid.png)
+![Facet grid layout example](02-block-facet-grid.png)
 
 ---
 
@@ -156,7 +156,7 @@ Select from over 20 built-in themes including classic ggplot2 themes (theme_mini
 
 Themes control non-data elements: backgrounds, grid lines, axis styling, legend appearance, and text formatting. Apply a theme block after visualization blocks to style the entire plot consistently. Common choices include theme_minimal for clean presentations, theme_classic for publication-ready plots, and theme_dark for emphasis or presentations on dark backgrounds.
 
-![](02-block-theme.png)
+![Theme block with theme selector](02-block-theme.png)
 
 ---
 
@@ -168,7 +168,7 @@ Select a layout style (horizontal, vertical, or grid) and specify the number of
 
 Grid composition is essential for complex figures that tell a complete story through multiple related views. Each input can be a complete visualization pipeline, allowing you to combine different chart types, subsets, or transformations. This is particularly powerful for academic papers, reports, or dashboards where you need to present multiple coordinated views.
 
-![](02-block-grid.png)
+![Grid block composing multiple plots](02-block-grid.png)
 
 ---
 
diff --git a/docs/blocks/03-io.md b/docs/blocks/03-io.md
@@ -37,7 +37,7 @@ When you select multiple files, the block provides combination strategies:
 
 This makes it easy to load and combine related datasets in one step.
 
-![](03-read-block.png)
+![Read block interface with file source and format options](03-read-block.png)
 
 ---
 
@@ -96,7 +96,7 @@ The write block accepts multiple dataframe inputs, similar to how you might comb
 
 Format-specific options (like CSV delimiter or quote character) can be configured through the `args` parameter.
 
-![](03-write-block.png)
+![Write block interface with format and output mode options](03-write-block.png)
 
 ---
 
diff --git a/docs/concepts/01-reactivity.md b/docs/concepts/01-reactivity.md
@@ -17,12 +17,12 @@ blockr did not invent reactivity! blockr is built on the [Shiny](https://shiny.p
 If you have already completed the [Build a dashboard](../../learn/02-build-a-dashboard) tutorial, you have already seen reactivity in action.
 In that tutorial you learnt how to build a simple dashboard which uses a filter to update a plot on penguins:
 
-![](01-img-01.png)
+![Penguins dashboard with filter updating the plot](01-img-01.png)
 
 Let's zoom into the workflow to better understand what is going on.
 Here, we can see that as one block updates, all downstream blocks update:
 
-![](01-img-02.png)
+![Diagram showing a change in one block updating the downstream block](01-img-02.png)
 
 In this example, this results in only a single block updating.
 
@@ -31,20 +31,20 @@ In other words, it comes after it in the workflow.
 If data flows from A → B → C, then B and C are both downstream of A.
 This means that for complicated workflows, a change higher up the workflow can result in many blocks being updated:
 
-![](01-img-03.png)
+![Complex workflow where a change propagates to many downstream blocks](01-img-03.png)
 
 Note that upstream blocks never get updated.
 In our simple example, this means that our data block does **not** get updated, because it is upstream of our filter block:
 
-![](01-img-04.png)
+![Upstream data block is not affected by changes in the filter block](01-img-04.png)
 
 ## Errors
 
 Sometimes updating a block can causes errors downstream.
 
 For example, again using our simple penguins dashboard, if we update the dataset block to use a dataset other than penguins, it will causes errors downstream:
 
-![](01-img-05.png)
+![Error in downstream blocks after changing the dataset](01-img-05.png)
 
 This happens because the downstream filter and plot blocks user variables from the penguins dataset.
 When this dataset changes, these variables are no longer available and so the downstream blocks error to let us know they are trying to use variables that no longer exist.
diff --git a/docs/dev/create-block.md b/docs/dev/create-block.md
@@ -2,7 +2,9 @@
 
 <VideoEmbed id="-PdixmAscQI" title="Creating blocks in blockr" />
 
-Write custom blocks in pure R to extend blockr with your own logic. A block is a specialized Shiny module that returns an **expression** (the R code it generates) and a **state** (its current input values).
+Write custom blocks in pure R to extend blockr with your own logic. A block is a specialized Shiny module that returns an **expression** (the R code it generates) and a **state** (its current input values). A workflow is a Shiny app composed of connected blocks.
+
+Blocks should live in an R package so they can be registered, shared, and tested. The examples below show the package-based approach.
 
 ## Block anatomy
 
diff --git a/examples/index.md b/examples/index.md
@@ -93,7 +93,7 @@ Curated demo workflows running on [blockr.cloud](https://blockr.cloud). Open any
 <img src="/examples/ai-ctrl.png" alt="AI Control + Pipeline Discovery" />
 <div class="example-body">
 <p class="example-title">AI Control + Pipeline Discovery</p>
-<p>AI-powered data filtering and automatic pipeline construction from natural language.</p>
+<p>AI-powered data filtering and pipeline construction. Click the sparkles button (✨) in a block to describe what you want in plain English.</p>
 <span class="example-link">Open in Playground →</span>
 </div>
 </a>
diff --git a/learn/00-installation.md b/learn/00-installation.md
@@ -0,0 +1,25 @@
+# Installation
+
+Most users access blockr through [blockr.cloud](https://blockr.cloud) and don't need to install anything. If you want to run blockr locally, follow the steps below.
+
+## Prerequisites
+
+You need [R](https://www.r-project.org/) (version 4.1 or later) installed on your system.
+
+## Install blockr
+
+```r
+install.packages("blockr")
+```
+
+## Run blockr
+
+```r
+blockr::run_app()
+```
+
+This opens an empty blockr canvas in your browser. From here you can add blocks, connect them, and build workflows just like on blockr.cloud.
+
+## Next steps
+
+- [Build your first app](01-build-your-first-app): a step-by-step tutorial to get started
diff --git a/learn/01-build-your-first-app.md b/learn/01-build-your-first-app.md
diff --git a/learn/02-build-a-dashboard.md b/learn/02-build-a-dashboard.md
diff --git a/learn/03-create-a-block.md b/learn/03-create-a-block.md
diff --git a/videos/exporting-data.md b/videos/exporting-data.md

Original file line number	Diff line number	Diff line change
`@@ -3,7 +3,7 @@`
`3`	`3`	`display: flex !important;`
`4`	`4`	`align-items: center;`
`5`	`5`	`gap: 8px;`
`6`		`- color: #999;`
	`6`	`+ color: #666;`
`7`	`7`	`font-size: 0.85em;`
`8`	`8`	`}`
`9`	`9`