@fjader/svelte 0.2.3 → 0.2.5

package/dist/gpu/ScaleTemplateSystem.js

@@ -178,10 +178,10 @@ const SCALE_FRAGMENTS = {
 					rangeMax
 				);
 				
-				// Return center of band
-				// X: left to right (index 0 at left)
-				// Y: bottom to top (index 0 at bottom, matching D3 convention)
-				${axis === 'y' ? 'return rangeMax - bandLayout.x - bandLayout.y * 0.5;' : 'return rangeMin + bandLayout.x + bandLayout.y * 0.5;'}
+				// Return center of band, slot 0 at the start of the range on both
+				// axes: the left on x, the top on y, so a y band axis reads top-down
+				// like a list and its exit (one past the last slot) is the list's end.
+				return rangeMin + bandLayout.x + bandLayout.y * 0.5;
 			}
   	`,
         bufferLayout: {
@@ -280,14 +280,14 @@ function _scaleFunctionName(scaleType, axis) {
 }
 /**
  * Bytes of immediate data every render pipeline declares: the chart's x and y
- * `ScaleParam`, 16 bytes each. Every layout declares the same size because a
+ * `ScaleParam`, 16 bytes each, and its entrance, a vec4. Every layout declares the same size because a
  * draw requires every declared byte to have been set, and the pass sets them
  * once, before its first draw.
  *
  * Immediates carry state shared across the pass and read by several marks: the
  * chart's scales and settings. 64 bytes are available on M-series Macs.
  */
-export const CHART_SCALE_IMMEDIATE_SIZE = 32;
+export const CHART_SCALE_IMMEDIATE_SIZE = 48;
 /**
  * Main template system class
  */
@@ -376,6 +376,7 @@ export class ScaleTemplateSystem {
       // ===== 3. HELPER FUNCTIONS =====
       
       ${this._buildSlotTableHelpers()}
+      ${this._buildEntranceHelpers(scaleTypes)}
       ${this._buildBandActivityHelpers(scaleTypes)}
       ${bandHelpers}
       ${implementations}
@@ -413,6 +414,10 @@ export class ScaleTemplateSystem {
       struct ChartScales {
         x: ScaleParam,
         y: ScaleParam,
+        // The chart's entrance, written per pass from its entrance clock:
+        // x = how far a growing mark has grown, y = a growing mark's opacity,
+        // z = a fading mark's opacity. All 1 once the chart has entered.
+        entrance: vec4<f32>,
       };
       var<immediate> chartScales: ChartScales;
 
@@ -448,6 +453,57 @@ export class ScaleTemplateSystem {
     `;
         return `${structDef}\n${chartScaleDeclaration}`;
     }
