@fundar/data-chart-telling 0.0.63 → 1.0.0

package/dist/layout/scales/niceDomain.js

@@ -1,6 +1,6 @@
 // d3-array-compatible "nice" tick step/generation, reimplemented locally to
 // avoid depending on internals svelteplot itself pulls in (not one of our
-// declared dependencies) — see https://d3js.org/d3-array/ticks.
+// declared dependencies) - see https://d3js.org/d3-array/ticks.
 /** Step between "nice" (1/2/5×10ⁿ) tick values for an approximate `count` over `[start, stop]`. */
 export function tickStep(start, stop, count) {
     const e10 = Math.sqrt(50);
@@ -28,12 +28,12 @@ export function ticksInRange(start, stop, step) {
         out.push(i * step);
     return out;
 }
-/** Ticks-per-axis heuristic — used by `ScalesLayout` to pick a target count from an axis's actual pixel span. */
+/** Ticks-per-axis heuristic - used by `ScalesLayout` to pick a target count from an axis's actual pixel span. */
 export function naturalTickCount(span, spacing, min) {
     return Math.max(min, Math.round(span / spacing));
 }
 /**
- * Widens `[lo, hi]` outward to the nearest `count`-ish "nice" step —
+ * Widens `[lo, hi]` outward to the nearest `count`-ish "nice" step -
  * equivalent to d3's own `scale.nice(count)`, except a value within
  * `epsilonFraction × step` of a step boundary is treated as already sitting
  * on it, rather than needing a full extra step to clear it.
@@ -45,7 +45,7 @@ export function naturalTickCount(span, spacing, min) {
  * to a whole" data, e.g. percentages of a total) still fails `hi <= step*N`
  * and gets rounded up a full step further than the data actually warrants
  * (`100` → `110`, not just a hair past `100`). `epsilonFraction` defaults to
- * 1% of the step — small enough to only catch rounding/summation noise, not
+ * 1% of the step - small enough to only catch rounding/summation noise, not
  * data that's genuinely meaningfully past the boundary.
  */
 export function niceDomain(lo, hi, count = 5, epsilonFraction = 0.01) {

package/dist/layout/styles/StylesLayout.svelte

@@ -1,75 +1,75 @@
 <script lang="ts">
-  import { Frame } from 'svelteplot';
-  import TileLayer from './TileLayer.svelte';
-  import { geometryLonLatBounds } from '../../plots/utils/geoAccessors';
-  import type { StylesLayoutConfig } from '../../types/layout/styles';
+	import { Frame } from 'svelteplot';
+	import TileLayer from './TileLayer.svelte';
+	import { geometryLonLatBounds } from '../../plots/utils/geoAccessors';
+	import type { StylesLayoutConfig } from '../../types/layout/styles';
 
-  /**
-   * Non-data cosmetic embellishments driven by a plot kind's own `styles`
-   * prop. Composed by `BasePlotLayout` for every plot kind, nested inside
-   * `CoordinatesLayout` so embellishments pan/zoom together with whatever
-   * they're placed alongside: the raster basemap `tileLayer` (`GeoPlot`
-   * only — other kinds' `styles` simply don't declare it) and the `frame`
-   * border, available on every plot kind.
-   */
-  let {
-    styles,
-    width,
-    height,
-    numericMargins,
-  }: {
-    styles?: StylesLayoutConfig;
-    width: number;
-    height: number;
-    numericMargins: { top: number; right: number; bottom: number; left: number };
-  } = $props();
+	/**
+	 * Non-data cosmetic embellishments driven by a plot kind's own `styles`
+	 * prop. Composed by `BasePlotLayout` for every plot kind, nested inside
+	 * `CoordinatesLayout` so embellishments pan/zoom together with whatever
+	 * they're placed alongside: the raster basemap `tileLayer` (`GeoPlot`
+	 * only - other kinds' `styles` simply don't declare it) and the `frame`
+	 * border, available on every plot kind.
+	 */
+	let {
+		styles,
+		width,
+		height,
+		numericMargins
+	}: {
+		styles?: StylesLayoutConfig;
+		width: number;
+		height: number;
+		numericMargins: { top: number; right: number; bottom: number; left: number };
+	} = $props();
 
-  const frame = $derived(styles?.frame);
-  const frameStyle = $derived(typeof frame === 'object' ? frame : undefined);
+	const frame = $derived(styles?.frame);
+	const frameStyle = $derived(typeof frame === 'object' ? frame : undefined);
 
-  /** Auto-fits `TileLayer` to the tile-layer feature set `GeoPlot` tacks onto `styles.tileLayer.features` — see `StylesLayoutConfig`'s own doc comment. */
-  const dataLonLatBounds = $derived.by((): [number, number, number, number] | null => {
-    const features = styles?.tileLayer?.features;
-    if (!features?.length) return null;
-    let minLon = Infinity;
-    let maxLon = -Infinity;
-    let minLat = Infinity;
-    let maxLat = -Infinity;
-    for (const f of features) {
-      const b = geometryLonLatBounds(f.geometry);
-      if (!b) continue;
-      if (b[0] < minLon) minLon = b[0];
-      if (b[2] > maxLon) maxLon = b[2];
-      if (b[1] < minLat) minLat = b[1];
-      if (b[3] > maxLat) maxLat = b[3];
-    }
-    return minLon === Infinity ? null : [minLon, minLat, maxLon, maxLat];
-  });
+	/** Auto-fits `TileLayer` to the tile-layer feature set `GeoPlot` tacks onto `styles.tileLayer.features` - see `StylesLayoutConfig`'s own doc comment. */
+	const dataLonLatBounds = $derived.by((): [number, number, number, number] | null => {
+		const features = styles?.tileLayer?.features;
+		if (!features?.length) return null;
+		let minLon = Infinity;
+		let maxLon = -Infinity;
+		let minLat = Infinity;
+		let maxLat = -Infinity;
+		for (const f of features) {
+			const b = geometryLonLatBounds(f.geometry);
+			if (!b) continue;
+			if (b[0] < minLon) minLon = b[0];
+			if (b[2] > maxLon) maxLon = b[2];
+			if (b[1] < minLat) minLat = b[1];
+			if (b[3] > maxLat) maxLat = b[3];
+		}
+		return minLon === Infinity ? null : [minLon, minLat, maxLon, maxLat];
+	});
 </script>
 
 {#if styles?.tileLayer}
-  <TileLayer
-    config={styles.tileLayer}
-    left={numericMargins.left}
-    top={numericMargins.top}
-    width={Math.max(0, width - numericMargins.left - numericMargins.right)}
-    height={Math.max(0, height - numericMargins.top - numericMargins.bottom)}
-    {dataLonLatBounds}
-  />
+	<TileLayer
+		config={styles.tileLayer}
+		left={numericMargins.left}
+		top={numericMargins.top}
+		width={Math.max(0, width - numericMargins.left - numericMargins.right)}
+		height={Math.max(0, height - numericMargins.top - numericMargins.bottom)}
+		{dataLonLatBounds}
+	/>
 {/if}
 {#if frame}
-  <Frame
-    fill={frameStyle?.fill}
-    fillOpacity={frameStyle?.fillOpacity}
-    stroke={frameStyle?.stroke}
-    strokeWidth={frameStyle?.strokeWidth}
-    strokeOpacity={frameStyle?.strokeOpacity}
-    strokeDasharray={frameStyle?.strokeDasharray}
-    borderRadius={frameStyle?.borderRadius}
-    inset={frameStyle?.inset}
-    insetTop={frameStyle?.insetTop}
-    insetRight={frameStyle?.insetRight}
-    insetBottom={frameStyle?.insetBottom}
-    insetLeft={frameStyle?.insetLeft}
-  />
+	<Frame
+		fill={frameStyle?.fill}
+		fillOpacity={frameStyle?.fillOpacity}
+		stroke={frameStyle?.stroke}
+		strokeWidth={frameStyle?.strokeWidth}
+		strokeOpacity={frameStyle?.strokeOpacity}
+		strokeDasharray={frameStyle?.strokeDasharray}
+		borderRadius={frameStyle?.borderRadius}
+		inset={frameStyle?.inset}
+		insetTop={frameStyle?.insetTop}
+		insetRight={frameStyle?.insetRight}
+		insetBottom={frameStyle?.insetBottom}
+		insetLeft={frameStyle?.insetLeft}
+	/>
 {/if}

package/dist/layout/styles/TileLayer.svelte

@@ -1,87 +1,89 @@
 <script lang="ts">
-  import { usePlot } from 'svelteplot';
-  import {
-    visibleTiles,
-    buildMercatorFit,
-    tileScreenBounds,
-    tileUrl,
-    toProjectionLike,
-    type StreamingProjection,
-  } from '../../plots/utils/tiles';
-  import type { GeoTileLayerConfig } from '../../types/layout/styles';
+	import { usePlot } from '../plot/usePlot';
+	import {
+		visibleTiles,
+		buildMercatorFit,
+		tileScreenBounds,
+		tileUrl,
+		toProjectionLike,
+		type StreamingProjection
+	} from '../../plots/utils/tiles';
+	import type { GeoTileLayerConfig } from '../../types/layout/styles';
 
-  /**
-   * Renders an XYZ raster tile basemap under the vector geometry. Mounted as
-   * a child of svelteplot's `<Plot>` so `usePlot()` resolves its already-fit
-   * projection — this module never depends on `d3-geo` directly.
-   *
-   * v1 limitation: the visible tile grid is computed once for the initial
-   * view, not re-fetched as the pan/zoom `<g>` transform changes — tiles pan
-   * and scale visually with the map, but don't reveal new coverage when
-   * panned far, and pixelate past their native resolution when zoomed in.
-   */
-  let {
-    config,
-    left,
-    top,
-    width,
-    height,
-    dataLonLatBounds,
-  }: {
-    config: GeoTileLayerConfig;
-    left: number;
-    top: number;
-    width: number;
-    height: number;
-    /** Forwarded to `visibleTiles`/`buildMercatorFit` — see `Plot.svelte`'s `dataLonLatBounds`. */
-    dataLonLatBounds?: [number, number, number, number] | null;
-  } = $props();
+	/**
+	 * Renders an XYZ raster tile basemap under the vector geometry. Mounted as
+	 * a child of svelteplot's `<Plot>` so `usePlot()` resolves its already-fit
+	 * projection - this module never depends on `d3-geo` directly.
+	 *
+	 * v1 limitation: the visible tile grid is computed once for the initial
+	 * view, not re-fetched as the pan/zoom `<g>` transform changes - tiles pan
+	 * and scale visually with the map, but don't reveal new coverage when
+	 * panned far, and pixelate past their native resolution when zoomed in.
+	 */
+	let {
+		config,
+		left,
+		top,
+		width,
+		height,
+		dataLonLatBounds
+	}: {
+		config: GeoTileLayerConfig;
+		left: number;
+		top: number;
+		width: number;
+		height: number;
+		/** Forwarded to `visibleTiles`/`buildMercatorFit` - see `Plot.svelte`'s `dataLonLatBounds`. */
+		dataLonLatBounds?: [number, number, number, number] | null;
+	} = $props();
 
-  const plot = usePlot();
+	const plot = usePlot().svelteplot;
 
-  const tileSize = $derived(config.tileSize ?? 256);
+	const tileSize = $derived(config.tileSize ?? 256);
 
-  // svelteplot's own `PlotScale` type doesn't reflect this, but at runtime
-  // `scales.projection` is `createProjection()`'s `{ stream, invert }`
-  // result (verified against svelteplot's own `helpers/projection.js`).
-  const rawProjection = $derived(plot.scales.projection as unknown as StreamingProjection | undefined);
-  const projection = $derived(rawProjection ? toProjectionLike(rawProjection) : undefined);
+	// svelteplot's own `PlotScale` type doesn't reflect this, but at runtime
+	// `scales.projection` is `createProjection()`'s `{ stream, invert }`
+	// result (verified against svelteplot's own `helpers/projection.js`).
+	const rawProjection = $derived(
+		plot.scales.projection as unknown as StreamingProjection | undefined
+	);
+	const projection = $derived(rawProjection ? toProjectionLike(rawProjection) : undefined);
 
-  const tiles = $derived.by(() => {
-    if (!projection) return [];
-    return visibleTiles(
-      projection,
-      { left, top, width, height },
-      tileSize,
-      config.minZoom ?? 0,
-      config.maxZoom ?? 19,
-      dataLonLatBounds,
-    );
-  });
+	const tiles = $derived.by(() => {
+		if (!projection) return [];
+		return visibleTiles(
+			projection,
+			{ left, top, width, height },
+			tileSize,
+			config.minZoom ?? 0,
+			config.maxZoom ?? 19,
+			dataLonLatBounds
+		);
+	});
 
-  // One affine fit per zoom level, shared across every tile in `tiles` — see
-  // `buildMercatorFit`'s doc comment for why this replaces forward-projecting
-  // each tile's own corners individually.
-  const fit = $derived.by(() => {
-    if (!projection || tiles.length === 0) return null;
-    return buildMercatorFit(projection, { left, top, width, height }, tiles[0].z, dataLonLatBounds);
-  });
+	// One affine fit per zoom level, shared across every tile in `tiles` - see
+	// `buildMercatorFit`'s doc comment for why this replaces forward-projecting
+	// each tile's own corners individually.
+	const fit = $derived.by(() => {
+		if (!projection || tiles.length === 0) return null;
+		return buildMercatorFit(projection, { left, top, width, height }, tiles[0].z, dataLonLatBounds);
+	});
 </script>
 
 {#if projection && fit}
-  <g class="dct-geo-tiles" opacity={config.opacity ?? 1}>
-    {#each tiles as tile (`${tile.z}/${tile.x}/${tile.y}`)}
-      {@const bounds = tileScreenBounds(fit, tile)}
-      {#if bounds}
-        <image
-          href={tileUrl(config.url, tile)}
-          x={bounds.left}
-          y={bounds.top}
-          width={bounds.width}
-          height={bounds.height}
-          preserveAspectRatio="none"
-        />
-      {/if}
-    {/each}
-  </g>
+	<g class="dct-geo-tiles" opacity={config.opacity ?? 1}>
+		{#each tiles as tile (`${tile.z}/${tile.x}/${tile.y}`)}
+			{@const bounds = tileScreenBounds(fit, tile)}
+			{#if bounds}
+				<image
+					href={tileUrl(config.url, tile)}
+					x={bounds.left}
+					y={bounds.top}
+					width={bounds.width}
+					height={bounds.height}
+					preserveAspectRatio="none"
+				/>
+			{/if}
+		{/each}
+	</g>
 {/if}

package/dist/layout/styles/TileLayer.svelte.d.ts

@@ -5,7 +5,7 @@ type $$ComponentProps = {
     top: number;
     width: number;
     height: number;
-    /** Forwarded to `visibleTiles`/`buildMercatorFit` — see `Plot.svelte`'s `dataLonLatBounds`. */
+    /** Forwarded to `visibleTiles`/`buildMercatorFit` - see `Plot.svelte`'s `dataLonLatBounds`. */
     dataLonLatBounds?: [number, number, number, number] | null;
 };
 declare const TileLayer: import("svelte").Component<$$ComponentProps, {}, "">;

package/dist/layout/styles/ValueLabels.d.ts

@@ -0,0 +1,97 @@
+import { Box } from '../margins/Box';
+import { PlotAxes } from '../../phases/data/PlotAxes';
+import type { PlotStylesConfig } from '../../types/configuration/styling';
+import type { ValuesStyle } from '../../types/layout/styles';
+import type { ValueLabelsOptions } from '../../types/phases/styles/phase';
+import type { Series } from '../../types/plots/data/common';
+import type { FontStyle, StrokeStyle } from '../../types/plots/styling';
+import type { TextAnchor, ValueAnchor } from '../../types/plots/constants';
+import type { BoxAnchors, EdgeBox } from '../../types/layout/box';
+import type { MarginSide } from '../../types/plots/props';
+import type { AxisPlotCtx, AxisPlotState, ProcessedRow } from '../../types/phases';
+import type { TextMarkerConfig } from '../../types/markers/common';
+/**
+ * A plot's value labels: the author's `styles.values` over the plot kind's
+ * own defaults, how their text measures, where they are expected to sit
+ * (`reach`, which the plot's margins keep room for), and what every label marker shares
+ * ({@link hooks}). The "markers" phase draws them.
+ */
+export declare class ValueLabels {
+    #private;
+    readonly show: boolean;
+    readonly anchor: ValueAnchor;
+    readonly format: (value: number, seriesName: string) => string;
+    readonly hoverIsolate: boolean;
+    readonly font: FontStyle | undefined;
+    readonly fontSize: number;
+    /** The connectors of labels that had to move apart. */
+    readonly strokeStyle: StrokeStyle | undefined;
+    /** How labels that would overlap move apart - the configuration's `text.declutter`. */
+    readonly declutter: PlotStylesConfig['text']['declutter'];
+    /** Where the labels are expected to sit: boxes around their points, on the edges those can reach. */
+    readonly reach: EdgeBox[];
+    constructor(values: ValuesStyle | undefined, cfg: PlotStylesConfig, options?: Omit<ValueLabelsOptions<never>, 'reach'>, reach?: (labels: ValueLabels) => EdgeBox[]);
+    /** A plot's value labels: `values` over `options`, the kind's own defaults, their reach read off `state`. */
+    static build<TState>(values: ValuesStyle | undefined, cfg: PlotStylesConfig, options: ValueLabelsOptions<TState>, state: TState): ValueLabels;
+    /** One line of label text's height. */
+    get lineHeight(): number;
+    /** The box one label's `text` takes. */
+    textBox(text: string): Box;
+    /** The labels' gap (px) from their mark along `axis`: their own `dx`/`dy`, else `fallback`. */
+    offset(axis: 'x' | 'y', fallback?: number): number;
+    /**
+     * Where a label reading `text` sits around its point: anchored `at` that
+     * offset from it (its `dx`/`dy`), on `side` of that anchor per axis - the
+     * way its `textAnchor`/`lineAnchor` set it - with the plot `edges` the
+     * point can sit on.
+     */
+    edgeBox(text: string, side: BoxAnchors, at: {
+        x?: number;
+        y?: number;
+    }, edges: MarginSide[]): EdgeBox;
+    /** Each series' value farthest from zero, read on `valueAxis` - the widest label it can show. */
+    extremes<S extends Series<any>>(series: S[], valueAxis?: 'x' | 'y'): {
+        series: S;
+        value: number;
+    }[];
+    /**
+     * The author's own `textAnchor`, if any. `'outside'` is a hover marker's
+     * per-point anchor; a label's own `anchor` already places it, so here it
+     * counts as unset.
+     */
+    get textAnchor(): Exclude<TextAnchor, 'outside'> | undefined;
+    /**
+     * What every label marker shares: the plot's margins grow to fit it, it
+     * dims with its row's series, and with `hoverIsolate`, hovering it
+     * isolates that series. A row without a series gets the margins only.
+     */
+    hooks(ctx: AxisPlotCtx): Pick<TextMarkerConfig, 'fillOpacity' | 'fitMargins' | 'onPointerEnter' | 'onPointerLeave'>;
+    /**
+     * A processed row's own value, read through its series' own value channel
+     * (`y`, or `x` on a horizontal plot) - what a label shows, even where a
+     * transform moved the row (a stacked row's top is the running total, not
+     * its own value).
+     */
+    static valueOf<TData extends Record<string, unknown>>(state: {
+        resolvedSeries?: Series<TData>[];
+        axes?: PlotAxes;
+    }): (d: ProcessedRow) => unknown;
+    /**
+     * A series-over-`x` plot's (line, area) labels: one `'text'` marker over
+     * the processed rows, each visible series' last row with a value
+     * (`filter` + `selectLast`, per series), at its top (a stacked row's
+     * `y2`), labelled with its own value and placed by `anchor`. Labels that
+     * would overlap fan out into a shared column (`declutter`), colored by the
+     * segment the row falls in.
+     */
+    atSeriesEnds<TData extends Record<string, unknown>>(state: AxisPlotState<TData, object>): TextMarkerConfig[];
+    /**
+     * Where {@link atSeriesEnds}' labels are expected to sit: past each
+     * series' last point, at the right edge (or the left, for labels set
+     * before their point; both for a fan of several series, which can flip),
+     * reaching up or down from the top or bottom edge. Read off the `y`
+     * domain when the scales set one, so it holds across a timeline; else off
+     * every value.
+     */
+    reachAtSeriesEnds<TData extends Record<string, unknown>>(state: AxisPlotState<TData, object>): EdgeBox[];
+}