@fjader/svelte 0.2.3 → 0.2.4

package/dist/components/marks/RectMark.svelte

@@ -48,6 +48,7 @@
 		table,
 		selection = undefined,
 		selectionResponse = undefined,
+		nulls = undefined,
 		x = null,
 		x1: x1Prop = null,
 		x2: x2Prop = null,
@@ -97,6 +98,7 @@
 		transforms: () => transforms,
 		selection: () => selection,
 		selectionResponse: () => selectionResponse,
+		nulls: () => nulls,
 		limit: () => limit,
 		preferredXScaleType: () => preferredXScaleType,
 		preferredYScaleType: () => preferredYScaleType,

package/dist/components/marks/RectXMark.svelte

@@ -48,6 +48,7 @@
 		table,
 		selection = undefined,
 		selectionResponse = undefined,
+		nulls = undefined,
 		x,
 		x1: x1Prop,
 		x2: x2Prop,
@@ -92,6 +93,7 @@
 		transforms: () => transforms,
 		selection: () => selection,
 		selectionResponse: () => selectionResponse,
+		nulls: () => nulls,
 		limit: () => limit,
 		preferredYScaleType: () => preferredYScaleType,
 		fitDomain: () => fitDomain,

package/dist/components/marks/RectYMark.svelte

@@ -49,6 +49,7 @@
 		table,
 		selection = undefined,
 		selectionResponse = undefined,
+		nulls = undefined,
 		x = null,
 		x1: x1Prop = null,
 		x2: x2Prop = null,
@@ -94,6 +95,7 @@
 		transforms: () => transforms,
 		selection: () => selection,
 		selectionResponse: () => selectionResponse,
+		nulls: () => nulls,
 		limit: () => limit,
 		preferredXScaleType: () => preferredXScaleType,
 		fitDomain: () => fitDomain,

package/dist/components/marks/RuleMarkX.svelte

@@ -36,6 +36,7 @@
 		table = undefined,
 		selection = undefined,
 		selectionResponse = undefined,
+		nulls = undefined,
 		x,
 		y: yShorthand = undefined,
 		y1: y1Prop = undefined,
@@ -124,6 +125,7 @@
 			transforms: () => transforms,
 			selection: () => selection,
 			selectionResponse: () => selectionResponse,
+			nulls: () => nulls,
 			limit: () => limit,
 			sort: () => sort,
 			domain: () => domain,

package/dist/components/marks/RuleMarkY.svelte

@@ -36,6 +36,7 @@
 		table = undefined,
 		selection = undefined,
 		selectionResponse = undefined,
+		nulls = undefined,
 		y,
 		x: xShorthand = undefined,
 		x1: x1Prop = undefined,
@@ -122,6 +123,7 @@
 			transforms: () => transforms,
 			selection: () => selection,
 			selectionResponse: () => selectionResponse,
+			nulls: () => nulls,
 			limit: () => limit,
 			sort: () => sort,
 			domain: () => domain,

package/dist/components/marks/TextMark.svelte

@@ -43,6 +43,7 @@
 		table,
 		selection = undefined,
 		selectionResponse = undefined,
+		nulls = undefined,
 		x,
 		y,
 		text,
@@ -131,6 +132,9 @@
 		get selectionResponse() {
 			return selectionResponse;
 		},
+		get nulls() {
+			return nulls;
+		},
 		get limit() {
 			return limit;
 		},
@@ -387,17 +391,12 @@
 		// range: a label off the left edge, or below the axis, where the shader
 		// discards the bar it belongs to. The GPU states this discard explicitly
 		// rather than leaving it to the scissor rect, and so does this.
