Scale providers

Read as Markdown

Import LinearScale, BarScale, UTCScale, and their types from @pibbl/core/viz. Use the core JSX runtime.

Each provider requires id, domain, and range, with optional reverse, style, and children. BarScale also accepts paddingInner and paddingOuter. There is no type prop. The corresponding props are LinearScaleProps, BarScaleProps, and UTCScaleProps (see UTC domains). ScaleId is a nonempty string or symbol. Nested providers shadow the nearest matching ID; siblings and independent roots cannot see each other’s providers.

LinearDomain contains two finite, unequal numbers, ascending or descending. ScaleRange is a finite numeric pair, "width", or "height". Allocation ranges start at zero and end at the local allocated extent. reverse swaps endpoints; use it with height to make larger values appear higher. Domain, range, and reverse accept core SignalValue inputs. Signal resolution is shallow.

ScaleLayoutStyle contains width, height, and core layout-item styles. Whole styles and direct fields may be core signals. Scale does not paint, transform, reserve gutters, or create a global chart rectangle. Its children receive the same allocation; put gutters and placement in ordinary core layout.

ResolvedScale is ResolvedContinuousScale | ResolvedBandScale. The linear snapshot has:

• type, domain, and range describe the mapping.
• frame has local x/y zero and the allocation’s width/height.
• map(value) maps finite values with linear extrapolation, without clamping.
• invert(pixel) reverses that mapping. A zero-span range maps to its endpoint but cannot be inverted.
• ticks(count = 5) returns evenly spaced values including both domain ends. Count must be an integer from 2 through 100. These are not calendar or nice ticks.

Use useLinearScale to read the scale signal. Definitions are lazy; malformed resolved inputs throw on evaluation. Nonfinite arithmetic results also throw. Updating a signal or allocation refreshes the existing scale signal; equivalent domain/range/frame values suppress downstream invalidation.

A scale provider and consumer must share one rendering instance. Put the complete scale subtree inside a Layer; lookup across a Layer boundary is unsupported. UTC calendar scales are available; see UTC domains. Local time, logarithmic, and auto-domain scales remain deferred.

Band scales

Use BarScale with an explicit ordered BandDomain of strings or finite numbers (BandCategory). Identity uses SameValueZero: 1 and "1" are distinct; -0 and 0 are the same category. Duplicate entries reject. Input order is preserved, and empty domains are valid. Unknown categories map to undefined.

paddingInner defaults to 0 and is a fraction of the step in [0, 1]. paddingOuter defaults to 0 and is a finite nonnegative number of steps per side. For n categories, step = extent / max(1, n - paddingInner + 2 * paddingOuter). Bandwidth = step * (1 - paddingInner); remaining space is centered. Empty domains have zero step/bandwidth. Collapsed ranges have zero bandwidth. Reverse changes category placement, while each map(category) remains the lower pixel edge.

Read useBarScale(id).get() for the immutable ResolvedBandScale: domain, range, frame, step, bandwidth, and map(category). There is no numeric inversion or tick method. Labels can use map(category) + bandwidth / 2. Domain, padding, reverse, and range accept signals and follow local allocation. For nested bands, BandScaleRange additionally accepts { bandwidthOf: ancestorId }. It resolves to [0, ancestor.bandwidth], reacting to ancestor domain, padding, and allocation changes. The reference must identify a visible ancestor band scale in the same rendering instance. Nearest matching scope wins, as with useLinearScale. Missing references and wrong scale families reject. Ancestor-only lookup prevents circular references. Zero ancestor bandwidth produces a collapsed range. The inner frame remains the layout allocation; only its range uses the ancestor bandwidth. Linear scales do not accept this range form.

API details from source

LinearScale

Provides a named linear mapping to descendant visualization components.

LinearScale: (props: LinearScaleProps) => PibblNode

Related API: LinearScale, LinearScaleProps, PibblNode.

Parameters

• props — Identity, domain, range, and children. See LinearScaleProps.

Returns

Descendant content within the scale scope.

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

BarScale

Provides categorical bands, including nested groups sized to a parent band.

BarScale: (props: BarScaleProps) => PibblNode

Related API: BarScale, BarScaleProps, PibblNode.

Parameters

• props — Categories, spacing, range, and children. See BarScaleProps.

Returns

Descendant content within the scale scope.

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

UTCScale

Provides a named utc mapping to descendant visualization components.

