blockr.dag

    library(blockr.dag)
    library(blockr.core)
    library(blockr.dock)

## Basic Usage

### Starting a DAG Board

We create an empty board from blockr.dock and serve it with the `new_dag_extension()` extension:

    # 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:

    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, 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:

    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:

    # 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.
- Toolbar.

### Extension block callback

blockr.dock exposes a callback system to extend block functionality. You can learn more in the following vignette.