@motionscript/charts 0.1.0 → 0.1.1-alpha.1

package/src/line-chart/shared.ts

@@ -1,109 +1,38 @@
-/**
- * Types and pure helpers specific to the {@link LineChart} family: the traced
- * polylines, the spotlit region they dim outside of, and the theme those two
- * add to the shared chart vocabulary.
- *
- * Everything a bar or a pie chart would want too — what a series is, how an axis
- * is scaled and formatted, the theme leaf resolvers, the legend and plot-panel
- * branches — lives in `../kit/shared.ts` and is imported here. What's
- * left below is what only a line chart has: points sorted along an x column,
- * a region clipped out of a polyline, and the `region` branch of the theme.
- *
- * Kept renderer-agnostic (no `Node` imports) so every part shares one
- * scale/format/palette/theme vocabulary, and so a host's own inspector
- * mapping can build a partial {@link ChartTheme} without
- * pulling the components in.
- */
+import { Types, type DataRecord, type Vector2 } from "@motionscript/sdk"
 
-import {
-  Fills,
-  fillOps,
-  lerpNumber,
-  strokeOps,
-  type DataRecord,
-  type Fill,
-  type FillResolved,
-  type Stroke,
-  type StrokeResolved,
-} from "@motionscript/sdk"
-
-import {
-  CHART_PALETTE,
-  DEFAULT_LEGEND,
-  DEFAULT_PLOT_AREA,
-  DEFAULT_SERIES_STROKES,
-  DEFAULT_X_AXIS,
-  DEFAULT_Y_AXIS,
-  SPOTLIGHT_DIM,
-  lerpAxisConfig,
-  lerpLegendConfig,
-  lerpPlotArea,
-  lerpSeriesStrokes,
-  niceStep,
-  num,
-  resolveAxisConfig,
-  resolveLegendConfig,
-  resolvePlotArea,
-  resolveSeriesStrokes,
-  type AxisConfig,
-  type ChartSeries,
-  type LegendConfig,
-  type LegendTheme,
-  type PlotAreaConfig,
-  type Range,
-} from "../kit/shared"
+import { niceRange, num, type ChartSeries, type Range } from "../kit/shared"
 import type { XScale } from "./x-scale"
 
-/**
- * One series in a {@link LineChart}: a polyline traced through the values in one
- * column of the chart's `data`, drawn in `fill` (or the theme's `seriesStyles`
- * palette when omitted) and captioned by `label` in the legend.
- *
- * The family-wide {@link ChartSeries} under a name that says what it draws here;
- * the chart's own `xField` prop names the column carrying the shared x values,
- * so every series is read off the same rows — one row per sample, one column per
- * series.
- */
+/** One polyline of a {@link LineChart}: {@link ChartSeries} under the name for what it draws here. */
 export type LineSeries = ChartSeries
 
-// ---- Plot regions -------------------------------------------------------
-
 /**
- * A rectangular slice of the plot, in **data units** — the author-facing input
- * to {@link LineChart.spotlightRegion} / {@link LineChart.zoomTo}.
- *
- * Either axis may be omitted, and that's the point: `{ x: [60, 100] }` is a
- * vertical band spanning the full height, `{ y: [8, 10] }` a horizontal band
- * spanning the full width, and both together a box. A reversed range is read
- * the same as the forward one — a region is a span, not a direction.
+ * A rectangular slice of the plot in data units, the input to `spotlightRegion`
+ * and `zoomTo`. Either axis may be omitted: `{ x: [60, 100] }` is a full-height
+ * band. A reversed range reads the same as a forward one.
  */
 export interface PlotRegion {
-  /** Horizontal span in x-axis data units. Omit to span the full plot width. */
+  /** Omit to span the full plot width. */
   x?: Range
-  /** Vertical span in y-axis data units. Omit to span the full plot height. */
+  /** Omit to span the full plot height. */
   y?: Range
 }
 
 /**
- * A {@link PlotRegion} resolved into the plot's **centred pixel space** (origin
- * at the plot centre, y-up) — the same local frame the series points live in,
- * so a line can be clipped against it directly.
- *
- * `xBounded`/`yBounded` carry which axes the author actually constrained: an
- * unbounded axis has its edges pinned to the plot's own and draws no rule.
+ * A {@link PlotRegion} in the plot's centred pixel space (origin at the centre,
+ * y-up), the frame the series points live in. An axis the author left unbounded
+ * has its edges pinned to the plot's own and draws no rule.
  */
 export interface RegionBox {
   left: number
   right: number
   bottom: number
   top: number
-  /** The author gave an x range — the left/right edges are real data bounds. */
   xBounded: boolean
-  /** The author gave a y range — the bottom/top edges are real data bounds. */
   yBounded: boolean
 }
 
