Graph: the Edges around a Block

The Edges of the Block index say which Block points at which. The graph is their neighbourhood in one answer: the Blocks within a few hops of a start, and the Edges between them. The library answers it (GET /api/editor/graph); the add-on @skaile/forge-editor-graph draws it.

The route

The walk follows Edges in both directions (what a Block points at and what points at it). It never follows tag Edges (a tag is no Block) or Edges to a Block that does not exist, and it never leaves the Documents the user may read: a Block in another Document is a node only when the user may read that Document. Every Edge in edges has both its Blocks in nodes.

The answer holds at most 500 Blocks. When the walk meets more, it keeps the first ones in the order it found them (start Blocks first) and sets truncated. Edges are answered once each, in the order they were met.

The walk itself is walkGraph(seeds, source, { depth, maxNodes?, keepIsolated? }) in @skaile/forge-editor/core, over a GraphSource (edges(address, direction) and node(address)). The route reads a GraphSource from the index port; the memory backend (createMemoryBackend) reads one from its projected rows (graphSourceOfRows), so a test or a demo draws the same graph.

The panel

import { GraphPanel } from '@skaile/forge-editor-graph/vue' // or '@skaile/forge-editor-graph/react'

<GraphPanel :document-id="documentId" :block-id="blockId" :open="openBlock" />

Opening a Block is the host's job, as for a search hit: in the open Document editor.commands.revealBlock(blockId), else navigate to the Document with ?block=<id>. The workspace host of this repository does both in openHit; the same function serves the graph ({ documentId, blockId } is what a BlockSearchHit also carries).

The panel draws:

The panel renders nothing when the backend has no index.graph.

Framework-free parts

@skaile/forge-editor-graph (no sigma, no DOM):

sigma (WebGL) loads when a panel mounts, so importing the package costs nothing and server-side rendering never meets it. The dashed Edges use sigma's layerDashed with the Edge attributes dash and gap: an authored Edge has 8 px dashes and 5 px gaps, every other Edge one dash longer than the canvas and no gap.

Wiring a host

The add-on needs no feature and no port of its own. The host only mounts the panel where it wants it (a sidebar tab, the Block's details) and passes open:

<script setup lang="ts">
import { GraphPanel } from '@skaile/forge-editor-graph/vue'
</script>

<template>
  <GraphPanel :document-id="documentId" :block-id="blockId" :open="openHit" />
</template>

The repository's document pages (the file-drawer layout, app/layouts/default.vue) show it behind NUXT_PUBLIC_ADDONS_GRAPH=1; the kitchen sink's standalone pages have no workspace index and show no graph.