UTCScale: (props: UTCScaleProps) => PibblNode

Related API: UTCScale, UTCScaleProps, PibblNode.

Parameters

• props — Identity, domain, range, and children. See UTCScaleProps.

Returns

Descendant content within the scale scope.

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

ScaleId

A string or symbol identifying a scale within visualization context.

type ScaleId = string | symbol

Related API: ScaleId.

See also

BandScaleRange

LinearScaleProps

LineSeriesProps

View source — packages/core/src/features/viz/lib/types.ts:23

LinearDomain

The two numeric endpoints of a continuous scale domain.

type LinearDomain = readonly [number, number]

Related API: LinearDomain.

See also

LinearScaleProps

ResolvedLinearScale

View source — packages/core/src/features/viz/lib/types.ts:30

BandCategory

A string or number used as a discrete band-scale category.

type BandCategory = string | number

Related API: BandCategory.

See also

BandDomain

ResolvedBandScale

BarCategoryAccessor

View source — packages/core/src/features/viz/lib/types.ts:102

BandDomain

The ordered categories allocated by a band scale.

type BandDomain = readonly BandCategory[]

Related API: BandDomain, BandCategory.

See also

BandCategory

BarScaleProps

ResolvedBandScale

View source — packages/core/src/features/viz/lib/types.ts:110

BarScaleProps

Authored inputs for BandScale, including the declared data and presentation options.

interface BarScaleProps extends Omit<
  LinearScaleProps,
  "domain" | "range"
>

Related API: BarScaleProps, LinearScaleProps.

See also

LinearScaleProps

SignalValue

BandDomain

BandScaleRange

View source — packages/core/src/features/viz/lib/types.ts:120

Properties and methods

domain

readonly domain: SignalValue<BandDomain>

Related API: SignalValue, BandDomain.

Data values or endpoints accepted by the scale. See SignalValue, BandDomain.

View source — packages/core/src/features/viz/lib/types.ts:127

range

readonly range: SignalValue<BandScaleRange>

Related API: SignalValue, BandScaleRange.

Logical output coordinates produced by the scale. See SignalValue, BandScaleRange.

View source — packages/core/src/features/viz/lib/types.ts:132

paddingInner (optional)

readonly paddingInner?: SignalValue<number> | undefined

Related API: SignalValue.

Relative spacing between adjacent categorical bands. See SignalValue.

View source — packages/core/src/features/viz/lib/types.ts:134

paddingOuter (optional)

readonly paddingOuter?: SignalValue<number> | undefined

Related API: SignalValue.

Relative spacing outside the first and last categorical bands. See SignalValue.

View source — packages/core/src/features/viz/lib/types.ts:136

id

readonly id: ScaleId

Related API: ScaleId.

Stable identifier of this resource or connection. See ScaleId.

View source — packages/core/src/features/viz/lib/types.ts:74

reverse (optional)

readonly reverse?: SignalValue<boolean> | undefined

Related API: SignalValue.

Whether to reverse the direction of the mapping or guide. See SignalValue.

View source — packages/core/src/features/viz/lib/types.ts:86

style (optional)

Full type declaration

readonly style?: SignalValue<Readonly<{ left?: SignalValue<number | `${number}%` | undefined>; top?: SignalValue<number | `${number}%` | undefined>; width?: SignalValue<Length | undefined>; height?: SignalValue<Length | undefined>; alignSelf?: SignalValue<"auto" | "center" | "end" | "flex-end" | "flex-start" | "start" | "stretch" | undefined>; justifySelf?: SignalValue<"auto" | "center" | "end" | "start" | "stretch" | undefined>; flexBasis?: SignalValue<Length | undefined>; flexGrow?: SignalValue<number | undefined>; flexShrink?: SignalValue<number | undefined>; gridColumnStart?: SignalValue<number | undefined>; gridColumnSpan?: SignalValue<number | undefined>; gridRowStart?: SignalValue<number | undefined>; gridRowSpan?: SignalValue<number | undefined>; transition?: SignalValue<PibblTransitionBinding | undefined>; custom?: unknown; filter?: SignalValue<PibblFilter | readonly PibblFilter[] | undefined>; }>> | undefined

Related API: SignalValue, Length, PibblTransitionBinding, PibblFilter.

Declared presentation and layout properties. See SignalValue, SignalStyle, ScaleLayoutStyle.

View source — packages/core/src/features/viz/lib/types.ts:91

children (optional)

