@jarenjs/charts 0.49.2 → 0.66.1

package/README.md

@@ -148,6 +148,51 @@ a single-hue blue ramp, light→dark, sampled continuously by
 kernel and can be host-linked with `theme: 'host'`, so charts follow
 the site's light/dark flip live without a re-render.
 
+### A time axis in a language
+
+A time axis labels its ticks by the granularity of the step they were
+laid on — `HH:mm:ss`, `HH:mm`, `yyyy-MM-dd`, `yyyy-MM`, `yyyy` (the
+`TIME_TICK_FORMATS` constant). Those are numeric, so nothing on a
+default axis is mistranslated and nothing on it needs a language. A
+`line` (with `x: 'time'`) or `candlestick` definition that wants month
+or weekday names carries two flat members beside `x` and `xLabel`:
+`timeFormats`, LDML patterns keyed by step granularity (`second`,
+`minute`, `day`, `month`, `year`; an omitted member keeps its default),
+and `dateNames`, the same `DateNames` record the Mermaid Gantt takes —
+exactly what `@jarenjs/locales`' `compileDateLocale(pack).names`
+produces:
+
+```js
+import { compileChart } from '@jarenjs/charts';
+import { compileDateLocale, nl } from '@jarenjs/locales';
+
+const chart = compileChart({
+  type: 'line', x: 'time',
+  dateNames: compileDateLocale(nl).names,
+  timeFormats: { day: 'EEEE d MMMM' },
+  series: [{ name: 'a', points: [
+    { x: '2026-07-20', y: 1 }, { x: '2026-07-24', y: 3 }, { x: '2026-07-29', y: 2 },
+  ] }],
+});
+chart.toSvgString(); // the ticks read 'maandag 20 juli', 'woensdag 22 juli', 'vrijdag 24 juli', …
+```
+
+Both members are data: they serialise with the definition, validate
+against the schema, and two charts on one page carry two records
+without touching each other. The five patterns are compiled **once per
+build** (`compileTimeTickFormat`, exported for a caller labelling its
+own axis), never per label, so a two-hundred-tick axis costs five
+compilations; a definition with neither member compiles nothing at all
+and labels exactly as `formatTimeTick` does.
+
+**Without a record a name token is a compile error, not a silent English
+fallback.** This engine ships no month or weekday names of its own, so
+`timeFormats: { day: 'EEEE d MMMM' }` with no `dateNames` throws a
+`TypeError` naming the member and the way out — the same rule, in the
+same words, as the Gantt's `axisFormat %B`. A numeric pattern needs no
+record. No ambient locale is ever read: the record is supplied or
+absent, never inferred.
+
 ## Streaming (the adapter)
 
 `@jarenjs/charts/stream-adapter` turns the unified reader events of
@@ -248,20 +293,23 @@ frame whose scales moved. `mode` reports which path ran. The
 correctness contract is byte equality: every tick's vnode serializes
 identically to a wholesale `compileChart()` of the same data, which is
 property-tested over thousands of random frames rather than assumed.
+Line sources containing series without an array of `points` also rebuild
+on changes: compilation filters those series, so source change indices
+no longer match the rendered series indices.
 
 Measured (`npm run benchmark:charts`, one appended point):
 
-<!--bm:charts.sessionTable-->
+<!--fact:charts.sessionTable-->
 | points × series | session tick | wholesale tick | frames incremental |
 |---|---:|---:|---:|
 | 100 × 5 | 6.26 µs | 301 µs | 1100 of 1100 |
 | 1,000 × 5 | 4.84 µs | 1.1 ms | 1100 of 1100 |
 | 10,000 × 5 | 4.44 µs | 8.61 ms | 1100 of 1100 |
 | 10,000 × 5 *(sampled)* | 3.25 ms | 2.53 ms | 0 of 1100 |
-<!--/bm-->
+<!--/fact-->
 
 The session tick is *flat* in n — it
