LogScale

Read as Markdown

Import LogScale and useLogScale from @pibbl/core/viz. Equal ratios map to equal distances. There is no generic scale-family selector.

import { LogScale, Axis } from "@pibbl/core/viz";
<LogScale id="mass" domain={[1, 1000]} range="width" base={10}>
  <Axis scale="mass" position="bottom" />
</LogScale>;

Provider signature and defaults

LogScale(props: LogScaleProps): PibblNode provides a named mapping to descendants.

Input	Default	Contract
`id`	required	Nonempty string or symbol
`domain`	required	Two distinct finite positive endpoints, ascending or descending
`range`	required	`"width"`, `"height"`, or two finite numeric endpoints
`reverse`	`false`	Reverses the range, independently of domain direction
`base`	`10`	Finite number greater than 1; controls power ticks, not mapping
`style`	omitted	Existing scale layout style; layout ownership remains explicit
`children`	omitted	Ordinary Pibbl nodes

Domain, range, reverse, base, whole style, and declared style fields accept the same signals as other scale providers. Changing base publishes a new snapshot even when the mapping stays equal. The provider responds to its containing allocation. No nicening or clamping is automatic.

Hook and fixed return contract

useLogScale(id: ScaleId): Signal<ResolvedLogScale> returns one stable shared readonly signal per provider. .get() reads the current frozen snapshot. Missing IDs fail; reading a mismatched family throws TypeError. Signal reads track the caller normally; the provider owns cleanup when unmounted.

The snapshot exposes type: "log", frozen original domain, resolved range, frame, base, and these methods:

map(value: number): number: finite positive input to logical pixels. Positive out-of-domain values extrapolate. Zero and negative values are errors.
invert(pixel: number): number: finite logical pixels to positive numeric values. Range endpoints return the exact original domain endpoints.
ticks(count = 5): readonly number[]: frozen, ordered, bounded ticks. Count must be an integer 2–100. Both original endpoints are always included. Interior ticks are integer powers of base, subsampled by an integer exponent stride to fit the count. Two requests return only endpoints; intervals with no interior powers also return endpoints. Tick count is a maximum, not a promise of an exact number. Ticks never change mapping or domain.

A collapsed range maps all values to its single pixel but cannot be inverted. A collapsed domain, nonpositive/nonfinite domain or map value, invalid base, nonfinite span/output, invalid count, or unrepresentable tick exponent throws RangeError. Extremely close endpoints whose logarithms become equal reject. Inversion that overflows or underflows to zero rejects. Invalid reverse uses the shared scale validation (TypeError). Malformed endpoints/ranges reject instead of being coerced. A base very close to one may map normally but reject tick requests whose integer exponents exceed numeric precision; use a larger base.

Composition and inspection

Axes, LineSeries, PointSeries, PlotSeries, ScaleAdjust, HoverData, nearestPoint, and nearestDomainValue accept this continuous mapping. Numeric inspection measures distances after mapping. Missing/nonfinite samples retain existing mark/query behavior; zero/negative log coordinates reject unless the caller excludes them with defined. Value bars need an explicit positive baseline or positive ranges; their default zero baseline is invalid on a log scale. A log chart has no zero position.

Labels remain independent: use Axis.labelOverlap="skip" for crowded endpoints and formatNumber for units. Never interpret a logarithmic bar length as an additive magnitude. The NASA example uses equal-size dots instead.

Runnable examples

The minimal log demo demonstrates the provider, hook, mapping, inverse, and ticks. The NASA mass chart compares checked-in planetary data across orders of magnitude with touch/keyboard inspection.

API details from source

LogScale

Provides a named positive logarithmic mapping to descendant marks and axes.

LogScale: (props: LogScaleProps) => PibblNode

Related API: LogScale, LogScaleProps, PibblNode.

Parameters

props — Identity, positive domain, range, and optional tick base. See LogScaleProps.

Returns

Descendant content within the logarithmic scale scope.

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

useLogScale

Reads an ancestor logarithmic scale as a stable shared readonly signal.

useLogScale: (id: ScaleId) => Signal<ResolvedLogScale>

Related API: useLogScale, ScaleId, Signal, ResolvedLogScale.

Parameters

id — Ancestor scale identity. See ScaleId.

Returns

The reactive logarithmic mapping. See ResolvedLogScale.

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

LogScaleProps

Positive logarithmic provider inputs. See LinearScaleProps.

interface LogScaleProps extends LinearScaleProps

Related API: LogScaleProps, LinearScaleProps.

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

Properties and methods

base (optional)

readonly base?: SignalValue<number> | undefined

Related API: SignalValue.

Base for power ticks; finite and greater than one, default 10. Mapping is base-independent.

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

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

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

ResolvedLogScale

Positive logarithmic mapping with numeric inverse. See ResolvedLinearScale.

interface ResolvedLogScale extends Omit<ResolvedLinearScale, "type">

Related API: ResolvedLogScale, ResolvedLinearScale.

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

Properties and methods

type

readonly type: "log"

Logarithmic mapping discriminant. See LogScaleProps.

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

base

readonly base: number

Resolved base used for power ticks. See LogScaleProps.

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

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

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

File sizes across orders of magnitude: Multiplying the size by ten moves the same distance. Plain source

Documentation version

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