readonly children?: PibblNode

Related API: PibblNode.

Descendant content or the callback that supplies it. See PibblNode.

View source — packages/core/src/features/viz/lib/types.ts:93

BandScaleRange

A logical range or the bandwidth of another scale for nested band layouts.

type BandScaleRange = | ScaleRange
  | {
      /** Identifier of a parent band scale whose bandwidth supplies this range. See {@link ScaleId}. */
      readonly bandwidthOf: ScaleId;
    }

Related API: BandScaleRange, ScaleRange, ScaleId.

See also

ScaleRange

ScaleId

BarScaleProps

View source — packages/core/src/features/viz/lib/types.ts:45

ResolvedBandScale

A resolved categorical mapping with its frame, bandwidth, and step.

interface ResolvedBandScale

Related API: ResolvedBandScale.

See also

BandDomain

LayoutBox

BandCategory

ResolvedScale

View source — packages/core/src/features/viz/lib/types.ts:159

Properties and methods

type

readonly type: "band"

The literal “band” identifying this variant. See ResolvedBandScale.

View source — packages/core/src/features/viz/lib/types.ts:161

domain

readonly domain: BandDomain

Related API: BandDomain.

Data values or endpoints accepted by the scale. See BandDomain.

View source — packages/core/src/features/viz/lib/types.ts:163

range

readonly range: readonly [number, number]

Logical output coordinates produced by the scale. See ResolvedBandScale.

View source — packages/core/src/features/viz/lib/types.ts:165

frame

readonly frame: Readonly<LayoutBox>

Related API: LayoutBox.

Resolved layout frame containing the scale. See LayoutBox.

View source — packages/core/src/features/viz/lib/types.ts:167

bandwidth

readonly bandwidth: number

Width allocated to one categorical band. See ResolvedBandScale.

View source — packages/core/src/features/viz/lib/types.ts:169

step

readonly step: number

Distance between successive band starts. See ResolvedBandScale.

View source — packages/core/src/features/viz/lib/types.ts:171

map

map: (value: BandCategory) => number | undefined

Related API: BandCategory.

Maps a category to its band coordinate, or returns undefined for an unknown category. See ResolvedBandScale .

Parameters

• value — Category to locate in the domain. See BandCategory.

Returns

The category’s range position, or undefined if it is absent from the domain.

View source — packages/core/src/features/viz/lib/types.ts:178

ScaleRange

An explicit numeric range or a range derived from layout width or height.

type ScaleRange = "width" | "height" | readonly [number, number]

Related API: ScaleRange.

See also

BandScaleRange

LinearScaleProps

View source — packages/core/src/features/viz/lib/types.ts:37

ScaleLayoutStyle

Sizing and parent-layout participation of a scale’s coordinate frame.

type ScaleLayoutStyle = Pick<BoxStyle, "width" | "height"> &
  LayoutItemStyle

Related API: ScaleLayoutStyle, BoxStyle, LayoutItemStyle.

See also

BoxStyle

LayoutItemStyle

LinearScaleProps

View source — packages/core/src/features/viz/lib/types.ts:58

Properties and methods

width (optional)

width?: Length | undefined

Related API: Length.

Horizontal extent in the units of the containing geometry or surface. See Length.

View source — packages/core/src/lib/style/types.ts:81

height (optional)

height?: Length | undefined

Related API: Length.

Vertical extent in the units of the containing geometry or surface. See Length.

View source — packages/core/src/lib/style/types.ts:83

left (optional)

left?: number | `${number}%` | undefined

Left edge coordinate or inset. See Length.

View source — packages/core/src/lib/style/positioning.ts:127

top (optional)

top?: number | `${number}%` | undefined

Top edge value or top envelope guide. See Length.

View source — packages/core/src/lib/style/positioning.ts:129

alignSelf (optional)

alignSelf?: "auto" | "center" | "end" | "flex-end" | "flex-start" | "start" | "stretch" | undefined

This child’s cross-axis or block-axis alignment override. See LayoutItemStyle.

View source — packages/core/src/lib/style/types.ts:121

justifySelf (optional)

justifySelf?: "auto" | "center" | "end" | "start" | "stretch" | undefined

This child’s inline-axis alignment override. See LayoutItemStyle.

View source — packages/core/src/lib/style/types.ts:123

flexBasis (optional)

flexBasis?: Length | undefined

Related API: Length.

Initial main-axis size before flex growth or shrinkage. See Length.

