Documentation / @ripl/core / Navigator

Class: Navigator

Defined in: packages/core/src/core/navigator.ts:175

An interactive 2D pan/zoom/brush controller, the flat-scene analogue of the 3D Camera. This base class is deliberately context-agnostic: it owns the view model (a { k, x, y } transform plus an optional brush selection) and the imperative commands that mutate it, but it attaches no input listeners of its own. That mirrors the Context/DOMContext split; the DOM-bound DOMNavigator in @ripl/dom extends this class to translate real wheel/pointer/touch gestures into these commands, while non-DOM environments can drive the same view model programmatically (or subclass it with their own input source).

The navigator does not itself repaint; consumers react to the emitted zoom/pan/change/ brush/brushend events (e.g. rescaling axis domains via rescaleDomain, or applying the transform to a context). Translation is unbounded, so a consumer can pan and zoom to content that currently sits outside the viewport: the Figma-style "navigate anywhere" behavior.

Extends

• EventBus<NavigatorEventMap>

Extended by

• DOMNavigator

Constructors

Constructor

new Navigator(options?): Navigator

Defined in: packages/core/src/core/navigator.ts:232

Parameters

Parameter	Type
options?	NavigatorOptions

Returns

Navigator

Overrides

EventBus.constructor

Properties

Property	Modifier	Type	Default value	Description	Inherited from	Defined in
_brush	protected	NavigatorBrush | null	null	-	-	packages/core/src/core/navigator.ts:177
_scaleExtent	protected	[number, number]	undefined	-	-	packages/core/src/core/navigator.ts:178
_transform	protected	NavigatorTransform	undefined	-	-	packages/core/src/core/navigator.ts:180
_viewport	protected	NavigatorViewport	undefined	-	-	packages/core/src/core/navigator.ts:179
parent?	public	EventBus<NavigatorEventMap>	undefined	The parent event bus that emitted events bubble up to, if any.	EventBus.parent	packages/core/src/core/event-bus.ts:107
defaultKey	readonly	typeof defaultKey	undefined	The key under which resources are retained when no explicit key is provided.	EventBus.defaultKey	packages/core/src/core/disposer.ts:11

Accessors

$events

Get Signature

get $events(): keyof NavigatorEventMap[]

Defined in: packages/core/src/core/navigator.ts:187

The event types a navigator can emit. See EventBus.$events.

Returns

keyof NavigatorEventMap[]

Overrides

EventBus.$events

---

brush

Get Signature

get brush(): NavigatorBrush | null

Defined in: packages/core/src/core/navigator.ts:206

The current brush selection, or null when nothing is selected.

Returns

NavigatorBrush | null

---

scaleExtent

Get Signature

get scaleExtent(): [number, number]

Defined in: packages/core/src/core/navigator.ts:213

The minimum/maximum zoom factor the transform is clamped to.

Returns

[number, number]

---

transform

Get Signature

get transform(): NavigatorTransform

Defined in: packages/core/src/core/navigator.ts:199

The current view transform (a copy; mutating it does not affect the navigator).

Returns

NavigatorTransform

---

viewport

Get Signature

get viewport(): NavigatorViewport

Defined in: packages/core/src/core/navigator.ts:220

The viewport dimensions used by centerOn/fitBounds.

Returns

NavigatorViewport

Set Signature

set viewport(viewport): void

Defined in: packages/core/src/core/navigator.ts:226

Parameters

Parameter	Type
viewport	NavigatorViewport

Returns

void

Methods

_commit()

protected _commit(event): void

Defined in: packages/core/src/core/navigator.ts:242

Parameters

Parameter	Type
event	"zoom" | "pan"

Returns

void

---

applyPoint()

applyPoint(point): Point

Defined in: packages/core/src/core/navigator.ts:250

Applies the transform to a point in content space, returning its on-screen position in logical pixels.

Parameters

Parameter	Type
point	Point

Returns

Point

---

centerOn()

centerOn(point, viewport?): void

Defined in: packages/core/src/core/navigator.ts:321

Centers a content-space point within the viewport, keeping the current zoom. Useful for bringing an off-screen element into view without changing scale.

Parameters

Parameter	Type
point	Point
viewport	NavigatorViewport

Returns

void

---

clearBrush()

clearBrush(): void

Defined in: packages/core/src/core/navigator.ts:389

Clears the brush selection and emits a brushend event with null.

Returns

void

---

destroy()

destroy(): void

Defined in: packages/core/src/core/event-bus.ts:210

Emits a destroyed event, clears all listeners, and disposes retained resources. Idempotent: a second call is a no-op, so a listener registered after teardown is not woken by it.

Returns

void

Inherited from

EventBus.destroy

---

dispose()

protected dispose(key?): void

Defined in: packages/core/src/core/disposer.ts:25

Disposes all resources under the given key, or all resources if no key is provided.

Parameters

Parameter	Type
key?	PropertyKey

Returns

void

Inherited from

EventBus.dispose

---

emit()

Call Signature

emit<TEvent>(event): TEvent

Defined in: packages/core/src/core/event-bus.ts:185

Emits an event, invoking all matching handlers and bubbling to the parent if applicable. Handlers for the event's own type run first, then EVENT_WILDCARD subscriptions.

