@motionscript/charts 0.1.0-alpha.5 → 0.1.0-alpha.7

package/src/kit/chart-legend.ts

@@ -1,22 +1,36 @@
 import {
+  Flow,
+  Paint,
   Rect,
+  Shapes,
   Text,
-  command,
-  easeOut,
-  property,
+  Types,
+  component2d,
   textOps,
-  type CommandArgs,
-  type EasingFunction,
   type Fill,
-  type MeasureContext2D,
-  type NodeConfig,
+  type NodeOf,
   type RectProps,
-  type Size2D,
-  type SizeConstraints,
+  // Named so the row's emitted type reaches the Rect surface it spreads through the sdk, not core.
+  type Alignment as _Alignment,
+  type CornerRadiusResolved as _CornerRadiusResolved,
+  type CornerStyleResolved as _CornerStyleResolved,
+  type FillResolved as _FillResolved,
+  type FlowMode as _FlowMode,
+  type FlowResolved as _FlowResolved,
+  type GapSize as _GapSize,
+  type Node2D as _Node2D,
+  type Node2DProps as _Node2DProps,
+  type RectCornerRadius as _RectCornerRadius,
+  type RectCornerStyle as _RectCornerStyle,
+  type Shadow as _Shadow,
+  type ShadowResolved as _ShadowResolved,
+  type Stroke as _Stroke,
+  type StrokeResolved as _StrokeResolved,
+  type Vector2 as _Vector2,
 } from "@motionscript/sdk"
 
