Scale hooks

Read as Markdown

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

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 and symlog/point 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

useLinearScale

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

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

Related API: useLinearScale, ScaleId, Signal, ResolvedLinearScale.

Parameters

• id — Ancestor scale identity. See ScaleId.

Returns

The reactive mapping. See ResolvedLinearScale and Signal.

View source — packages/core/src/features/viz/lib/use-linear-scale.ts:10

useBarScale

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

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

Related API: useBarScale, ScaleId, Signal, ResolvedBandScale.

Parameters

• id — Ancestor scale identity. See ScaleId.

Returns

The reactive mapping. See ResolvedBandScale and Signal.

View source — packages/core/src/features/viz/lib/use-bar-scale.ts:10

useUTCScale

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

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

Related API: useUTCScale, ScaleId, Signal, ResolvedUtcScale.

Parameters

• id — Ancestor scale identity. See ScaleId.

Returns

The reactive mapping. See ResolvedUtcScale and Signal.

View source — packages/core/src/features/viz/lib/use-utc-scale.ts:10

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

• Scales and axes: Create band and linear scales with a typed axis and inspect resolved mappings. Plain source
• UTC dates across New Year: Keep month, day, and year visible when a calendar axis crosses into a new year. Plain source

Documentation version

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