Component props and options

<Diagram>

Imported from @the-package-labs/idocs-astro/Diagram.astro. See the Diagram component for how to use it.

Prop	Type	Default	Description
name	string	required	The folder name under diagrams/. The build stops with the available names if it does not match.
view	string	the diagram’s defaults.view, then the first view	The view to show first.
scenario	string	the diagram’s defaults.scenario	The scenario to select first.
mode	'flow' | 'sequence' | 'story'	the scenario’s mode, the diagram’s defaults.mode, then flow	How the scenario is shown.
autoplay	boolean	the diagram’s defaults.autoplay, then false	Play the scenario selected first as soon as the diagram is laid out. Ignored when the reader prefers reduced motion.
maxHeight	number	780	The tallest the canvas may grow before it scrolls inside its frame, in pixels. The canvas is as tall as the diagram needs, between 300 px and this limit; the reader can still drag its bottom edge or expand it.
showTitle	boolean	false	Show the diagram’s title.
showDescription	boolean	false	Show the diagram’s description above the first view.
hash	boolean	true	Keep the scenario, step and opened nodes in the URL hash.
sidebar	boolean	the diagram’s defaults.sidebar, then auto	Start with the panel over the picture (outline, scenarios, views and the player) open. Left out, it starts open when there is a scenario or another view to choose and the widget is wider than about 640 px. false starts it folded to a pill that names the scenario in play and keeps the play buttons; the reader can open it. Passing true opens it in a narrow widget too.
subtitles	boolean	the diagram’s defaults.subtitles, then true	Write what the scenario is doing over the picture while it plays. The reader can turn them off with CC.

The props win over what the diagram file says under defaults. The component loads its interactive part with client:visible. Do not add a client: directive. The diagrams this one can open travel inside it, so nested diagrams need nothing more.

<DiagramView>

Imported from @the-package-labs/idocs-react. The same component, for use outside Astro. See using the React component.

Prop	Type	Default	Description
diagram	CompiledDiagram	required	One compiled diagram: plain JSON from loadProject.
view	string	the diagram’s defaults.view, then the first view	The view to show first.
scenario	string	the diagram’s defaults.scenario	The scenario to select first.
mode	'flow' | 'sequence' | 'story'	the scenario’s mode, the diagram’s defaults.mode, then flow	How the scenario is shown.
autoplay	boolean	the diagram’s defaults.autoplay, then false	Play the scenario selected first once it is laid out.
maxHeight	number	780	The tallest the canvas may grow, in pixels.
showTitle	boolean	false	Show the diagram’s title.
showDescription	boolean	false	Show the diagram’s description above the first view.
hash	boolean	true	Keep the scenario, step and opened nodes in the URL hash so they can be shared.
sidebar	boolean	the diagram’s defaults.sidebar, then auto	Start with the panel over the picture (outline, scenarios, views and the player) open. Left out, it starts open when there is a scenario or another view to choose and the widget is wider than about 640 px. false starts it folded to a pill that names the scenario in play and keeps the play buttons; the reader can open it.
subtitles	boolean	the diagram’s defaults.subtitles, then true	Write what the scenario is doing over the picture while it plays. The reader can turn them off with CC.
className	string		An extra class on the root element.
onNodeSelect	(id: string) => void		Handle node clicks in your own inspector instead of the detail drawer.
selectedNode	string | null		Control which node is highlighted. Leave undefined for built-in selection.

The Astro integration

import idocs from '@the-package-labs/idocs-astro'

idocs({ dir: 'diagrams' })

Option	Type	Default	Description
dir	string	'diagrams'	The folder with one sub-folder per diagram, relative to the project root.

The integration compiles that folder into a virtual module, fails astro build on any diagram error, prints warnings, and reloads the dev server when a diagram file changes. Restart pnpm dev after upgrading idocs, because the compiler is loaded once at startup.

The virtual module

import { diagrams, diagnostics } from 'virtual:idocs/diagrams'

Export	Description
diagrams	A map from diagram name to CompiledDiagram. Also the default export.
diagnostics	Every error and warning from the last compile.

Add /// <reference types="@the-package-labs/idocs-astro/virtual" /> to src/env.d.ts for the types. This is how a page can read a diagram’s metadata at build time, for example to show how many nodes it has.

Stylesheets

File	What it is
@the-package-labs/idocs-react/styles.css	The renderer’s styles and every --idocs-* token. Imported by <Diagram> for you.
@the-package-labs/idocs-astro/starlight.css	Widens Starlight’s content column for diagrams and holds prose to a readable width. Add it to Starlight’s customCss.