@fjader/svelte 0.2.2 → 0.2.4

package/README.md

@@ -16,6 +16,8 @@ pip install fjader                 # Python: marimo and Jupyter
 pip install "fjader[streamlit]"    # Python: Streamlit
 ```
 
+`@uwdata/mosaic-sql` is a peer dependency (0.34 or 0.35), so your app and fjader share one copy. Two copies would not recognise each other's expressions: an aggregate such as `sum(...)` written with one would be misread by the other.
+
 fjader needs Chrome 149 or later, or another Chromium browser on that version. It relies on two recent features other browsers don't ship yet: WebGPU's `immediate_address_space`, through which every chart passes its scales to the shaders (so every zoom and pan uses it), and the `Temporal` API, used for calendar offsets. There is no fallback renderer.
 
 Three things to know before using it in a deployed app:

package/dist/components/axes/AxisBottom.svelte

@@ -8,9 +8,24 @@
 	interface Props {
 		ticksNumber?: number;
 		tickFormat?: ((value: unknown) => string) | null;
+		/**
+		 * Draw the scale's label as the axis title (default). `false` draws none; the
+		 * label still names the scale, so charts sharing it still link their zoom.
+		 */
+		title?: boolean;
+		/**
+		 * Where along the axis the title sits: `'center'` (default), or at the plot's
+		 * `'start'` (left) or `'end'` (right) edge.
+		 */
+		titleAnchor?: 'start' | 'center' | 'end';
 	}
 
-	let { ticksNumber = 5, tickFormat = null }: Props = $props();
+	let {
+		ticksNumber = 5,
+		tickFormat = null,
+		title = true,
+		titleAnchor = 'center'
+	}: Props = $props();
 	const c = getContext<ChartContext>('chart');
 
 	// Propagate custom format to scale state once it exists (for MarginLabel, tooltips, etc.)
@@ -47,10 +62,6 @@
 					{tickFormatter(tick)}
 				</text>
 			{/each}
-
-			<text text-anchor="middle" x={c.innerWidth / 2} y={28}>
-				{c.xLabel}
-			</text>
 		{:else if c.scaleTypes.x === 'band' && c.xScale}
 			<BandAxisTicks
 				scale={c.xScaleState as BandScaleState}
@@ -60,8 +71,14 @@
 				tickLength={5}
 				labelGap={16}
 			/>
+		{/if}
 
-			<text text-anchor="middle" x={c.innerWidth / 2} y={28}>
+		{#if title && c.xScale}
+			<text
+				text-anchor={titleAnchor === 'start' ? 'start' : titleAnchor === 'end' ? 'end' : 'middle'}
+				x={titleAnchor === 'start' ? 0 : titleAnchor === 'end' ? c.innerWidth : c.innerWidth / 2}
+				y={28}
+			>
 				{c.xLabel}
 			</text>
 		{/if}

package/dist/components/axes/AxisBottom.svelte.d.ts

@@ -1,6 +1,16 @@
 interface Props {
     ticksNumber?: number;
     tickFormat?: ((value: unknown) => string) | null;
+    /**
+     * Draw the scale's label as the axis title (default). `false` draws none; the
+     * label still names the scale, so charts sharing it still link their zoom.
+     */
+    title?: boolean;
+    /**
+     * Where along the axis the title sits: `'center'` (default), or at the plot's
+     * `'start'` (left) or `'end'` (right) edge.
+     */
+    titleAnchor?: 'start' | 'center' | 'end';
 }
 declare const AxisBottom: import("svelte").Component<Props, {}, "">;
 type AxisBottom = ReturnType<typeof AxisBottom>;

package/dist/components/axes/AxisLeft.svelte

@@ -4,13 +4,38 @@
 	import type { BandScaleState } from '../../scales/BandScaleState.svelte';
 	import BandAxisTicks from './BandAxisTicks.svelte';
 	import type { ContinuousScaleState } from '../../types';
+	import { categoryLabel } from '../../query-engine/categorical-identity';
+	import { clearTitleOffset, sameTicks, textWidth } from './axis-title';
 
 	interface Props {
 		ticksNumber?: number;
 		tickFormat?: ((value: unknown) => string) | null;
+		/**
+		 * Draw the scale's label as the axis title (default). `false` draws none; the
+		 * label still names the scale, so charts sharing it still link their zoom.
+		 */
+		title?: boolean;
+		/**
+		 * How far left of the axis the title sits, in px (default 32), or `'auto'`:
+		 * clear of the widest tick label, as far as the chart's left margin allows.
+		 */
+		titleOffset?: number | 'auto';
+		/**
+		 * Where the title goes: `'side'` (default), rotated beside the tick labels, or
+		 * `'top'`, horizontal above the plot at the axis. `'top'` cannot meet the tick
+		 * labels, so it needs no `titleOffset` and no room in the left margin; it takes
+		 * the space above the plot (the chart's top margin).
+		 */
+		titlePlacement?: 'side' | 'top';
 	}
 
-	let { ticksNumber = 5, tickFormat = null }: Props = $props();
+	let {
+		ticksNumber = 5,
+		tickFormat = null,
+		title = true,
+		titleOffset = 32,
+		titlePlacement = 'side'
+	}: Props = $props();
 	const c = getContext<ChartContext>('chart');
 
 	// Propagate custom format to scale state once it exists (for MarginLabel, tooltips, etc.)
@@ -34,6 +59,43 @@
 
 	// Unified formatter interface - all scale states have tickFormat()
 	const tickFormatter = $derived(c.yScaleState?.tickFormat ? c.yScaleState.tickFormat() : String);
+
+	// The title's distance from the axis. Measured only for 'auto', from the labels
+	// drawn (each distinct string once, then cached). It follows the widest label
+	// seen on this scale and never moves back in: pan and zoom change the ticks
+	// all the time, and a title that followed them would jitter. Taking the
+	// maximum is idempotent, so re-evaluating this changes nothing.
+	let widestSeen = 0;
+	let widestScale: unknown = null;
+	// The ticks and formatter the widest was last taken from: a pan that only moves
+	// the same ticks measures (and formats) nothing.
+	let measuredTicks: ArrayLike<unknown> | null = null;
+	let measuredFormatter: unknown = null;
+	const titleX = $derived.by(() => {
+		if (titleOffset !== 'auto') return titleOffset;
+		const scale = c.yScaleState;
+		if (scale !== widestScale) {
+			widestScale = scale;
+			widestSeen = 0;
+			measuredTicks = null;
+		}
+		const band = c.scaleTypes?.y === 'band';
+		const ticks: ArrayLike<unknown> = band ? bandTicks : continuousTicks;
+		if (!sameTicks(measuredTicks, ticks) || (!band && measuredFormatter !== tickFormatter)) {
+			if (band) {
+				for (const tick of bandTicks) {
+					widestSeen = Math.max(widestSeen, textWidth(String(categoryLabel(tick.value))));
+				}
+			} else {
+				for (const tick of continuousTicks) {
+					widestSeen = Math.max(widestSeen, textWidth(String(tickFormatter(tick))));
+				}
+			}
+			measuredTicks = ticks;
+			measuredFormatter = tickFormatter;
+		}
+		return clearTitleOffset(widestSeen, c.margin.left);
+	});
 </script>
 
 {#if c.isReady && c.scaleTypes}
@@ -47,10 +109,6 @@
 					{tickFormatter(tick)}
 				</text>
 			{/each}
-
-			<text text-anchor="middle" transform={`translate(-32, ${c.innerHeight / 2}) rotate(-90)`}>
-				{c.yLabel}
-			</text>
 		{:else if c.scaleTypes.y === 'band' && c.yScale}
 			<BandAxisTicks
 				scale={c.yScaleState as BandScaleState}
@@ -60,10 +118,21 @@
 				dir={-1}
 				textAnchor="end"
 			/>
+		{/if}
 
-			<text text-anchor="middle" transform={`translate(-32, ${c.innerHeight / 2}) rotate(-90)`}>
-				{c.yLabel}
-			</text>
+		{#if title && c.yScale}
+			{#if titlePlacement === 'top'}
+				<text text-anchor="start" x={0} y={-18}>
+					{c.yLabel}
+				</text>
+			{:else}
+				<text
+					text-anchor="middle"
+					transform={`translate(${-titleX}, ${c.innerHeight / 2}) rotate(-90)`}
+				>
+					{c.yLabel}
+				</text>
+			{/if}
 		{/if}
 	</g>
 {/if}

package/dist/components/axes/AxisLeft.svelte.d.ts

@@ -1,6 +1,23 @@
 interface Props {
     ticksNumber?: number;
     tickFormat?: ((value: unknown) => string) | null;
+    /**
+     * Draw the scale's label as the axis title (default). `false` draws none; the
+     * label still names the scale, so charts sharing it still link their zoom.
+     */
+    title?: boolean;
+    /**
+     * How far left of the axis the title sits, in px (default 32), or `'auto'`:
+     * clear of the widest tick label, as far as the chart's left margin allows.
+     */
+    titleOffset?: number | 'auto';
+    /**
+     * Where the title goes: `'side'` (default), rotated beside the tick labels, or
+     * `'top'`, horizontal above the plot at the axis. `'top'` cannot meet the tick
+     * labels, so it needs no `titleOffset` and no room in the left margin; it takes
+     * the space above the plot (the chart's top margin).
+     */
+    titlePlacement?: 'side' | 'top';
 }
 declare const AxisLeft: import("svelte").Component<Props, {}, "">;
 type AxisLeft = ReturnType<typeof AxisLeft>;

package/dist/components/axes/BandAxisTicks.svelte

@@ -1,21 +1,25 @@
 <script lang="ts">
+	import { getContext } from 'svelte';
 	import type { BandScaleState, BandTick } from '../../scales/BandScaleState.svelte';
+	import type { ChartContext } from '../../types';
+	import { categoryLabel } from '../../query-engine/categorical-identity';
+	import type { FilterGroupRegistry } from '../../query-engine/FilterGroupRegistry.svelte';
 
 	/**
 	 * The labels on a band axis, wherever that axis is drawn.
 	 *
 	 * Three components rendered this: AxisBottom, AxisLeft and AxisCenter. The
-	 * arithmetic was already shared — `tickPosition`, `tickOpacity` and
-	 * `isTickDimmed` all live on the scale — so what was actually duplicated
+	 * arithmetic was already shared — `tickPosition` and `tickOpacity` live on
+	 * the scale — so what was actually duplicated
 	 * was the markup around it, and what differs between the three is a handful
 	 * of numbers: which way the ticks point, how long they are, how far the
 	 * label sits, and where it anchors.
 	 *
 	 * Those are props here, so the structure is written once. The structure is
 	 * the part with the reasons attached: the keyed `{#each}` so a reorder
-	 * MOVES a label rather than replacing it, the opacity wrapper the scale
-	 * drives per frame so a label travels and fades with its bar, and the
-	 * dimming class inside it so a selection does not fight the transition.
+	 * MOVES a label rather than replacing it, and the opacity wrapper the scale
+	 * drives per frame so a label travels, enters, leaves and dims for a
+	 * selection with its bar, all on the scale's clocks.
 	 *
 	 * A band label is positioned through `tickPosition`, which reads the
 	 * category's CURRENT fractional slot, not through the d3 scale. The d3
@@ -54,26 +58,66 @@
 		textAnchor = 'middle'
 	}: Props = $props();
 
