@gluonjs/graph

@gluonjs/graph / packages/graph/src / GluonGraphElement

Class: GluonGraphElement

A dependency-free, canvas-backed network graph Custom Element. The element owns camera interaction, deterministic layout, selection, and drawing; a host can own product-specific filters and controls through the public properties.

Extends

• GluonElement<GluonGraphEvents>

Constructors

Constructor

new GluonGraphElement(): GluonGraphElement

Returns

GluonGraphElement

Overrides

GluonElement.constructor

Properties

activeGroups

activeGroups: readonly string[]

groups

groups: readonly GraphGroup[]

linkDensity

linkDensity: number

links

links: readonly GraphLink[]

nodes

nodes: readonly GraphNode[]

nodeScale

nodeScale: number

renderRoot

protected readonly renderRoot: ShadowRoot

Shadow root rendered by update; override createRenderRoot to customize it.

Inherited from

GluonElement.renderRoot

searchQuery

searchQuery: string

seed

seed: string

showLabels

showLabels: boolean

events

readonly static events: object

Declares native output events and their propagation, cancellation, and validation rules.

graph-node-select

graph-node-select: object = {}

graph-viewport-change

graph-viewport-change: object = {}

Overrides

GluonElement.events

properties

readonly static properties: object

Declares reactive inputs and their attribute conversion, reflection, and validation rules.

activeGroups

activeGroups: object

activeGroups.attribute

attribute: false = false

activeGroups.default

default: () => never[]

Returns

never[]

groups

groups: object

groups.attribute

attribute: false = false

groups.default

default: () => never[]

Returns

never[]

linkDensity

linkDensity: object

linkDensity.attribute

attribute: string = 'link-density'

linkDensity.default

default: number = 1

linkDensity.type

type: NumberConstructor = Number

links

links: object

links.attribute

attribute: false = false

links.default

default: () => never[]

Returns

never[]

nodes

nodes: object

nodes.attribute

attribute: false = false

nodes.default

default: () => never[]

Returns

never[]

nodeScale

nodeScale: object

nodeScale.attribute

attribute: string = 'node-scale'

nodeScale.default

default: number = 1

nodeScale.type

type: NumberConstructor = Number

searchQuery

searchQuery: object

searchQuery.attribute

attribute: string = 'search-query'

searchQuery.default

default: string = ''

searchQuery.type

type: StringConstructor = String

seed

seed: object

seed.default

default: string = 'gluon-graph'

seed.type

type: StringConstructor = String

showLabels

showLabels: object

showLabels.attribute

attribute: string = 'show-labels'

showLabels.default

default: false = false

showLabels.type

type: BooleanConstructor = Boolean

Overrides

GluonElement.properties

shadowRootRegistry?

readonly static optional shadowRootRegistry?: GluonElementRegistry

Optional explicit registry associated with this element's ShadowRoot.

Inherited from

GluonElement.shadowRootRegistry

slots

readonly static slots: SlotDeclarations = {}

Declares required named/default slots and whether the template supplies fallback content.

Inherited from

GluonElement.slots

styles

readonly static styles: CSSStyleSheet = graphStyles

Lists constructable stylesheets adopted into each instance's render root.

Overrides

GluonElement.styles

Accessors

updateComplete

Get Signature

get updateComplete(): Promise<void>

Resolves after the currently scheduled render and its update hooks finish.

Returns

Promise<void>

Inherited from

GluonElement.updateComplete

observedAttributes

Get Signature

get static observedAttributes(): string[]

Attribute names derived from properties; managed by Gluon for the Custom Elements platform.

Returns

string[]

Inherited from

GluonElement.observedAttributes

Methods

attributeChangedCallback()

attributeChangedCallback(name, oldValue, value): void

Converts a changed declared attribute and writes the corresponding property.

Parameters

name

string

oldValue

string | null

value

string | null

Returns

void

Inherited from

GluonElement.attributeChangedCallback

beginHydration()

beginHydration(): void

Defers the first connection render while official hydration binds declarative Shadow DOM.

Returns

void

Inherited from

GluonElement.beginHydration

connectedCallback()

connectedCallback(): void

Starts connection-owned reactivity and queues the first render. Prefer onConnected in subclasses.

Returns

void

Inherited from

GluonElement.connectedCallback

createRenderRoot()

protected createRenderRoot(): ShadowRoot

Creates the component render root. Override only when the default open ShadowRoot is unsuitable.

Returns

ShadowRoot

Inherited from

GluonElement.createRenderRoot

disconnectedCallback()

disconnectedCallback(): void

Stops connection-owned work and suspends rendering. Prefer onDisconnected in subclasses.

Returns

void

Inherited from

GluonElement.disconnectedCallback

emit()

protected emit<Name>(type, detail, init?): boolean

Dispatches a typed native CustomEvent using the matching static event declaration.