Type Parameters

Type Parameter	Default type
TEvent extends Event<undefined>	Event<undefined>

Parameters

Parameter	Type
event	TEvent

Returns

TEvent

Inherited from

EventBus.emit

Call Signature

emit<TEvent>(type, data): Event<NavigatorEventMap[TEvent]>

Defined in: packages/core/src/core/event-bus.ts:186

Emits an event, invoking all matching handlers and bubbling to the parent if applicable. Handlers for the event's own type run first, then EVENT_WILDCARD subscriptions.

Type Parameters

Type Parameter
TEvent extends keyof NavigatorEventMap

Parameters

Parameter	Type
type	TEvent
data	NavigatorEventMap[TEvent]

Returns

Event<NavigatorEventMap[TEvent]>

Inherited from

EventBus.emit

---

fitBounds()

fitBounds(bounds, options?): void

Defined in: packages/core/src/core/navigator.ts:338

Zooms and pans so a content-space box fills the viewport (respecting the scale extent and an optional padding). This is the primary way to jump the view to content, including content that currently lies entirely outside the viewport.

Parameters

Parameter	Type
bounds	NavigatorBrush
options?	NavigatorFitOptions

Returns

void

---

has()

has(type): boolean

Defined in: packages/core/src/core/event-bus.ts:123

Returns whether there are any listeners registered for the given event type. Wildcard subscriptions (EVENT_WILDCARD) are not listeners for any concrete type, so a bus observed only through the wildcard still reports false here.

Parameters

Parameter	Type
type	keyof NavigatorEventMap

Returns

boolean

Inherited from

EventBus.has

---

invertPoint()

invertPoint(point): Point

Defined in: packages/core/src/core/navigator.ts:258

Inverts an on-screen point, in logical pixels, back to content space.

Parameters

Parameter	Type
point	Point

Returns

Point

---

off()

off<TEvent>(type, handler): void

Defined in: packages/core/src/core/event-bus.ts:144

Removes a previously registered handler for the given event type.

Type Parameters

Type Parameter
TEvent extends keyof NavigatorEventMap

Parameters

Parameter	Type
type	TEvent
handler	EventHandler<NavigatorEventMap[TEvent]>

Returns

void

Inherited from

EventBus.off

---

on()

on<TEvent>(type, handler, options?): Disposable

Defined in: packages/core/src/core/event-bus.ts:131

Subscribes a handler to the given event type and returns a disposable for cleanup. Pass EVENT_WILDCARD to receive every event emitted on the bus regardless of type.

Type Parameters

Type Parameter
TEvent extends keyof NavigatorEventMap

Parameters

Parameter	Type
type	TEvent
handler	EventHandler<NavigatorEventMap[TEvent]>
options?	EventSubscriptionOptions

Returns

Disposable

Inherited from

EventBus.on

---

once()

once<TEvent>(type, handler, options?): Disposable

Defined in: packages/core/src/core/event-bus.ts:159

Subscribes a handler that is automatically removed after it fires once.

Type Parameters

Type Parameter
TEvent extends keyof NavigatorEventMap

Parameters

Parameter	Type
type	TEvent
handler	EventHandler<NavigatorEventMap[TEvent]>
options?	EventSubscriptionOptions

Returns

Disposable

Inherited from

EventBus.once

---

panBy()

panBy(dx, dy): void

Defined in: packages/core/src/core/navigator.ts:277

Pans the view by a pixel delta.

Parameters

Parameter	Type
dx	number
dy	number

Returns

void

---

panTo()

panTo(x, y): void

Defined in: packages/core/src/core/navigator.ts:288

Pans the view to an absolute translation.

Parameters

Parameter	Type
x	number
y	number

Returns

void

---

reset()

reset(): void

Defined in: packages/core/src/core/navigator.ts:366

Resets the transform to the identity (no zoom, no pan).

Returns

void

---

retain()

protected retain(value, key?): void

Defined in: packages/core/src/core/disposer.ts:14

Registers a disposable resource under an optional key for later cleanup.

Parameters

Parameter	Type	Default value
value	Disposable	undefined
key	PropertyKey	Disposer.defaultKey

Returns

void

Inherited from

EventBus.retain

---

setBrush()

setBrush(brush): void

Defined in: packages/core/src/core/navigator.ts:377

Sets the brush selection, normalizing the extent, and emits a brush event.

Parameters

Parameter	Type
brush	NavigatorBrush

Returns

void

---

setTransform()

setTransform(transform): void

Defined in: packages/core/src/core/navigator.ts:266

Replaces the view transform outright (clamping k to the scale extent).

Parameters

Parameter	Type
transform	NavigatorTransform

Returns

void

---

zoomBy()

zoomBy(factor, center?): void

Defined in: packages/core/src/core/navigator.ts:299

Multiplies the zoom by factor, keeping center (logical pixels, defaults to the origin) fixed.

Parameters

Parameter	Type
factor	number
center	Point

Returns

void

---

zoomTo()

zoomTo(k, center?): void

Defined in: packages/core/src/core/navigator.ts:313

Sets the absolute zoom factor, keeping center fixed.

Parameters

Parameter	Type
k	number
center	Point

Returns

void