@fundar/data-chart-telling 1.18.0 → 1.19.0

package/dist/markers/MarkerKinds.d.ts

@@ -1,4 +1,4 @@
-import type { MarkerTraits } from '../types/markers/traits';
+import type { InheritedChannel, MarkerTraits } from '../types/markers/traits';
 /**
  * Every marker kind's traits, in one row each. Typed over every kind, so a
  * new kind can't be added without declaring all of its traits here.
@@ -6,9 +6,16 @@ import type { MarkerTraits } from '../types/markers/traits';
 export declare class MarkerKinds {
     static readonly traits: {
         area: {
+            oriented: true;
+            inherits: ("grouping" | "x" | "y" | "color" | "opacity")[];
             clip: true;
             drawsRows: true;
             legendSymbol: "area";
+            labels: {
+                default: "point";
+                path: "area";
+                point: "top";
+            };
         };
         arrow: {
             clip: false;
@@ -20,11 +27,21 @@ export declare class MarkerKinds {
             legendSymbol: "rect";
         };
         bar: {
+            oriented: true;
+            inherits: ("x" | "y" | "color")[];
             clip: true;
             drawsRows: true;
             legendSymbol: "bar";
+            labels: {
+                default: "box";
+                box: "band";
+                path: "box";
+                point: "box";
+            };
         };
         bollinger: {
+            oriented: true;
+            inherits: ("x" | "y")[];
             clip: true;
             drawsRows: true;
             legendSymbol: "line";
@@ -34,14 +51,23 @@ export declare class MarkerKinds {
             drawsRows: false;
         };
         box: {
+            oriented: true;
+            inherits: ("x" | "y")[];
             clip: true;
             drawsRows: true;
             legendSymbol: "bar";
         };
         cell: {
+            inherits: ("x" | "y" | "color" | "opacity")[];
             clip: true;
             drawsRows: true;
             legendSymbol: "cell";
+            labels: {
+                default: "box";
+                box: "cell";
+                path: "box";
+                point: "box";
+            };
         };
         component: {
             clip: false;
@@ -52,10 +78,12 @@ export declare class MarkerKinds {
             drawsRows: false;
         };
         delaunayLink: {
+            inherits: ("grouping" | "x" | "y" | "color")[];
             clip: true;
             drawsRows: true;
         };
         delaunayMesh: {
+            inherits: ("grouping" | "x" | "y" | "color")[];
             clip: true;
             drawsRows: true;
         };
@@ -64,19 +92,27 @@ export declare class MarkerKinds {
             drawsRows: false;
         };
         density: {
+            inherits: ("grouping" | "x" | "y" | "color")[];
             clip: true;
             drawsRows: true;
             legendSymbol: "area";
         };
         difference: {
+            inherits: ("x" | "y")[];
             clip: true;
             drawsRows: true;
             legendSymbol: "area";
         };
         dot: {
+            inherits: ("symbol" | "x" | "y" | "color" | "opacity" | "r")[];
             clip: false;
             drawsRows: true;
             legendSymbol: "dot";
+            labels: {
+                default: "point";
+                path: "rim";
+                point: "dot";
+            };
         };
         geo: {
             clip: false;
@@ -99,11 +135,13 @@ export declare class MarkerKinds {
             drawsRows: false;
         };
         hull: {
+            inherits: ("grouping" | "x" | "y" | "color")[];
             clip: true;
             drawsRows: true;
             legendSymbol: "area";
         };
         image: {
+            inherits: ("x" | "y")[];
             clip: false;
             drawsRows: true;
         };
@@ -112,9 +150,15 @@ export declare class MarkerKinds {
             drawsRows: false;
         };
         line: {
+            inherits: ("grouping" | "x" | "y" | "color")[];
             clip: true;
             drawsRows: true;
             legendSymbol: "line";
+            labels: {
+                default: "point";
+                path: "stroke";
+                point: "row";
+            };
         };
         link: {
             clip: false;
@@ -125,11 +169,20 @@ export declare class MarkerKinds {
             drawsRows: true;
         };
         rect: {
+            inherits: ("x" | "y" | "color" | "opacity")[];
             clip: true;
             drawsRows: true;
             legendSymbol: "rect";
+            labels: {
+                default: "box";
+                box: "edges";
+                path: "box";
+                point: "box";
+            };
         };
         regression: {
+            oriented: true;
+            inherits: ("x" | "y")[];
             clip: true;
             drawsRows: true;
             legendSymbol: "line";
@@ -144,40 +197,65 @@ export declare class MarkerKinds {
             drawsRows: false;
         };
         text: {
+            inherits: ("x" | "y")[];
             clip: false;
             drawsRows: true;
         };
         tick: {
+            oriented: true;
+            inherits: "color"[];
             clip: true;
             drawsRows: true;
         };
         trail: {
+            inherits: ("grouping" | "x" | "y" | "color" | "opacity" | "r")[];
             clip: true;
             drawsRows: true;
             legendSymbol: "line";
+            labels: {
+                default: "point";
+                path: "stroke";
+                point: "row";
+            };
         };
         vector: {
+            inherits: "length"[];
             clip: false;
             drawsRows: false;
         };
         violin: {
+            oriented: true;
+            inherits: ("x" | "y")[];
             clip: true;
             drawsRows: true;
             legendSymbol: "area";
         };
         voronoi: {
+            inherits: ("grouping" | "x" | "y" | "color")[];
             clip: true;
             drawsRows: true;
         };
         voronoiMesh: {
+            inherits: ("grouping" | "x" | "y" | "color")[];
             clip: true;
             drawsRows: true;
         };
         waffle: {
+            oriented: true;
+            inherits: ("x" | "y" | "color")[];
             clip: true;
             drawsRows: true;
+            labels: {
+                default: "box";
+                box: "band";
+                path: "box";
+                point: "box";
+            };
         };
     };
     /** The traits of a marker kind, or `undefined` for a type no kind declares. */
     static of(type: string | undefined): MarkerTraits | undefined;
