HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
GraphView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorA frame around a graph of notes drawn by another library, and the list that makes it readable.StableSince 0.116.0MediaUsageimport'@fusion.dev/helix/graph'import'@fusion.dev/helix-headless/graph'Preview
API ReferenceRoothelix-graphA frame around a graph of notes drawn by another library, and the list that makes it readable.
PropTypeDescriptionactivateHintLabelstringDefault"Press the graph to use it"The hint shown when a surface waiting to be pressed is scrolled or
swiped over, with gestures="activate". Each family declares it as a
word property with its own English, such as "Press the map to use it".activestringThe value of the current item.controlsstringWhich controls to show, as a list such as pan zoom fullscreen, or
none. A family can add words of its own.controlsLabelstringDefault"Graph controls"The name of the group of controls, read by screen readers. Each family
declares it as a word property with its own English, "Map controls" or
"Board controls", which names what the controls drive rather than the
mechanism.controlsPlacement"top-start"|"top-end"|"bottom-start"|"bottom-end"Which corner the controls sit in.countLabelstringDefault"{count, plural, one {# note} other {# notes}}"What the list says of how many notes it holds. {count} is the count,
written in the locale, and each language writes the forms it has.defaultActivestringDefault""The value of the item declared current in markup.depthnumberHow many links from the selected note to show, for its local graph. Unset
shows every note. The list holds what the drawing shows.emptyLabelstringDefault"No notes"What the panel shows when the list holds no notes: the graph has none, or
a search or the legend hid them all. A slotted empty replaces it.fallbackLabelstringDefault"Graph"The graph's name where label is empty and the host has no
aria-label.fullscreenLabelstringDefault"Fill the screen"The fullscreen button's label.gestures"activate"|"always"|"cooperative"Which gestures the surface takes from the page.hiddenGroupsreadonlystring[]Default[]The groups turned off in the legend, by name, whose notes neither the drawing nor the list shows. A property, never an attribute.idleDelaynumberDefault0How long, in milliseconds, before the header and footer hide when the
user is inactive. 0 keeps them visible. The attribute also takes a CSS
time, such as 3s.labelstringDefault""The graph's name, read by screen readers, such as "Research notes".
Required.legendbooleanDefaultfalseNames the groups over the drawing, each a button in its color that shows
or hides its notes. Drawn where the notes have two groups or more.legendLabelstringDefault"Groups"The legend's name, read by screen readers.linkCountLabelstringDefault"{note}. {count, plural, =0 {No links} one {# link} other {# links}}"What screen readers hear when a walk along the links reaches a note that
has no link to follow, or goes back to a note: {note} for its name and
{count} for how many notes the list holds that it links to or from.linkedBothLabelstringDefault"Linked both ways with {note}"How a note linked both to and from the selected one is described, with {note}.linkedFromLabelstringDefault"Linked from {note}"How a note the selected one links to is described, with {note}, the selected note's name.linksreadonlyGraphLink[]Default[]The links between notes, each from source to target. A property, never an attribute.linksToLabelstringDefault"Links to {note}"How a note that links to the selected one is described, with {note}.loadingbooleanDefaultfalseMarks the graph as busy while its notes arrive: the list is aria-busy,
and the panel says so where it holds no notes yet.loadingLabelstringDefault"Loading notes"What the panel says while loading is set and the list holds no notes.movedDownLabelstringDefault"Moved down"What screen readers hear once the drawing has moved down, after moved().movedLeftLabelstringDefault"Moved left"What screen readers hear once the drawing has moved left, after moved().movedRightLabelstringDefault"Moved right"What screen readers hear once the drawing has moved right, after moved().movedUpLabelstringDefault"Moved up"What screen readers hear once the drawing has moved up, after moved().nodesreadonlyGraphNode[]Default[]The notes. A property, never an attribute.noPanelbooleanDefaultfalseLeaves the search and the list out of the frame, behind a button among
its controls that opens them over the drawing. For a graph shown large,
such as at the top of a page, where the drawing takes the whole frame.noteContent((node: GraphNode) => unknown)What each note's row in the list shows in place of its name: a function
given the note that returns text, an element or a Lit template.notesLabelstringDefault"Notes"The list's name, read by screen readers, and the name of the button that opens it with no-panel.panDownLabelstringDefault"Pan down"The pan down button's label.panLeftLabelstringDefault"Pan left"The pan left button's label.panRightLabelstringDefault"Pan right"The pan right button's label.panStepnumberDefault0.25How far one press pans the view, as a fraction of its size.panUpLabelstringDefault"Pan up"The pan up button's label.roleLabelstringDefault"graph"What a screen reader calls the graph in place of its role, after its
name: "Research notes, graph". Said only where the graph has a name of its
own, since the fallback name is the same word. Empty leaves the role.searchLabelstringDefault"Find a note"The search field's name.selectedLabelstringDefault"Selected"How the selected note is described in the list.selectionLabelstringDefault"{note}, selected. {count}"What screen readers hear after a reader selects a note, in the list or in
the drawing, with {note} for its name and {count} for how many notes
the list then holds, written with count-label.settlingLabelstringDefault"Placing the notes"What the settling part says while a layout runs unseen, where the reader
asked for less motion or the page paused its motion.stopLayoutLabelstringDefault"Stop the layout"What the button that stops a long layout says.twoFingerHintLabelstringDefault"Use two fingers to move the graph"The hint shown when one finger swipes over a surface with
gestures="cooperative". Each family declares it as a word property.usingLabelstringDefault"Using the graph. Press Escape to scroll the page again."The line shown while a surface with gestures="activate" has the
gestures. Each family declares it as a word property.walkLabelstringDefault"{note}. {relation}. {index} of {count}"What screen readers hear when a walk along the links moves to a note:
{note} for its name, {relation} for how it stands to the note the
step came from, such as "Linked from Roadmap", and {index} and {count}
for its place among that note's links.wheelHintLabelstringDefault"Use {key} and scroll to zoom the graph"The hint shown when the wheel scrolls past a surface with
gestures="cooperative", with {key}. Each family declares it as a
word property.zoomedInLabelstringDefault"Zoomed in"What screen readers hear once the drawing has zoomed in, after moved().zoomedOutLabelstringDefault"Zoomed out"What screen readers hear once the drawing has zoomed out, after moved().zoomInLabelstringDefault"Zoom in"The zoom in button's label.zoomOutLabelstringDefault"Zoom out"The zoom out button's label.
ReadTypeDescriptionreadybooleanWhether the graph has been drawn whole. For code that runs after helix-graph-ready.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The renderer's box, which the drawing is made in.emptyWhat the panel shows when the list holds no notes. Defaults to empty-label.filter-iconThe icon in the search field. Defaults to a magnifying glass.footerContent below the graph.fullscreen-iconReplaces the glyph inside the fullscreen button.headerContent above the graph.loadingWhat the panel shows while loading is set and the list holds no notes. Defaults to loading-label.pan-down-iconReplaces the glyph inside the pan down button.pan-end-iconReplaces the glyph inside the button that pans toward the end of a line of text.pan-start-iconReplaces the glyph inside the button that pans toward the start of a line of text.pan-up-iconReplaces the glyph inside the pan up button.zoom-in-iconReplaces the glyph inside the zoom-in button.zoom-out-iconReplaces the glyph inside the zoom-out button.
EventTypeDescriptionhelix-activateHelixActivateEventA note was selected, in the list or in the drawing. The detail's value is its id.helix-before-activateHelixBeforeActivateEventA note is about to be selected. Cancelable: cancel it to keep the selection in your own state.helix-graph-filterHelixGraphFilterEventA group in the legend was pressed, to show or hide its notes. The detail's hidden is every group that would be hidden. Cancelable: cancel it to keep the groups as they were, or to set hiddenGroups yourself.helix-graph-layoutHelixGraphLayoutEventA layout settled, with where it put each note, sent by laidOut(). Keep the positions and pass them back as each note's x and y, and z where a renderer draws in three dimensions.helix-graph-panHelixGraphPanEventA pan button or arrow key was pressed. connectGraph moves the drawing, then calls moved().helix-graph-part-changeHelixGraphPartChangeEventThe notes, the links, the selection, the depth, the note the keys are on, or the gestures changed. Used by connectGraph; pages do not need to listen for it.helix-graph-readyHelixGraphReadyEventThe graph has been drawn whole, laid out and settled. Sent each time drawn() says it is drawn after it was not.helix-graph-signalHelixGraphSignalEventSomething passed between two notes, sent by signal(). Used by connectGraph; pages do not need to listen for it.helix-graph-zoomHelixGraphZoomEventA zoom button or key was pressed. connectGraph zooms the drawing, then calls moved().
MethodTypeDescriptiondrawn(whole: unknown) => voidSays the graph has been drawn whole, or with false, that it no longer
is. Called by connectGraph once its layout has settled; a page drawing
its own graph calls it when that graph is finished. The first call after
the graph was not drawn sends helix-graph-ready and turns on
:state(ready).laidOut(positions: Record<string, { x: number; y: number; z?: number | undefined }>) => voidSays where a layout put each note, by its id: sends
helix-graph-layout for the page to keep. Called by connectGraph once
its layout has settled; a page laying out its own graph calls it the same
way.moved() => voidSays the drawing moved the way a reader asked, by a key or a control:
the live region says "Moved right" or "Zoomed in" in the frame's words.
Called by connectGraph once the renderer has moved; a page answering
helix-graph-pan and helix-graph-zoom itself calls it once its view
has moved.pan(to: ViewportWay) => voidPans the view one step in a direction.requestActive(next: string, cause: string) => booleanRequests a new current item, and returns whether the change was applied.settling(stop: () => void, unseen: unknown) => voidSays a layout is running, with what ends it where the notes stand, or
with nothing, that it has ended. Called by connectGraph.signal(from: string, to: string, options: { tone?: GraphSignalDetail["tone"] }) => voidShows something passing from one note to another, such as a message, a
request or a payment, drawn traveling along the drawing and arriving with
a pulse. tone says what it means and colors it. Call it as often as
things happen; each call is one signal.toggleFullscreen() => voidTurns fullscreen on or off.zoom(by: number) => voidZooms the view one step: 1 zooms in and -1 zooms out.
PartDescriptionafterThe room the notes after those drawn would take, so the list scrolls its whole length.beforeThe room the notes before those drawn would take.bodyThe drawing beside the list, or above it where the frame is narrow.controlsThe toolbar the pan and zoom buttons sit in, one tab stop.countHow many notes the list holds, which a search narrows, at the end of the search bar.emptyThe box in place of the list when it holds no notes, holding the empty slot.filter-iconThe icon beside the search field.filter-markThe default icon beside the search field, shown when none is slotted.footerThe strip below the graph.fullscreenThe button that makes the graph fill the screen.fullscreen-buttonfullscreen's inner button.fullscreen-livefullscreen's live region, which speaks while it is pending.fullscreen-spinnerThe ring fullscreen turns while it is pending.fullscreen-textThe box fullscreen's glyph sits in.gesture-hintWords over the graph for a moment when it lets a gesture pass to the page, such as how to zoom it.gesture-statusThe line shown while a graph with gestures="activate" has the gestures.headerThe strip above the graph.legendThe groups over the drawing, with legend: a toolbar of buttons, each showing or hiding its notes, which is one tab stop.legend-itemOne group in the legend, pressed while its notes are shown. Carries data-tone where every note in the group has the same tone, which colors the notes over the group's own color.legend-item-hiddenA group in the legend whose notes are hidden.legend-swatchThe mark in a group's color, before its name.listThe list of notes, which draws only the rows in view.liveWhat screen readers hear: how many notes there are when a search or the legend changes it, and which way the drawing went after a key or a control moved it. Visually hidden in the styled tier.loadingThe box in place of the list while loading is set and it holds no notes, holding the loading slot.noteOne note in the list.note-cursorThe note the keyboard is on in the list.note-linkedA note linked to or from the selected one.note-nameA note's name in the list.note-relationHow a note stands to the selected one, such as "Linked from Alpha".note-selectedThe selected note, first in the list.notes-toggleThe button among the controls that opens the search and the list over the drawing, with no-panel.notes-toggle-buttonnotes-toggle's inner button.notes-toggle-livenotes-toggle's live region, which speaks while it is pending.notes-toggle-spinnerThe ring notes-toggle turns while it is pending.notes-toggle-textThe box notes-toggle's glyph sits in.pan-downThe button that moves the graph down.pan-down-buttonpan-down's inner button.pan-down-livepan-down's live region, which speaks while it is pending.pan-down-spinnerThe ring pan-down turns while it is pending.pan-down-textThe box pan-down's glyph sits in.pan-endThe button that moves the graph toward the end of a line of text: right in English.pan-end-buttonpan-end's inner button.pan-end-livepan-end's live region, which speaks while it is pending.pan-end-spinnerThe ring pan-end turns while it is pending.pan-end-textThe box pan-end's glyph sits in.pan-startThe button that moves the graph toward the start of a line of text: left in English.pan-start-buttonpan-start's inner button.pan-start-livepan-start's live region, which speaks while it is pending.pan-start-spinnerThe ring pan-start turns while it is pending.pan-start-textThe box pan-start's glyph sits in.pan-upThe button that moves the graph up.pan-up-buttonpan-up's inner button.pan-up-livepan-up's live region, which speaks while it is pending.pan-up-spinnerThe ring pan-up turns while it is pending.pan-up-textThe box pan-up's glyph sits in.panelThe search field and the list, beside the drawing or below it, or over the drawing when opened with no-panel.regionThe frame: the drawing, its controls and the list.searchThe bar holding the icon, the search field and the count.search-fieldThe field that finds a note by its name.settlingWhat is said while a layout runs unseen, where the reader asked for less motion or the page paused its motion, over the hidden drawing.stageThe drawing and its controls.stop-layoutThe button that stops a layout that has run past five seconds, where the notes stand.viewportThe box the renderer draws in.zoom-inThe zoom in button.zoom-in-buttonzoom-in's inner button.zoom-in-livezoom-in's live region, which speaks while it is pending.zoom-in-spinnerThe ring zoom-in turns while it is pending.zoom-in-textThe box zoom-in's glyph sits in.zoom-outThe zoom out button.zoom-out-buttonzoom-out's inner button.zoom-out-livezoom-out's live region, which speaks while it is pending.zoom-out-spinnerThe ring zoom-out turns while it is pending.zoom-out-textThe box zoom-out's glyph sits in.
CSS PropertyDescription--graph-background-colorThe color behind the drawing while it loads.--graph-block-sizeThe frame's height, as a length.--graph-border-colorThe frame's border color.--graph-note-hover-colorThe wash over a note in the list while the pointer is over it, and over the note the keyboard is on.--graph-note-padding-inlineThe space at either end of a note in the list.--graph-note-relation-colorThe color of how a note stands to the selected one, such as "Linked from Alpha".--graph-note-selected-background-colorThe fill behind the selected note, which leads the list.--graph-note-selected-weightThe weight of the selected note's name.--graph-note-textThe size of a note's name in the list.--graph-panel-background-colorThe fill behind the search and the list.--graph-panel-colorThe text color of the search and the list.--graph-panel-sizeThe list's width beside the drawing, or over it when opened with no-panel.--viewport-control-background-colorThe background of the zoom and fullscreen buttons. Map and Canvas use the same property.
Custom stateDescriptionemptyThe list holds no notes: the graph has none, or a search or the groups hid them all.fullscreenThe graph fills the screen.idleThe user has been still long enough for the header and footer to fade.loadingWhile loading is set.localThe drawing shows the selected note's local graph, with depth.panel-openA graph with no-panel has the search and the list open over the drawing.readyThe graph has been drawn whole, after helix-graph-ready.searchingThe search field holds words, and the list holds only the notes they find.selectedA note is selected, in the list or in the drawing.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.settlingA layout is running.settling-unseenA layout is running with the drawing hidden, where the reader asked for less motion or the page paused its motion.sharingThe page keeps the plain wheel and one finger, with gestures="cooperative" or while a graph with gestures="activate" waits to be pressed.usingA graph with gestures="activate" has been pressed and has the gestures.
Roothelix-headless-graphA frame around a graph of notes drawn by another library, and the list that makes it readable.
PropTypeDescriptionactivateHintLabelstringDefault"Press the graph to use it"The hint shown when the graph, waiting to be pressed with
gestures="activate", is scrolled or swiped over.activestringThe value of the current item.controlsstringWhich controls to show, as a list such as pan zoom fullscreen, or
none. A family can add words of its own.controlsLabelstringDefault"Graph controls"The name of the group of controls, read by screen readers, which names
what the controls drive rather than the mechanism.controlsPlacement"top-start"|"top-end"|"bottom-start"|"bottom-end"Which corner the controls sit in.countLabelstringDefault"{count, plural, one {# note} other {# notes}}"What the list says of how many notes it holds. {count} is the count,
written in the locale, and each language writes the forms it has.defaultActivestringDefault""The value of the item declared current in markup.depthnumberHow many links from the selected note to show, for its local graph. Unset
shows every note. The list holds what the drawing shows.emptyLabelstringDefault"No notes"What the panel shows when the list holds no notes: the graph has none, or
a search or the legend hid them all. A slotted empty replaces it.fallbackLabelstringDefault"Graph"The graph's name where label is empty and the host has no
aria-label.fullscreenLabelstringDefault"Fill the screen"The fullscreen button's label.gestures"activate"|"always"|"cooperative"Which gestures the surface takes from the page.hiddenGroupsreadonlystring[]Default[]The groups turned off in the legend, by name, whose notes neither the drawing nor the list shows. A property, never an attribute.idleDelaynumberDefault0How long, in milliseconds, before the header and footer hide when the
user is inactive. 0 keeps them visible. The attribute also takes a CSS
time, such as 3s.labelstringDefault""The graph's name, read by screen readers, such as "Research notes".
Required.legendbooleanDefaultfalseNames the groups over the drawing, each a button in its color that shows
or hides its notes. Drawn where the notes have two groups or more.legendLabelstringDefault"Groups"The legend's name, read by screen readers.linkCountLabelstringDefault"{note}. {count, plural, =0 {No links} one {# link} other {# links}}"What screen readers hear when a walk along the links reaches a note that
has no link to follow, or goes back to a note: {note} for its name and
{count} for how many notes the list holds that it links to or from.linkedBothLabelstringDefault"Linked both ways with {note}"How a note linked both to and from the selected one is described, with {note}.linkedFromLabelstringDefault"Linked from {note}"How a note the selected one links to is described, with {note}, the selected note's name.linksreadonlyGraphLink[]Default[]The links between notes, each from source to target. A property, never an attribute.linksToLabelstringDefault"Links to {note}"How a note that links to the selected one is described, with {note}.loadingbooleanDefaultfalseMarks the graph as busy while its notes arrive: the list is aria-busy,
and the panel says so where it holds no notes yet.loadingLabelstringDefault"Loading notes"What the panel says while loading is set and the list holds no notes.movedDownLabelstringDefault"Moved down"What screen readers hear once the drawing has moved down, after moved().movedLeftLabelstringDefault"Moved left"What screen readers hear once the drawing has moved left, after moved().movedRightLabelstringDefault"Moved right"What screen readers hear once the drawing has moved right, after moved().movedUpLabelstringDefault"Moved up"What screen readers hear once the drawing has moved up, after moved().nodesreadonlyGraphNode[]Default[]The notes. A property, never an attribute.noPanelbooleanDefaultfalseLeaves the search and the list out of the frame, behind a button among
its controls that opens them over the drawing. For a graph shown large,
such as at the top of a page, where the drawing takes the whole frame.noteContent((node: GraphNode) => unknown)What each note's row in the list shows in place of its name: a function
given the note that returns text, an element or a Lit template.notesLabelstringDefault"Notes"The list's name, read by screen readers, and the name of the button that opens it with no-panel.panDownLabelstringDefault"Pan down"The pan down button's label.panLeftLabelstringDefault"Pan left"The pan left button's label.panRightLabelstringDefault"Pan right"The pan right button's label.panStepnumberDefault0.25How far one press pans the view, as a fraction of its size.panUpLabelstringDefault"Pan up"The pan up button's label.roleLabelstringDefault"graph"What a screen reader calls the graph in place of its role, after its
name: "Research notes, graph". Said only where the graph has a name of its
own, since the fallback name is the same word. Empty leaves the role.searchLabelstringDefault"Find a note"The search field's name.selectedLabelstringDefault"Selected"How the selected note is described in the list.selectionLabelstringDefault"{note}, selected. {count}"What screen readers hear after a reader selects a note, in the list or in
the drawing, with {note} for its name and {count} for how many notes
the list then holds, written with count-label.settlingLabelstringDefault"Placing the notes"What the settling part says while a layout runs unseen, where the reader
asked for less motion or the page paused its motion.stopLayoutLabelstringDefault"Stop the layout"What the button that stops a long layout says.twoFingerHintLabelstringDefault"Use two fingers to move the graph"The hint shown when one finger swipes over the graph with gestures="cooperative".usingLabelstringDefault"Using the graph. Press Escape to scroll the page again."The line shown while the graph, with gestures="activate", has the gestures.walkLabelstringDefault"{note}. {relation}. {index} of {count}"What screen readers hear when a walk along the links moves to a note:
{note} for its name, {relation} for how it stands to the note the
step came from, such as "Linked from Roadmap", and {index} and {count}
for its place among that note's links.wheelHintLabelstringDefault"Use {key} and scroll to zoom the graph"The hint shown when the wheel scrolls past the graph with
gestures="cooperative". {key} is ⌘ on a Mac and Ctrl elsewhere.zoomedInLabelstringDefault"Zoomed in"What screen readers hear once the drawing has zoomed in, after moved().zoomedOutLabelstringDefault"Zoomed out"What screen readers hear once the drawing has zoomed out, after moved().zoomInLabelstringDefault"Zoom in"The zoom in button's label.zoomOutLabelstringDefault"Zoom out"The zoom out button's label.
ReadTypeDescriptionreadybooleanWhether the graph has been drawn whole. For code that runs after helix-graph-ready.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The renderer's box, which the drawing is made in.emptyWhat the panel shows when the list holds no notes. Defaults to empty-label.filter-iconThe icon in the search field. Defaults to a magnifying glass.footerContent below the graph.fullscreen-iconReplaces the glyph inside the fullscreen button.headerContent above the graph.loadingWhat the panel shows while loading is set and the list holds no notes. Defaults to loading-label.pan-down-iconReplaces the glyph inside the pan down button.pan-end-iconReplaces the glyph inside the button that pans toward the end of a line of text.pan-start-iconReplaces the glyph inside the button that pans toward the start of a line of text.pan-up-iconReplaces the glyph inside the pan up button.zoom-in-iconReplaces the glyph inside the zoom-in button.zoom-out-iconReplaces the glyph inside the zoom-out button.
EventTypeDescriptionhelix-activateHelixActivateEventA note was selected, in the list or in the drawing. The detail's value is its id.helix-before-activateHelixBeforeActivateEventA note is about to be selected. Cancelable: cancel it to keep the selection in your own state.helix-graph-filterHelixGraphFilterEventA group in the legend was pressed, to show or hide its notes. The detail's hidden is every group that would be hidden. Cancelable: cancel it to keep the groups as they were, or to set hiddenGroups yourself.helix-graph-layoutHelixGraphLayoutEventA layout settled, with where it put each note, sent by laidOut(). Keep the positions and pass them back as each note's x and y, and z where a renderer draws in three dimensions.helix-graph-panHelixGraphPanEventA pan button or arrow key was pressed. connectGraph moves the drawing, then calls moved().helix-graph-part-changeHelixGraphPartChangeEventThe notes, the links, the selection, the depth, the note the keys are on, or the gestures changed. Used by connectGraph; pages do not need to listen for it.helix-graph-readyHelixGraphReadyEventThe graph has been drawn whole, laid out and settled. Sent each time drawn() says it is drawn after it was not.helix-graph-signalHelixGraphSignalEventSomething passed between two notes, sent by signal(). Used by connectGraph; pages do not need to listen for it.helix-graph-zoomHelixGraphZoomEventA zoom button or key was pressed. connectGraph zooms the drawing, then calls moved().
MethodTypeDescriptiondrawn(whole: unknown) => voidSays the graph has been drawn whole, or with false, that it no longer
is. Called by connectGraph once its layout has settled; a page drawing
its own graph calls it when that graph is finished. The first call after
the graph was not drawn sends helix-graph-ready and turns on
:state(ready).laidOut(positions: Record<string, { x: number; y: number; z?: number | undefined }>) => voidSays where a layout put each note, by its id: sends
helix-graph-layout for the page to keep. Called by connectGraph once
its layout has settled; a page laying out its own graph calls it the same
way.moved() => voidSays the drawing moved the way a reader asked, by a key or a control:
the live region says "Moved right" or "Zoomed in" in the frame's words.
Called by connectGraph once the renderer has moved; a page answering
helix-graph-pan and helix-graph-zoom itself calls it once its view
has moved.pan(to: ViewportWay) => voidPans the view one step in a direction.requestActive(next: string, cause: string) => booleanAsks for a note to be selected, and remembers the ask, so the selection is said once it lands.settling(stop: () => void, unseen: unknown) => voidSays a layout is running, with what ends it where the notes stand, or
with nothing, that it has ended. Called by connectGraph.signal(from: string, to: string, options: { tone?: GraphSignalDetail["tone"] }) => voidShows something passing from one note to another, such as a message, a
request or a payment, drawn traveling along the drawing and arriving with
a pulse. tone says what it means and colors it. Call it as often as
things happen; each call is one signal.toggleFullscreen() => voidTurns fullscreen on or off.zoom(by: number) => voidZooms the view one step: 1 zooms in and -1 zooms out.
PartDescriptionafterThe room the notes after those drawn would take, so the list scrolls its whole length.beforeThe room the notes before those drawn would take.bodyThe drawing beside the list, or above it where the frame is narrow.controlsThe toolbar the pan and zoom buttons sit in, one tab stop.countHow many notes the list holds, which a search narrows, at the end of the search bar.emptyThe box in place of the list when it holds no notes, holding the empty slot.filter-iconThe icon beside the search field.filter-markThe default icon beside the search field, shown when none is slotted.footerThe strip below the graph.fullscreenThe button that makes the graph fill the screen.fullscreen-buttonfullscreen's inner button.fullscreen-livefullscreen's live region, which speaks while it is pending.fullscreen-spinnerThe ring fullscreen turns while it is pending.fullscreen-textThe box fullscreen's glyph sits in.gesture-hintWords over the graph for a moment when it lets a gesture pass to the page, such as how to zoom it.gesture-statusThe line shown while a graph with gestures="activate" has the gestures.headerThe strip above the graph.legendThe groups over the drawing, with legend: a toolbar of buttons, each showing or hiding its notes, which is one tab stop.legend-itemOne group in the legend, pressed while its notes are shown. Carries data-tone where every note in the group has the same tone, which colors the notes over the group's own color.legend-item-hiddenA group in the legend whose notes are hidden.legend-swatchThe mark in a group's color, before its name.listThe list of notes, which draws only the rows in view.liveWhat screen readers hear: how many notes there are when a search or the legend changes it, and which way the drawing went after a key or a control moved it. Visually hidden in the styled tier.loadingThe box in place of the list while loading is set and it holds no notes, holding the loading slot.noteOne note in the list.note-cursorThe note the keyboard is on in the list.note-linkedA note linked to or from the selected one.note-nameA note's name in the list.note-relationHow a note stands to the selected one, such as "Linked from Alpha".note-selectedThe selected note, first in the list.notes-toggleThe button among the controls that opens the search and the list over the drawing, with no-panel.notes-toggle-buttonnotes-toggle's inner button.notes-toggle-livenotes-toggle's live region, which speaks while it is pending.notes-toggle-spinnerThe ring notes-toggle turns while it is pending.notes-toggle-textThe box notes-toggle's glyph sits in.pan-downThe button that moves the graph down.pan-down-buttonpan-down's inner button.pan-down-livepan-down's live region, which speaks while it is pending.pan-down-spinnerThe ring pan-down turns while it is pending.pan-down-textThe box pan-down's glyph sits in.pan-endThe button that moves the graph toward the end of a line of text: right in English.pan-end-buttonpan-end's inner button.pan-end-livepan-end's live region, which speaks while it is pending.pan-end-spinnerThe ring pan-end turns while it is pending.pan-end-textThe box pan-end's glyph sits in.pan-startThe button that moves the graph toward the start of a line of text: left in English.pan-start-buttonpan-start's inner button.pan-start-livepan-start's live region, which speaks while it is pending.pan-start-spinnerThe ring pan-start turns while it is pending.pan-start-textThe box pan-start's glyph sits in.pan-upThe button that moves the graph up.pan-up-buttonpan-up's inner button.pan-up-livepan-up's live region, which speaks while it is pending.pan-up-spinnerThe ring pan-up turns while it is pending.pan-up-textThe box pan-up's glyph sits in.panelThe search field and the list, beside the drawing or below it, or over the drawing when opened with no-panel.regionThe frame: the drawing, its controls and the list.searchThe bar holding the icon, the search field and the count.search-fieldThe field that finds a note by its name.settlingWhat is said while a layout runs unseen, where the reader asked for less motion or the page paused its motion, over the hidden drawing.stageThe drawing and its controls.stop-layoutThe button that stops a layout that has run past five seconds, where the notes stand.viewportThe box the renderer draws in.zoom-inThe zoom in button.zoom-in-buttonzoom-in's inner button.zoom-in-livezoom-in's live region, which speaks while it is pending.zoom-in-spinnerThe ring zoom-in turns while it is pending.zoom-in-textThe box zoom-in's glyph sits in.zoom-outThe zoom out button.zoom-out-buttonzoom-out's inner button.zoom-out-livezoom-out's live region, which speaks while it is pending.zoom-out-spinnerThe ring zoom-out turns while it is pending.zoom-out-textThe box zoom-out's glyph sits in.
Custom stateDescriptionemptyThe list holds no notes: the graph has none, or a search or the groups hid them all.fullscreenThe graph fills the screen.idleThe user has been still long enough for the header and footer to fade.loadingWhile loading is set.localThe drawing shows the selected note's local graph, with depth.panel-openA graph with no-panel has the search and the list open over the drawing.readyThe graph has been drawn whole, after helix-graph-ready.searchingThe search field holds words, and the list holds only the notes they find.selectedA note is selected, in the list or in the drawing.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.settlingA layout is running.settling-unseenA layout is running with the drawing hidden, where the reader asked for less motion or the page paused its motion.sharingThe page keeps the plain wheel and one finger, with gestures="cooperative" or while a graph with gestures="activate" waits to be pressed.usingA graph with gestures="activate" has been pressed and has the gestures.
Examples
NameDescriptionArchitectureA web service's architecture as an isometric diagram: each service a block, each store a cylinder, and each tier on a plate of its own.BrainEight thousand notes fitted into the shape of a brain, each region of the mind a region of the drawing, with thoughts passing between them.Brain 3dEight thousand notes on the surface of a 3D model of a brain, each region of the mind in its lobe of the brain, with thoughts passing between them.KnotThree thousand services on the surface of a 3D model, a knot, each team a stretch of it, with requests passing between them.LargeTwenty thousand notes, laid out and drawn on the GPU by cosmos.gl, with messages passing between them.LiveA graph of company notes drawn by Sigma.js, with notes arriving and messages passing between them as they happen, and a legend that shows or hides each subject.NetworkAn office network seen from a steeper angle, turned a little from the front, with each floor on a plate of its own.PipelineA data pipeline whose notes give no places: the driver lays them out in columns along the links, sources first, turned so the flow runs across the page.PreviewA graph of linked notes, with the selected note's links and backlinks listed first.PreviewA graph of linked notes, with the selected note's links and backlinks listed first.TurningThe same architecture with buttons that turn it a quarter at a time and look at it from above. Shift with a drag turns and tilts it freely.