Continuous domain navigation

Read as Markdown

Import from @pibbl/core/viz:

import type {
  ResolvedContinuousScale,
  LinearDomain,
  PanDomainOptions,
  ZoomDomainOptions,
} from "@pibbl/core/viz";

declare function panDomain(
  scale: ResolvedContinuousScale,
  options: PanDomainOptions,
): LinearDomain;
declare function zoomDomain(
  scale: ResolvedContinuousScale,
  options: ZoomDomainOptions,
): LinearDomain;

PanDomainOptions extends DomainNavigationConstraints with required rangeDelta: number. ZoomDomainOptions extends the same constraints with required rangeAnchor: number and factor: number. All settings live directly in the second argument: { rangeDelta, bounds, minimumSpanRatio? } or { rangeAnchor, factor, bounds, minimumSpanRatio? }. The old positional signatures are not supported.

Both return a frozen two-number domain pair and own no signals, layout, events, resources, or scheduling. Read the current mapping from its dedicated scale hook, call the operation in an event handler, and write the pair to an application-owned domain signal. The algorithms work through map/invert for linear, UTC, log, and symlog scales, including reversed ranges and descending domains. Categorical scales are not continuous mappings and are not accepted.

options.bounds is a required finite two-endpoint hard domain extent, in either order. Values must be valid for the chosen scale (positive for log, safe integer milliseconds for UTC). minimumSpanRatio defaults to 0.01, must be greater than zero and at most one, and measures the minimum fraction of the mapped hard bounds. On log scales, this is a logarithmic extent, not a minimum arithmetic difference.

The helpers impose no unit on numeric ranges. rangeDelta is a displacement in range units; rangeAnchor is a position in those same coordinates. A range may represent logical pixels, normalized coordinates, or another numeric system. Positive rangeDelta shifts mapped values toward increasing range coordinates and moves the viewing domain oppositely. factor > 1 magnifies; a factor between zero and one zooms out. The anchor’s data value stays stationary unless bounds or the minimum span limit the request. At constraints the window shifts/clamps; a too-small window expands around its center. Bounds can therefore move the anchor. UTC results round to integer milliseconds, with corresponding sub-ms anchor error. No caller data is sorted, aggregated, or changed.

Nonfinite values, nonpositive factors, invalid minimum ratios, collapsed bounds, collapsed current domain/range, nonfinite mapped arithmetic, and a result that collapses at numeric precision throw RangeError (or the mapping’s validation error). Inputs are ordinary values: resolve signals explicitly. Wheel delta normalization, touch behavior, reset policy, and gesture cancellation belong to the application, as shown in the domain exploration example.

API details from source

panDomain

Moves the visible continuous domain by a displacement expressed in range units. Positive displacement shifts mapped values toward increasing range coordinates; the returned domain moves oppositely.

panDomain: (scale: ResolvedContinuousScale, options: PanDomainOptions) => LinearDomain

Related API: panDomain, ResolvedContinuousScale, PanDomainOptions, LinearDomain.

Parameters

• scale — Current resolved continuous mapping. See ResolvedContinuousScale.

• options — Displacement, bounds, and minimum span. See PanDomainOptions.

Returns

A new immutable domain pair. See LinearDomain.

Throws

When inputs, bounds, or the resulting extent are invalid or collapsed.

See also

zoomDomain

View source — packages/core/src/features/viz/lib/domain-navigation.ts:94

zoomDomain

Magnifies a continuous domain around an anchor in range coordinates. Factor greater than one zooms in; hard bounds and minimum span may limit anchor preservation.

zoomDomain: (scale: ResolvedContinuousScale, options: ZoomDomainOptions) => LinearDomain

Related API: zoomDomain, ResolvedContinuousScale, ZoomDomainOptions, LinearDomain.

Parameters

• scale — Current resolved continuous mapping. See ResolvedContinuousScale.

• options — Anchor, magnification, bounds, and minimum span. See ZoomDomainOptions.

Returns

A new immutable domain pair. See LinearDomain.

Throws

When factor, mapping, bounds, or the resulting extent are invalid or collapsed.

See also

panDomain

View source — packages/core/src/features/viz/lib/domain-navigation.ts:117

DomainNavigationConstraints

Explicit hard bounds and minimum mapped extent for continuous-domain navigation.

interface DomainNavigationConstraints

Related API: DomainNavigationConstraints.

See also

panDomain

zoomDomain

View source — packages/core/src/features/viz/lib/domain-navigation.ts:3

Properties and methods

bounds

readonly bounds: LinearDomain

Related API: LinearDomain.

Finite hard domain endpoints, in either order, valid for the supplied scale. See LinearDomain.

View source — packages/core/src/features/viz/lib/domain-navigation.ts:5

minimumSpanRatio (optional)

readonly minimumSpanRatio?: number | undefined

Minimum span as a fraction of the mapped hard bounds, greater than zero through one. Defaults to 0.01.

View source — packages/core/src/features/viz/lib/domain-navigation.ts:7

PanDomainOptions

Named pan settings with explicit navigation limits.

interface PanDomainOptions extends DomainNavigationConstraints

Related API: PanDomainOptions, DomainNavigationConstraints.

See also

panDomain

View source — packages/core/src/features/viz/lib/domain-navigation.ts:10

Properties and methods

rangeDelta

readonly rangeDelta: number

Finite displacement in range units; positive shifts mapped values toward increasing range coordinates.

View source — packages/core/src/features/viz/lib/domain-navigation.ts:12

bounds

readonly bounds: LinearDomain

Related API: LinearDomain.

Finite hard domain endpoints, in either order, valid for the supplied scale. See LinearDomain.

View source — packages/core/src/features/viz/lib/domain-navigation.ts:5

minimumSpanRatio (optional)

readonly minimumSpanRatio?: number | undefined

Minimum span as a fraction of the mapped hard bounds, greater than zero through one. Defaults to 0.01.

View source — packages/core/src/features/viz/lib/domain-navigation.ts:7

ZoomDomainOptions

Named zoom settings with explicit navigation limits.

interface ZoomDomainOptions extends DomainNavigationConstraints

Related API: ZoomDomainOptions, DomainNavigationConstraints.

See also

zoomDomain

View source — packages/core/src/features/viz/lib/domain-navigation.ts:15

Properties and methods

rangeAnchor

readonly rangeAnchor: number

Finite anchor in the scale’s range coordinates, using the same units as its range.

View source — packages/core/src/features/viz/lib/domain-navigation.ts:17

factor

readonly factor: number

Finite positive magnification; greater than one zooms in.

View source — packages/core/src/features/viz/lib/domain-navigation.ts:19

bounds

readonly bounds: LinearDomain

Related API: LinearDomain.

Finite hard domain endpoints, in either order, valid for the supplied scale. See LinearDomain.

View source — packages/core/src/features/viz/lib/domain-navigation.ts:5

minimumSpanRatio (optional)

readonly minimumSpanRatio?: number | undefined

Minimum span as a fraction of the mapped hard bounds, greater than zero through one. Defaults to 0.01.

View source — packages/core/src/features/viz/lib/domain-navigation.ts:7

Implementation guidance for agents

Read the Data visualization companion for ownership, adaptation, failure modes, and verification. Agent start provides the version-selection workflow.

Complete minimal examples

• Bounded domain navigation: Pan and zoom by mapping and inverting an explicit continuous scale. Plain source

Documentation version

Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.