-moves <!--bm:charts.sessionFlatness-->0.7× while the wholesale tick grows 28.6×<!--/bm-->. Supported types: `line` (appends
+moves <!--fact:charts.sessionFlatness-->0.7× while the wholesale tick grows 28.6×<!--/fact-->. Supported types: `line` (appends
 and ring-buffer evictions), `bar` (live counts and sums) and
 `candlestick` (keyed kline upserts — one candle group re-renders). The
 website's Binance demo runs on it.
@@ -331,17 +379,17 @@ reports the data rather than the drawing.
 
 Measured (`npm run benchmark:charts`, one series):
 
-<!--bm:charts.samplingTable-->
+<!--fact:charts.samplingTable-->
 | source points | drawn | method | source → AST | source → svg |
 |---:|---:|---|---:|---:|
 | 2,000 | 2,000 | none | 73.4 µs → 72.3 µs | 587 µs → 515 µs |
 | 20,000 | 560 | lttb | 838 µs → 1.28 ms | 5.84 ms → 1.05 ms |
 | 100,000 | 560 | lttb | 4.35 ms → 5.36 ms | 27.8 ms → 5.42 ms |
-<!--/bm-->
+<!--/fact-->
 
 Choosing the points costs about what mapping them costs — the sampler
 reads every reading either way — so the AST column is a small **loss**.
-What it buys is the render — <!--bm:charts.samplingWin-->100,000 points draw as 560 and render 5.1× faster<!--/bm-->. The invariants above are asserted in the benchmark
+What it buys is the render — <!--fact:charts.samplingWin-->100,000 points draw as 560 and render 5.1× faster<!--/fact-->. The invariants above are asserted in the benchmark
 before a single timing is printed.
 
 **Sampling is not retention.** `createStreamAdapter`'s `maxPoints`
@@ -361,3 +409,21 @@ pie AST onto `compileChart` inputs.
 `schemas/chart-definition.schema.json` describes the definition
 document; validate untrusted definitions with `@jarenjs/validate`
 before compiling.
+
+## Exports
+
+Every subpath a consumer can import, derived from the manifest by
+`npm run docs:derive` (`npm run docs:check` fails when the two drift):
+
+<!--fact:exports.charts-->
+| Import | Kind | Declarations |
+|---|---|---|
+| `@jarenjs/charts` | JavaScript | declared |
+| `@jarenjs/charts/component` | JavaScript | declared |
+| `@jarenjs/charts/stream-adapter` | JavaScript | declared |
+| `@jarenjs/charts/transforms/mermaid-adapter` | JavaScript | declared |
+| `@jarenjs/charts/transforms/benchmark-adapter` | JavaScript | declared |
+| `@jarenjs/charts/styles/charts.css` | asset | — |
+| `@jarenjs/charts/schemas/chart-definition.schema.json` | schema | — |
+| `@jarenjs/charts/package.json` | metadata | — |
+<!--/fact-->

package/dist/types/core/axis.d.ts

@@ -36,6 +36,50 @@ export declare function axisTicksOrdinal(categories: readonly string[]): {
  * @returns {string}
  */
 export declare function formatTickValue(v: number): string;
+/**
+ * The label patterns a time axis compiles, keyed by the granularity of
+ * the step the ticks were laid on. Every default is numeric, so an axis
+ * with no `dateNames` record needs none; a caller overrides a member
+ * through `timeFormats` on the chart definition.
+ * @type {Readonly<Record<'second'|'minute'|'day'|'month'|'year', string>>}
+ */
+export declare const TIME_TICK_FORMATS: Readonly<Record<'second' | 'minute' | 'day' | 'month' | 'year', string>>;
+export type TimeTickFormatOptions = {
+    /**
+     * - the
+     * month, weekday and meridiem names a name token (`MMMM`, `EEE`, `a`)
+     * reads; exactly the `names` member `compileDateLocale(pack)` returns
+     */
+    dateNames?: import('@jarenjs/core/dates').DateNames;
+    /**
+     * - LDML patterns replacing the defaults in `TIME_TICK_FORMATS`, per
+     * step granularity
+     */
+    timeFormats?: Partial<Record<'second' | 'minute' | 'day' | 'month' | 'year', string>>;
+};
+/**
+ * Build a time-axis labeller: the five step patterns compiled once,
+ * against the `dateNames` record the chart definition carries, so a
+ * render compiles per build and never per label. The result has the
+ * signature and rules of `formatTimeTick`. With neither member given it
+ * labels exactly as `formatTimeTick` does.
+ *
+ * A pattern with a name token (`MMMM`, `MMM`, `EEEE`, `EEE`, `a`) and no
+ * `dateNames` is a refusal — a `TypeError` — not a silent English
+ * fallback; the numeric defaults need no record.
+ *
+ * @param {TimeTickFormatOptions} [options]
+ * @returns {(v: number|Date, step?: [string, number]) => string}
+ * @throws {TypeError} on a name token with no `dateNames`, or a pattern
+ *   that does not compile
+ * @example
+ * const label = compileTimeTickFormat({
+ *   dateNames: compileDateLocale(nl).names,
+ *   timeFormats: { day: 'EEEE d MMMM' },
+ * });
+ * label(Date.UTC(2026, 6, 27), ['day', 1]); // 'maandag 27 juli'
+ */
+export declare function compileTimeTickFormat(options?: TimeTickFormatOptions): (v: number | Date, step?: [string, number]) => string;
 /**
  * A time-axis tick label in UTC (deterministic across machines).
  *
@@ -45,6 +89,9 @@ export declare function formatTickValue(v: number): string;
  * it keeps the historical behaviour: `HH:MM:SS`, or the date when the
  * value sits exactly on a day boundary.
  *
+ * The patterns are the numeric defaults in `TIME_TICK_FORMATS`; a
+ * localized axis compiles its own labeller with `compileTimeTickFormat`.
+ *
  * @param {number|Date} v - Epoch milliseconds or a Date
  * @param {[string, number]} [step] - The [unit, amount] the axis stepped by
  * @returns {string}

package/dist/types/index.d.ts

@@ -16,7 +16,7 @@
  */
 export { compileChart, chartTypes } from './core/chart.js';
 export { scaleLinear, scaleLog, scaleOrdinal, scaleBand, scaleTime } from './core/scale.js';
-export { niceStep, axisTicksLinear, axisTicksLog, axisTicksOrdinal, formatTickValue, formatTimeTick, axisTicksTime, niceTimeStep, } from './core/axis.js';
+export { niceStep, axisTicksLinear, axisTicksLog, axisTicksOrdinal, formatTickValue, formatTimeTick, compileTimeTickFormat, TIME_TICK_FORMATS, axisTicksTime, niceTimeStep, } from './core/axis.js';
 export { CATEGORICAL, SEQUENTIAL, seriesColor, sequentialColor, inkFor, createTheme, THEMES, HOST_VARS } from './core/palette.js';
 export { buildPieAST, renderPieAST } from './types/pie.js';
 export { buildBarAST, renderBarAST } from './types/bar.js';

package/dist/types/types/candlestick.d.ts

@@ -5,7 +5,15 @@
  * host-linked (`--ok`/`--fail`) like every semantic color. Data shape:
  *
  *   data   = { candles: [{t, open, high, low, close}] }
- *   config = { type:'candlestick', title?, xLabel?, yLabel?, domain? }
+ *   config = { type:'candlestick', title?, xLabel?, yLabel?, domain?,
+ *              dateNames?, timeFormats? }
+ *
+ * The time axis labels its ticks through a labeller compiled once per
+ * build (`compileTimeTickFormat`) from the definition's optional
+ * `dateNames` record and `timeFormats` patterns; a definition without
+ * them labels exactly as `formatTimeTick` does. The per-candle hover
+ * text keeps the numeric `formatTimeTick` — it is a datum's timestamp,
+ * not an axis label.
  *
  * Candle width comes from the band-width math: an equal share of the
  * axis per candle (klines arrive at a fixed interval, so equal bands

package/dist/types/types/line.d.ts

@@ -8,7 +8,14 @@
  *
  *   data   = { series: [{ name, points: [{x, y}] }] }
  *   config = { type:'line', title?, x?: 'linear'|'time', log?,
- *              markers?, xLabel?, yLabel?, domain?, sampling? }
+ *              markers?, xLabel?, yLabel?, domain?, sampling?,
+ *              dateNames?, timeFormats? }
+ *
+ * A time axis labels its ticks through a labeller compiled once per
+ * build (`compileTimeTickFormat`) from the definition's optional
+ * `dateNames` record and `timeFormats` patterns, so a localized axis
+ * costs five compilations per render and none per label, and a
+ * definition without them labels exactly as `formatTimeTick` does.
  *
  * `config.sampling` (`core/sampling.js`) decides how many of those
  * points are drawn: above two thousand a time line is reduced through

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/charts",
   "private": false,
-  "version": "0.49.2",
+  "version": "0.66.1",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -70,7 +70,7 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.49.2",
-    "@jarenjs/view": "^0.49.2"
+    "@jarenjs/core": "^0.66.1",
+    "@jarenjs/view": "^0.66.1"
   }
 }