View source — packages/core/src/lib/style/types.ts:125

flexGrow (optional)

flexGrow?: number | undefined

Relative share of positive free space assigned to this child. See LayoutItemStyle.

View source — packages/core/src/lib/style/types.ts:127

flexShrink (optional)

flexShrink?: number | undefined

Relative factor used when reducing main-axis size. See LayoutItemStyle.

View source — packages/core/src/lib/style/types.ts:129

gridColumnStart (optional)

gridColumnStart?: number | undefined

Explicit starting grid column. See LayoutItemStyle.

View source — packages/core/src/lib/style/types.ts:131

gridColumnSpan (optional)

gridColumnSpan?: number | undefined

Number of columns occupied by this child. See LayoutItemStyle.

View source — packages/core/src/lib/style/types.ts:133

gridRowStart (optional)

gridRowStart?: number | undefined

Explicit starting grid row. See LayoutItemStyle.

View source — packages/core/src/lib/style/types.ts:135

gridRowSpan (optional)

gridRowSpan?: number | undefined

Number of rows occupied by this child. See LayoutItemStyle.

View source — packages/core/src/lib/style/types.ts:137

transition (optional)

transition?: PibblTransitionBinding | undefined

Related API: PibblTransitionBinding.

Visibility-transition binding applied to this primitive and its captured descendants. See SystemStyle.

View source — packages/core/src/lib/types.ts:69

custom (optional)

custom?: unknown

Application-defined style payload passed through the runtime. See SystemStyle.

View source — packages/core/src/lib/types.ts:71

filter (optional)

filter?: PibblFilter | readonly PibblFilter[] | undefined

Related API: PibblFilter.

Ordered pixel-only filters applied to the receiving primitive and its descendants. See PibblFilter.

View source — packages/core/src/lib/types.ts:76

LinearScaleProps

Authored inputs for LinearScale, including the declared data and presentation options.

interface LinearScaleProps

Related API: LinearScaleProps.

See also

ScaleId

SignalValue

LinearDomain

ScaleRange

SignalStyle

ScaleLayoutStyle

PibblNode

BarScaleProps

View source — packages/core/src/features/viz/lib/types.ts:72

Properties and methods

id

readonly id: ScaleId

Related API: ScaleId.

Stable identifier of this resource or connection. See ScaleId.

View source — packages/core/src/features/viz/lib/types.ts:74

domain

readonly domain: SignalValue<LinearDomain>

Related API: SignalValue, LinearDomain.

Data values or endpoints accepted by the scale. See SignalValue, LinearDomain .

View source — packages/core/src/features/viz/lib/types.ts:79

range

readonly range: SignalValue<ScaleRange>

Related API: SignalValue, ScaleRange.

Logical output coordinates produced by the scale. See SignalValue, ScaleRange .

View source — packages/core/src/features/viz/lib/types.ts:84

reverse (optional)

readonly reverse?: SignalValue<boolean> | undefined

Related API: SignalValue.

Whether to reverse the direction of the mapping or guide. See SignalValue.

View source — packages/core/src/features/viz/lib/types.ts:86

style (optional)

Full type declaration

readonly style?: SignalValue<Readonly<{ left?: SignalValue<number | `${number}%` | undefined>; top?: SignalValue<number | `${number}%` | undefined>; width?: SignalValue<Length | undefined>; height?: SignalValue<Length | undefined>; alignSelf?: SignalValue<"auto" | "center" | "end" | "flex-end" | "flex-start" | "start" | "stretch" | undefined>; justifySelf?: SignalValue<"auto" | "center" | "end" | "start" | "stretch" | undefined>; flexBasis?: SignalValue<Length | undefined>; flexGrow?: SignalValue<number | undefined>; flexShrink?: SignalValue<number | undefined>; gridColumnStart?: SignalValue<number | undefined>; gridColumnSpan?: SignalValue<number | undefined>; gridRowStart?: SignalValue<number | undefined>; gridRowSpan?: SignalValue<number | undefined>; transition?: SignalValue<PibblTransitionBinding | undefined>; custom?: unknown; filter?: SignalValue<PibblFilter | readonly PibblFilter[] | undefined>; }>> | undefined

Related API: SignalValue, Length, PibblTransitionBinding, PibblFilter.

Declared presentation and layout properties. See SignalValue, SignalStyle, ScaleLayoutStyle.

View source — packages/core/src/features/viz/lib/types.ts:91

