# Scale hooks

Import from `@pibbl/core/viz`. Each hook accepts only an ancestor scale ID and
returns a stable, shared readonly core signal:

```ts
import type { Signal } from "@pibbl/core";
import type {
  ScaleId,
  ResolvedLinearScale,
  ResolvedBandScale,
  ResolvedUtcScale,
  ResolvedLogScale,
  ResolvedSymlogScale,
  ResolvedPointScale,
} from "@pibbl/core/viz";
declare function useLinearScale(id: ScaleId): Signal<ResolvedLinearScale>;
declare function useBarScale(id: ScaleId): Signal<ResolvedBandScale>;
declare function useUTCScale(id: ScaleId): Signal<ResolvedUtcScale>;
declare function useLogScale(id: ScaleId): Signal<ResolvedLogScale>;
declare function useSymlogScale(id: ScaleId): Signal<ResolvedSymlogScale>;
declare function usePointScale(id: ScaleId): Signal<ResolvedPointScale>;
```

Call `.get()` to read the immutable mapping and track its dependencies. Consumers
of the same provider and hook share signal identity across domain, range, and
allocation changes. Reading a different family throws when `.get()` is called.

Use the matching `LinearScale`, `BarScale`, `UTCScale`, `LogScale`, `SymlogScale`,
or `PointScale` provider. The [log](/reference/components/log-scale/) and
[symlog/point](/reference/components/symlog-point-scales/) references describe their
family-specific mappings and hooks. Nearest matching
IDs shadow ancestors. Unknown IDs, use outside component evaluation, and crossing
Layer boundaries throw. Keep hooks in ordinary stable call order.

Provider formulas use transactional core `useComputed`: successful traversal
commits updates; failed traversal rolls back candidate formulas. Core computed
signals release subscriptions when unobserved. There is no separate visualization
subscription loop. Each family has its own importable implementation; there is no
public `useScale` overload or family-selector argument.

## API details from source

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

### useLinearScale

Reads an ancestor linear scale as a stable, shared readonly signal.

```ts
useLinearScale: (id: ScaleId) => Signal<ResolvedLinearScale>
```

Related API: [useLinearScale](/reference/hooks/use-scale/), [ScaleId](/reference/components/scale/), [Signal](/reference/types/canvas-runtime/#signal), [ResolvedLinearScale](/reference/components/scale/).

#### Parameters

- **`id`** — Ancestor scale identity. See [ScaleId](/reference/components/scale/).

#### Returns

The reactive mapping. See [ResolvedLinearScale](/reference/components/scale/) and [Signal](/reference/types/canvas-runtime/#signal).

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

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

### useBarScale

Reads an ancestor band scale as a stable, shared readonly signal.

```ts
useBarScale: (id: ScaleId) => Signal<ResolvedBandScale>
```

Related API: [useBarScale](/reference/hooks/use-scale/), [ScaleId](/reference/components/scale/), [Signal](/reference/types/canvas-runtime/#signal), [ResolvedBandScale](/reference/components/scale/).

#### Parameters

- **`id`** — Ancestor scale identity. See [ScaleId](/reference/components/scale/).

#### Returns

The reactive mapping. See [ResolvedBandScale](/reference/components/scale/) and [Signal](/reference/types/canvas-runtime/#signal).

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

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

### useUTCScale

Reads an ancestor utc scale as a stable, shared readonly signal.

```ts
useUTCScale: (id: ScaleId) => Signal<ResolvedUtcScale>
```

Related API: [useUTCScale](/reference/hooks/use-scale/), [ScaleId](/reference/components/scale/), [Signal](/reference/types/canvas-runtime/#signal), [ResolvedUtcScale](/reference/functions/utc-domains/).

#### Parameters

- **`id`** — Ancestor scale identity. See [ScaleId](/reference/components/scale/).

#### Returns

The reactive mapping. See [ResolvedUtcScale](/reference/functions/utc-domains/) and [Signal](/reference/types/canvas-runtime/#signal).

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

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

- [Scales and axes](/minimal-examples/viz/scales/): Create band and linear scales with a typed axis and inspect resolved mappings. [Plain source](/minimal/viz/scales.tsx)
- [UTC dates across New Year](/minimal-examples/viz/utc-numeric/): Keep month, day, and year visible when a calendar axis crosses into a new year. [Plain source](/minimal/viz/utc-numeric.tsx)
## Documentation version

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