-		const slotted = (
-			band: BandScaleState,
-			raw: string | number,
-			range: number,
-			axis: 'x' | 'y'
-		) => {
+		const slotted = (band: BandScaleState, raw: string | number, range: number) => {
 			const key = bandSlotKey(band, raw);
 			if (key == null) return null;
 			// Asked once and handed on: tickPosition would look it up again.
 			const slot = band.tickSlot(key);
-			return slot < 0 ? null : band.slotPosition(slot, range, axis);
+			return slot < 0 ? null : band.slotPosition(slot, range);
 		};
 
 		const newPos = new Array(items.length);
@@ -406,13 +405,13 @@
 			let px, py;
 
 			if (xBand) {
-				px = slotted(xBand, xRaw[dataIdx], rangeX, 'x');
+				px = slotted(xBand, xRaw[dataIdx], rangeX);
 			} else {
 				px = xScale(xRaw[dataIdx]);
 			}
 
 			if (yBand) {
-				py = slotted(yBand, yRaw[dataIdx], rangeY, 'y');
+				py = slotted(yBand, yRaw[dataIdx], rangeY);
 			} else {
 				py = yScale(yRaw[dataIdx]);
 			}

package/dist/components/marks/lifecycle/MarkLifecycleV2.svelte.d.ts

@@ -19,7 +19,7 @@
  */
 import type { ScaleRequirement } from '../../../scales/ScalePriorities';
 import type { DataAccessor } from '../../../data/DataAccessor';
-import type { FieldRef, NormalizedSortConfig, Transform, ChartContext } from '../../../types';
+import type { FieldRef, NormalizedSortConfig, Transform, ChartContext, NullsResponse } from '../../../types';
 import type { ColorScaleState } from '../../../scales/ColorScaleState.svelte';
 import type { SizeScaleState } from '../../../scales/SizeScaleState.svelte';
 import type { QueryEngine } from '../../../query-engine/QueryEngine';
@@ -27,6 +27,7 @@ import type { FilterGroup } from '../../../query-engine/FilterGroup.svelte';
 import { type SelectionResponse } from '../../rendering/activity-reads';
 import type { MarkLODSurface } from '../../../lod/rung-types';
 import type { GPUCoordinator } from '../../../gpu/GPUCoordinator.svelte';
+import { OtherRows } from './other-rows.svelte';
 export interface MarkLifecycleV2Config {
     markType: string;
     supportedScaleTypes: {
@@ -93,6 +94,8 @@ export interface ReactiveConfig {
     readonly fitDomain: 'x' | 'y' | boolean | undefined;
     readonly tip: (unknown | '*')[] | false | undefined;
     readonly selectionResponse: SelectionResponse | undefined;
+    readonly nulls: NullsResponse | undefined;
+    readonly contributeDomain: boolean | undefined;
 }
 export declare class MarkLifecycleV2 {
     #private;
@@ -101,6 +104,8 @@ export declare class MarkLifecycleV2 {
         gpuCoordinator?: GPUCoordinator | null;
         onMarkLOD?: ((surface: MarkLODSurface | null) => void) | null;
     });
+    /** What this mark's Other rows hold, and what is done with it. */
+    readonly otherRows: OtherRows;
     /**
      * The axis whose rows are one per category, in category order — or null.
      *

package/dist/components/marks/lifecycle/MarkLifecycleV2.svelte.js

@@ -42,6 +42,7 @@ import { buildQueryParts, assembleQuery, castReal } from './query-builder';
 import { setScalesReady, markDeferredScalesReady, setInitialContinuousDomains, registerDataDerivedDomains } from './domain-registration';
 import { fetchCategoricalDomains, fetchGlobalAggregates } from './domain-queries';
 import { transformScaleKey } from './transform-scale-key';
+import { OtherRows } from './other-rows.svelte';
 // ---------------------------------------------------------------------------
 // MarkLifecycleV2
 // ---------------------------------------------------------------------------
@@ -185,8 +186,68 @@ export class MarkLifecycleV2 {
         this.#inlineIdentityColumns(resolvedSelect);
         this.#inlineTimeOffsets(resolvedSelect);
         const parts = buildQueryParts(resolvedSelect, this.#config._orderConfig ?? null, this.#transformCompiler.hasSQLTransforms(), passthroughChannels);
+        const nullDrops = this.#nullDrops(semanticSelect, resolvedSelect);
+        if (nullDrops.length > 0)
+            parts.nullDrops = nullDrops;
         return parts;
     });
+    /**
+     * The mark's categorical channels, each with the source expression it draws:
+     * a band or point axis, an ordinal colour, a separate series, and the facet
+     * (`__facet`, from the chart's fx). What `nulls="drop"` filters.
+     */
+    #categoricalChannels(select) {
+        const out = [];
+        const categorical = (type) => type === 'band' || type === 'point';
+        if (categorical(this.actualXScaleType))
+            out.push(['x', select.x]);
+        if (categorical(this.actualYScaleType))
+            out.push(['y', select.y]);
+        const colorChannel = this.#config.colorChannel || 'fill';
+        if (this.#colorScaleState?.isOrdinal)
+            out.push([colorChannel, select[colorChannel]]);
+        const seriesChannel = this.#config._orderConfig?.seriesChannel ?? null;
+        if (seriesChannel && seriesChannel !== colorChannel) {
+            out.push([seriesChannel, select[seriesChannel]]);
+        }
+        if (this.#chartContext.fx)
+            out.push(['__facet', this.#chartContext.fx]);
+        // Only row-level values: an aggregate has no NULL category to drop.
+        return out.filter(([, source]) => source != null &&
+            typeof source !== 'number' &&
+            !(isNode(source) && isAggregateExpression(source)));
+    }
+    /**
+     * `nulls="drop"`, by channel (see QueryParts.nullDrops). A channel the query
+     * selects as its dim's id column drops the NULL category's id; one still
+     * carrying its raw value (identity not landed yet) drops SQL NULL. Read off
+     * the select itself, so the two cannot disagree: inlining an id column is
+     * what changes the channel's expression.
+     */
+    #nullDrops(semantic, resolved) {
+        if (this.#reactiveConfig.nulls !== 'drop')
+            return [];
+        const drops = [];
+        for (const [channel, source] of this.#categoricalChannels(semantic)) {
+            const encoded = channel === '__facet' ? '__facet' in resolved : resolved[channel] !== source;
+            if (channel === '__facet' && !encoded)
+                continue;
+            const key = encoded ? identityKeyFor(source)?.key : null;
+            const nullId = key ? this.#queryEngine.identityFor(key).nullId : null;
+            drops.push({ channel, nullId });
+        }
+        return drops;
+    }
+    /**
+     * `nulls="drop"` for a query over the RAW select (no id columns, no
+     * `__facet`): `<source> IS NOT NULL` per categorical channel, the facet's
+     * on the chart's fx. Passed as that query's filter.
+     */
+    #rawNullFilters(select) {
+        if (this.#reactiveConfig.nulls !== 'drop')
+            return [];
+        return this.#categoricalChannels(select).map(([, source]) => isNotNull((typeof source === 'string' ? sqlColumn(source) : source)));
+    }
     // --- Domain State ---
     #channelsNeedingDataDomain = new Set();
     #dataDerivedDomainsSet = $state(false);
@@ -257,6 +318,25 @@ export class MarkLifecycleV2 {
         // than rebuilding. With no sort it passes the query through.
         this.#transformCompiler = new TransformCompiler(withRanking(withDenseCategories(config.transforms || [], config.dense !== false), () => this.#rankingSort), this.#transformConfig);
         this.#detectAutoBins();
+        this.otherRows = new OtherRows({
+            queryEngine,
+            filterGroup,
+            markId,
+            table: () => this.#handle?.arrowTable ?? null,
+            dataVersion: () => this.dataVersion,
+            identity: () => this.#identity,
+            identityKey: (axis) => this.#identityKey(axis)?.key ?? null,
+            filtered: () => this.#reactiveConfig.selectionResponse === 'filter',
+            plan: () => this.#splitPlan,
+            colorKey: () => {
+                const color = this.#colorScaleState;
+                return color?.isOrdinal ? color.identityKey : null;
+            },
+            bandScaleKey: (axis) => {
+                const band = (axis === 'x' ? this.#chartContext.xScaleState : this.#chartContext.yScaleState);
+                return band?.identityKey ?? null;
+            }
+        });
         // AdaptiveBinRung for binned marks (watches viewport domain, triggers rebin)
         if (this.#autoBinNodes.size > 0 && options?.gpuCoordinator) {
             const binAxes = [...this.#autoBinNodes.keys()].map((ch) => (ch.startsWith('x') ? 'x' : 'y'));
@@ -342,7 +422,8 @@ export class MarkLifecycleV2 {
             return;
         this.#identityFields.clear();
         // The Other ids name rows of the dropped dims. Every holder lets go, so
-        // the scale acquires afresh when setup re-runs.
+        // the scale acquires afresh when setup re-runs; so do the registered rows.
+        this.otherRows.unregister();
         for (const scale of [...this.#otherScales])
             this.#releaseOther(scale);
         // Every dim it names just went away — topN must not bucket into one.
@@ -491,14 +572,35 @@ export class MarkLifecycleV2 {
                 return;
             untrack(() => {
                 this.#handleDataDomains(dv);
+                this.otherRows.register();
             });
         });
-        // Tooltip: write tooltip table when data updates (debounced).
+        // Tooltip: two effects, so a data update does not take the table away.
+        //
+        // This one owns the table's lifetime: it drops it when tooltips go from
+        // wanted to not. It used to be one effect with the write below, and its
+        // cleanup then ran on every data update too: the table was dropped and
+        // marked not ready, the mark's tooltip unregistered, and the hovered row
+        // went with it. A click right after a data update found no row under the
+        // pointer, read as a click on empty space and cleared the selection, and
+        // the next click did nothing until the pointer moved.
+        $effect(() => {
+            const tooltipConfig = this.#reactiveConfig.tooltip;
+            const fitDomain = this.#reactiveConfig.fitDomain;
+            if (tooltipConfig === false && !fitDomain)
+                return;
+            return () => {
+                clearTimeout(this.#tooltipWriteTimeout);
+                this.#tooltipTableReady = false;
+                this.#queryEngine.exec(`DROP TABLE IF EXISTS "${this.#tooltipTableName}"`).catch(() => { });
+            };
+        });
+        // And this one rewrites it when data updates (debounced). The old table
+        // stays readable until the rewrite replaces it.
         $effect(() => {
             const tooltipConfig = this.#reactiveConfig.tooltip;
             const fitDomain = this.#reactiveConfig.fitDomain;
-            const tooltipWanted = tooltipConfig !== false || !!fitDomain;
-            if (!tooltipWanted)
+            if (tooltipConfig === false && !fitDomain)
                 return;
             const dataVersion = this.dataVersion;
             if (dataVersion === 0)
@@ -511,12 +613,7 @@ export class MarkLifecycleV2 {
                         this.#writeTooltipTable(data);
                 }, 300);
             });
-            // Cleanup: when tooltip goes true→false, drop the temp table.
-            return () => {
-                clearTimeout(this.#tooltipWriteTimeout);
-                this.#tooltipTableReady = false;
-                this.#queryEngine.exec(`DROP TABLE IF EXISTS "${this.#tooltipTableName}"`).catch(() => { });
-            };
+            return () => clearTimeout(this.#tooltipWriteTimeout);
         });
         // fitDomain — query DuckDB for fitted axis extent on driving axis change.
         $effect(() => {
@@ -612,7 +709,7 @@ export class MarkLifecycleV2 {
             const [schemaColumns, fetchCount, aggResult, fieldStats] = await Promise.all([
                 // Fetch table schema (cached on QueryEngine, needed for CAST type decisions)
                 this.#queryEngine.describe(this.#config.table),
-                fetchCategoricalDomains(this.#queryEngine, this.#config.table, this.#config.select, this.actualXScaleType, this.actualYScaleType, this.#chartContext.xScaleState, this.#chartContext.yScaleState, this.#chartContext.facetBandScale, this.#chartContext.fx, this.#config.colorChannel || 'fill', this.#colorScaleState, this.#config.sizeChannel || 'r', this.#sizeScaleState, this.#seriesScaleState, seriesKey, this.#bandDomainFromData, this.#markId, this.#reactiveConfig.domain),
+                fetchCategoricalDomains(this.#queryEngine, this.#config.table, this.#config.select, this.actualXScaleType, this.actualYScaleType, this.#bandScaleForDomain('x'), this.#bandScaleForDomain('y'), this.#chartContext.facetBandScale, this.#chartContext.fx, this.#config.colorChannel || 'fill', this.#colorScaleState, this.#config.sizeChannel || 'r', this.#sizeScaleState, this.#seriesScaleState, seriesKey, this.#bandDomainFromData, this.#markId, this.#reactiveConfig.domain, this.#reactiveConfig.nulls === 'drop'),
                 fetchGlobalAggregates(this.#queryEngine, this.#config.table, this.#config.select, this.#channelsNeedingDataDomain, this.#autoBinNodes.size, this.#buildQueryForAggregates.bind(this), this.#config, this.#chartContext.xScaleState, this.#chartContext.yScaleState, this.#colorScaleState, this.#markId),
                 this.#fetchFieldStats(),
                 this.#ensureIdentityColumns()
@@ -872,7 +969,7 @@ export class MarkLifecycleV2 {
             const additionalChannels = this.#transformCompiler.getAdditionalChannels();
             const xState = this.#chartContext.xScaleState;
             const yState = this.#chartContext.yScaleState;
-            const domainResult = registerDataDerivedDomains(data, this.#channelsNeedingDataDomain, additionalChannels, this.#skipDomainUpdateForAxis, this.#config.zeroBaseline, this.actualXScaleType, this.actualYScaleType, xState, yState, this.#bandDomainFromData, this.#chartContext.xScaleState, this.#chartContext.yScaleState, this.#markId, false, // isRebinning
+            const domainResult = registerDataDerivedDomains(data, this.#channelsNeedingDataDomain, additionalChannels, this.#skipDomainUpdateForAxis, this.#config.zeroBaseline, this.actualXScaleType, this.actualYScaleType, xState, yState, this.#bandDomainFromData, this.#bandScaleForDomain('x'), this.#bandScaleForDomain('y'), this.#markId, false, // isRebinning
             this.#colorScaleState);
             this.#dataDerivedDomainsSet = domainResult.dataDerivedDomainsSet;
             this.#skipDomainUpdateForAxis = domainResult.skipDomainUpdateForAxis;
@@ -1007,11 +1104,15 @@ export class MarkLifecycleV2 {
         const identity = {};
         const describe = (channel, key, positional) => {
             const present = this.#queryEngine.presentTableFor(key, this.#config.table);
+            // nulls="drop": its rows are filtered out, and dense() must not pad a
+            // zero row for it either, or a sorted axis keeps a "(null)" slot.
+            const nullId = this.#reactiveConfig.nulls === 'drop' ? this.#queryEngine.identityFor(key).nullId : null;
             identity[channel] = {
                 dim: this.#queryEngine.dimTableFor(key),
                 size: this.#queryEngine.identityFor(key).values.length,
                 positional,
-                ...(present ? { present } : {})
+                ...(present ? { present } : {}),
+                ...(nullId !== null ? { dropNullId: nullId } : {})
             };
         };
         for (const { axis, key } of axes)
@@ -1136,6 +1237,67 @@ export class MarkLifecycleV2 {
                 this.#releaseOther(scale);
         }
     }
+    #warnedFollow = false;
+    /**
+     * Whether this mark follows its band axes instead of adding its categories to
+     * them (`contributeDomain={false}`). It cannot also choose its own categories
+     * or their order: a topN or a ranking would be what a follower exists not to
+     * do, and an explicit domain is a contribution. Such a mark is refused, once,
+     * and contributes as usual.
+     */
+    get #followsDomain() {
+        if (this.#reactiveConfig.contributeDomain !== false)
+            return false;
+        const reason = this.#transformCompiler.hasCategoryReducingTransforms()
+            ? 'a category-reducing transform (topN)'
+            : this.#rankingSort
+                ? 'a sort'
+                : this.#reactiveConfig.domain
+                    ? 'an explicit domain'
+                    : null;
+        if (!reason)
+            return true;
+        if (!this.#warnedFollow) {
+            this.#warnedFollow = true;
+            console.error(`[${this.#markId}] Unsupported: contributeDomain={false} with ${reason}. A mark that ` +
+                `follows its band axis cannot choose its own categories or their order. It will ` +
+                `contribute to the domain as usual.`);
+        }
+        return false;
+    }
+    /**
+     * The band scale of an axis, for registering this mark's categories on it:
+     * null for a mark that follows, so it registers nothing and withdraws what it
+     * had (the prop can change). The scale still draws the mark's rows, only those
+     * of categories it shows.
+     */
+    #bandScaleForDomain(axis) {
+        const scale = (axis === 'x' ? this.#chartContext.xScaleState : this.#chartContext.yScaleState);
+        // Only a band or point axis has categories to follow; a value axis is
+        // the mark's own.
+        const type = axis === 'x' ? this.actualXScaleType : this.actualYScaleType;
+        if ((type !== 'band' && type !== 'point') || !this.#followsDomain)
+            return scale;
+        scale?.removeMark(this.#markId);
+        return null;
+    }
+    /** What this mark's Other rows hold, and what is done with it. */
+    otherRows;
+    /** What the mark is, for whether its Other bar splits; null before setup completes. */
+    get #splitPlan() {
+        if (!this.setupComplete)
+            return null;
+        const markType = this.#transformConfig.markType;
+        const length = markType === 'barx' ? this.#transformConfig.x : this.#transformConfig.y;
+        return {
+            markType,
+            length,
+            by: this.#transformCompiler.otherBy(),
+            expr: length ? this.#config.select[length] : undefined,
+            hasOther: this.#transformCompiler.hasSyntheticOtherBucket(),
+            hasJsTransforms: this.#transformCompiler.jsTransforms.length > 0
+        };
+    }
     /** The band scales whose Other bucket this mark holds a claim on. */
     #otherScales = new Set();
     #releaseOther(scale) {
@@ -1195,10 +1357,12 @@ export class MarkLifecycleV2 {
         // Build raw query parts directly from config.select (no identity columns,
         // no bin resolution — scale states aren't ready yet during Phase 1).
         const parts = buildQueryParts(this.#config.select, this.#config._orderConfig ?? null, this.#transformCompiler.hasSQLTransforms());
+        // Domains from the rows the mark draws: without what nulls="drop" leaves
+        // out. This select is raw, so the filter is on the raw values.
         const q = assembleQuery({
             table: this.#config.table,
             parts,
-            filter,
+            filter: [...filter, ...this.#rawNullFilters(this.#config.select)],
             transformCompiler: this.#transformCompiler
         });
         if (!q)
@@ -1496,10 +1660,8 @@ export class MarkLifecycleV2 {
                 // the rest are scalars (the rank, id columns), cheap to keep, and the
                 // lists are the only ones whose size grows with the field.
                 const withoutMembers = withoutOtherMembers(tooltipQuery);
-                await this.#queryEngine.exec([
-                    `DROP TABLE IF EXISTS "${tableName}"`,
-                    `CREATE TEMP TABLE "${tableName}" AS SELECT *${replaceClause} FROM (${withoutMembers})${orderClause}`
-                ]);
+                // One statement: a hover query never finds the table missing.
+                await this.#queryEngine.exec(`CREATE OR REPLACE TEMP TABLE "${tableName}" AS SELECT *${replaceClause} FROM (${withoutMembers})${orderClause}`);
             }
             else {
                 // Path B: Serialize transformed data via SQL VALUES.
@@ -1554,6 +1716,9 @@ export class MarkLifecycleV2 {
                 }
             }
             this.#tooltipTableReady = true;
+            // The row under a still pointer was read from the old table: read it
+            // again, so the tooltip and a click show the new data without a move.
+            this.#chartContext.tooltipManager?.refresh();
             this.#onTooltipTableWritten();
         }
         catch (error) {
@@ -1624,6 +1789,9 @@ export class MarkLifecycleV2 {
         }
         Object.assign(sidecarSelect, tipExtras);
         const sidecarParts = buildQueryParts(sidecarSelect, undefined, this.#transformCompiler.hasSQLTransforms());
+        // The same rows as the mark: it leaves out what the mark leaves out. Its
+        // select holds every non-aggregate channel, so each dropped one is there.
+        sidecarParts.nullDrops = this.#resolvedQueryParts.nullDrops;
         const filter = this.#filterGroup.selection.predicate(this.#route) ?? [];
         const sidecarQuery = assembleQuery({
             table: this.#sourceTable,
@@ -1822,6 +1990,7 @@ export class MarkLifecycleV2 {
         this.#destroyed = true;
         this.#identityResetOff?.();
         this.#identityResetOff = null;
+        this.otherRows.unregister();
         for (const scale of [...this.#otherScales])
             this.#releaseOther(scale);
         this.#handle?.destroy();

package/dist/components/marks/lifecycle/domain-queries.d.ts

@@ -14,7 +14,9 @@ import type { ContinuousScaleState } from '../../../types';
 export declare function fetchCategoricalDomains(coordinator: QueryEngine, table: string, select: Record<string, unknown>, actualXScaleType: string, actualYScaleType: string, xScaleState: BandScaleState | null, yScaleState: BandScaleState | null, facetBandScale: BandScaleState | null | undefined, fx: unknown, colorChannel: string, colorScaleState: ColorScaleState | null, sizeChannel: string, sizeScaleState: SizeScaleState | null, seriesScaleState: ColorScaleState | null, seriesChannel: string | null, bandDomainFromData: boolean, markId: string, explicitDomain?: {
     x?: DimValue[];
     y?: DimValue[];
-} | null): Promise<number>;
+} | null, 
+/** nulls="drop": the band and facet domains leave out the NULL category. */
+dropNull?: boolean): Promise<number>;
 /**
  * Fetch global min/max extents for aggregated fields using a "sidecar" query.
  * Runs the same aggregation as the main query but without filters, wrapped

package/dist/components/marks/lifecycle/domain-queries.js

@@ -10,7 +10,13 @@ import { identityKeyFor } from '../../../query-engine/identity-key';
  *
  * Returns the number of fetches executed (for logging).
  */
-export async function fetchCategoricalDomains(coordinator, table, select, actualXScaleType, actualYScaleType, xScaleState, yScaleState, facetBandScale, fx, colorChannel, colorScaleState, sizeChannel, sizeScaleState, seriesScaleState, seriesChannel, bandDomainFromData, markId, explicitDomain) {
+export async function fetchCategoricalDomains(coordinator, table, select, actualXScaleType, actualYScaleType, xScaleState, yScaleState, facetBandScale, fx, colorChannel, colorScaleState, sizeChannel, sizeScaleState, seriesScaleState, seriesChannel, bandDomainFromData, markId, explicitDomain, 
+/** nulls="drop": the band and facet domains leave out the NULL category. */
+dropNull = false) {
+    const categoriesOf = (key) => {
+        const categories = coordinator.categoryValues(key, table);
+        return dropNull ? categories.filter((c) => c !== null) : categories;
+    };
     const fetches = [];
     const setupFetch = (axis, field, scaleState) => {
         if (!field || !scaleState)
@@ -65,7 +71,7 @@ export async function fetchCategoricalDomains(coordinator, table, select, actual
             // Idempotent and coalesced — the mark's own setup calls this too.
             await coordinator.ensureColumns(table, { categorical: [identityField] });
             // This table's categories: the dim spans every table on the field.
-            const categories = coordinator.categoryValues(identityField.key, table);
+            const categories = categoriesOf(identityField.key);
             // A snapshot of the real categories. The scale adopts the live
             // identity itself in MarkLifecycleV2's #ensureIdentityColumns, which
             // also covers the explicit-domain axes that never reach this branch.
@@ -103,9 +109,8 @@ export async function fetchCategoricalDomains(coordinator, table, select, actual
             // Registered from the data.
         }
         else if (explicitDomain?.y && yScaleState) {
-            // Y band scale maps index 0 → bottom, so reverse the user's
-            // top-to-bottom array to match GPU rendering order.
-            deferredExplicitY = [...explicitDomain.y].reverse();
+            // Slot 0 is at the top of a y band axis, so the list is used as given.
+            deferredExplicitY = explicitDomain.y;
         }
         else {
             setupFetch('y', select.y, yScaleState);
@@ -123,7 +128,7 @@ export async function fetchCategoricalDomains(coordinator, table, select, actual
         fetches.push((async () => {
             // Idempotent and coalesced — the mark's own setup calls this too.
             await coordinator.ensureColumns(table, { categorical: [facetKey] });
-            const categories = coordinator.categoryValues(facetKey.key, table);
+            const categories = categoriesOf(facetKey.key);
             if (categories.length > 0)
                 facetBandScale.addMark(categories, markId);
         })());

package/dist/components/marks/lifecycle/domain-registration.js

@@ -193,12 +193,8 @@ export function registerDataDerivedDomains(data, channelsNeedingDataDomain, addi
                 // order the ranked query had. See RANK_COLUMN.
                 const ranked = data.getColumn(RANK_COLUMN) != null;
                 const ids = extractIdsRankedFromData(data, axis, RANK_COLUMN);
-                // A y band axis puts slot 0 at the bottom and a ranking is read
-                // from the top. Reversed here, once, for every ranked axis —
-                // topN's and the sort's alike — rather than by whichever transform
-                // produced the rank.
-                if (ranked && axis === 'y')
-                    ids.reverse();
+                // Used as ranked on both axes: slot 0 is at the left of x and the
+                // top of y, where a ranking is read from.
                 if (ids.length === 0)
                     continue;
                 // `sorted` says this list is a ranking the axis should prefer over