children (optional)

readonly children?: PibblNode

Related API: PibblNode.

Descendant content or the callback that supplies it. See PibblNode.

View source — packages/core/src/features/viz/lib/types.ts:93

ResolvedLinearScale

A resolved continuous scale with forward mapping, inversion, and tick generation.

interface ResolvedLinearScale

Related API: ResolvedLinearScale.

See also

LinearDomain

LayoutBox

ResolvedScale

nearestDomainValue

View source — packages/core/src/features/viz/lib/types.ts:188

Properties and methods

type

readonly type: "linear"

The literal “linear” identifying this variant. See ResolvedLinearScale.

View source — packages/core/src/features/viz/lib/types.ts:190

domain

readonly domain: LinearDomain

Related API: LinearDomain.

Data values or endpoints accepted by the scale. See LinearDomain.

View source — packages/core/src/features/viz/lib/types.ts:192

range

readonly range: readonly [number, number]

Logical output coordinates produced by the scale. See ResolvedLinearScale.

View source — packages/core/src/features/viz/lib/types.ts:194

frame

readonly frame: Readonly<LayoutBox>

Related API: LayoutBox.

Resolved layout frame containing the scale. See LayoutBox.

View source — packages/core/src/features/viz/lib/types.ts:196

map

map: (value: number) => number

Maps a numeric domain value to a logical range coordinate. See ResolvedLinearScale.

Parameters

• value — Numeric domain coordinate.

Returns

The corresponding range coordinate.

View source — packages/core/src/features/viz/lib/types.ts:202

invert

invert: (pixel: number) => number

Related API: invert.

Maps a logical range coordinate back into the numeric domain. See ResolvedLinearScale .

Parameters

• pixel — Coordinate in the scale’s pixel range.

Returns

The corresponding numeric domain value.

View source — packages/core/src/features/viz/lib/types.ts:209

ticks

ticks: (count?: number) => readonly number[]

Returns representative numeric tick values for the requested count. See ResolvedLinearScale.

Parameters

• count — Suggested number of ticks.

Returns

Tick values in domain coordinates.

View source — packages/core/src/features/viz/lib/types.ts:216

ResolvedScale

A numeric or categorical mapping snapshot. See ResolvedContinuousScale.

type ResolvedScale = ResolvedContinuousScale | ResolvedBandScale | ResolvedPointScale

Related API: ResolvedScale, ResolvedContinuousScale, ResolvedBandScale, ResolvedPointScale.

View source — packages/core/src/features/viz/lib/types.ts:251

Properties and methods

type

readonly type: "band" | "linear" | "log" | "point" | "symlog" | "utc"

The literal “band” identifying this variant. See ResolvedBandScale. The literal “linear” identifying this variant. See ResolvedLinearScale. Logarithmic mapping discriminant. See LogScaleProps. Categorical point discriminant. See PointScaleProps. Signed logarithmic discriminant. See SymlogScaleProps. UTC calendar scale discriminant. See UTCScaleProps.

View source — packages/core/src/features/viz/lib/types.ts:161

domain

readonly domain: BandDomain | LinearDomain

Related API: BandDomain, LinearDomain.

Data values or endpoints accepted by the scale. See BandDomain. Data values or endpoints accepted by the scale. See LinearDomain.

View source — packages/core/src/features/viz/lib/types.ts:163

range

readonly range: readonly [number, number]

Logical output coordinates produced by the scale. See ResolvedBandScale. Logical output coordinates produced by the scale. See ResolvedLinearScale.

View source — packages/core/src/features/viz/lib/types.ts:165

frame

readonly frame: Readonly<LayoutBox>

Related API: LayoutBox.

Resolved layout frame containing the scale. See LayoutBox.

View source — packages/core/src/features/viz/lib/types.ts:167

map

map: ((value: BandCategory) => number | undefined) | ((value: number) => number)

Related API: BandCategory.

Maps a category to its band coordinate, or returns undefined for an unknown category. See ResolvedBandScale . Maps a numeric domain value to a logical range coordinate. See ResolvedLinearScale.

Parameters

• value — Category to locate in the domain. See BandCategory.

• value — Numeric domain coordinate.

Returns

The category’s range position, or undefined if it is absent from the domain.

The corresponding range coordinate.

View source — packages/core/src/features/viz/lib/types.ts:178

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 380919b. ALPHA — NOT FOR PRODUCTION USE.