+    /**
+     * The chart's entrance, for marks to apply in the vertex stage.
+     *
+     * A mark either GROWS along one axis (bars, histograms and areas, from the
+     * value 0 on their measure axis) or FADES (everything else). Which one is
+     * the mark's to say, as `axis`: 0 fades, 1 grows along x, 2 along y. The
+     * chart's mode is already folded into the immediates, so a chart set to
+     * fade hands a growing mark g = 1 and its opacity instead.
+     *
+     * The base a mark grows from is where 0 sits on screen, clamped to the plot:
+     * a domain that leaves 0 out grows from the edge, which is where its bars
+     * visibly start anyway. A log axis has no 0 and grows from its low edge.
+     * Decided per scale type here, so no shader evaluates log(0).
+     */
+    _buildEntranceHelpers(scaleTypes) {
+        const base = (axis, type) => {
+            const a = axis.toLowerCase();
+            const lo = `frameUniforms.rangeMin.${a}`;
+            const hi = `frameUniforms.rangeMax.${a}`;
+            if (type === 'band' || type === 'point')
+                return '0.0';
+            // Screen y runs downward: the low edge of a y axis is rangeMax.
+            if (type === 'log')
+                return axis === 'X' ? lo : hi;
+            return `clamp(${_scaleFunctionName(type, axis)}From(0.0, chartScale${axis}()), ${lo}, ${hi})`;
+        };
+        return `
+    // ===== ENTRANCE =====
+    fn entranceBaseX() -> f32 {
+      return ${base('X', scaleTypes.x)};
+    }
+    fn entranceBaseY() -> f32 {
+      return ${base('Y', scaleTypes.y)};
+    }
+    // A screen position as it is during the entrance: pulled toward the base
+    // on the growing axis, untouched otherwise.
+    fn entrancePosition(p: vec2<f32>, axis: u32) -> vec2<f32> {
+      let g = chartScales.entrance.x;
+      if (axis == 1u) {
+        return vec2<f32>(mix(entranceBaseX(), p.x, g), p.y);
+      }
+      if (axis == 2u) {
+        return vec2<f32>(p.x, mix(entranceBaseY(), p.y, g));
+      }
+      return p;
+    }
+    fn entranceAlpha(axis: u32) -> f32 {
+      return select(chartScales.entrance.z, chartScales.entrance.y, axis != 0u);
+    }
+    `;
+    }
     /**
      * `bandActivityX(value, group)` and `bandActivityY(value, group)`: how
      * selected a band or point axis's category is in the mark's filter group,
@@ -465,6 +521,9 @@ export class ScaleTemplateSystem {
             if (type !== 'band' && type !== 'point') {
                 return `fn bandActivity${axis}(value: f32, group: u32) -> f32 {
       return 1.0;
+    }
+    fn bandFreeActivity${axis}(group: u32) -> f32 {
+      return 1.0;
     }`;
             }
             return `fn bandActivity${axis}(value: f32, group: u32) -> f32 {
@@ -472,6 +531,9 @@ export class ScaleTemplateSystem {
         return 1.0;
       }
       return identityActivity(u32(chartScale${axis}().p4), group, u32(value));
+    }
+    fn bandFreeActivity${axis}(group: u32) -> f32 {
+      return identityFreeActivity(u32(chartScale${axis}().p4), group);
     }`;
         };
         return `
@@ -554,6 +616,21 @@ export class ScaleTemplateSystem {
       }
       return identitySlots[actRef + n * group + id];
     }
+
+    fn identityFreeActivity(base: u32, group: u32) -> f32 {
+      // The last slot of the group's run, past every id: 1 while the group
+      // selects nothing on the field, 0 while it selects anything, at the
+      // selection clock (FieldActivity's FREE SLOT). 1 without a block.
+      if (group == ${NO_GROUP}u) {
+        return 1.0;
+      }
+      let actRef = u32(identitySlots[base + 1u]);
+      let n = u32(identitySlots[base + 2u]);
+      if (n == 0u) {
+        return 1.0;
+      }
+      return identitySlots[actRef + n * group + n - 1u];
+    }
     `;
     }
     _buildBandHelpers(scaleTypes) {

package/dist/index.d.ts

@@ -1,4 +1,11 @@
-import type { DuckDBConnection } from './query-engine';
+import type { DuckDBConnection, InitDuckDBOptions, QueryEngineOptions } from './query-engine';
+export interface FjaderOptions extends InitDuckDBOptions {
+    /** An existing connection (or a promise of one); skips internal DuckDB-WASM init. */
+    connection?: DuckDBConnection | Promise<DuckDBConnection>;
+    /** Advanced: query engine tuning (see QueryEngineOptions). */
+    engine?: QueryEngineOptions;
+}
+type FjaderInit = DuckDBConnection | Promise<DuckDBConnection> | FjaderOptions;
 /**
  * Initialize Fjader: QueryEngine, ScaleRegistry, GPUCoordinator, FilterGroups.
  * Call once in a top-level component's <script> block.
@@ -6,10 +13,14 @@ import type { DuckDBConnection } from './query-engine';
  *   import { initFjader } from '@fjader/svelte';
  *   const { queryEngine } = initFjader();
  *
- * Pass an existing DuckDB connection to skip internal DuckDB-WASM init:
- *   const { queryEngine } = initFjader(myConnection);
+ * Serve the DuckDB-WASM bundles yourself instead of loading them from jsDelivr:
+ *   initFjader({ bundles: { mvp: { mainModule, mainWorker }, eh: { … } } });
+ *
+ * Pass an existing DuckDB connection to skip internal DuckDB-WASM init, e.g. to
+ * keep the AsyncDuckDB instance for registerFileBuffer:
+ *   const { queryEngine } = initFjader(connectionFrom(await db.connect()));
  */