+	const chart = getContext<ChartContext | undefined>('chart');
+	const filterGroups = getContext<FilterGroupRegistry | undefined>('filter-groups');
+
+	/**
+	 * The filter groups whose selection the labels show: those of the chart's
+	 * marks. A selection dims the axis's marks in their own group, so a label
+	 * dims when any of those groups dims its category; a background mark in a
+	 * group with nothing selected changes nothing.
+	 */
+	const groups = $derived.by(() => {
+		if (!chart || !filterGroups) return [];
+		const indices: number[] = [];
+		for (const entry of chart.config.entries.values()) {
+			// A 'filter' mark never dims; its labels follow it.
+			if (entry.selectionResponse === 'filter') continue;
+			const index = filterGroups.get(entry.selection).index;
+			if (!indices.includes(index)) indices.push(index);
+		}
+		return indices;
+	});
+
+	/**
+	 * The field the axis's selection is kept under: its identity key, or its
+	 * column before. As for the legend, the two differ for a computed field,
+	 * so its labels briefly lose their dimming while a reload empties identity.
+	 */
+	const key = $derived(scale.identityKey ?? scale.sourceField);
+
+	/**
+	 * A label's opacity: the scale's own (travel, clipping) times its selection
+	 * fade. Read by id where the tick's key is one — the only way to reach an
+	 * Other bucket, whose label is not a value — and by value before identity.
+	 */
+	function opacityOf(tick: BandTick): number {
+		const selected = !filterGroups
+			? 1
+			: scale.hasIdentity
+				? filterGroups.opacityOfId(key, groups, tick.key)
+				: filterGroups.opacityOfValue(key, groups, tick.value);
+		return scale.tickOpacity(tick.key) * selected;
+	}
+
 	const tickEnd = $derived(base + dir * tickLength);
 	const labelAt = $derived(base + dir * labelGap);
 </script>
 
 {#each ticks as tick (tick.key)}
-	{@const pos = scale.tickPosition(tick.key, rangeSize, axis)}
-	<g opacity={scale.tickOpacity(tick.key)}>
-		<g class:tick-dimmed={scale.isTickDimmed(tick)}>
-			{#if axis === 'x'}
-				<line x1={pos} x2={pos} y1={base} y2={tickEnd} />
-				<text text-anchor={textAnchor} x={pos} y={labelAt}>
-					{tick.value}
-				</text>
-			{:else}
-				<line x1={base} x2={tickEnd} y1={pos} y2={pos} />
-				<text text-anchor={textAnchor} dominant-baseline="middle" x={labelAt} y={pos}>
-					{tick.value}
-				</text>
-			{/if}
-		</g>
+	{@const pos = scale.tickPosition(tick.key, rangeSize)}
+	<g opacity={opacityOf(tick)}>
+		{#if axis === 'x'}
+			<line x1={pos} x2={pos} y1={base} y2={tickEnd} />
+			<text text-anchor={textAnchor} x={pos} y={labelAt}>
+				{categoryLabel(tick.value)}
+			</text>
+		{:else}
+			<line x1={base} x2={tickEnd} y1={pos} y2={pos} />
+			<text text-anchor={textAnchor} dominant-baseline="middle" x={labelAt} y={pos}>
+				{categoryLabel(tick.value)}
+			</text>
+		{/if}
 	</g>
 {/each}
 
@@ -87,9 +131,4 @@
 		font-family: var(--fjader-font, system-ui, sans-serif);
 		font-size: 10px;
 	}
-
-	.tick-dimmed {
-		opacity: 0.25;
-		transition: opacity 0.15s ease;
-	}
 </style>

package/dist/components/axes/BandAxisTicks.svelte.d.ts

@@ -3,17 +3,17 @@ import type { BandScaleState, BandTick } from '../../scales/BandScaleState.svelt
  * The labels on a band axis, wherever that axis is drawn.
  *
  * Three components rendered this: AxisBottom, AxisLeft and AxisCenter. The
- * arithmetic was already shared — `tickPosition`, `tickOpacity` and
- * `isTickDimmed` all live on the scale — so what was actually duplicated
+ * arithmetic was already shared — `tickPosition` and `tickOpacity` live on
+ * the scale — so what was actually duplicated
  * was the markup around it, and what differs between the three is a handful
  * of numbers: which way the ticks point, how long they are, how far the
  * label sits, and where it anchors.
  *
  * Those are props here, so the structure is written once. The structure is
  * the part with the reasons attached: the keyed `{#each}` so a reorder
- * MOVES a label rather than replacing it, the opacity wrapper the scale
- * drives per frame so a label travels and fades with its bar, and the
- * dimming class inside it so a selection does not fight the transition.
+ * MOVES a label rather than replacing it, and the opacity wrapper the scale
+ * drives per frame so a label travels, enters, leaves and dims for a
+ * selection with its bar, all on the scale's clocks.
  *
  * A band label is positioned through `tickPosition`, which reads the
  * category's CURRENT fractional slot, not through the d3 scale. The d3

package/dist/components/axes/axis-title.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Where an axis title sits relative to its tick labels.
+ *
+ * The left axis puts its tick labels right-anchored 9px from the axis line and
+ * its title, rotated, to the left of them. A fixed offset is right for short
+ * labels and runs into wide ones (`40,000`, a band name). `'auto'` places the
+ * title clear of the widest label, within the margin the chart gave it.
+ */
+/** The title's offset when nothing says otherwise, and the least `'auto'` uses. */
+export declare const DEFAULT_TITLE_OFFSET = 32;
+/**
+ * The width of a tick label in px. Measured on a canvas, once per distinct
+ * string (a band axis has the same labels frame after frame); 6px a character
+ * where there is no document. An estimate by design: the page's own font can
+ * differ a little, and CLEARANCE covers that.
+ */
+export declare function textWidth(text: string): number;
+/**
+ * How far left of the axis line the title's baseline goes, clear of a label
+ * `widest` px wide: never less than the default, and never so far that its body
+ * leaves the margin. A margin too narrow for the labels leaves them overlapping,
+ * and only a wider margin fixes that.
+ */
+export declare function clearTitleOffset(widest: number, marginLeft: number): number;
+/**
+ * Whether two tick lists are the same ticks: equal values, or band ticks of the
+ * same key. A loop with no allocation, to skip re-measuring labels when a pan
+ * moved the ticks but did not change them.
+ */
+export declare function sameTicks(a: ArrayLike<unknown> | null, b: ArrayLike<unknown>): boolean;

package/dist/components/axes/axis-title.js

@@ -0,0 +1,77 @@
+/**
+ * Where an axis title sits relative to its tick labels.
+ *
+ * The left axis puts its tick labels right-anchored 9px from the axis line and
+ * its title, rotated, to the left of them. A fixed offset is right for short
+ * labels and runs into wide ones (`40,000`, a band name). `'auto'` places the
+ * title clear of the widest label, within the margin the chart gave it.
+ */
+/** Where the tick labels end, from the axis line: AxisLeft's text x and BandAxisTicks' labelGap. */
+const TICK_GAP = 9;
+/** Between the widest label and the title's baseline; the title's descenders reach into it. */
+const CLEARANCE = 12;
+/** A rotated title's glyphs sit on the far side of its baseline, away from the axis. */
+const TITLE_BODY = 10;
+/** The title's offset when nothing says otherwise, and the least `'auto'` uses. */
+export const DEFAULT_TITLE_OFFSET = 32;
+const FONT = '10px system-ui, sans-serif';
+const FALLBACK_CHAR_WIDTH = 6;
+const CACHE_LIMIT = 2000;
+let context;
+const widths = new Map();
+/**
+ * The width of a tick label in px. Measured on a canvas, once per distinct
+ * string (a band axis has the same labels frame after frame); 6px a character
+ * where there is no document. An estimate by design: the page's own font can
+ * differ a little, and CLEARANCE covers that.
+ */
+export function textWidth(text) {
+    const known = widths.get(text);
+    if (known !== undefined)
+        return known;
+    if (context === undefined) {
+        context =
+            typeof document === 'undefined' ? null : document.createElement('canvas').getContext('2d');
+        if (context)
+            context.font = FONT;
+    }
+    const width = context ? context.measureText(text).width : text.length * FALLBACK_CHAR_WIDTH;
+    if (widths.size >= CACHE_LIMIT)
+        widths.clear();
+    widths.set(text, width);
+    return width;
+}
+/**
+ * How far left of the axis line the title's baseline goes, clear of a label
+ * `widest` px wide: never less than the default, and never so far that its body
+ * leaves the margin. A margin too narrow for the labels leaves them overlapping,
+ * and only a wider margin fixes that.
+ */
+export function clearTitleOffset(widest, marginLeft) {
+    const wanted = Math.max(TICK_GAP + widest + CLEARANCE, DEFAULT_TITLE_OFFSET);
+    return Math.max(0, Math.min(wanted, marginLeft - TITLE_BODY));
+}
+/**
+ * Whether two tick lists are the same ticks: equal values, or band ticks of the
+ * same key. A loop with no allocation, to skip re-measuring labels when a pan
+ * moved the ticks but did not change them.
+ */
+export function sameTicks(a, b) {
+    if (!a || a.length !== b.length)
+        return false;
+    for (let i = 0; i < b.length; i++) {
+        const x = a[i];
+        const y = b[i];
+        if (x === y)
+            continue;
+        if (typeof x === 'object' &&
+            typeof y === 'object' &&
+            x !== null &&
+            y !== null &&
+            x.key !== undefined &&
+            x.key === y.key)
+            continue;
+        return false;
+    }
+    return true;
+}

package/dist/components/charts/ChartCell.svelte

@@ -897,7 +897,7 @@
 			if (overBrush) {
 				tooltipManager?.updatePosition(null, null);
 			} else {
-				tooltipManager?.updatePointerScreen(x, y);
+				tooltipManager?.updatePointerClient(x + svgLeft, y + svgTop);
 				tooltipManager?.updatePosition(
 					scales.xScaleState?.currentDataPoint,
 					scales.yScaleState?.currentDataPoint

package/dist/components/charts/ChartContainer.svelte

@@ -13,6 +13,7 @@
 	import { identityKeyFor } from '../../query-engine/identity-key';
 	import { checkFacetCells } from './facet-limits';
 	import ChartCell from './ChartCell.svelte';
+	import { categoryLabel } from '../../query-engine/categorical-identity';
 
 	interface Props {
 		xLabel?: string | null;
@@ -77,6 +78,13 @@
 		clipPadding?: number;
 		useXSelection?: boolean;
 		useYSelection?: boolean;
+		/**
+		 * The tooltip's colours against the color-scheme the chart inherits:
+		 * `contrast` is the opposite scheme (dark on a light page), `follow` the
+		 * same. Unset, the nearest `data-fjader-tooltip` ancestor decides, else
+		 * contrast. `--fjader-tooltip-bg`/`-text` set by the app override both.
+		 */
+		tooltipScheme?: 'contrast' | 'follow';
 	}
 
 	let {
@@ -107,7 +115,8 @@
 		margin: marginOverride = {},
 		clipPadding = 0,
 		useXSelection = false,
-		useYSelection = false
+		useYSelection = false,
+		tooltipScheme = undefined
 	}: Props = $props();
 
 	const defaultMargin = { top: 30, right: 50, bottom: 35, left: 75 };
@@ -451,7 +460,7 @@
 	setContext('legend-position', () => legendPosition);
 </script>
 
-<div class="figure-container" bind:clientWidth={layout.width}>
+<div class="figure-container" bind:clientWidth={layout.width} data-fjader-tooltip={tooltipScheme}>
 	{#if legend && legendPosition === 'top'}
 		<div
 			class="legend-container legend-top"
@@ -481,7 +490,7 @@
 					<ChartCell
 						cellChartId={facetChartIds[i]}
 						facetIndex={i}
-						facetLabel={String(cat)}
+						facetLabel={String(categoryLabel(cat))}
 						margin={{ top: 20, right: 10, bottom: 35, left: 55 }}
 						{scales}
 						{chartConfig}

package/dist/components/charts/ChartContainer.svelte.d.ts

@@ -69,6 +69,13 @@ interface Props {
     clipPadding?: number;
     useXSelection?: boolean;
     useYSelection?: boolean;
+    /**
+     * The tooltip's colours against the color-scheme the chart inherits:
+     * `contrast` is the opposite scheme (dark on a light page), `follow` the
+     * same. Unset, the nearest `data-fjader-tooltip` ancestor decides, else
+     * contrast. `--fjader-tooltip-bg`/`-text` set by the app override both.
+     */
+    tooltipScheme?: 'contrast' | 'follow';
 }
 declare const ChartContainer: import("svelte").Component<Props, {}, "">;
 type ChartContainer = ReturnType<typeof ChartContainer>;

package/dist/components/guides/legend/ContinuousColorLegend.svelte

@@ -166,7 +166,8 @@
 
 	const brushHandle: SourceHandle | null = filterGroup
 		? filterGroup.register(sourceId, {
-				excludeMarkIds: () => new Set<string>(),
+				// No chart: an interval cannot dim, so the chart it sits in filters by
+				// it rather than showing nothing.
 				// The brush maps the bar linearly onto [min, max], whatever the color
 				// transform, so its pixel bins do too: barLength pixels over the domain.
 				activeDims: () =>
@@ -193,7 +194,13 @@
 					column: scaleState.field,
 					label: scaleState.field,
 					values: value ? [(value as number[])[0], (value as number[])[1]] : []
-				})
+				}),
+				// The clause was removed from outside (clearAll, a filter pill): take the
+				// brush down too, which only this legend holds.
+				onCleared: () => {
+					brushT0 = null;
+					brushT1 = null;
+				}
 			})
 		: null;