+    static inherits(type: string | undefined, channel: InheritedChannel): boolean;
+    /** Whether the kind takes the plot's scales: it inherits a channel that has one. */
+    static inheritsScales(type: string | undefined): boolean;
 }

package/dist/markers/MarkerKinds.js

@@ -1,48 +1,167 @@
+const SCALED = ['color', 'opacity', 'symbol', 'r', 'length'];
 /**
  * Every marker kind's traits, in one row each. Typed over every kind, so a
  * new kind can't be added without declaring all of its traits here.
  */
 export class MarkerKinds {
     static traits = {
-        area: { clip: true, drawsRows: true, legendSymbol: 'area' },
+        area: {
+            oriented: true,
+            inherits: ['x', 'y', 'grouping', 'color', 'opacity'],
+            clip: true,
+            drawsRows: true,
+            legendSymbol: 'area',
+            labels: { default: 'point', path: 'area', point: 'top' }
+        },
         arrow: { clip: false, drawsRows: true },
         band: { clip: true, drawsRows: false, legendSymbol: 'rect' },
-        bar: { clip: true, drawsRows: true, legendSymbol: 'bar' },
-        bollinger: { clip: true, drawsRows: true, legendSymbol: 'line' },
+        bar: {
+            oriented: true,
+            inherits: ['x', 'y', 'color'],
+            clip: true,
+            drawsRows: true,
+            legendSymbol: 'bar',
+            labels: { default: 'box', box: 'band', path: 'box', point: 'box' }
+        },
+        bollinger: {
+            oriented: true,
+            inherits: ['x', 'y'],
+            clip: true,
+            drawsRows: true,
+            legendSymbol: 'line'
+        },
         brush: { clip: false, drawsRows: false },
-        box: { clip: true, drawsRows: true, legendSymbol: 'bar' },
-        cell: { clip: true, drawsRows: true, legendSymbol: 'cell' },
+        box: {
+            oriented: true,
+            inherits: ['x', 'y'],
+            clip: true,
+            drawsRows: true,
+            legendSymbol: 'bar'
+        },
+        cell: {
+            inherits: ['x', 'y', 'color', 'opacity'],
+            clip: true,
+            drawsRows: true,
+            legendSymbol: 'cell',
+            labels: { default: 'box', box: 'cell', path: 'box', point: 'box' }
+        },
         component: { clip: false, drawsRows: false },
         contour: { clip: false, drawsRows: false },
-        delaunayLink: { clip: true, drawsRows: true },
-        delaunayMesh: { clip: true, drawsRows: true },
+        delaunayLink: {
+            inherits: ['x', 'y', 'grouping', 'color'],
+            clip: true,
+            drawsRows: true
+        },
+        delaunayMesh: {
+            inherits: ['x', 'y', 'grouping', 'color'],
+            clip: true,
+            drawsRows: true
+        },
         delta: { clip: false, drawsRows: false },
-        density: { clip: true, drawsRows: true, legendSymbol: 'area' },
-        difference: { clip: true, drawsRows: true, legendSymbol: 'area' },
-        dot: { clip: false, drawsRows: true, legendSymbol: 'dot' },
+        density: {
+            inherits: ['x', 'y', 'grouping', 'color'],
+            clip: true,
+            drawsRows: true,
+            legendSymbol: 'area'
+        },
+        difference: {
+            inherits: ['x', 'y'],
+            clip: true,
+            drawsRows: true,
+            legendSymbol: 'area'
+        },
+        dot: {
+            inherits: ['x', 'y', 'color', 'opacity', 'symbol', 'r'],
+            clip: false,
+            drawsRows: true,
+            legendSymbol: 'dot',
+            labels: { default: 'point', path: 'rim', point: 'dot' }
+        },
         geo: { clip: false, drawsRows: false },
         'geo-component': { clip: false, drawsRows: true },
         'geo-hover': { clip: false, drawsRows: false },
         graticule: { clip: false, drawsRows: false },
         hover: { clip: false, drawsRows: false },
-        hull: { clip: true, drawsRows: true, legendSymbol: 'area' },
-        image: { clip: false, drawsRows: true },
+        hull: {
+            inherits: ['x', 'y', 'grouping', 'color'],
+            clip: true,
+            drawsRows: true,
+            legendSymbol: 'area'
+        },
+        image: {
+            inherits: ['x', 'y'],
+            clip: false,
+            drawsRows: true
+        },
         inset: { clip: false, drawsRows: false },
-        line: { clip: true, drawsRows: true, legendSymbol: 'line' },
+        line: {
+            inherits: ['x', 'y', 'grouping', 'color'],
+            clip: true,
+            drawsRows: true,
+            legendSymbol: 'line',
+            labels: { default: 'point', path: 'stroke', point: 'row' }
+        },
         link: { clip: false, drawsRows: false },
         raster: { clip: true, drawsRows: true },
-        rect: { clip: true, drawsRows: true, legendSymbol: 'rect' },
-        regression: { clip: true, drawsRows: true, legendSymbol: 'line' },
+        rect: {
+            inherits: ['x', 'y', 'color', 'opacity'],
+            clip: true,
+            drawsRows: true,
+            legendSymbol: 'rect',
+            labels: { default: 'box', box: 'edges', path: 'box', point: 'box' }
+        },
+        regression: {
+            oriented: true,
+            inherits: ['x', 'y'],
+            clip: true,
+            drawsRows: true,
+            legendSymbol: 'line'
+        },
         rule: { clip: true, drawsRows: false, legendSymbol: 'line' },
         sphere: { clip: false, drawsRows: false },
-        text: { clip: false, drawsRows: true },
-        tick: { clip: true, drawsRows: true },
-        trail: { clip: true, drawsRows: true, legendSymbol: 'line' },
-        vector: { clip: false, drawsRows: false },
-        violin: { clip: true, drawsRows: true, legendSymbol: 'area' },
-        voronoi: { clip: true, drawsRows: true },
-        voronoiMesh: { clip: true, drawsRows: true },
-        waffle: { clip: true, drawsRows: true }
+        text: {
+            inherits: ['x', 'y'],
+            clip: false,
+            drawsRows: true
+        },
+        tick: {
+            oriented: true,
+            inherits: ['color'],
+            clip: true,
+            drawsRows: true
+        },
+        trail: {
+            inherits: ['x', 'y', 'grouping', 'color', 'opacity', 'r'],
+            clip: true,
+            drawsRows: true,
+            legendSymbol: 'line',
+            labels: { default: 'point', path: 'stroke', point: 'row' }
+        },
+        vector: { inherits: ['length'], clip: false, drawsRows: false },
+        violin: {
+            oriented: true,
+            inherits: ['x', 'y'],
+            clip: true,
+            drawsRows: true,
+            legendSymbol: 'area'
+        },
+        voronoi: {
+            inherits: ['x', 'y', 'grouping', 'color'],
+            clip: true,
+            drawsRows: true
+        },
+        voronoiMesh: {
+            inherits: ['x', 'y', 'grouping', 'color'],
+            clip: true,
+            drawsRows: true
+        },
+        waffle: {
+            oriented: true,
+            inherits: ['x', 'y', 'color'],
+            clip: true,
+            drawsRows: true,
+            labels: { default: 'box', box: 'band', path: 'box', point: 'box' }
+        }
     };
     /** The traits of a marker kind, or `undefined` for a type no kind declares. */
     static of(type) {
@@ -50,4 +169,11 @@ export class MarkerKinds {
             ? MarkerKinds.traits[type]
             : undefined;
     }
+    static inherits(type, channel) {
+        return MarkerKinds.of(type)?.inherits?.includes(channel) ?? false;
+    }
+    /** Whether the kind takes the plot's scales: it inherits a channel that has one. */
+    static inheritsScales(type) {
+        return SCALED.some((channel) => MarkerKinds.inherits(type, channel));
+    }
 }

package/dist/markers/area/AreaMarker.svelte

@@ -16,7 +16,7 @@
 	const events = MarkerEvents.use(() => marker);
 
 	const plot = usePlot();
-	const isHorizontal = $derived(plot.axes?.isHorizontal ?? false);
+	const isHorizontal = $derived(marker.isHorizontal ?? plot.axes?.isHorizontal ?? false);
 	const AreaMark = $derived(isHorizontal ? AreaX : AreaY);
 
 	const cfg = $derived(getConfiguration());

package/dist/markers/bar/BarMarker.svelte

@@ -19,7 +19,9 @@
 	const data = $derived(marker.data ?? []);
 	const channelFill = $derived(MarkerChannels.buildFill(data, marker.color, marker.scales, cfg));
 
-	const plot = usePlot().svelteplot;
+	const context = usePlot();
+	const plot = context.svelteplot;
+	const isHorizontal = $derived(marker.isHorizontal ?? context.axes?.isHorizontal ?? false);
 	function categoryScaleFor(isHorizontal: boolean) {
 		return isHorizontal ? plot.scales.y : plot.scales.x;
 	}
@@ -36,11 +38,11 @@
 </script>
 
 {#if marker.role === 'segment'}
-	{@const categoryScale = categoryScaleFor(marker.isHorizontal)}
+	{@const categoryScale = categoryScaleFor(isHorizontal)}
 	{@const bandwidth = categoryScale?.type === 'band' ? categoryScale.fn.bandwidth() : 0}
 	{@const centered =
 		marker.thickness != null ? Math.max(0, (bandwidth - marker.thickness) / 2) : undefined}
-	{#if marker.isHorizontal}
+	{#if isHorizontal}
 		<BarX
 			{...events.props}
 			{data}
@@ -80,7 +82,7 @@
 		/>
 	{/if}
 {:else}
-	{@const categoryScale = categoryScaleFor(marker.isHorizontal)}
+	{@const categoryScale = categoryScaleFor(isHorizontal)}
 	{#if categoryScale?.type === 'band'}
 		{@const bandwidth = categoryScale.fn.bandwidth()}
 		{@const bandStart = Number(categoryScale.fn(marker.category as never) ?? 0)}
@@ -89,8 +91,8 @@
 		{@const insetTop = (marker.styles?.insetTop ?? 0) * bandwidth}
 		{@const insetBottom = (marker.styles?.insetBottom ?? 0) * bandwidth}
 		<!-- The band runs the plot's whole value axis, so the pointer needn't be over the bar. -->
-		{@const [rangeMin, rangeMax] = valueExtentFor(marker.isHorizontal)}
-		{#if marker.isHorizontal}
+		{@const [rangeMin, rangeMax] = valueExtentFor(isHorizontal)}
+		{#if isHorizontal}
 			<rect
 				class="dct-hit-area"
 				x={rangeMin + insetLeft}

package/dist/markers/bollinger/BollingerMarker.svelte

@@ -22,7 +22,7 @@
 	const events = MarkerEvents.use(() => marker);
 
 	const plot = usePlot();
-	const isHorizontal = $derived(plot.axes?.isHorizontal ?? false);
+	const isHorizontal = $derived(marker.isHorizontal ?? plot.axes?.isHorizontal ?? false);
 	const BollingerMark = $derived(isHorizontal ? BollingerX : BollingerY);
 
 	const cfg = $derived(getConfiguration());

package/dist/markers/box/BoxMarker.svelte

@@ -19,7 +19,7 @@
 	const events = MarkerEvents.use(() => marker);
 
 	const plot = usePlot();
-	const isHorizontal = $derived(plot.axes?.isHorizontal ?? false);
+	const isHorizontal = $derived(marker.isHorizontal ?? plot.axes?.isHorizontal ?? false);
 	const BoxMark = $derived(isHorizontal ? BoxX : BoxY);
 
 	/**

package/dist/markers/dot/DotRadius.d.ts

@@ -0,0 +1,11 @@
+import type { BoxScales } from '../../types/markers/labels/box';
+type Dotted = {
+    r?: unknown;
+    styles?: object;
+};
+/** A dot's radius in pixels, as its marker draws it. */
+export declare class DotRadius {
+    /** Its `r`: a number as it is, a channel through the plot's `r` scale; else its `dotRadius`, else `fallback`. */
+    static of(marker: Dotted, row: unknown, scales: BoxScales, fallback?: number): number;
+}
+export {};

package/dist/markers/dot/DotRadius.js

@@ -0,0 +1,21 @@
+const read = (channel, row) => typeof channel === 'function'
+    ? channel(row)
+    : typeof channel === 'string' || typeof channel === 'symbol'
+        ? row?.[channel]
+        : channel;
+/** A dot's radius in pixels, as its marker draws it. */
+export class DotRadius {
+    /** Its `r`: a number as it is, a channel through the plot's `r` scale; else its `dotRadius`, else `fallback`. */
+    static of(marker, row, scales, fallback = 5) {
+        const { r } = marker;
+        if (typeof r === 'number')
+            return r;
+        if (r !== undefined && scales.r) {
+            const value = Number(scales.r.fn(read(r, row)));
+            if (Number.isFinite(value))
+                return value;
+        }
+        const own = marker.styles?.dotRadius;
+        return typeof own === 'number' ? own : fallback;
+    }
+}

package/dist/markers/labels/CurveLabel.svelte

@@ -0,0 +1,56 @@
+<script lang="ts">
+	import { usePlot } from '../../layout/plot/usePlot';
+	import { getConfiguration } from '../../configuration/config.svelte';
+	import { CurveGeometry } from './geometry/CurveGeometry';
+	import { Box } from '../../layout/margins/Box';
+	import type { PathLabelConfig, PathShape } from '../../types/markers/labels/path';
+	import type { BoxScales } from '../../types/markers/labels/box';
+
+	/** Writes one `'path'` label along the curves of a marker: its lines, an area's edge or each dot's rim. */
+	const {
+		marker,
+		label,
+		shape
+	}: {
+		marker: Record<string, unknown>;
+		label: PathLabelConfig<string, string>;
+		shape: Exclude<PathShape, 'box'>;
+	} = $props();
+	const plot = usePlot();
+	const cfg = $derived(getConfiguration());
+	const id = $props.id();
+
+	const styles = $derived(label.styles ?? {});
+	const curves = $derived(
+		CurveGeometry.build(shape, marker, label, {
+			scales: plot.svelteplot.scales as unknown as BoxScales,
+			gap: cfg.text.label.gap,
+			measure: (text) => Box.ofText(text, Number(styles.fontSize ?? 11), cfg).width
+		})
+	);
+	// Centred on its curve, a label is drawn over a halo of the background so the curve does not cross it.
+	const halo = $derived((label.side ?? '') === 'on' && styles.stroke === undefined);
+	/** A style's value for a curve's row: a function of the row, or the value itself. */
+	const of = (value: unknown, row: unknown) =>
+		(typeof value === 'function' ? value(row) : value) as string | number | undefined;
+</script>
+
+{#each curves as curve, i (i)}
+	<path id="{id}-{i}" d={curve.d} fill="none" stroke="none" />
+	<text
+		dy={curve.dy}
+		dominant-baseline={curve.baseline}
+		text-anchor={curve.textAnchor}
+		fill={String(of(styles.fill, curve.row) ?? curve.fill ?? 'currentColor')}
+		fill-opacity={of(styles.fillOpacity, curve.row)}
+		font-size={styles.fontSize ?? 11}
+		font-weight={of(styles.fontWeight, curve.row)}
+		font-style={of(styles.fontStyle, curve.row)}
+		stroke={halo ? cfg.background : (of(styles.stroke, curve.row) as string | undefined)}
+		stroke-width={halo ? 3 : of(styles.strokeWidth, curve.row)}
+		paint-order={halo ? 'stroke' : styles.paintOrder}
+		pointer-events="none"
+	>
+		<textPath href="#{id}-{i}" startOffset={curve.startOffset}>{curve.text}</textPath>
+	</text>
+{/each}

package/dist/markers/labels/CurveLabel.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { PathLabelConfig, PathShape } from '../../types/markers/labels/path';
+type $$ComponentProps = {
+    marker: Record<string, unknown>;
+    label: PathLabelConfig<string, string>;
+    shape: Exclude<PathShape, 'box'>;
+};
+declare const CurveLabel: import("svelte").Component<$$ComponentProps, {}, "">;
+type CurveLabel = ReturnType<typeof CurveLabel>;
+export default CurveLabel;

package/dist/markers/labels/LabelMerge.d.ts

@@ -0,0 +1,11 @@
+import type { TextMarkerConfig } from '../../types/markers/basic/text';
+/** The label a merged row was written by. */
+export declare const LABEL_SOURCE: unique symbol;
+/**
+ * Labels drawn as one `text` marker: those whose other options are alike merge, each row tagged with the label
+ * it comes from, so labels from several markers declutter together and draw as one.
+ */
+export declare class LabelMerge {
+    #private;
+    static merge(markers: TextMarkerConfig[]): TextMarkerConfig[];
+}