-export declare function initFjader(connection?: DuckDBConnection | Promise<DuckDBConnection>): {
+export declare function initFjader(init?: FjaderInit): {
     queryEngine: import("./query-engine").QueryEngine;
     filterGroups: import("./query-engine").FilterGroupRegistry;
     scaleRegistry: import("./scales").ScaleRegistry;
@@ -19,5 +30,9 @@ export * from './components';
 export * from './transforms';
 export * from './sql/bin';
 export * from './types';
+export { getFilterGroups } from './query-engine';
+export { connectionFrom } from './query-engine';
+export type { DuckDBConnection, InitDuckDBOptions } from './query-engine';
+export type { FilterGroupRegistry, FilterGroup, FilterItem } from './query-engine';
 export { Fjader, render } from './spec';
 export type { FjaderSpec, FjaderHandle, RenderOptions } from './spec';

package/dist/index.js

@@ -2,6 +2,14 @@
 import { setScaleRegistry } from './scales';
 import { setGPUCoordinator } from './gpu';
 import { setQueryContext, initDuckDB } from './query-engine';
+/** A connection has query(), a promise has then(); anything else is options. */
+function toOptions(init) {
+    if (!init)
+        return {};
+    if ('query' in init || 'then' in init)
+        return { connection: init };
+    return init;
+}
 /**
  * Initialize Fjader: QueryEngine, ScaleRegistry, GPUCoordinator, FilterGroups.
  * Call once in a top-level component's <script> block.
@@ -9,11 +17,16 @@ import { setQueryContext, initDuckDB } from './query-engine';
  *   import { initFjader } from '@fjader/svelte';
  *   const { queryEngine } = initFjader();
  *
- * Pass an existing DuckDB connection to skip internal DuckDB-WASM init:
- *   const { queryEngine } = initFjader(myConnection);
+ * Serve the DuckDB-WASM bundles yourself instead of loading them from jsDelivr:
+ *   initFjader({ bundles: { mvp: { mainModule, mainWorker }, eh: { … } } });
+ *
+ * Pass an existing DuckDB connection to skip internal DuckDB-WASM init, e.g. to
+ * keep the AsyncDuckDB instance for registerFileBuffer:
+ *   const { queryEngine } = initFjader(connectionFrom(await db.connect()));
  */
-export function initFjader(connection) {
-    const { queryEngine, filterGroups } = setQueryContext(connection ?? initDuckDB());
+export function initFjader(init) {
+    const { connection, bundles, engine } = toOptions(init);
+    const { queryEngine, filterGroups } = setQueryContext(connection ?? initDuckDB({ bundles }), engine);
     const scaleRegistry = setScaleRegistry();
     const gpuCoordinator = setGPUCoordinator({ msaaSampleCount: 4 });
     gpuCoordinator.setScaleRegistry(scaleRegistry);
@@ -25,5 +38,10 @@ export * from './components';
 export * from './transforms';
 export * from './sql/bin';
 export * from './types';
+// Selection state: the registry initFjader() returns, for code outside it (is anything
+// brushed? which groups exist?). Read from the same context.
+export { getFilterGroups } from './query-engine';
+// DuckDB: adapt an app-owned duckdb-wasm connection for initFjader(connection).
+export { connectionFrom } from './query-engine';
 // Spec-driven rendering API
 export { Fjader, render } from './spec';

package/dist/interactors/Interval1D.svelte

@@ -97,7 +97,12 @@
 			column: typeof resolvedField === 'string' ? resolvedField : (resolvedField?.toString() ?? ''),
 			label: typeof resolvedField === 'string' ? resolvedField : resolvedField?.toString(),
 			values: value ? [(value as number[])[0], (value as number[])[1]] : []
-		})
+		}),
+		// The clause was removed from outside (clearAll, a filter pill): take the
+		// rectangle down too, which only this control holds.
+		onCleared: () => {
+			if (brush.active) clearBrush();
+		}
 	});
 
 	// Pointer state (reused to avoid GC)