-/** The empty box, used as the "no region" resting value. */
+/** The "no region" resting value. */
 export const EMPTY_REGION_BOX: RegionBox = {
   left: 0,
   right: 0,
@@ -113,19 +42,15 @@ export const EMPTY_REGION_BOX: RegionBox = {
   yBounded: false,
 }
 
-/** Is `box` a real, non-degenerate region — i.e. is there anything to spotlight? */
+/** Whether `box` is non-degenerate, so there is something to spotlight. */
 export function hasRegion(box: RegionBox): boolean {
   return box.right > box.left && box.top > box.bottom
 }
 
 /**
- * Resolve a {@link PlotRegion} against the plot's pixel box and the chart's
- * scales. `plot` is the plot rectangle in centred pixel space, and
- * `xScale`/`yScale` the data ranges those edges span.
- *
- * An omitted axis takes the plot's own edges, so the region spans it. A given
- * axis is clamped to the plot, so a range running off the scale still produces
- * a box inside the panel.
+ * Resolve a {@link PlotRegion} against the plot rectangle (centred pixel space)
+ * and the data ranges its edges span. An omitted axis takes the plot's own
+ * edges; a given one is clamped to the plot.
  */
 export function resolveRegionBox(
   region: PlotRegion | null | undefined,
@@ -159,40 +84,31 @@ export function resolveRegionBox(
   return { left, right, bottom, top, xBounded, yBounded }
 }
 
-/** A bare `{x, y}` — declared locally so this module stays free of node imports. */
-interface Vector2Like {
-  x: number
-  y: number
-}
-
 /**
- * The parts of `points` that fall **inside** `box`, as a list of contiguous
- * sub-polylines — the geometry behind the region spotlight: a series is drawn
- * dimmed in full, then these runs are re-drawn over it at full strength.
- *
- * Segments are clipped against the box rather than filtered by endpoint, so a
- * line entering the region mid-segment is cut exactly on the boundary.
+ * The parts of `points` inside `box`, as contiguous sub-polylines: a series is
+ * drawn dimmed in full, then these runs are re-drawn at full strength. Segments
+ * are clipped, not filtered by endpoint, so a line entering mid-segment is cut
+ * exactly on the boundary.
  */
 export function clipPolylineToBox(
-  points: Vector2Like[],
+  points: Vector2[],
   box: RegionBox
-): Vector2Like[][] {
+): Vector2[][] {
   if (points.length < 2 || !hasRegion(box)) return []
 
-  const runs: Vector2Like[][] = []
-  let run: Vector2Like[] = []
+  const runs: Vector2[][] = []
+  let run: Vector2[] = []
 
   for (let i = 1; i < points.length; i++) {
     const seg = clipSegment(points[i - 1], points[i], box)
     if (!seg) {
-      // Segment misses the box entirely — close whatever run was open.
+      // Misses the box: close the open run.
       if (run.length >= 2) runs.push(run)
       run = []
       continue
     }
     const [a, b] = seg
-    // Continue the open run when this clipped segment starts where the last one
-    // ended; otherwise the line left the box and came back, which is a new run.
+    // Continues the open run if it starts where the last ended; otherwise the line left and came back.
     if (run.length > 0 && samePoint(run[run.length - 1], a)) run.push(b)
     else {
       if (run.length >= 2) runs.push(run)
@@ -204,25 +120,22 @@ export function clipPolylineToBox(
 }
 
 /** Points within half a pixel are the same point, for run-joining purposes. */
-function samePoint(a: Vector2Like, b: Vector2Like): boolean {
+function samePoint(a: Vector2, b: Vector2): boolean {
   return Math.abs(a.x - b.x) < 0.5 && Math.abs(a.y - b.y) < 0.5
 }
 
-/**
- * Liang–Barsky clip of one segment against the axis-aligned `box`. Returns the
- * surviving `[start, end]`, or `null` when the segment lies wholly outside.
- */
+/** Liang-Barsky clip of one segment against `box`: the surviving `[start, end]`, or `null` when wholly outside. */
 function clipSegment(
-  a: Vector2Like,
-  b: Vector2Like,
+  a: Vector2,
+  b: Vector2,
   box: RegionBox
-): [Vector2Like, Vector2Like] | null {
+): [Vector2, Vector2] | null {
   const dx = b.x - a.x
   const dy = b.y - a.y
   let t0 = 0
   let t1 = 1
 
-  // Each edge as (p, q): the segment survives where p·t <= q.
+  // Each edge as (p, q): the segment survives where p*t <= q.
   const edges: [number, number][] = [
     [-dx, a.x - box.left],
     [dx, box.right - a.x],
@@ -231,7 +144,7 @@ function clipSegment(
   ]
   for (const [p, q] of edges) {
     if (p === 0) {
-      // Parallel to this edge: outside it means the whole segment is out.
+      // Parallel to this edge: outside it, the whole segment is out.
       if (q < 0) return null
       continue
     }
@@ -250,170 +163,10 @@ function clipSegment(
   ]
 }
 
-// ---- Theme ---------------------------------------------------------------
-
-/**
- * How a spotlit {@link PlotRegion} is drawn — the dashed rules on its bounded
- * edges, the wash filling it, and how far the series fade outside it.
- */
-export interface RegionConfig {
-  /** The dashed rule marking each bounded edge. */
-  stroke: Stroke
-  /** Wash filling the region, drawn under the series lines. */
-  fill: Fill
-  /** Opacity the stretch of every series *outside* the region fades to. */
-  dimOpacity: number
-}
-
-/** A {@link LineChart}'s full, resolved visual theme. */
-export interface ChartConfig {
-  /**
-   * Default per-series line stroke, cycled by series index (`i % length`). A
-   * series' own `fill`, when set, overrides just the colour.
-   */
-  seriesStyles: Stroke[]
-  xAxis: AxisConfig
-  yAxis: AxisConfig
-  /** The plot panel: border, fill, and drop shadow. */
-  plotArea: PlotAreaConfig
-  legend: LegendConfig
-  /** The spotlit-region annotation — see {@link RegionConfig}. */
-  region: RegionConfig
-}
-
-/**
- * Author-facing partial theme, passed as {@link LineChart}'s `theme` prop —
- * every branch optional and deep-merged onto {@link DEFAULT_CHART_THEME}.
- */
-export type ChartTheme = {
-  seriesStyles?: Stroke[]
-  xAxis?: Partial<AxisConfig>
-  yAxis?: Partial<AxisConfig>
-  plotArea?: Partial<PlotAreaConfig>
-  legend?: LegendTheme
-  region?: Partial<RegionConfig>
-}
-
-/**
- * The legend of a line chart: the shared one, with a small rounded-square
- * swatch in place of the wide chip. A bar's or a wedge's swatch stands in for
- * an area of paint and is drawn like one; a line's stands in for a colour, and
- * a square reads as the sample it is.
- */
-const LINE_CHART_LEGEND: LegendConfig = {
-  ...DEFAULT_LEGEND,
-  markerStyle: {
-    ...DEFAULT_LEGEND.markerStyle,
-    width: 20,
-    height: 20,
-    borderRadius: 6,
-  },
-}
-
-/** The chart's out-of-the-box look. */
-export const DEFAULT_CHART_THEME: ChartConfig = {
-  seriesStyles: DEFAULT_SERIES_STROKES,
-  xAxis: DEFAULT_X_AXIS,
-  yAxis: DEFAULT_Y_AXIS,
-  plotArea: DEFAULT_PLOT_AREA,
-  legend: LINE_CHART_LEGEND,
-  region: {
-    // Brighter than the grid and dashed, so the boundary reads as a call-out
-    // rather than another axis line; `butt` caps keep the dash lengths exact.
-    stroke: {
-      weight: 3,
-      fill: CHART_PALETTE.regionColor,
-      dash: [14, 12],
-      cap: "butt",
-    },
-    // A wash barely above the panel — enough to tint the band, not enough to
-    // mute the series drawn over it.
-    fill: Fills.color(CHART_PALETTE.regionColor, { opacity: 0.08 }),
-    dimOpacity: SPOTLIGHT_DIM,
-  },
-}
-
-function resolveRegionConfig(
-  region: Partial<RegionConfig> | undefined,
-  previous: RegionConfig
-): RegionConfig {
-  return {
-    stroke: strokeOps.resolve(region?.stroke ?? previous.stroke),
-    fill: fillOps.resolve(region?.fill ?? previous.fill),
-    dimOpacity: region?.dimOpacity ?? previous.dimOpacity,
-  }
-}
-
-function lerpRegionConfig(
-  from: RegionConfig,
-  to: RegionConfig,
-  t: number
-): RegionConfig {
-  return {
-    stroke: strokeOps.lerp(
-      from.stroke as StrokeResolved[],
-      to.stroke as StrokeResolved[],
-      t
-    ),
-    fill: fillOps.lerp(
-      from.fill as FillResolved[],
-      to.fill as FillResolved[],
-      t
-    ),
-    dimOpacity: lerpNumber(from.dimOpacity, to.dimOpacity, t),
-  }
-}
-
-/**
- * {@link LineChart}'s `theme` entry's resolve: merges the author's partial
- * {@link ChartTheme} onto `previous` (falling back to
- * {@link DEFAULT_CHART_THEME} on first resolution), fully resolving every leaf.
- */
-export function resolveChartTheme(
-  theme: ChartTheme | undefined,
-  previous?: ChartConfig
-): ChartConfig {
-  const base = previous ?? DEFAULT_CHART_THEME
-  return {
-    seriesStyles: resolveSeriesStrokes(theme?.seriesStyles, base.seriesStyles),
-    xAxis: resolveAxisConfig(theme?.xAxis, base.xAxis),
-    yAxis: resolveAxisConfig(theme?.yAxis, base.yAxis),
-    plotArea: resolvePlotArea(theme?.plotArea, base.plotArea),
-    legend: resolveLegendConfig(theme?.legend, base.legend),
-    region: resolveRegionConfig(theme?.region, base.region),
-  }
-}
-
-/** {@link LineChart}'s `theme` entry's lerp — leaf by leaf. */
-export function lerpChartTheme(
-  from: ChartConfig,
-  to: ChartConfig,
-  t: number
-): ChartConfig {
-  return {
-    seriesStyles: lerpSeriesStrokes(from.seriesStyles, to.seriesStyles, t),
-    xAxis: lerpAxisConfig(from.xAxis, to.xAxis, t),
-    yAxis: lerpAxisConfig(from.yAxis, to.yAxis, t),
-    plotArea: lerpPlotArea(from.plotArea, to.plotArea, t),
-    legend: lerpLegendConfig(from.legend, to.legend, t),
-    region: lerpRegionConfig(from.region, to.region, t),
-  }
-}
-
-// ---- Scales --------------------------------------------------------------
-
 /**
- * Resolve one series' `[x, y]` points out of the chart's rows: each row's
- * position on the {@link XScale} paired with its own `field` column, sorted
- * along x so the polyline traces left-to-right whatever order the rows arrived
- * in.
- *
- * A row missing its y column contributes a 0 rather than a gap — these charts
- * draw continuous lines, so dropping the point would silently bridge the hole.
- *
- * Takes the resolved scale rather than the column *name*, because what a row's x
- * is depends on what kind of column it came out of: a number, an instant, or a
- * place in the file. See `x-scale.ts`.
+ * One series' `[x, y]` points, sorted along x so the polyline traces left to
+ * right. A row missing its y contributes 0 rather than a gap, since dropping it
+ * would silently bridge the hole.
  */
 export function seriesPoints(
   data: DataRecord[],
@@ -425,7 +178,6 @@ export function seriesPoints(
     .sort((a, b) => a[0] - b[0])
 }
 
-/** Min/max across every series' column, the fallback when unset. */
 export function yExtent(data: DataRecord[], series: LineSeries[]): Range {
   let lo = Infinity
   let hi = -Infinity
@@ -439,11 +191,9 @@ export function yExtent(data: DataRecord[], series: LineSeries[]): Range {
 }
 
 /**
- * Effective vertical scale: the explicit `range`, else the data's y extent
- * nudged out to tidy step bounds so markers read as round numbers.
- *
- * `divisions` is how many segments the auto-range is stepped into (one fewer
- * than a marker count) — it only shapes the tidy step when `range` is omitted.
+ * The explicit `range`, else the data's y extent nudged out to tidy step bounds.
+ * `divisions` (one fewer than the marker count) only shapes the step when
+ * `range` is omitted.
  */
 export function resolveYScale(
   data: DataRecord[],
@@ -451,23 +201,198 @@ export function resolveYScale(
   range: Range | undefined,
   divisions: number
 ): Range {
-  if (range) return range
-  const [lo, hi] = yExtent(data, series)
-  const segments = Math.max(1, Math.round(divisions))
-  if (hi === lo) return constantScale(lo, segments)
-  const step = niceStep((hi - lo) / segments)
-  return [Math.floor(lo / step) * step, Math.ceil(hi / step) * step]
+  return range ?? niceRange(yExtent(data, series), divisions)
+}
+
+/** How the series sit on one another: apart, each on the sum of those before it, or as shares of the row's total. */
+export type LineStack = "none" | "stacked" | "percent"
+
+/** One series as drawn: its `[x, y]` points along x, and the line its area fills down to (`null`: the baseline). */
+export interface StackedSeries {
+  readonly points: [x: number, y: number][]
+  readonly base: [x: number, y: number][] | null
 }
 
 /**
- * The scale for data that never moves. A zero-width scale puts every tick on the
- * same value and the line on the plot's floor, so it is widened to a few steps
- * either side of the value (the step sized to its magnitude, so `5` gets
- * `[3, 7]` and `5000` gets `[3000, 7000]`), or to `[0, 1]` for all zeros, as for
- * no data at all.
+ * Every series' points under `stack`, rows in x order. A series contributes its
+ * values times its weight (`1` when missing), so a series sinking out of a stack
+ * lowers the ones above it. `percent` reads each row as shares of its total
+ * magnitude, so the top of a full stack is 100.
  */
-function constantScale(value: number, segments: number): Range {
-  if (value === 0) return [0, 1]
-  const step = niceStep(Math.abs(value) / segments)
-  return [value - step, value + step]
+export function stackSeries(
+  data: DataRecord[],
+  x: XScale,
+  series: readonly LineSeries[],
+  stack: LineStack,
+  weights: readonly number[] = []
+): StackedSeries[] {
+  const order = data.map((_, i) => i).sort((a, b) => x.at(a) - x.at(b))
+  if (stack !== "stacked" && stack !== "percent") {
+    return series.map((s) => ({ points: order.map((r): [number, number] => [x.at(r), num(data[r], s.field)]), base: null }))
+  }
+  const weight = (i: number) => Math.max(0, weights[i] ?? 1)
+  const totals = order.map((r) => series.reduce((sum, s, i) => sum + Math.abs(num(data[r], s.field) * weight(i)), 0))
+  const running = order.map(() => 0)
+  return series.map((s, i) => {
+    const base = order.map((r, k): [number, number] => [x.at(r), running[k]])
+    const points = order.map((r, k): [number, number] => {
+      const value = num(data[r], s.field) * weight(i)
+      running[k] += stack === "percent" ? (totals[k] > 0 ? (value / totals[k]) * 100 : 0) : value
+      return [x.at(r), running[k]]
+    })
+    return { points, base }
+  })
+}
+
+/** The lowest and highest y anything in `stacks` reaches, its bases included. */
+export function stackExtent(stacks: readonly StackedSeries[]): Range {
+  let lo = Infinity
+  let hi = -Infinity
+  for (const { points, base } of stacks)
+    for (const [, y] of [...points, ...(base ?? [])]) {
+      if (y < lo) lo = y
+      if (y > hi) hi = y
+    }
+  return lo <= hi ? [lo, hi] : [0, 1]
+}
+
+/** How a series' line runs between its points. */
+export type LineCurve = "smooth" | "linear" | "step"
+
+/** Points along a cubic Bezier segment, its start left out. */
+const SAMPLES = 16
+
+/**
+ * The drawn path through `points` (ordered along x) as a polyline: the points
+ * themselves for `linear`; for `step`, level runs that change at the midpoint
+ * between neighbours; for `smooth`, a monotone cubic (Fritsch-Carlson, as d3's
+ * `curveMonotoneX`), which never overshoots the data between two points.
+ */
+export function curvePoints(points: readonly Vector2[], curve: LineCurve): Vector2[] {
+  if (curve === "step") {
+    const out: Vector2[] = points.length > 0 ? [points[0]] : []
+    for (let i = 1; i < points.length; i++) {
+      const mid = (points[i - 1].x + points[i].x) / 2
+      out.push({ x: mid, y: points[i - 1].y }, { x: mid, y: points[i].y }, points[i])
+    }
+    return out
+  }
+  if (curve !== "smooth" || points.length < 3) return [...points]
+  const tangents = monotoneTangents(points)
+  const out: Vector2[] = [points[0]]
+  for (let i = 1; i < points.length; i++) {
+    const a = points[i - 1]
+    const b = points[i]
+    const dx = (b.x - a.x) / 3
+    const c1 = { x: a.x + dx, y: a.y + dx * tangents[i - 1] }
+    const c2 = { x: b.x - dx, y: b.y - dx * tangents[i] }
+    for (let k = 1; k <= SAMPLES; k++) {
+      const t = k / SAMPLES
+      const u = 1 - t
+      out.push({
+        x: u * u * u * a.x + 3 * u * u * t * c1.x + 3 * u * t * t * c2.x + t * t * t * b.x,
+        y: u * u * u * a.y + 3 * u * u * t * c1.y + 3 * u * t * t * c2.y + t * t * t * b.y,
+      })
+    }
+  }
+  return out
+}
+
+function monotoneTangents(points: readonly Vector2[]): number[] {
+  const n = points.length
+  const slope = (i: number) => {
+    const h = points[i + 1].x - points[i].x
+    return h === 0 ? 0 : (points[i + 1].y - points[i].y) / h
+  }
+  const m = new Array<number>(n).fill(0)
+  for (let i = 1; i < n - 1; i++) {
+    const h0 = points[i].x - points[i - 1].x
+    const h1 = points[i + 1].x - points[i].x
+    const s0 = slope(i - 1)
+    const s1 = slope(i)
+    const p = h0 + h1 === 0 ? 0 : (s0 * h1 + s1 * h0) / (h0 + h1)
+    m[i] = (Math.sign(s0) + Math.sign(s1)) * Math.min(Math.abs(s0), Math.abs(s1), 0.5 * Math.abs(p)) || 0
+  }
+  m[0] = endTangent(slope(0), m[1])
+  m[n - 1] = endTangent(slope(n - 2), m[n - 2])
+  return m
+}
+
+/** d3's one-sided end tangent, held to the end segment's own direction and to three times its slope, past which it would overshoot. */
+function endTangent(secant: number, inner: number): number {
+  const t = (3 * secant - inner) / 2
+  if (secant === 0 || Math.sign(t) !== Math.sign(secant)) return 0
+  return Math.abs(t) > 3 * Math.abs(secant) ? 3 * secant : t
+}
+
+/** The part of `points` (ordered along x) left of `x`, ending on the point where it crosses `x`. */
+export function cutAt(points: readonly Vector2[], x: number): Vector2[] {
+  if (points.length === 0 || x < points[0].x) return []
+  const out: Vector2[] = []
+  for (let i = 0; i < points.length; i++) {
+    const p = points[i]
+    if (p.x <= x) {
+      out.push(p)
+      continue
+    }
+    const a = points[i - 1]
+    if (a && p.x > a.x) out.push({ x, y: a.y + ((p.y - a.y) * (x - a.x)) / (p.x - a.x) })
+    break
+  }
+  return out
+}
+
+/**
+ * `polygon` clipped to `box` (Sutherland-Hodgman against each edge in turn).
+ * The box is convex, so the result is the part inside, possibly with seams of
+ * no width where a concave outline leaves and re-enters, which fill as nothing.
+ */
+export function clipPolygonToBox(polygon: readonly Vector2[], box: RegionBox): Vector2[] {
+  if (polygon.length < 3 || !hasRegion(box)) return []
+  const edges: ((p: Vector2) => number)[] = [
+    (p) => p.x - box.left,
+    (p) => box.right - p.x,
+    (p) => p.y - box.bottom,
+    (p) => box.top - p.y,
+  ]
+  let out: Vector2[] = [...polygon]
+  for (const inside of edges) {
+    const input = out
+    out = []
+    for (let i = 0; i < input.length; i++) {
+      const cur = input[i]
+      const prev = input[(i + input.length - 1) % input.length]
+      const dc = inside(cur)
+      const dp = inside(prev)
+      if (dc >= 0) {
+        if (dp < 0) out.push(crossing(prev, cur, dp, dc))
+        out.push(cur)
+      } else if (dp >= 0) out.push(crossing(prev, cur, dp, dc))
+    }
+    if (out.length === 0) return []
+  }
+  return out
+}
+
+function crossing(a: Vector2, b: Vector2, da: number, db: number): Vector2 {
+  const t = da / (da - db)
+  return { x: a.x + (b.x - a.x) * t, y: a.y + (b.y - a.y) * t }
+}
+
+/** A line chart's own look: how each series is stroked, dotted and filled. */
+export const LINE_MARKS = {
+  strokeWidth: Types.number(4, { min: 0, max: 24, step: 0.5, unit: "px" }),
+  curve: Types.oneOf(["smooth", "linear", "step"] as const),
+  dots: Types.boolean(false),
+  /** Each dot's diameter. */
+  dotSize: Types.number(12, { min: 0, max: 48, step: 1, unit: "px" }),
+  /** Fill under each line: none, the series colour, or the colour fading to nothing at the baseline. */
+  area: Types.oneOf(["none", "solid", "gradient"] as const),
+  /** The fill's opacity at the line. */
+  areaOpacity: Types.number(0.4, { min: 0, max: 1, step: 0.05 }),
+}
+
+export const LINE_LABELS = {
+  /** Read as the chart is built: each point's value printed above or below it, or none. */
+  values: Types.oneOf(["none", "above", "below"] as const, { animatable: false }),
 }