Events bubble and cross the Shadow DOM boundary by default. The return value is false only when a cancelable event was canceled by a listener.

Type Parameters

Name

Name extends "graph-node-select" | "graph-viewport-change"

Parameters

type

Name

detail

GluonGraphEvents[Name]

init?

Omit<CustomEventInit<Events[Name]>, "detail"> = {}

Returns

boolean

Inherited from

GluonElement.emit

endHydration()

endHydration(): void

Resumes connection rendering after official hydration installs the hydrated root.

Returns

void

Inherited from

GluonElement.endHydration

expose()

protected expose<Public>(value): Readonly<Public>

Publishes a frozen, deliberately small public object for use with exposedRef().

Type Parameters

Public

Public extends object

Parameters

value

Public

Returns

Readonly<Public>

Inherited from

GluonElement.expose

getViewport()

getViewport(): GraphViewport

Returns an immutable snapshot of the current camera position.

Returns

GraphViewport

onBeforeUpdate()

protected onBeforeUpdate(callback): void

Runs a callback before every update after the first render.

Parameters

callback

ComponentLifecycleCallback

Returns

void

Inherited from

GluonElement.onBeforeUpdate

onConnected()

protected onConnected(callback): void

Runs a callback once after the first render of each connection.

Parameters

callback

ComponentLifecycleCallback

Returns

void

Inherited from

GluonElement.onConnected

onDisconnected()

protected onDisconnected(callback): void

Runs a callback during disconnection after scoped reactive cleanup and render suspension.

Parameters

callback

ComponentLifecycleCallback

Returns

void

Inherited from

GluonElement.onDisconnected

onErrorCaptured()

protected onErrorCaptured(callback): void

Captures descendant component errors; return true to stop propagation to outer boundaries.

Parameters

callback

ComponentErrorBoundary

Returns

void

Inherited from

GluonElement.onErrorCaptured

onUpdated()

protected onUpdated(callback): void

Runs a callback after every successful render, including the first render.

Parameters

callback

ComponentLifecycleCallback

Returns

void

Inherited from

GluonElement.onUpdated

recenter()

recenter(): void

Restores the deterministic centered camera and clears the selection.

Returns

void

render()

protected render(): TemplateResult

Returns the template for the current component state.

Returns

TemplateResult

Overrides

GluonElement.render

renderForServer()

renderForServer(): TemplateResult

Returns the component template without browser connection lifecycle for official server rendering.

Returns

TemplateResult

Inherited from

GluonElement.renderForServer

requestHotUpdate()

requestHotUpdate(): Promise<void>

Requests a render pass after the official Vite runtime patches compatible logic. Application code should use normal reactive or property updates.

Returns

Promise<void>

Inherited from

GluonElement.requestHotUpdate

requestUpdate()

protected requestUpdate(): Promise<void>

Schedules a deduplicated render and returns the same completion promise exposed by updateComplete.

Returns

Promise<void>

Inherited from

GluonElement.requestUpdate

restartSimulation()

restartSimulation(): void

Recreates positions from a new deterministic seed and redraws the graph.

Returns

void

setupConnection()

protected setupConnection(): void

Initializes work once per connection inside the connection's reactive effect scope.

Returns

void

Inherited from

GluonElement.setupConnection

teardownConnection()

protected teardownConnection(): void

Releases connection-local references after scoped cleanup and disconnect hooks.

Returns

void

Inherited from

GluonElement.teardownConnection

update()

protected update(): void

Commits the value returned by render into renderRoot.

Returns

void

Overrides

GluonElement.update

zoomIn()

zoomIn(): void

Increases the camera scale around the graph centre.

Returns

void

zoomOut()

zoomOut(): void

Decreases the camera scale around the graph centre.

Returns

void

Example

Render an optional, canvas-backed graph from typed input and retain its native pan, zoom, selection, and recenter controls:

import '@gluonjs/graph';
import { graphTagName, type GluonGraphElement, type GluonGraphEvents, type GraphGroup, type GraphLink, type GraphNode, type GraphNodeSelection, type GraphViewport } from '@gluonjs/graph';

const groups = [{ id: 'research', label: 'Research', color: '#8ba9ff' }] satisfies readonly GraphGroup[];
const nodes = [{ id: 'brief', label: 'Research brief', group: 'research', weight: 3 }] satisfies readonly GraphNode[];
const links = [] satisfies readonly GraphLink[];
const graph = document.createElement(graphTagName) as GluonGraphElement;
Object.assign(graph, { groups, nodes, links, showLabels: true });
const selection = (event: CustomEvent<GluonGraphEvents['graph-node-select']>) => {
  const detail: GraphNodeSelection = event.detail;
  console.log(detail.node.label, detail.selected);
};
graph.addEventListener('graph-node-select', selection as EventListener);
const viewport: GraphViewport = graph.getViewport();
graph.recenter();
console.log(viewport.scale);