Numeric ticks and formatting

Read as Markdown

Import these pure helpers from @pibbl/core/viz. They accept ordinary values, not signals. Read a signal with .get() inside a component or computed value to reactively recompute. They create no subscriptions or resources themselves.

Readable ticks

linearTicks(domain: NumericDomain, options?: LinearTickOptions): readonly number[] returns frozen ticks at 1, 2, or 5 times a power of ten. count defaults to 5 and requests approximate intervals, not an exact output length. Output is capped at 100 ticks by increasing the readable step when necessary. Only aligned values within the domain are emitted, in domain order. Negative zero becomes zero. The domain and scale mapping are unchanged; endpoints need not be ticks. Existing useLinearScale(id).get().ticks(count) retains its evenly spaced, endpoint-inclusive contract.

niceLinearDomain(domain: NumericDomain, options?: LinearTickOptions): NumericDomain returns frozen endpoints expanded outward to these readable boundaries, preserving ascending or descending direction. Pass the result explicitly to LinearScale; axes never silently expand a domain.

Both helpers require two distinct finite endpoints with a finite span and an integer count from 2 to 100. Invalid input, unrepresentable tick spacing, or non-finite expanded bounds throws RangeError. Neither mutates its input.

Number and unit formatting

formatNumber(value: number, options?: NumberFormatOptions): string uses Intl.NumberFormat. locale defaults to "en-US". prefix and suffix default to empty strings and are literal (include any desired space). All other options are standard Intl.NumberFormatOptions, including fraction precision, significant digits, currency, percent, compact notation, and units. Default decimal precision is at most three fractional digits. Rounded negative zero displays as positive zero. Non-finite values throw RangeError; invalid locale or Intl options retain the native Intl error. Results follow the host’s Intl locale data. No locale or unit is inferred from the data.

Minimal runnable composition

The editable minimal numeric demo and NOAA example uses these helpers with height-dependent tick density and label collision handling. This complete mount demonstrates every helper:

import { Group, pibbl } from "@pibbl/core";
import {
  Axis,
  LinearScale,
  linearTicks,
  niceLinearDomain,
  formatNumber,
} from "@pibbl/core/viz";

export default function mount(canvas: HTMLCanvasElement) {
  const domain = niceLinearDomain([0.13, 0.97]);
  return pibbl(
    canvas,
    <Group style={{ translateX: 24, translateY: 24 }}>
      <LinearScale id="value" domain={domain} range={[0, 240]}>
        <Axis
          scale="value"
          position="top"
          tickValues={linearTicks(domain)}
          labelOverlap="skip"
          tickFormat={(value) =>
            formatNumber(Number(value), {
              minimumFractionDigits: 1,
              maximumFractionDigits: 1,
              suffix: " ppm",
            })
          }
        />
      </LinearScale>
    </Group>,
  );
}

Layout belongs to the composition: leave gutters for labels and units. Use labelOverlap="skip" to omit crowded labels while preserving every tick mark.

API details from source

linearTicks

Generates bounded ticks at readable 1, 2, or 5 × powers-of-ten intervals. Endpoints are included only when aligned. Does not change scale geometry.

linearTicks: (domain: NumericDomain, options?: LinearTickOptions) => readonly number[]

Related API: linearTicks, NumericDomain, LinearTickOptions.

Parameters

domain — Distinct finite endpoints, ascending or descending.
options — Target density; defaults to five intervals.

Returns

Frozen ticks in domain order. See niceLinearDomain.

View source — packages/core/src/features/viz/lib/numeric-ticks.ts:39

niceLinearDomain

Expands a linear domain to readable tick boundaries, preserving direction.

niceLinearDomain: (domain: NumericDomain, options?: LinearTickOptions) => NumericDomain

Parameters

domain — Distinct finite numeric endpoints; never mutated.
options — Target density; defaults to five intervals.

Returns

Frozen expanded endpoints. See linearTicks.

View source — packages/core/src/features/viz/lib/numeric-ticks.ts:51

formatNumber

Formats a finite number with Intl precision, currency, percent, or unit options. Rounded negative zero is displayed as positive zero.

formatNumber: (value: number, options?: NumberFormatOptions) => string

Related API: formatNumber, NumberFormatOptions.

Parameters

value — Finite numeric value.
options — Intl options plus locale and literal affixes; default maximum fraction digits is 3.

Returns

Formatted text. Invalid Intl options retain native errors. See NumberFormatOptions.

View source — packages/core/src/features/viz/lib/numeric-ticks.ts:73

LinearTickOptions

Readable linear tick density. See linearTicks.

interface LinearTickOptions

Related API: LinearTickOptions.

View source — packages/core/src/features/viz/lib/numeric-ticks.ts:4

Properties and methods

count (optional)

readonly count?: number | undefined

Target number of intervals, from 2 to 100; defaults to 5.

View source — packages/core/src/features/viz/lib/numeric-ticks.ts:6

NumberFormatOptions

Number formatting with explicit locale and literal unit affixes. See formatNumber.

interface NumberFormatOptions extends Intl.NumberFormatOptions

Related API: NumberFormatOptions.

View source — packages/core/src/features/viz/lib/numeric-ticks.ts:58

Properties and methods

locale (optional)

readonly locale?: string | undefined

Locale for formatting; defaults to en-US.

View source — packages/core/src/features/viz/lib/numeric-ticks.ts:60

prefix (optional)

readonly prefix?: string | undefined

Literal prefix; defaults to empty.

View source — packages/core/src/features/viz/lib/numeric-ticks.ts:62

suffix (optional)

readonly suffix?: string | undefined

Literal suffix, including any desired space; defaults to empty.

View source — packages/core/src/features/viz/lib/numeric-ticks.ts:64

Implementation guidance for agents

Read the Authoring, signals, and lifecycle companion for ownership, adaptation, failure modes, and verification. Agent start provides the version-selection workflow.

Complete minimal examples

Readable numeric ticks: Round a temperature range outward and format evenly spaced tick labels with units. Plain source

Documentation version

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