graph-lab

TypeScript library for lane-style timeline graphs: a vertical list of nodes with colored rails and merge-style connectors. The layout is domain-agnostic (Git history, CI runs, workflow debug, arbitrary DAGs). SVG output is optional and renderer-agnostic.

Layout algorithm ported from git-graph-plus (Apache-2.0) / SourceGit (MIT).

Layout model (core)

• TimelineRow: id + predecessorIds[] (display order is newest first; index 0 of predecessorIds is the main continuation rail, further ids are side / merge inputs).
• buildLaneLayout(rows, options?) → LaneGraphLayout: rails, connectors, node anchors, contentInsetX (layout units).
• LayoutOptions: optional suppressAuxiliaryConnectorsForRowIds, primaryRowIds, rowPresentation (e.g. dimmed / accent) — all generic; no Git vocabulary in the core.

import {
  buildLaneLayout,
  buildSvgPrimitives,
  renderToSvgString,
  summarizeRowLanes,
} from '@graph-lab/graph-lab';
import type { TimelineRow, LaneGraphLayout, LayoutOptions } from '@graph-lab/graph-lab';

const rows: TimelineRow[] = [
  { id: 'step-3', predecessorIds: ['step-2', 'step-side'] },
  { id: 'step-2', predecessorIds: ['step-1'] },
  { id: 'step-side', predecessorIds: ['step-1'] },
  { id: 'step-1', predecessorIds: [] },
];

const options: LayoutOptions = {
  primaryRowIds: new Set(['step-3']),
};

const layout: LaneGraphLayout = buildLaneLayout(rows, options);
const primitives = buildSvgPrimitives(layout, { rowHeight: 28 });
const svg = renderToSvgString(primitives);

LaneGraphLayout is JSON-serializable → fine for Electron IPC between main and renderer.

Optional Git adapter

If your rows look like Git commits (parent hashes, refs, branch tracking), map them with:

import {
  toTimelineRowsFromGit,
  layoutOptionsFromGit,
  type GitAnnotatedRow,
} from '@graph-lab/graph-lab';

const gitRows: GitAnnotatedRow[] = [ /* id, parents, refs */ ];
const rows = toTimelineRowsFromGit(gitRows);
const layout = buildLaneLayout(rows, layoutOptionsFromGit(gitRows, branchTrackingArray));

Repo layout

src/
  types.ts
  graph-builder.ts
  renderer.ts
  svg-string.ts
  adapters/git.ts
  index.ts
NOTICE

Package name: @graph-lab/graph-lab.

Install from another project

{
  "dependencies": {
    "@graph-lab/graph-lab": "file:../graph-lab"
  }
}

Run npm run build in this repo so dist/ exists before consuming the dependency (or add a prepare script if you want that automated).

Scripts

| Command | Description | |---------|-------------| | npm run build | Compile src/ → dist/ | | npm test | Vitest | | npm run demo | Static server → http://localhost:4000/demo/ |

License

See NOTICE.