Color scales
Import from @pibbl/core/viz. Each continuous provider takes id, domain, colors, and
optional children. Domain and colors accept ordinary values or signals.
SequentialColorScale: two finite domain values and two colors.useSequentialColorScale(id): Signal<ResolvedSequentialColorScale>.DivergingColorScale: three finite domain values (endpoint, center, endpoint) and three colors.useDivergingColorScale(id): Signal<ResolvedDivergingColorScale>.
A resolved mapping exposes frozen domain, colors, stops, and
map(value: number): string. ColorScaleStop is {value: number, color: string}.
Use actual resolved stops and map results to compose annotations with core Text
and shapes. No inversion, generic scale hook, or automatic legend is provided.
Colors are required #RRGGBB strings (case-insensitive input); output is canonical
lowercase #rrggbb. Interpolation is linear per encoded sRGB channel, rounded
to the nearest integer, with exact authored endpoint and center colors. It is not
linear-light or perceptually uniform interpolation. There is no default palette;
choose endpoints that suit the data and provide labels or shapes in addition to
color when distinctions matter. Named CSS colors, alpha, gradients, and other
color spaces are deliberately outside this mapping contract.
Sequential domains may ascend or descend, preserving endpoint-color association. If both domain values are equal, every finite input maps to the channel midpoint. Diverging domains must be strictly increasing or strictly decreasing around the authored center; no symmetry is inferred. A center input maps to the exact center color. Both families clamp finite out-of-domain inputs to endpoint colors; extrapolation is not supported. Nonfinite inputs reject rather than returning an unknown color. Providers validate lazily when the resolved mapping is read.
Invalid counts, colors, domain values, or diverging order throw TypeError or RangeError. IDs must be nonempty strings or symbols. Each dedicated hook resolves the nearest matching ID and rejects a different color family, absent provider, or crossing a Layer boundary. Color IDs occupy a separate namespace from positional scale IDs. Scopes are restored after traversal/failure; signals and computed mapping lifetimes are mount-owned.
These providers allocate no drawing box, position, clipping, or event targets.
Place marks and annotations using ordinary layout and positional scales. Read a
mapping with .get() inside a component to subscribe to its domain/color changes;
retain the returned hook signal for stable provider identity.
Threshold colors
Section titled “Threshold colors”ThresholdColorScale takes id, thresholds, colors, and optional children.
useThresholdColorScale(id): Signal<ResolvedThresholdColorScale> returns frozen
thresholds, colors, bands, and map(value: number): string. Thresholds and
colors accept signals. Boundaries must be finite and strictly increasing with no
duplicates; colors must contain exactly one more entry than boundaries.
Each frozen ThresholdColorBand has lower: number | undefined,
upper: number | undefined, and canonical color: string. Lower bounds are
inclusive and upper bounds exclusive: equality belongs to the next/upper bucket.
Undefined edges are unbounded. Empty thresholds with one color define a constant
mapping with one unbounded band. Nonfinite map inputs reject. This is threshold
classification, not quantization or distribution-derived quantiles. No data is
aggregated or sorted on the caller’s behalf. The same context, palette, failure,
and ownership rules apply as for the continuous families.
API details from source
Section titled “API details from source”
SequentialColorScale
Section titled “SequentialColorScale”Provides an allocation-independent sequential color mapping.
SequentialColorScale: (props: SequentialColorScaleProps) => PibblNodeRelated API: SequentialColorScale, SequentialColorScaleProps, PibblNode.
Parameters
Section titled “Parameters”props— Explicit domain, colors, identity, and children. See SequentialColorScaleProps.
Returns
Section titled “Returns”Descendant content.
View source — packages/core/src/features/viz/lib/sequential-color-scale.ts:55
useSequentialColorScale
Section titled “useSequentialColorScale”Reads the dedicated ancestor sequential mapping.
useSequentialColorScale: (id: ScaleId) => Signal<ResolvedSequentialColorScale>Related API: useSequentialColorScale, ScaleId, Signal, ResolvedSequentialColorScale.
Parameters
Section titled “Parameters”id— Color-scale identity. See ScaleId.
Returns
Section titled “Returns”Shared readonly mapping signal. See ResolvedSequentialColorScale.
View source — packages/core/src/features/viz/lib/sequential-color-scale.ts:65
DivergingColorScale
Section titled “DivergingColorScale”Provides an allocation-independent color mapping with an authored center.
DivergingColorScale: (props: DivergingColorScaleProps) => PibblNodeRelated API: DivergingColorScale, DivergingColorScaleProps, PibblNode.
Parameters
Section titled “Parameters”props— Explicit domain, colors, identity, and children. See DivergingColorScaleProps.
Returns
Section titled “Returns”Descendant content.
View source — packages/core/src/features/viz/lib/diverging-color-scale.ts:58
useDivergingColorScale
Section titled “useDivergingColorScale”Reads the dedicated ancestor diverging mapping.
useDivergingColorScale: (id: ScaleId) => Signal<ResolvedDivergingColorScale>Related API: useDivergingColorScale, ScaleId, Signal, ResolvedDivergingColorScale.
Parameters
Section titled “Parameters”id— Color-scale identity. See ScaleId.
Returns
Section titled “Returns”Shared readonly mapping signal. See ResolvedDivergingColorScale.
View source — packages/core/src/features/viz/lib/diverging-color-scale.ts:68
ColorScaleStop
Section titled “ColorScaleStop”One authored domain/color association.
interface ColorScaleStopRelated API: ColorScaleStop.
See also
Section titled “See also”View source — packages/core/src/features/viz/lib/color-types.ts:4
Properties and methods
Section titled “Properties and methods”
value
readonly value: numberNumeric data value at the color stop.
View source — packages/core/src/features/viz/lib/color-types.ts:5
color
readonly color: stringCanonical lowercase six-digit hexadecimal sRGB color.
View source — packages/core/src/features/viz/lib/color-types.ts:6
SequentialColorScaleProps
Section titled “SequentialColorScaleProps”Inputs for a dedicated sequential color provider.
interface SequentialColorScalePropsRelated API: SequentialColorScaleProps.
See also
Section titled “See also”View source — packages/core/src/features/viz/lib/color-types.ts:41
Properties and methods
Section titled “Properties and methods”
id
readonly id: ScaleIdRelated API: ScaleId.
Identity in the color-scale namespace. See ScaleId.
View source — packages/core/src/features/viz/lib/color-types.ts:42
domain
readonly domain: SignalValue<readonly [number, number]>Related API: SignalValue.
Finite endpoints; equal endpoints map all finite inputs to the color midpoint.
View source — packages/core/src/features/viz/lib/color-types.ts:43
colors
readonly colors: SignalValue<readonly [string, string]>Related API: SignalValue.
Required #RRGGBB endpoint colors. No default palette is chosen.
View source — packages/core/src/features/viz/lib/color-types.ts:46
children (optional)
readonly children?: PibblNodeRelated API: PibblNode.
Descendants consuming the mapping. See PibblNode.
View source — packages/core/src/features/viz/lib/color-types.ts:49
DivergingColorScaleProps
Section titled “DivergingColorScaleProps”Inputs for a dedicated diverging color provider.
interface DivergingColorScalePropsRelated API: DivergingColorScaleProps.
See also
Section titled “See also”View source — packages/core/src/features/viz/lib/color-types.ts:52
Properties and methods
Section titled “Properties and methods”
id
readonly id: ScaleIdRelated API: ScaleId.
Identity in the color-scale namespace. See ScaleId.
View source — packages/core/src/features/viz/lib/color-types.ts:53
domain
readonly domain: SignalValue<readonly [number, number, number]>Related API: SignalValue.
Strictly increasing or decreasing finite endpoints and center.
View source — packages/core/src/features/viz/lib/color-types.ts:54
colors
readonly colors: SignalValue<readonly [string, string, string]>Related API: SignalValue.
Required #RRGGBB endpoint and center colors.
View source — packages/core/src/features/viz/lib/color-types.ts:57
children (optional)
readonly children?: PibblNodeRelated API: PibblNode.
Descendants consuming the mapping. See PibblNode.
View source — packages/core/src/features/viz/lib/color-types.ts:60
ResolvedSequentialColorScale
Section titled “ResolvedSequentialColorScale”Readonly continuous two-stop color mapping.
interface ResolvedSequentialColorScaleRelated API: ResolvedSequentialColorScale.
See also
Section titled “See also”View source — packages/core/src/features/viz/lib/color-types.ts:9
Properties and methods
Section titled “Properties and methods”
domain
readonly domain: readonly [number, number]Authored finite endpoints, preserving ascending or descending order.
View source — packages/core/src/features/viz/lib/color-types.ts:10
colors
readonly colors: readonly [string, string]Canonical endpoint colors, in authored order.
View source — packages/core/src/features/viz/lib/color-types.ts:14
stops
readonly stops: readonly ColorScaleStop[]Related API: ColorScaleStop.
Frozen endpoint/value pairs for scale-derived annotations.
View source — packages/core/src/features/viz/lib/color-types.ts:18
map
map: (value: number) => stringMaps finite data to a clamped color.
Parameters
Section titled “Parameters”value— Numeric input.
Returns
Section titled “Returns”Canonical #rrggbb color.
View source — packages/core/src/features/viz/lib/color-types.ts:21
ResolvedDivergingColorScale
Section titled “ResolvedDivergingColorScale”Readonly continuous mapping with an explicit center.
interface ResolvedDivergingColorScaleRelated API: ResolvedDivergingColorScale.
See also
Section titled “See also”View source — packages/core/src/features/viz/lib/color-types.ts:24
Properties and methods
Section titled “Properties and methods”
domain
readonly domain: readonly [number, number, number]Strictly monotonic finite endpoints and center, in authored order.
View source — packages/core/src/features/viz/lib/color-types.ts:25
colors
readonly colors: readonly [string, string, string]Canonical endpoint and center colors.
View source — packages/core/src/features/viz/lib/color-types.ts:30
stops
readonly stops: readonly ColorScaleStop[]Related API: ColorScaleStop.
Frozen endpoint/center pairs for scale-derived annotations.
View source — packages/core/src/features/viz/lib/color-types.ts:35
map
map: (value: number) => stringMaps finite data through the authored center.
Parameters
Section titled “Parameters”value— Numeric input.
Returns
Section titled “Returns”Canonical #rrggbb color.
View source — packages/core/src/features/viz/lib/color-types.ts:38
ThresholdColorScale
Section titled “ThresholdColorScale”Provides a lazy, discrete threshold-to-color mapping for descendants.
ThresholdColorScale: (props: ThresholdColorScaleProps) => PibblNodeRelated API: ThresholdColorScale, ThresholdColorScaleProps, PibblNode.
Parameters
Section titled “Parameters”props— Boundaries, colors, identity and descendants. See ThresholdColorScaleProps.
Returns
Section titled “Returns”Descendant content.
View source — packages/core/src/features/viz/lib/threshold-color-scale.ts:90
useThresholdColorScale
Section titled “useThresholdColorScale”Reads the matching ancestor threshold color mapping.
useThresholdColorScale: (id: ScaleId) => Signal<ResolvedThresholdColorScale>Related API: useThresholdColorScale, ScaleId, Signal, ResolvedThresholdColorScale.
Parameters
Section titled “Parameters”id— Provider identity. See ScaleId.
Returns
Section titled “Returns”Shared readonly mapping signal. See ResolvedThresholdColorScale.
View source — packages/core/src/features/viz/lib/threshold-color-scale.ts:101
ThresholdColorBand
Section titled “ThresholdColorBand”One lower-inclusive, upper-exclusive threshold color bucket.
interface ThresholdColorBandRelated API: ThresholdColorBand.
See also
Section titled “See also”View source — packages/core/src/features/viz/lib/threshold-color-scale.ts:12
Properties and methods
Section titled “Properties and methods”
lower
readonly lower: number | undefinedLower inclusive boundary, omitted for the first bucket.
View source — packages/core/src/features/viz/lib/threshold-color-scale.ts:14
upper
readonly upper: number | undefinedUpper exclusive boundary, omitted for the last bucket.
View source — packages/core/src/features/viz/lib/threshold-color-scale.ts:16
color
readonly color: stringValidated #RRGGBB paint for this bucket.
View source — packages/core/src/features/viz/lib/threshold-color-scale.ts:18
ThresholdColorScaleProps
Section titled “ThresholdColorScaleProps”Authored threshold boundaries, bucket colors, identity, and descendant content.
interface ThresholdColorScalePropsRelated API: ThresholdColorScaleProps.
See also
Section titled “See also”View source — packages/core/src/features/viz/lib/threshold-color-scale.ts:36
Properties and methods
Section titled “Properties and methods”
id
readonly id: ScaleIdRelated API: ScaleId.
Stable provider identity.
View source — packages/core/src/features/viz/lib/threshold-color-scale.ts:38
thresholds
readonly thresholds: SignalValue<readonly number[]>Related API: SignalValue.
Strictly ascending finite boundaries; each equality belongs to the upper bucket.
View source — packages/core/src/features/viz/lib/threshold-color-scale.ts:40
colors
readonly colors: SignalValue<readonly string[]>Related API: SignalValue.
Exactly one #RRGGBB color per bucket.
View source — packages/core/src/features/viz/lib/threshold-color-scale.ts:42
children (optional)
readonly children?: PibblNodeRelated API: PibblNode.
Descendant content using this dedicated color context.
View source — packages/core/src/features/viz/lib/threshold-color-scale.ts:44
ResolvedThresholdColorScale
Section titled “ResolvedThresholdColorScale”Immutable resolved threshold mapping shared with descendant marks.
interface ResolvedThresholdColorScaleRelated API: ResolvedThresholdColorScale.
See also
Section titled “See also”View source — packages/core/src/features/viz/lib/threshold-color-scale.ts:22
Properties and methods
Section titled “Properties and methods”
thresholds
readonly thresholds: readonly number[]Strictly ascending finite authored bucket boundaries.
View source — packages/core/src/features/viz/lib/threshold-color-scale.ts:24
colors
readonly colors: readonly string[]One validated color for every bucket.
View source — packages/core/src/features/viz/lib/threshold-color-scale.ts:26
bands
readonly bands: readonly ThresholdColorBand[]Related API: ThresholdColorBand.
Readable bucket descriptions in authored order.
View source — packages/core/src/features/viz/lib/threshold-color-scale.ts:28
map
readonly map: (value: number) => stringMaps a finite numeric value to its containing bucket paint.
Parameters
Section titled “Parameters”value— Finite input.
Returns
Section titled “Returns”Canonical lowercase #rrggbb color.
View source — packages/core/src/features/viz/lib/threshold-color-scale.ts:32
Implementation guidance for agents
Section titled “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
Section titled “Complete minimal examples”- Explicit color scales: Map real observations with dedicated providers and authored palettes. Plain source
Documentation version
Section titled “Documentation version”Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.