# Continuous domain navigation

Import from `@pibbl/core/viz`:

```ts
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](/playground/#/examples/composition/viz-domain-exploration).

## API details from source

<span id="api-panDomain"></span>

### 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.

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

Related API: [panDomain](/reference/functions/domain-navigation/), [ResolvedContinuousScale](/reference/functions/utc-domains/), [PanDomainOptions](/reference/functions/domain-navigation/), [LinearDomain](/reference/components/scale/).

#### Parameters

- **`scale`** — Current resolved continuous mapping. See [ResolvedContinuousScale](/reference/functions/utc-domains/).

- **`options`** — Displacement, bounds, and minimum span. See [PanDomainOptions](/reference/functions/domain-navigation/).

#### Returns

A new immutable domain pair. See [LinearDomain](/reference/components/scale/).

#### Throws

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

#### See also

[zoomDomain](/reference/functions/domain-navigation/)

[View source — packages/core/src/features/viz/lib/domain-navigation.ts:94](/source/packages/core/src/features/viz/lib/domain-navigation-ts/#L94)

<span id="api-zoomDomain"></span>

### 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.

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

Related API: [zoomDomain](/reference/functions/domain-navigation/), [ResolvedContinuousScale](/reference/functions/utc-domains/), [ZoomDomainOptions](/reference/functions/domain-navigation/), [LinearDomain](/reference/components/scale/).

#### Parameters

- **`scale`** — Current resolved continuous mapping. See [ResolvedContinuousScale](/reference/functions/utc-domains/).

- **`options`** — Anchor, magnification, bounds, and minimum span. See [ZoomDomainOptions](/reference/functions/domain-navigation/).

#### Returns

A new immutable domain pair. See [LinearDomain](/reference/components/scale/).

#### Throws

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

#### See also

[panDomain](/reference/functions/domain-navigation/)

[View source — packages/core/src/features/viz/lib/domain-navigation.ts:117](/source/packages/core/src/features/viz/lib/domain-navigation-ts/#L117)

<span id="api-DomainNavigationConstraints"></span>

### DomainNavigationConstraints

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

```ts
interface DomainNavigationConstraints
```

Related API: [DomainNavigationConstraints](/reference/functions/domain-navigation/).

#### See also

[panDomain](/reference/functions/domain-navigation/)

[zoomDomain](/reference/functions/domain-navigation/)

[View source — packages/core/src/features/viz/lib/domain-navigation.ts:3](/source/packages/core/src/features/viz/lib/domain-navigation-ts/#L3)

#### Properties and methods

<span id="api-DomainNavigationConstraints-bounds"></span>
<details>
<summary>bounds</summary>


```ts
readonly bounds: LinearDomain
```

Related API: [LinearDomain](/reference/components/scale/).

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](/source/packages/core/src/features/viz/lib/domain-navigation-ts/#L5)

</details>

<span id="api-DomainNavigationConstraints-minimumSpanRatio"></span>
<details>
<summary>minimumSpanRatio (optional)</summary>


```ts
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](/source/packages/core/src/features/viz/lib/domain-navigation-ts/#L7)

</details>

<span id="api-PanDomainOptions"></span>

### PanDomainOptions

Named pan settings with explicit navigation limits.

```ts
interface PanDomainOptions extends DomainNavigationConstraints
```

Related API: [PanDomainOptions](/reference/functions/domain-navigation/), [DomainNavigationConstraints](/reference/functions/domain-navigation/).

#### See also

[panDomain](/reference/functions/domain-navigation/)

[View source — packages/core/src/features/viz/lib/domain-navigation.ts:10](/source/packages/core/src/features/viz/lib/domain-navigation-ts/#L10)

#### Properties and methods

<span id="api-PanDomainOptions-rangeDelta"></span>
<details>
<summary>rangeDelta</summary>


```ts
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](/source/packages/core/src/features/viz/lib/domain-navigation-ts/#L12)

</details>

<span id="api-PanDomainOptions-bounds"></span>
<details>
<summary>bounds</summary>


```ts
readonly bounds: LinearDomain
```

Related API: [LinearDomain](/reference/components/scale/).

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](/source/packages/core/src/features/viz/lib/domain-navigation-ts/#L5)

</details>

<span id="api-PanDomainOptions-minimumSpanRatio"></span>
<details>
<summary>minimumSpanRatio (optional)</summary>


```ts
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](/source/packages/core/src/features/viz/lib/domain-navigation-ts/#L7)

</details>

<span id="api-ZoomDomainOptions"></span>

### ZoomDomainOptions

Named zoom settings with explicit navigation limits.

```ts
interface ZoomDomainOptions extends DomainNavigationConstraints
```

Related API: [ZoomDomainOptions](/reference/functions/domain-navigation/), [DomainNavigationConstraints](/reference/functions/domain-navigation/).

#### See also

[zoomDomain](/reference/functions/domain-navigation/)

[View source — packages/core/src/features/viz/lib/domain-navigation.ts:15](/source/packages/core/src/features/viz/lib/domain-navigation-ts/#L15)

#### Properties and methods

<span id="api-ZoomDomainOptions-rangeAnchor"></span>
<details>
<summary>rangeAnchor</summary>


```ts
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](/source/packages/core/src/features/viz/lib/domain-navigation-ts/#L17)

</details>

<span id="api-ZoomDomainOptions-factor"></span>
<details>
<summary>factor</summary>


```ts
readonly factor: number
```

Finite positive magnification; greater than one zooms in.

[View source — packages/core/src/features/viz/lib/domain-navigation.ts:19](/source/packages/core/src/features/viz/lib/domain-navigation-ts/#L19)

</details>

<span id="api-ZoomDomainOptions-bounds"></span>
<details>
<summary>bounds</summary>


```ts
readonly bounds: LinearDomain
```

Related API: [LinearDomain](/reference/components/scale/).

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](/source/packages/core/src/features/viz/lib/domain-navigation-ts/#L5)

</details>

<span id="api-ZoomDomainOptions-minimumSpanRatio"></span>
<details>
<summary>minimumSpanRatio (optional)</summary>


```ts
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](/source/packages/core/src/features/viz/lib/domain-navigation-ts/#L7)

</details>

## Implementation guidance for agents

Read the [Data visualization companion](/agents/topics/visualization/) for ownership, adaptation, failure modes, and verification. [Agent start](/agents/) provides the version-selection workflow.

## Complete minimal examples

- [Bounded domain navigation](/minimal-examples/viz/navigation/): Pan and zoom by mapping and inverting an explicit continuous scale. [Plain source](/minimal/viz/navigation.tsx)
## Documentation version

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