package/dist/interactors/Interval2D.svelte

@@ -97,7 +97,12 @@
 			yColumn: resolvedYField,
 			xValues: (value as unknown[][])?.[0],
 			yValues: (value as unknown[][])?.[1]
-		})
+		}),
+		// The clause was removed from outside (clearAll, a filter pill): take the
+		// rectangle down too, which only this control holds.
+		onCleared: () => {
+			if (brush.active) clearBrush();
+		}
 	});
 
 	// Pointer state (reused to avoid GC)

package/dist/interactors/ParallelAxisSource.svelte

@@ -83,7 +83,16 @@
 			column,
 			label: column,
 			values: value ? [(value as number[])[0], (value as number[])[1]] : []
-		})
+		}),
+		// The clause was removed from outside (clearAll, a filter pill): take this
+		// axis's rectangle down too, which only ParallelBrushes' state holds.
+		onCleared: () => {
+			const axis = axes.get(column);
+			if (!axis) return;
+			axis.brush.clear();
+			axis.lastEmitted.min = null;
+			axis.lastEmitted.max = null;
+		}
 	});
 
 	axes.set(column, { handle, brush: new BrushState1D(), lastEmitted: { min: null, max: null } });

package/dist/interactors/Toggle.svelte

@@ -70,7 +70,7 @@
 	function bandCategoryAt(
 		axis: 'x' | 'y',
 		innerPos: number
-	): { field: string; value: unknown } | null {
+	): { field: string; value: unknown; otherId: number | null } | null {
 		if (chart.scaleTypes?.[axis] !== 'band') return null;
 		const bandState = chart[`${axis}ScaleState`] as BandScaleState;
 		const extent = axis === 'x' ? chart.innerWidth : chart.innerHeight;
@@ -79,7 +79,28 @@
 		const id = bandState.idAtSlot(slot);
 		// undefined is "no category here"; null is the NULL category, a real one.
 		const value = id == null ? undefined : bandState.categoryAt(id);
-		return value === undefined ? null : { field: bandState.sourceField, value };
+		if (value === undefined) return null;
+		// The axis's Other bucket: its label is no value, so the click selects
+		// what it holds instead.
+		const otherId = id != null && id === bandState.otherId ? id : null;
+		return { field: bandState.sourceField, value, otherId };
+	}
+
+	/**
+	 * The Other bucket an inner click hit, or null: the hit row's band id on an
+	 * axis of the declared field, when it is that axis's Other. The label in
+	 * the row can't say, so the tooltip keeps the raw id beside it.
+	 */
+	function otherHit(point: Record<string, unknown>): number | null {
+		if (!declaredField) return null;
+		for (const axis of ['x', 'y'] as const) {
+			if (chart.scaleTypes?.[axis] !== 'band') continue;
+			const bandState = chart[`${axis}ScaleState`] as BandScaleState;
+			if (bandState.sourceField !== declaredField) continue;
+			const id = point[axis === 'x' ? '__bandIdX' : '__bandIdY'];
+			if (typeof id === 'number' && id === bandState.otherId) return id;
+		}
+		return null;
 	}
 
 	chart.onChartClick = (event) => {
@@ -91,6 +112,12 @@
 		// Path 1: Inner area click — use tooltip hit data (don't require visible —
 		// pointer micro-movement during click hides tooltip but data stays valid)
 		if (xInBounds && yInBounds && tm?.currentPoint) {
+			const otherId = otherHit(tm.currentPoint);
+			if (otherId !== null) {
+				const facetId = tm.currentPoint.__facetId;
+				declared.toggleOther(otherId, typeof facetId === 'number' ? facetId : null, isMulti);
+				return;
+			}
 			const tuple = fields.map((f) => tm.currentPoint![f]);
 			// A missing field is undefined; null is the NULL category, selectable.
 			if (tuple.some((v) => v === undefined)) return;
@@ -106,7 +133,9 @@
 					? bandCategoryAt('x', innerPoint.x)
 					: null;
 		if (hit) {
-			toggleFor(hit.field)?.toggle([hit.value], isMulti);
+			const toggle = toggleFor(hit.field);
+			if (hit.otherId !== null) toggle?.toggleOther(hit.otherId, null, isMulti);
+			else toggle?.toggle([hit.value], isMulti);
 			return;
 		}
 

package/dist/interactors/Tooltip.svelte

@@ -2,8 +2,12 @@
   Tooltip.svelte - Display component for data tooltips.
 
   Reads from TooltipManager (via context) and renders a floating tooltip
-  at the cursor position. Uses CSS anchor positioning for automatic
-  edge-aware placement.
+  at the cursor. It is a manual popover, so it paints in the top layer and no
+  overflow, scroll area, stacking context or transformed ancestor clips it. It
+  stays in the chart's DOM, so inherited theme variables and scoped styles still
+  apply. Placed in viewport pixels with the `translate` property (no layout per
+  move), flipped and clamped against the viewport, and measured by a
+  ResizeObserver rather than by reading its size.
 
   Always renders one point at a time (stable layout). When multiple
   points match, colored dots appear at the bottom and the user can
@@ -14,6 +18,7 @@
 	import { format as d3format } from 'd3-format';
 	import { categoryLabel } from '../query-engine/categorical-identity';
 	import type { ChartContext, ContinuousScaleState } from '../types';
+	import { otherTooltipRows } from './other-tooltip';
 
 	const commaFormat = d3format(',.4~g');
 
@@ -36,40 +41,76 @@
 	let colorField = $derived(tm?.currentColorField ?? null);
 	let channelFields = $derived(tm?.currentChannelFields ?? null);
 	let displayFields = $derived(tm?.currentDisplayFields ?? null);
-	let px = $derived(tm?.pointerScreenX ?? 0);
-	let py = $derived(tm?.pointerScreenY ?? 0);
+	let px = $derived(tm?.pointerClientX ?? 0);
+	let py = $derived(tm?.pointerClientY ?? 0);
 
-	// High-water mark for tooltip width — grows but never shrinks.
-	let tooltipEl: HTMLDivElement;
+	// The tooltip's size, from a ResizeObserver: read after the browser's own
+	// layout, so measuring forces none. Its width is a high-water mark (grows,
+	// never shrinks) so it does not jitter between points: content wider than
+	// min-width makes the observed width exceed it, and min-width follows.
 	let minWidth = $state(0);
 	let tooltipW = $state(0);
 	let tooltipH = $state(0);
 
-	$effect(() => {
-		// Dependencies: re-measure when focused point or index changes
-		void point;
-		void focusedIndex;
-		if (!visible || !tooltipEl) return;
-		const prev = tooltipEl.style.minWidth;
-		tooltipEl.style.minWidth = '0px';
-		const natural = tooltipEl.offsetWidth;
-		tooltipEl.style.minWidth = prev;
-		if (natural > minWidth) minWidth = natural;
-		tooltipW = tooltipEl.offsetWidth;
-		tooltipH = tooltipEl.offsetHeight;
-	});
+	function measure(el: HTMLElement) {
+		const observer = new ResizeObserver((entries) => {
+			const box = entries[entries.length - 1].borderBoxSize[0];
+			// A closed popover is display: none and reports 0: keep the last size.
+			if (box.inlineSize === 0) return;
+			tooltipW = box.inlineSize;
+			tooltipH = box.blockSize;
+			if (box.inlineSize > minWidth) minWidth = box.inlineSize;
+		});
+		observer.observe(el);
+		return () => observer.disconnect();
+	}
+
+	// The viewport, without the scrollbars. Read when the tooltip opens and on
+	// resize, never per move.
+	let viewW = $state(0);
+	let viewH = $state(0);
+	function readViewport() {
+		const root = document.documentElement;
+		viewW = root.clientWidth;
+		viewH = root.clientHeight;
+	}
+
+	// Open in the top layer while shown; closed again once it has faded out, so a
+	// page of charts keeps at most the hovered one's tooltip there.
+	function popover(el: HTMLElement) {
+		if (visible && !el.matches(':popover-open')) {
+			readViewport();
+			el.showPopover();
+		}
+	}
+	function handleTransitionEnd(event: TransitionEvent) {
+		const el = event.currentTarget as HTMLElement;
+		if (event.propertyName === 'opacity' && !visible && el.matches(':popover-open')) {
+			el.hidePopover();
+		}
+	}
 
-	// Flip when tooltip would overflow chart bounds, with hysteresis to prevent jitter
+	// Left of the cursor when it fits, else right; below it, else above. With
+	// hysteresis so it does not jitter at the edge. Then clamped into the viewport,
+	// for a tooltip that fits on neither side.
 	const GAP = 12;
 	const HYSTERESIS = 40;
-	let flippedX = $state(true);
-	let flippedY = $state(false);
-	$effect(() => {
+	const MARGIN = 8;
+	let leftOfCursor = true;
+	let aboveCursor = false;
+	const flippedX = $derived.by(() => {
 		const spaceLeft = px - tooltipW - GAP;
-		flippedX = spaceLeft >= 0 && (!flippedX ? spaceLeft >= HYSTERESIS : true);
-		const spaceY = chart.height - py - tooltipH;
-		flippedY = spaceY < 0 || (flippedY && spaceY < HYSTERESIS);
+		leftOfCursor = spaceLeft >= 0 && (leftOfCursor || spaceLeft >= HYSTERESIS);
+		return leftOfCursor;
 	});
+	const flippedY = $derived.by(() => {
+		const spaceBelow = viewH - py - tooltipH;
+		aboveCursor = spaceBelow < 0 || (aboveCursor && spaceBelow < HYSTERESIS);
+		return aboveCursor;
+	});
+	const clamp = (v: number, max: number) => Math.max(MARGIN, Math.min(v, max - MARGIN));
+	const left = $derived(clamp(flippedX ? px - tooltipW - GAP : px + GAP, viewW - tooltipW));
+	const top = $derived(clamp(flippedY ? py - tooltipH + 4 : py - 4, viewH - tooltipH));
 
 	// Transform origin: corner nearest the anchor point
 	let originX = $derived(flippedX ? '100%' : '0%');
@@ -95,7 +136,8 @@
 		if (!point) return [];
 		if (displayFields) return displayFields.filter((k) => k in point);
 		if (fields) return fields.filter((k) => k in point);
-		return Object.keys(point);
+		// Keys starting with `_` are kept for clicks (a band's raw id), never shown.
+		return Object.keys(point).filter((k) => !k.startsWith('_'));
 	});
 
 	// Scale-aware formatters for numeric values (same as MarginLabel)
@@ -110,6 +152,14 @@
 			: null
 	);
 
+	// An Other bar's rows, after the point's own: written with the value axis's format.
+	let otherRows = $derived.by(() => {
+		const stats = tm?.focusedOtherStats;
+		if (!stats || !point) return [];
+		const format = ('__bandIdX' in point ? yFormat : xFormat) ?? commaFormat;
+		return otherTooltipRows(stats, format);
+	});
+
 	function formatValue(key: string, value: unknown) {
 		if (formatters[key]) return formatters[key](value);
 		if (typeof value === 'number') {
@@ -123,20 +173,23 @@
 
 	const channelIcons: Record<string, string> = { x: '\u2192', y: '\u2191' };
 
-	// Computed style values — kept here so Prettier can't break them by line-wrapping
-	const translateX = $derived(flippedX ? 'calc(-100% - 12px)' : '12px');
-	const translateY = $derived(flippedY ? 'calc(-100% + 4px)' : '-4px');
-	const translate = $derived(`${translateX} ${translateY}`);
+	// Computed style values — kept here so Prettier can't break them by line-wrapping.
+	// `translate`, not `transform` or left/top: it moves the box without layout, and
+	// it applies after `scale`, so the pop-in scales about the box's own corner.
+	const translate = $derived(`${left}px ${top}px`);
 	const transformOrigin = $derived(`${originX} ${originY}`);
 </script>
 
-<!-- Tooltip positioned via JS with flip detection -->
+<svelte:window onresize={readViewport} />
+
+<!-- In the top layer, placed in viewport pixels with flip detection -->
 <div
 	class="tooltip"
 	class:visible
-	bind:this={tooltipEl}
-	style:left="{px}px"
-	style:top="{py}px"
+	popover="manual"
+	{@attach measure}
+	{@attach popover}
+	ontransitionend={handleTransitionEnd}
 	style:translate
 	style:transform-origin={transformOrigin}
 	style:min-width="{minWidth}px"
@@ -155,6 +208,12 @@
 			</span>
 		</div>
 	{/each}
+	{#each otherRows as row (row.key)}
+		<div class="row">
+			<span class="key">{row.key}</span>
+			<span class="value">{row.value}</span>
+		</div>
+	{/each}
 	<div class="dots" class:show={isMulti}>
 		{#each matched as m, i (i)}
 			<span
@@ -168,24 +227,53 @@
 
 <style>
 	.tooltip {
-		position: absolute;
-		background: var(--fjader-tooltip-bg, rgba(0, 0, 0, 0.88));
-		color: var(--fjader-tooltip-text, #ffffff);
+		/* A popover in the top layer: fixed to the viewport at its origin, placed by
+		   translate. Resets the UA popover box (inset, margin, border, overflow). */
+		position: fixed;
+		inset: 0 auto auto 0;
+		margin: 0;
+		border: 0;
+		overflow: visible;
+		/* Colours, highest first: the app's --fjader-tooltip-bg/-text; the mode a
+		   data-fjader-tooltip ancestor picks; contrast. light-dark() resolves against
+		   the color-scheme the tooltip inherits from the chart's DOM ancestors. */
+		background: var(
+			--fjader-tooltip-bg,
+			var(--_fjader-tooltip-bg, light-dark(rgba(0, 0, 0, 0.88), rgba(255, 255, 255, 0.92)))
+		);
+		color: var(--fjader-tooltip-text, var(--_fjader-tooltip-text, light-dark(#ffffff, #111827)));
 		padding: 6px 10px;
 		border-radius: 4px;
 		font-family: var(--fjader-font, system-ui, sans-serif);
 		font-size: 12px;
 		line-height: 1.4;
 		pointer-events: none;
-		z-index: 1000;
 		white-space: nowrap;
-		box-shadow: 0 2px 8px rgba(0, 0, 0, 0.25);
+		box-shadow:
+			0 0 0 1px var(--_fjader-tooltip-ring, transparent),
+			0 2px 8px rgba(0, 0, 0, 0.25);
 		opacity: 0;
 		scale: 0.78;
 		transition:
 			opacity 100ms ease-out,
 			scale 200ms cubic-bezier(0.34, 1.3, 0.64, 1);
-		will-change: opacity, scale;
+		will-change: opacity, scale, translate;
+	}
+
+	/* The mode, set on any ancestor (the page, a panel, a chart through ChartContainer's
+	   tooltipScheme): custom properties inherit, so the nearest one wins. `contrast` is
+	   the opposite of the scheme, `follow` the same, with a ring to separate it from a
+	   background of its own colour. */
+	:global([data-fjader-tooltip='contrast']) {
+		--_fjader-tooltip-bg: light-dark(rgba(0, 0, 0, 0.88), rgba(255, 255, 255, 0.92));
+		--_fjader-tooltip-text: light-dark(#ffffff, #111827);
+		--_fjader-tooltip-ring: transparent;
+	}
+
+	:global([data-fjader-tooltip='follow']) {
+		--_fjader-tooltip-bg: light-dark(rgba(255, 255, 255, 0.96), rgba(31, 41, 55, 0.96));
+		--_fjader-tooltip-text: light-dark(#111827, #f9fafb);
+		--_fjader-tooltip-ring: light-dark(rgba(17, 24, 39, 0.1), rgba(255, 255, 255, 0.12));
 	}
 
 	.tooltip.visible {
@@ -193,6 +281,15 @@
 		scale: 1;
 	}
 
+	/* Opening the popover takes it out of display: none, which runs no transition:
+	   start the pop-in from the hidden look. */
+	@starting-style {
+		.tooltip.visible {
+			opacity: 0;
+			scale: 0.78;
+		}
+	}
+
 	.row {
 		display: flex;
 		gap: 8px;