Scale providers

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.

LinearDomain

The two numeric endpoints of a continuous scale domain.

type LinearDomain = readonly [number, number]

Related API: LinearDomain.

BandCategory

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

type BandCategory = string | number

Related API: BandCategory.

BandDomain

The ordered categories allocated by a band scale.

type BandDomain = readonly BandCategory[]

Related API: BandDomain, BandCategory.

BarScaleProps

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

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

Related API: BarScaleProps, LinearScaleProps.

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:128

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:133

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:135

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:137

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:75

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:87

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

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

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

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:94

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.

ResolvedBandScale

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

interface ResolvedBandScale

Related API: ResolvedBandScale.

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:162

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:164

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:166

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:168

bandwidth

readonly bandwidth: number

Width allocated to one categorical band. See ResolvedBandScale.

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

step

readonly step: number

Distance between successive band starts. See ResolvedBandScale.

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

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:179

ScaleRange

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

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

Related API: ScaleRange.

ScaleLayoutStyle

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

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

Related API: ScaleLayoutStyle, BoxStyle, LayoutItemStyle.

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.

Properties and methods

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:75

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:80

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:85

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:87

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

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

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

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:94

ResolvedLinearScale

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

interface ResolvedLinearScale

Related API: ResolvedLinearScale.

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:191

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:193

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:195

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:197

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:203

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:210

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:217

ResolvedScale

A numeric or categorical mapping snapshot. See ResolvedContinuousScale.

type ResolvedScale = ResolvedContinuousScale | ResolvedBandScale | ResolvedPointScale

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

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:162

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:164

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:166

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:168

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:179

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 2dccb19. ALPHA — NOT FOR PRODUCTION USE.

Scale providers

Band scales

API details from source

LinearScale

Parameters

Returns

BarScale

Parameters

Returns

UTCScale

Parameters

Returns

ScaleId

See also

LinearDomain

See also

BandCategory

See also

BandDomain

See also

BarScaleProps

See also

Properties and methods

BandScaleRange

See also

ResolvedBandScale

See also

Properties and methods

Parameters

Returns

ScaleRange

See also

ScaleLayoutStyle

See also

Properties and methods

LinearScaleProps

See also

Properties and methods

ResolvedLinearScale

See also

Properties and methods

Parameters

Returns

Parameters

Returns

Parameters

Returns

ResolvedScale

Properties and methods

Parameters

Returns

Implementation guidance for agents

Complete minimal examples

Documentation version