package/schemas/chart-definition.schema.json

@@ -63,6 +63,8 @@
           "yLabel": { "type": ["string", "null"] },
           "domain": { "$ref": "#/$defs/domainPolicy" },
           "sampling": { "$ref": "#/$defs/samplingPolicy" },
+          "dateNames": { "$ref": "#/$defs/dateNames" },
+          "timeFormats": { "$ref": "#/$defs/timeFormats" },
           "series": {
             "type": "array",
             "items": { "$ref": "#/$defs/lineSeries" }
@@ -77,6 +79,8 @@
           "xLabel": { "type": ["string", "null"] },
           "yLabel": { "type": ["string", "null"] },
           "domain": { "$ref": "#/$defs/domainPolicy" },
+          "dateNames": { "$ref": "#/$defs/dateNames" },
+          "timeFormats": { "$ref": "#/$defs/timeFormats" },
           "candles": {
             "type": "array",
             "items": { "$ref": "#/$defs/candle" }
@@ -443,6 +447,28 @@
         }
       ]
     },
+    "dateNames": {
+      "description": "the month, weekday and meridiem names a time-axis pattern with a name token reads (compileDateLocale(pack).names from @jarenjs/locales); a name token with no record is a compile error, never an English fallback",
+      "type": "object",
+      "properties": {
+        "months": { "type": "array", "minItems": 12, "maxItems": 12, "items": { "type": "string" } },
+        "monthsShort": { "type": "array", "minItems": 12, "maxItems": 12, "items": { "type": "string" } },
+        "weekdays": { "type": "array", "minItems": 7, "maxItems": 7, "items": { "type": "string" } },
+        "weekdaysShort": { "type": "array", "minItems": 7, "maxItems": 7, "items": { "type": "string" } },
+        "meridiem": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "string" } }
+      }
+    },
+    "timeFormats": {
+      "description": "LDML label patterns for a time axis, keyed by the granularity of the tick step; an omitted member keeps its numeric default (HH:mm:ss, HH:mm, yyyy-MM-dd, yyyy-MM, yyyy)",
+      "type": "object",
+      "properties": {
+        "second": { "type": "string" },
+        "minute": { "type": "string" },
+        "day": { "type": "string" },
+        "month": { "type": "string" },
+        "year": { "type": "string" }
+      }
+    },
     "domainPolicy": {
       "description": "domain-stability policy: a quantized sliding x window and/or pinned or step-quantized y bounds, so most streaming ticks keep the scales still",
       "type": "object",

package/src/core/axis.js

@@ -66,12 +66,124 @@ export function formatTickValue(v) {
   return trim(v);
 }
 
-// label patterns by how coarse the step is, compiled once
-const LABEL_SECOND = compileDateFormat('HH:mm:ss');
-const LABEL_MINUTE = compileDateFormat('HH:mm');
-const LABEL_DAY = compileDateFormat('yyyy-MM-dd');
-const LABEL_MONTH = compileDateFormat('yyyy-MM');
-const LABEL_YEAR = compileDateFormat('yyyy');
+/**
+ * The label patterns a time axis compiles, keyed by the granularity of
+ * the step the ticks were laid on. Every default is numeric, so an axis
+ * with no `dateNames` record needs none; a caller overrides a member
+ * through `timeFormats` on the chart definition.
+ * @type {Readonly<Record<'second'|'minute'|'day'|'month'|'year', string>>}
+ */
+export const TIME_TICK_FORMATS = Object.freeze({
+  second: 'HH:mm:ss',
+  minute: 'HH:mm',
+  day: 'yyyy-MM-dd',
+  month: 'yyyy-MM',
+  year: 'yyyy',
+});
+
+/**
+ * @typedef {object} TimeTickFormatOptions
+ * @property {import('@jarenjs/core/dates').DateNames} [dateNames] - the
+ *  month, weekday and meridiem names a name token (`MMMM`, `EEE`, `a`)
+ *  reads; exactly the `names` member `compileDateLocale(pack)` returns
+ * @property {Partial<Record<'second'|'minute'|'day'|'month'|'year', string>>} [timeFormats]
+ *  - LDML patterns replacing the defaults in `TIME_TICK_FORMATS`, per
+ *  step granularity
+ */
+
+/**
+ * Compile the five patterns once against a names record — the compile
+ * step of a two-stage labeller, so the per-label work is one walk of a
+ * compiled chain and never a pattern scan. A pattern that asks for a
+ * locale name with no record to answer it is refused here, at compile
+ * time, in the same terms the Mermaid Gantt refuses one: this engine
+ * ships no month or weekday names of its own.
+ * @param {TimeTickFormatOptions} options
+ * @returns {Record<'second'|'minute'|'day'|'month'|'year', (parts: object) => string>}
+ */
+function compileTickSet(options) {
+  const names = options.dateNames ?? undefined;
+  const patterns = options.timeFormats ?? undefined;
+  const set = /** @type {any} */ ({});
+  for (const key of /** @type {const} */ (['second', 'minute', 'day', 'month', 'year'])) {
+    const pattern = patterns?.[key] ?? TIME_TICK_FORMATS[key];
+    try {
+      set[key] = compileDateFormat(pattern, names);
+    }
+    catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (names === undefined && message.includes('names provider')) {
+        throw new TypeError(`timeFormats.${key} '${pattern}' asks for a locale name, so it needs a`
+          + " 'dateNames' record (a 'dateNames' member on the chart definition);"
+          + ' this engine ships no month or weekday names of its own');
+      }
+      throw new TypeError(`timeFormats.${key} '${pattern}' cannot be compiled: ${message}`);
+    }
+  }
+  return set;
+}
+
+/**
+ * The label for one tick out of a compiled set — see `formatTimeTick`
+ * for the step and no-step rules.
+ * @param {Record<string, (parts: object) => string>} set
+ * @param {number|Date} v
+ * @param {[string, number]|undefined} step
+ * @returns {string}
+ */
+function labelTimeTick(set, v, step) {
+  const ms = typeof v === 'number' ? v : v.getTime();
+  const parts = partsFromEpoch(ms);
+  if (step === undefined) {
+    return parts.hours === 0 && parts.minutes === 0 && parts.seconds === 0
+      ? set.day(parts)
+      : set.second(parts);
+  }
+  const unit = step[0];
+  if (unit === 'second')
+    return set.second(parts);
+  if (unit === 'minute' || unit === 'hour')
+    return set.minute(parts);
+  if (unit === 'day' || unit === 'week')
+    return set.day(parts);
+  return unit === 'month' ? set.month(parts) : set.year(parts);
+}
+
+/**
+ * Build a time-axis labeller: the five step patterns compiled once,
+ * against the `dateNames` record the chart definition carries, so a
+ * render compiles per build and never per label. The result has the
+ * signature and rules of `formatTimeTick`. With neither member given it
+ * labels exactly as `formatTimeTick` does.
+ *
+ * A pattern with a name token (`MMMM`, `MMM`, `EEEE`, `EEE`, `a`) and no
+ * `dateNames` is a refusal — a `TypeError` — not a silent English
+ * fallback; the numeric defaults need no record.
+ *
+ * @param {TimeTickFormatOptions} [options]
+ * @returns {(v: number|Date, step?: [string, number]) => string}
+ * @throws {TypeError} on a name token with no `dateNames`, or a pattern
+ *   that does not compile
+ * @example
+ * const label = compileTimeTickFormat({
+ *   dateNames: compileDateLocale(nl).names,
+ *   timeFormats: { day: 'EEEE d MMMM' },
+ * });
+ * label(Date.UTC(2026, 6, 27), ['day', 1]); // 'maandag 27 juli'
+ */
+export function compileTimeTickFormat(options = {}) {
+  // nothing to compile against: the shared record-free labeller, so a
+  // definition with neither member costs no compilation per build
+  if (options.dateNames === undefined && options.timeFormats === undefined)
+    return formatTimeTick;
+  const set = compileTickSet(options);
+  return (v, step = undefined) => labelTimeTick(set, v, step);
+}
+
+// The record-free set behind `formatTimeTick`: compiled on first use and
+// kept, so a render with no `dateNames` compiles nothing at all.
+/** @type {Record<string, (parts: object) => string>|null} */
+let DEFAULT_SET = null;
 
 /**
  * A time-axis tick label in UTC (deterministic across machines).
@@ -82,26 +194,17 @@ const LABEL_YEAR = compileDateFormat('yyyy');
  * it keeps the historical behaviour: `HH:MM:SS`, or the date when the
  * value sits exactly on a day boundary.
  *
+ * The patterns are the numeric defaults in `TIME_TICK_FORMATS`; a
+ * localized axis compiles its own labeller with `compileTimeTickFormat`.
+ *
  * @param {number|Date} v - Epoch milliseconds or a Date
  * @param {[string, number]} [step] - The [unit, amount] the axis stepped by
  * @returns {string}
  */
 export function formatTimeTick(v, step = undefined) {
-  const ms = typeof v === 'number' ? v : v.getTime();
-  const parts = partsFromEpoch(ms);
-  if (step === undefined) {
-    return parts.hours === 0 && parts.minutes === 0 && parts.seconds === 0
-      ? LABEL_DAY(parts)
-      : LABEL_SECOND(parts);
-  }
-  const unit = step[0];
-  if (unit === 'second')
-    return LABEL_SECOND(parts);
-  if (unit === 'minute' || unit === 'hour')
-    return LABEL_MINUTE(parts);
-  if (unit === 'day' || unit === 'week')
-    return LABEL_DAY(parts);
-  return unit === 'month' ? LABEL_MONTH(parts) : LABEL_YEAR(parts);
+  if (DEFAULT_SET === null)
+    DEFAULT_SET = compileTickSet({});
+  return labelTimeTick(DEFAULT_SET, v, step);
 }
 
 function trim(x) {

package/src/index.js

@@ -20,7 +20,8 @@ export { compileChart, chartTypes } from './core/chart.js';
 export { scaleLinear, scaleLog, scaleOrdinal, scaleBand, scaleTime } from './core/scale.js';
 export {
   niceStep, axisTicksLinear, axisTicksLog, axisTicksOrdinal,
-  formatTickValue, formatTimeTick, axisTicksTime, niceTimeStep,
+  formatTickValue, formatTimeTick, compileTimeTickFormat, TIME_TICK_FORMATS,
+  axisTicksTime, niceTimeStep,
 } from './core/axis.js';
 export { CATEGORICAL, SEQUENTIAL, seriesColor, sequentialColor, inkFor, createTheme, THEMES, HOST_VARS } from './core/palette.js';
 export { buildPieAST, renderPieAST } from './types/pie.js';

package/src/types/candlestick.js

@@ -6,7 +6,15 @@
  * host-linked (`--ok`/`--fail`) like every semantic color. Data shape:
  *
  *   data   = { candles: [{t, open, high, low, close}] }
- *   config = { type:'candlestick', title?, xLabel?, yLabel?, domain? }
+ *   config = { type:'candlestick', title?, xLabel?, yLabel?, domain?,
+ *              dateNames?, timeFormats? }
+ *
+ * The time axis labels its ticks through a labeller compiled once per
+ * build (`compileTimeTickFormat`) from the definition's optional
+ * `dateNames` record and `timeFormats` patterns; a definition without
+ * them labels exactly as `formatTimeTick` does. The per-candle hover
+ * text keeps the numeric `formatTimeTick` — it is a datum's timestamp,
+ * not an axis label.
  *
  * Candle width comes from the band-width math: an equal share of the
  * axis per candle (klines arrive at a fixed interval, so equal bands
@@ -32,6 +40,7 @@ import { clamp01 } from '@jarenjs/core/math';
 import { scaleLinear, scaleTime } from '../core/scale.js';
 import {
   axisTicksLinear, axisTicksTime, niceTimeStep, formatTickValue, formatTimeTick,
+  compileTimeTickFormat,
 } from '../core/axis.js';
 import { cartesianFrame, annotateChart } from '../core/cartesian.js';
 import { normalizeTooltip, markProps } from '../core/marks.js';
@@ -173,6 +182,9 @@ export function buildCandlestickAST(data, config = {}) {
   const domains = resolveCandleDomains(ext, policy);
   const xScale = scaleTime(domains.x[0], domains.x[1]);
   const yScale = scaleLinear(domains.y[0], domains.y[1]);
+  const timeLabel = compileTimeTickFormat({
+    dateNames: config.dateNames, timeFormats: config.timeFormats,
+  });
 
   const w = ext.kept.length === 0 ? 0.1 : (1 / ext.kept.length) * 0.7;
   const candles = ext.kept.map((c) => candleUnit(c, xScale, yScale, w));
@@ -182,7 +194,7 @@ export function buildCandlestickAST(data, config = {}) {
     title: config.title ?? null,
     x: {
       ticks: domains.xTickValues.map((v) => ({
-        pos: clamp01(xScale(v)), label: formatTimeTick(v, domains.xTickStep),
+        pos: clamp01(xScale(v)), label: timeLabel(v, domains.xTickStep),
       })),
       label: config.xLabel ?? null,
     },

package/src/types/line.js

@@ -9,7 +9,14 @@
  *
  *   data   = { series: [{ name, points: [{x, y}] }] }
  *   config = { type:'line', title?, x?: 'linear'|'time', log?,
- *              markers?, xLabel?, yLabel?, domain?, sampling? }
+ *              markers?, xLabel?, yLabel?, domain?, sampling?,
+ *              dateNames?, timeFormats? }
+ *
+ * A time axis labels its ticks through a labeller compiled once per
+ * build (`compileTimeTickFormat`) from the definition's optional
+ * `dateNames` record and `timeFormats` patterns, so a localized axis
+ * costs five compilations per render and none per label, and a
+ * definition without them labels exactly as `formatTimeTick` does.
  *
  * `config.sampling` (`core/sampling.js`) decides how many of those
  * points are drawn: above two thousand a time line is reduced through
@@ -39,7 +46,7 @@ import { clamp01 } from '@jarenjs/core/math';
 import { scaleLinear, scaleLog, scaleTime } from '../core/scale.js';
 import {
   axisTicksLinear, axisTicksLog, axisTicksTime, niceTimeStep,
-  formatTickValue, formatTimeTick,
+  formatTickValue, compileTimeTickFormat,
 } from '../core/axis.js';
 import { cartesianFrame, annotateChart } from '../core/cartesian.js';
 import { numOf } from '../core/stream-adapter.js';
@@ -213,6 +220,9 @@ export function buildLineAST(data, config = {}) {
   const policy = normalizeDomainPolicy(config.domain);
   const domains = resolveLineDomains(scanLineExtremes(input, policy, log), policy, time, log);
   const { xScale, yScale } = lineScales(domains, time, log);
+  const timeLabel = time
+    ? compileTimeTickFormat({ dateNames: config.dateNames, timeFormats: config.timeFormats })
+    : null;
 
   // Sampling chooses which points are DRAWN; it never moves a domain,
   // which is scanned from every source point above. A series the policy
@@ -239,7 +249,7 @@ export function buildLineAST(data, config = {}) {
     x: {
       ticks: domains.xTickValues.map((v) => ({
         pos: clamp01(xScale(v)),
-        label: time ? formatTimeTick(v, domains.xTickStep) : formatTickValue(v),
+        label: timeLabel !== null ? timeLabel(v, domains.xTickStep) : formatTickValue(v),
       })),
       label: config.xLabel ?? null,
     },