-import { drive, hold, together, type Seekable } from "@motionscript/sdk/component"
-
+import { fresh } from "./entries"
+import { frameEase } from "./motion"
 import {
   DEFAULT_LEGEND,
   SPOTLIGHT_DIM,
@@ -29,7 +43,7 @@ export interface ChartLegendProps extends RectProps {
    * One entry per series: legend `label`, its `enabled` default, and — through
    * {@link ChartLegendProps.swatches} — the colour its chip is painted. A series
    * that starts enabled (the default) is added to the row up front; one that
-   * starts `false` is hidden until a later {@link ChartLegend.showSeries}.
+   * starts `false` is hidden until a later `showSeries`.
    */
   series: ChartSeries[]
   /**
@@ -43,25 +57,40 @@ export interface ChartLegendProps extends RectProps {
   legend: LegendConfig
 }
 
+/** A row's entries are a `Rect`'s: paint, the flow of its children, its corners. */
+const row = { ...Paint.state, ...Flow.state, ...Shapes.corners }
+
 /**
- * One legend entry. It hugs its caption and swatch; `shown` scales that width from
- * nothing to the whole of it.
+ * One legend entry. It hugs its caption and swatch; `shown` scales that width
+ * from nothing to the whole of it.
  *
  * The width is taken from the content on every measure, at any reveal, so a frame
  * never depends on whether the entry was once seen fully shown. A collapse needs a
  * number to scale, and `"hug"` is not one until something measures it — this is
  * the something.
  */
-class LegendEntry extends Rect {
-  constructor(props: NodeConfig<Rect, RectProps>, private readonly _shown: () => number) {
-    super(props)
-  }
+const LegendEntry = component2d({
+  key: "legendEntry",
+  state: { ...row, shown: Types.number(1) },
+  commands: { ...Paint.commands },
+  measure: (measurer, state, children) => {
+    const size = Flow.measure(measurer, state, children, Paint.inset(state))
+    return state.shown >= 1 ? size : { ...size, width: state.shown * size.width }
+  },
+  layout: (box, state, children) => Flow.layout(box, state, children, Paint.inset(state)),
+  render: (ctx, state) => Paint.draw(ctx, state, Shapes.rect(ctx.size, state)),
+})
 
-  override measure(constraints: SizeConstraints, scope: MeasureContext2D): Partial<Size2D> {
-    const size = super.measure(constraints, scope)
-    const shown = this._shown()
-    return shown >= 1 ? size : { ...size, width: shown * (size.width ?? 0) }
-  }
+/**
+ * How far each entry is shown, written whole (a document, a `set`) or one
+ * entry at a time (a command, as `{ [index]: reveal }`), which leaves the others
+ * as the frame left them — so two series moving at once each move their own.
+ */
+function revealOf(value: readonly number[] | Readonly<Record<number, number>>, previous?: number[]): number[] {
+  if (Array.isArray(value)) return value as number[]
+  const next = [...(previous ?? [])]
+  for (const [index, reveal] of Object.entries(value)) next[Number(index)] = reveal
+  return next
 }
 
 /**
@@ -70,176 +99,131 @@ class LegendEntry extends Rect {
  * with a rounded colour swatch; only the swatch carries the series colour, the
  * caption reads in the legend's neutral ink.
  *
- * {@link showSeries}/{@link hideSeries} flip a series on or off — showing one
- * adds its entry back into the row at its stable series position and grows it
- * in, hiding one shrinks it away and removes it. So the row only ever holds the
- * currently-enabled series, in series order, and closes the gap when one leaves.
+ * `showSeries`/`hideSeries` flip a series on or off — showing one grows its
+ * entry back in at its stable series position, hiding one shrinks it away. So
+ * the row only ever shows the currently-enabled series, in series order, and
+ * closes the gap when one leaves.
  *
  * This node *is* the row, so the parent places it (centred below the chart) and
  * it hugs its entries.
  */
-export class ChartLegend extends Rect {
-  @property({ default: () => [] as ChartSeries[] }) declare series: ChartSeries[]
-  @property({ default: () => [] as Fill[] }) declare swatches: Fill[]
-  @property({ default: DEFAULT_LEGEND }) declare legend: LegendConfig
-
-  /** One entry per series. **Every** entry is a child — see {@link reveal}. */
-  private items: LegendEntry[] = []
-  /**
-   * How far each entry is shown, `0`–`1`. Drives its width, opacity and gap
-   * together, so `0` is an entry that takes no room and `1` is one at its
-   * natural size.
-   *
-   * This replaces adding and removing the entry from the row, which is what
-   * `showSeries`/`hideSeries` used to do. That could not be a command: a command
-   * is asked what it looks like at a time, and "is this node a child" is not a
-   * value a time can produce — the tree either contains it or it doesn't, and
-   * getting there means having run the add. Collapsed-but-present is the same
-   * picture reached by a route that *is* a function of `t`.
-   *
-   * One array in one slot, because the count is the series count, which is data.
-   * It is replaced rather than mutated: a write is a slot write, so the timeline
-   * sees it and restores it to the authored reveal before the command starts
-   * and after a seek back. The entries' props are bound to it, so writing it
-   * still moves the layout.
-   */
-  @property({ default: () => [] as number[] }) private declare reveal: number[]
-
-  constructor(props?: NodeConfig<ChartLegend, ChartLegendProps>) {
-    // `flow` after the spread, with the rest of the geometry: this class *is*
-    // the row, so the direction is its own answer and not the caller's. It has
-    // to be stated — a `Rect` given no flow lays its children out `freeform`,
-    // which stacks every entry on the same spot. One series looks perfect that
-    // way and three look like one smeared caption, so the failure only shows up
-    // on the charts that most need a legend.
-    super({
-      ...(props as RectProps),
-      flow: "horizontal",
-      align: "center",
-      width: "hug",
-      height: "hug",
-    })
-
-    // Structure is one entry per series, so it's composed here from the resolved
-    // props super() applied. Fixed row geometry last, so it wins over super().
-    this.set({ gap: this.legend.itemGap, padding: this.legend.padding })
-
-    this.reveal = this.series.map((s) => ((s.enabled ?? true) ? 1 : 0))
-    this.items = this.series.map((s, i) => this.buildItem(s, i))
-
-    // All of them, in series order. Order is now fixed rather than depending on
-    // which siblings happen to be shown, so an entry always comes back where it
-    // belongs and `insertionIndex` has nothing left to compute.
-    for (const item of this.items) this.add(item)
-  }
-
-  /** One entry: the series caption beside its colour swatch. */
-  private buildItem(series: ChartSeries, index: number): LegendEntry {
-    const marker = this.legend.markerStyle
-    const item = new LegendEntry({ flow: "horizontal",
-      gap: 12,
-      align: "center",
-      // Bound to the reveal, so showing and hiding is a number moving rather
-      // than a child arriving and leaving. The width follows it in `measure`.
-      width: "hug",
-      opacity: () => this.reveal[index] ?? 0,
-      height: "hug",
-      children: [
-        new Text({
-          ...textOps.styleProps(this.legend.textStyle),
-          text: series.label,
-        }),
-        new Rect({
-          width: marker.width,
-          height: marker.height,
-          cornerRadius: marker.borderRadius,
-          fill: this.swatches[index] ?? "white",
-          stroke: marker.stroke,
-          shadow: marker.shadow,
-        }),
-      ],
-    }, () => this.reveal[index] ?? 0)
-    // `gapScale` is a `Node` prop rather than a container one, so it is bound here
-    // instead of in the config. It tracks the reveal so the flanking gap closes
-    // with the entry rather than snapping when it reaches zero.
-    item.set({ gapScale: () => this.reveal[index] ?? 0 })
-    return item
-  }
-
-  /** True if series `index` is showing at all — see {@link reveal}. */
-  isEnabled(index: number): boolean {
-    return (this.reveal[index] ?? 0) > 0
-  }
-
-  /**
-   * Grow series `index`'s entry back in at its series-order position, the
-   * siblings sliding over to make room.
-   *
-   * A reveal tween rather than an animated `addChildAt`. The entry never left —
-   * see {@link reveal} — so there is no add to have happened, and the whole
-   * thing is a function of `t`.
-   */
-  @command()
-  showSeries(args: CommandArgs<{ index: number }>): Seekable {
-    const { index = 0 } = args.data ?? {}
-    return this.revealTo(index, 1, args.duration ?? 0.35, args.easing ?? easeOut())
-  }
-
-  /**
-   * Shrink series `index`'s entry away, the gap closing behind it — the mirror
-   * of {@link showSeries}.
-   */
-  @command()
-  hideSeries(args: CommandArgs<{ index: number }>): Seekable {
-    const { index = 0 } = args.data ?? {}
-    return this.revealTo(index, 0, args.duration ?? 0.35, args.easing ?? easeOut())
-  }
+export const ChartLegend = component2d({
+  key: "chartLegend",
+  state: {
+    ...row,
+    series: fresh<ChartSeries[]>(() => []),
+    swatches: fresh<Fill[]>(() => []),
+    legend: Types.custom<LegendConfig>(DEFAULT_LEGEND),
+    /**
+     * How far each entry is shown, `0`–`1`. Drives its width, opacity and gap
+     * together, so `0` is an entry that takes no room and `1` is one at its
+     * natural size.
+     *
+     * This replaces adding and removing the entry from the row: a command is
+     * asked what it looks like at a time, and "is this node a child" is not a
+     * value a time can produce. Collapsed-but-present is the same picture reached
+     * by a route that *is* a function of `t`.
+     */
+    reveal: fresh<number[], number[] | Readonly<Record<number, number>>>(() => [], { resolve: revealOf }),
+  },
+  // This node *is* the row, so the direction is its own answer. It has to be
+  // stated — a `Rect` given no flow lays its children out `freeform`, which
+  // stacks every entry on the same spot. The gap and padding are the theme's.
+  defaults: {
+    flow: "horizontal",
+    width: "hug",
+    height: "hug",
+    gap: (state) => state.legend.itemGap,
+    padding: (state) => state.legend.padding,
+    reveal: (state) => state.series.map((s) => ((s.enabled ?? true) ? 1 : 0)),
+  },
+  // One entry per series, in series order, every one a child for good: order is
+  // fixed rather than depending on which siblings happen to be shown, so an entry
+  // always comes back where it belongs.
+  children: (state) => {
+    const marker = state.legend.markerStyle
+    return state.series.map((series, index) =>
+      LegendEntry({
+        flow: "horizontal",
+        gap: 12,
+        align: "center",
+        width: "hug",
+        height: "hug",
+        // Bound to the reveal, so showing and hiding is a number moving rather
+        // than a child arriving and leaving. The width follows it in `measure`,
+        // and the flanking gap closes with the entry rather than snapping.
+        opacity: () => state.reveal[index] ?? 0,
+        gapScale: () => state.reveal[index] ?? 0,
+        shown: () => state.reveal[index] ?? 0,
+        children: [
+          Text({ ...textOps.styleProps(state.legend.textStyle), text: series.label }),
+          Rect({
+            width: marker.width,
+            height: marker.height,
+            cornerRadius: marker.borderRadius,
+            fill: state.swatches[index] ?? "white",
+            stroke: marker.stroke,
+            shadow: marker.shadow,
+          }),
+        ],
+      })
+    )
+  },
+  commands: {
+    ...Paint.commands,
+    /**
+     * Grow series `index`'s entry back in at its series-order position, the
+     * siblings sliding over to make room. A reveal tween rather than an animated
+     * `addChildAt`: the entry never left, so the whole thing is a function of `t`.
+     */
+    showSeries: {
+      args: { index: Types.number(0, { min: 0, step: 1 }) },
+      // An index that is not a series takes its slot and moves nothing.
+      run: (timeline, state) => (timeline.args.index in state.series
+        ? timeline.animate(revealFrame(state, timeline.args.index, 1, frameEase(timeline)))
+        : timeline.wait(timeline.duration)),
+    },
+    /** Shrink series `index`'s entry away, the gap closing behind it — the mirror of `showSeries`. */
+    hideSeries: {
+      args: { index: Types.number(0, { min: 0, step: 1 }) },
+      run: (timeline, state) => (timeline.args.index in state.series
+        ? timeline.animate(revealFrame(state, timeline.args.index, 0, frameEase(timeline)))
+        : timeline.wait(timeline.duration)),
+    },
+    /**
+     * Dim every entry but series `index` to {@link SPOTLIGHT_DIM} and bring that
+     * one back to full — the legend half of a chart's `spotlightSeries`. Entries
+     * stay in place; only their opacity moves, so the row doesn't reflow. Only
+     * the entries shown when it is built are touched: a hidden series' entry is
+     * left as `hideSeries` left it.
+     */
+    spotlightSeries: {
+      args: { index: Types.number(0, { min: 0, step: 1 }) },
+      run: (timeline, state, children) =>
+        timeline.together(
+          children.flatMap((entry, i) =>
+            (state.reveal[i] ?? 0) > 0 ? [entry.to({ opacity: i === timeline.args.index ? 1 : SPOTLIGHT_DIM })] : []
+          )
+        ),
+    },
+  },
+  measure: (measurer, state, children) => Flow.measure(measurer, state, children, Paint.inset(state)),
+  layout: (box, state, children) => Flow.layout(box, state, children, Paint.inset(state)),
+  render: (ctx, state) => Paint.draw(ctx, state, Shapes.rect(ctx.size, state)),
+})
 
-  /**
-   * Ramp one entry's reveal to `target`.
-   *
-   * `from` is read when the command is built, which for a driven scene is with
-   * the node in the state its own start time implies — so a hide that follows a
-   * show starts where the show left it rather than at whatever the node happens
-   * to hold now.
-   */
-  private revealTo(
-    index: number,
-    target: number,
-    duration: number,
-    easing: EasingFunction
-  ): Seekable {
-    if (this.items[index] === undefined) return hold(duration)
-    const from = this.reveal[index] ?? 0
-    return drive(duration, (t) => {
-      const next = [...this.reveal]
-      next[index] = from + (target - from) * easing(t)
-      this.reveal = next
-    })
-  }
+/**
+ * One entry's reveal ramping to `target` from where the command finds it — so a
+ * hide that follows a show starts where the show left it.
+ */
+function revealFrame(state: { readonly reveal: readonly number[] }, index: number, target: number, ease: (t: number) => number) {
+  const from = state.reveal[index] ?? 0
+  return (t: number) => ({ reveal: { [index]: from + (target - from) * ease(t) } })
+}
 
-  /**
-   * Dim every entry but series `index` to {@link SPOTLIGHT_DIM} and bring that
-   * one back to full — the legend half of a chart's `spotlightSeries`. Entries
-   * stay in place; only their opacity moves, so the row doesn't reflow.
-   *
-   * Only the currently-shown entries are touched — a hidden series' entry is
-   * left as {@link hideSeries} left it.
-   */
-  @command()
-  spotlightSeries(args: CommandArgs<{ index: number }>): Seekable {
-    const { index = 0 } = args.data ?? {}
-    const duration = args.duration ?? 0.35
-    const easing = args.easing ?? easeOut()
-    // Opacity only, on entries that are already in the row — no membership
-    // changes, so unlike {@link showSeries} this is a plain function of `t`.
-    return together(
-      ...this.items
-        .map((item, i) => ({ item, i }))
-        .filter(({ i }) => this.isEnabled(i))
-        .map(({ item, i }) =>
-          item.to({ data: { opacity: i === index ? 1 : SPOTLIGHT_DIM }, duration, easing })
-        )
-    )
-  }
+/** Whether series `index` is showing at all on `legend`. */
+export function legendShows(legend: { readonly reveal: readonly number[] }, index: number): boolean {
+  return (legend.reveal[index] ?? 0) > 0
 }
+
+export type ChartLegend = NodeOf<typeof ChartLegend>

package/src/kit/entries.ts

@@ -0,0 +1,20 @@
+import { Types, type Element, type Node2D, type Type } from "@motionscript/sdk"
+
+/**
+ * An entry made fresh for every node: each node gets its own array or box
+ * rather than one shared literal, and a host is told no default for it.
+ */
+export function fresh<T, In = T>(make: () => T, options?: { readonly resolve?: (value: In) => T; readonly kind?: string }): Type<In, T> {
+  // A function default is a factory: the component calls it once per node.
+  return Types.custom<In, T>(make as unknown as In, options)
+}
+
+/**
+ * Nodes a `children` builder made with `new`, as the elements it returns. A
+ * part built that way can be read in a binding — its own box, or its parent's,
+ * which is the component it was built for — where a call would hand back only
+ * the element.
+ */
+export function asParts(nodes: readonly Node2D[]): readonly Element[] {
+  return nodes as unknown as readonly Element[]
+}

package/src/kit/motion.ts

@@ -0,0 +1,90 @@
+import { Types, easeOut, type EasingFunction, type Piece, type Timeline } from "@motionscript/sdk"
+
+const identity: EasingFunction = (t) => t
+
+/** Any component's timeline: these helpers only build pieces, which every timeline builds alike. */
+type AnyTimeline = Timeline<any, any>
+
+/**
+ * The ease a part's own frames apply to `t`: none when its command was given
+ * one, which already eases every frame the command builds, and otherwise the
+ * ease-out every chart command defaults to.
+ */
+export function frameEase(timeline: { readonly easing: EasingFunction | undefined }): EasingFunction {
+  return timeline.easing ? identity : easeOut()
+}
+
+/** A piece of a command placed at its own time: from `at` seconds, for `duration` seconds. */
+export interface Beat {
+  readonly at: number
+  readonly duration: number
+  readonly piece: Piece
+}
+
+/**
+ * `beats` at their own offsets over the command, each eased on its own and held
+ * at its last frame once it is done. A beat ahead of the playhead writes nothing,
+ * so whatever stands before it is written by a piece ahead of these. Beats that
+ * run past the command are played faster to end with it.
+ */
+export function beats(timeline: AnyTimeline, parts: readonly Beat[]): Piece {
+  const total = timeline.duration
+  const natural = parts.reduce((end, part) => Math.max(end, part.at + part.duration), 0)
+  const k = natural > total && natural > 0 ? total / natural : 1
+  return timeline.together(
+    parts.map(({ at, duration, piece }) => {
+      const start = at * k
+      const length = duration * k
+      return timeline.sequence([timeline.wait(start), piece, timeline.wait(Math.max(0, total - start - length))])
+    })
+  )
+}
+
+/** How far one piece of a staggered entrance has come: its opacity, and how far it still sits off its place. */
+export interface Arrival {
+  readonly opacity: number
+  readonly shift: number
+}
+
+/** Each piece's arrival, by key. An unlisted piece has landed. */
+export type Arrivals = Readonly<Record<string, Arrival>>
+
+export const LANDED: Arrival = { opacity: 1, shift: 0 }
+
+/**
+ * A part's private record of its pieces' arrivals. A write merges into it, so
+ * beats placed apart each write their own piece and leave the others as the
+ * frame left them.
+ */
+export function arrivalsEntry() {
+  return Types.custom<Arrivals>({}, { private: true, resolve: (next: Arrivals, previous?: Arrivals) => ({ ...previous, ...next }) })
+}
+
+export function arrivalOf(arrivals: Arrivals, key: string | number): Arrival {
+  return arrivals[key] ?? LANDED
+}
+
+/** Every piece in `keys` armed at `from`: the first frame of their entrance. */
+export function armed(keys: readonly (string | number)[], from: Arrival): Arrivals {
+  const record: Record<string, Arrival> = {}
+  for (const key of keys) record[key] = from
+  return record
+}
+
+/**
+ * A piece arriving from `from` over its beat: a part armed at `from` tweened to
+ * `{ opacity: 1, [axis]: 0 }`, eased by `ease`.
+ */
+export function arrival(timeline: AnyTimeline, key: string | number, from: Arrival, ease: EasingFunction): Piece {
+  return timeline.animate((t) => {
+    const e = ease(t)
+    return {
+      arrivals: {
+        [key]: {
+          opacity: from.opacity + (LANDED.opacity - from.opacity) * e,
+          shift: from.shift + (LANDED.shift - from.shift) * e,
+        },
+      },
+    }
+  })
+}

package/src/kit/paints.ts

@@ -0,0 +1,15 @@
+import type { FillResolved, Loader, ShadowResolved, StrokeResolved } from "@motionscript/sdk"
+
+/** Paints a chart part holds in entries of its own, which no paint entry loads for it. */
+export interface PartPaints {
+  readonly fills?: readonly (readonly FillResolved[])[]
+  readonly strokes?: readonly (readonly StrokeResolved[])[]
+  readonly shadows?: readonly (readonly ShadowResolved[])[]
+}
+
+/** Declare `paints` from a component's `load`. */
+export function loadPaints(loader: Loader, paints: PartPaints): void {
+  for (const fill of paints.fills ?? []) loader.fill(fill)
+  for (const strokes of paints.strokes ?? []) for (const stroke of strokes) loader.fill(stroke.fill)
+  for (const shadows of paints.shadows ?? []) for (const shadow of shadows) loader.fill(shadow.fill)
+}

package/src/kit/shared.ts

@@ -13,7 +13,7 @@
  * within one app.
  *
  * Kept renderer-agnostic (no `Node` imports) so a host's own inspector
- * mappings can build a partial theme without pulling the node classes in.
+ * mappings can build a partial theme without pulling the components in.
  *
  * **Two conventions run through every resolver and lerp below**, inherited from
  * the shape system's `resolveStroke`/`resolveShadow`:
@@ -101,7 +101,7 @@ export interface AxisDomainConfig {
 }
 
 /**
- * An axis domain's @property mapper: merges the author's partial input onto
+ * An axis domain entry's resolve: merges the author's partial input onto
  * `previous`, so a later partial `.set({ yAxis: {...} })` patches
  * `label`/`range`/`ticks` independently. `range`/`ticks` staying `undefined`
  * after the merge is the auto-derive signal the scale getters read.
@@ -119,7 +119,7 @@ export function resolveAxisDomain(
 }
 
 /**
- * An axis domain's @property tween: interpolates `range`/`ticks` numerically
+ * An axis domain entry's lerp: interpolates `range`/`ticks` numerically
  * (pairwise by index for `ticks`), so a `to` command that restates a range
  * rescales the plot smoothly. `label`, and either field when one side is in
  * auto-derive mode, step at the midpoint.
@@ -188,6 +188,55 @@ export function axisTweenTarget(
   return target
 }
 
+/**
+ * An axis domain part-way through a tween that leaves or reaches a `range` or
+ * `ticks` left to the data: both ends as stored, and how far along. Only the
+ * chart knows what an auto side draws as, so {@link settleAxisDomain} resolves
+ * it there. Its own fields are the plain {@link lerpAxisDomain} of its ends, so
+ * a mapper merging onto one still reads a domain.
+ */
+export interface AxisDomainBlend extends AxisDomainConfig {
+  readonly blend: { readonly from: AxisDomainConfig; readonly to: AxisDomainConfig; readonly t: number }
+}
+
+function blendOf(domain: AxisDomainConfig): AxisDomainBlend["blend"] | undefined {
+  return (domain as Partial<AxisDomainBlend>).blend
+}
+
+/**
+ * A chart's axis entry tween: what `to({ yAxis: { range } })` moves through.
+ * Between two explicit domains it is {@link lerpAxisDomain}, and a restated
+ * `range` without `ticks` spreads explicit ticks across it, keeping their count.
+ * When either end leaves `range` or `ticks` to the data, the value between is an
+ * {@link AxisDomainBlend}, which the chart draws as the blend of what each end
+ * draws: a rescale from an auto axis is continuous, not a cut at the midpoint.
+ */
+export function lerpAxisEntry(from: AxisDomainConfig, to: AxisDomainConfig, t: number): AxisDomainConfig {
+  // The mapper merged the request onto `from`, so a field it left unstated is `from`'s own, by identity.
+  const rangeMoved = to.range !== from.range
+  const target = rangeMoved && to.range && to.ticks && to.ticks === from.ticks
+    ? { ...to, ticks: markerValues(to.range, Math.max(2, to.ticks.length) - 1) }
+    : to
+  const blended = blendOf(from) !== undefined
+  const moved = blended || rangeMoved || target.ticks !== from.ticks
+  const auto = blended || from.range === undefined || from.ticks === undefined || target.range === undefined || target.ticks === undefined
+  if (!moved || !auto) return lerpAxisDomain(from, target, t)
+  if (t === 0) return from
+  if (t === 1) return target
+  const blend: AxisDomainBlend = { ...lerpAxisDomain(from, target, t), blend: { from, to: target, t } }
+  return blend
+}
+
+/**
+ * `domain` as the chart draws it: `drawn` resolves a plain domain's auto `range`
+ * and `ticks` off the data, and a blend is the lerp of what its two ends draw.
+ */
+export function settleAxisDomain(domain: AxisDomainConfig, drawn: (domain: AxisDomainConfig) => AxisDomainConfig): AxisDomainConfig {
+  const blend = blendOf(domain)
+  if (!blend) return drawn(domain)
+  return lerpAxisDomain(settleAxisDomain(blend.from, drawn), settleAxisDomain(blend.to, drawn), blend.t)
+}
+
 /**
  * The low-level colour tokens the default themes are built from — a dark plot
  * panel with warm-grey axis furniture.