---
title: "blockr.dag"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{blockr.dag}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = FALSE
)
```

```{r setup}
library(blockr.dag)
library(blockr.core)
library(blockr.dock)
```

## Basic Usage

### Starting a DAG Board

We create an empty board from [blockr.dock](https://github.com/BristolMyersSquibb/blockr.dock) and serve it with the `new_dag_extension()` extension:

```{r}
# Create an empty board.
serve(new_dock_board(extensions = new_dag_extension()))
```

### Start from a graph object

You can also start with a custom graph structure:

```{r}
graph <- new_graph(
  nodes = list(
    list(id = 1),
    list(id = 2)
  ),
  edges = list(
    list(
      source = 1,
      target = 2,
      style = list(labelText = "1-2")
    )
  )
)

serve(
  new_dock_board(
    extensions = new_dag_extension(graph)
  )
)
```

## User Interface Elements

### Keyboard Shortcuts

- **Shift + Drag**: Create connections between blocks.
- **Ctrl + Backspace**: Remove selected elements.
- **Alt/Option(Mac) + Drag**: Multi-select elements.

## Developer Guide

### Where does blockr.dag fit in?

In the blockr [ecosystem](https://bristolmyerssquibb.github.io/blockr/), blockr.dag is a high level extension that usually comes at the end of the stack. It depends on blockr.core for core functionalities and blockr.dock for the user interface. It also relies on external packages like g6R for rendering and interaction, as well as extra block packages like blockr.dplyr and blockr.ggplot for additional block types:

```{mermaid}
graph TD
    subgraph Core Layer
        blockr.core[blockr.core]
    end

    subgraph Extension Blocks
        blockr.dplyr[blockr.dplyr]
        blockr.ggplot[blockr.ggplot]
    end

    subgraph UI Layer
        blockr.dock[blockr.dock]
        blockr.dag[blockr.dag]
    end

    subgraph External Dependencies
        dockViewR[dockViewR]
        g6R[g6R]
    end

    blockr.core --> blockr.dock
    blockr.dock --> blockr.dag
    dockViewR --> blockr.dock
    g6R --> blockr.dag

    blockr.core --> blockr.dplyr
    blockr.core --> blockr.ggplot

    blockr.dplyr -.-> blockr.dock
    blockr.dplyr -.-> blockr.dag
    blockr.ggplot -.-> blockr.dock
    blockr.ggplot -.-> blockr.dag
```

### Maintaining the DAG state

Server-side observers handle state synchronization between the block.core __board__ and the g6R output. `update` and `board` are inherited from `blockr.core`:

`update` is composed of:

| Category | Operation | Description |
|----------|-----------|-------------|
| `blocks` | `add` | New blocks to add (blocks object) |
|          | `mod` | Modified blocks (blocks object) |
|          | `rm` | Deleted blocks (block IDS, character) |
| `stacks` | `add` | New stacks to add (stacks object) |
|          | `mod` | Modified stacks (stacks object) |
|          | `rm` | Deleted stacks (stacks IDS, character) |
| `links`  | `add` | New links to add (links object) |
|          | `mod` | Modified links (links object) |
|          | `rm` | Deleted links (links IDS, character()) |

We listen to `update()` and apply the necessary changes to the `g6R` widget via its __proxy__ functions:

```{r}
# Update observer handles board changes
update_observer <- function(update, board, proxy) {
  observeEvent(update(), {
    upd <- update()

    if (length(upd$blocks$add)) {
      add_nodes(upd$blocks$add, board$board, proxy)
    }

    if (length(upd$stacks$mod)) {
      update_combos(upd$stacks$mod, board$board, proxy)
    }

    # Handle other update types...
  })
}
```

## Extending the Package

### Custom context menu and toolbar

You can learn more in the following vignettes:

- [Context menu](https://bristolmyerssquibb.github.io/blockr.dag/articles/context-menu.html).
- [Toolbar](https://bristolmyerssquibb.github.io/blockr.dag/articles/toolbar.html).

### Extension block callback

blockr.dock exposes a callback system to extend block functionality. You can learn more in the following [vignette](https://bristolmyerssquibb.github.io/blockr.dag/articles/block-callback.html).