@finchart

Appearance

Documentation / @finchart/core / index / XMapping

Interface: XMapping ​

Defined in: packages/core/src/scale/x-mapping.ts:21

Where a data point's x lands on screen. This is everything a series knows about x.

If series used Scale directly, "x is continuous" would be baked into drawing code everywhere, leaving no room for the bar-index coordinate system financial charts want (where weekends and market closures don't open up as gaps).

So there's a layer in between. Scale only does domain↔pixel underneath it, and this contract decides whether the domain is time or a bar index.

Continuous is the default — turning irregular numeric x into a bar index erases the meaning of spacing, so bar index has to be something a chart opts into, not something imposed on it.

Properties ​

barSpacingDefaults? ​

optional barSpacingDefaults?: object

Defined in: packages/core/src/scale/x-mapping.ts:49

The bar-spacing limits to use when wiring hasn't set its own (pixels per one domain unit).

Only the mapping knows what one domain unit means, so the mapping declares the default too — one unit of a continuous mapping might be ms or might be days, and it would be a disaster for the core to guess. PlotConfig's min/maxBarSpacing always wins over this.

max? ​

optional max?: number

min? ​

optional min?: number

domainToPixel? ​

optional domainToPixel?: (value) => number

Defined in: packages/core/src/scale/x-mapping.ts:99

Scale domain value → screen px. The O(1) arithmetic that places a place produced by toDomain/fromDomain onto a pixel — the back half of toPixel.

Used when drawing from a place decimation already computed — the front half (toDomain), which searches the merged x list per point, drops out entirely. Absent means drawing falls back to toPixel.

Parameters ​

value ​

number

Returns ​

number

Methods ​

fromDomain() ​

fromDomain(value): number

Defined in: packages/core/src/scale/x-mapping.ts:38

Scale domain value → data x. The inverse of toDomain.

Parameters ​

value ​

number

Returns ​

number

fromPixel() ​

fromPixel(px): number

Defined in: packages/core/src/scale/x-mapping.ts:25

Screen px → data x.

Parameters ​

px ​

number

Returns ​

number

rebuild()? ​

optional rebuild(sources): void

Defined in: packages/core/src/scale/x-mapping.ts:60

The data changed — a chance to re-index. If this is absent there's nothing to count (continuous mapping), and Plot skips collecting x altogether at that point.

sources is the list of x values per registration (each ascending). Merging them into an index is the mapping's job — Plot only gathers x.

Parameters ​

sources ​

readonly readonly number[][]

Returns ​

void

scanToDomain()? ​

optional scanToDomain(): (x) => number

Defined in: packages/core/src/scale/x-mapping.ts:76

Opens one ascending scan pass — returns a function with the same answers as toDomain, except that function owns its own cursor.

Keeping a single cursor inside the mapping and sharing it across every caller would let a scanning consumer and a point-by-point consumer (drawing, hit testing) trample each other's cursor. toDomain stays pure (binary search, no state), and only a consumer that needs scan acceleration opens a pass through this door and gets a cursor that's born and dies with that pass.

Absent means the domain equals x (continuous mapping) — same rule as rebuild: existence itself is the declaration.

Returns ​

(x) => number

scanToPixel()? ​

optional scanToPixel(): (x) => number

Defined in: packages/core/src/scale/x-mapping.ts:88

The screen-space form of scanToDomain — one ascending scan pass's toPixel. Drawing is this pass's second consumer: a series walks points in ascending x, so it walks with the pass-owned cursor instead of a binary search per point.

Same rule as scanToDomain — the answer always matches toPixel (it just falls back to binary search when it misses), and its absence means toPixel is already O(1).

Returns ​

(x) => number

toDomain() ​

toDomain(x): number

Defined in: packages/core/src/scale/x-mapping.ts:36

Data x → scale domain value. Identity when continuous, an index when it's bar-index.

Pan/zoom operates in the scale domain (it has to, for bar-index, to move evenly bar by bar), while the data-side world (slicing, events) speaks in x. The index is a monotonic function of x, so an interval maps to an interval.

Parameters ​

x ​

number

Returns ​

number

toPixel() ​

toPixel(x): number

Defined in: packages/core/src/scale/x-mapping.ts:23

Data x → screen px.

Parameters ​

x ​

number

Returns ​

number