@fjader/svelte 0.2.2 → 0.2.4

package/dist/scales/ScaleRegistry.svelte.js

@@ -9,6 +9,7 @@ import { BandScaleState } from './BandScaleState.svelte';
 import { ColorScaleState } from './ColorScaleState.svelte';
 import { SizeScaleState } from './SizeScaleState.svelte';
 import { scaleOrdinal } from 'd3-scale';
+import { MAX_COLOR_SLOTS } from '../gpu/ColorScaleShaderLib';
 import { isTransformType } from './color-utils';
 // Helper to stringify sorted
 const stableStringify = (obj) => {
@@ -50,7 +51,8 @@ export class ScaleRegistry {
     #nextColorSlot = 0;
     #nextRampSlot = 0;
     #nextPaletteSlot = 0;
-    #maxColorSlots = 64;
+    // The shader's array length and the coordinator's buffer size, stated once.
+    #maxColorSlots = MAX_COLOR_SLOTS;
     #maxRampSlots = 64;
     #maxPaletteSlots = 64;
     // Size scale slot management
@@ -348,6 +350,25 @@ export class ScaleRegistry {
     chartsUsing(scale) {
         return this.#chartsFor.get(scale) ?? NO_CHARTS;
     }
+    /**
+     * Fill `out` with every chart drawing a scale on the categorical field
+     * `key` (by identity key), each once: the charts a selection fade on that
+     * field redraws. A superset of the charts whose marks read the field's
+     * activity, since every such mark draws through a scale on it; the extra
+     * charts (other groups, marks holding the scale without reading it) redraw
+     * for the 0.25 s of a fade. Read on every frame a fade runs.
+     */
+    chartsDrawingField(key, out) {
+        for (const [scale, charts] of this.#chartsFor) {
+            if (scale.identityKey !== key)
+                continue;
+            for (let i = 0; i < charts.length; i++) {
+                if (!out.includes(charts[i]))
+                    out.push(charts[i]);
+            }
+        }
+        return out;
+    }
     /** Re-derive one scale's redraw list. The only writer. */
     #publishCharts(scale, chartIds) {
         this.#chartsFor.set(scale, Array.from(chartIds));

package/dist/scales/TimeScaleState.svelte.js

@@ -20,7 +20,13 @@ export class TimeScaleState extends LinearScaleState {
         return 'time';
     }
     // --- Time Metadata ---
-    #t0 = null; // Origin Date (raw global min datetime)
+    /**
+     * Origin Date (raw global min datetime). State, because SQL is built from
+     * it: a mark's offset select and a brush's predicate are $derived, and one
+     * computed before the first datetime extent landed must rebuild when it
+     * does, or it keeps comparing the raw column with offsets.
+     */
+    #t0 = $state.raw(null);
     #unit = 1; // Seconds per offset unit (1 = seconds)
     // --- Datetime Extent Tracking ---
     #datetimeExtents = new Map(); // Map<markId, [minDate, maxDate]>

package/dist/spec/index.js

@@ -47,6 +47,7 @@ export async function render(target, spec, options = {}) {
     // 4. Build context map — injected into Svelte mount() so child components
     //    find these via getContext() calls (same keys as initFjader())
     const { filterGroups } = createQueryServices(queryEngine);
+    gpuCoordinator.setFilterGroups(filterGroups);
     const context = new Map();
     context.set('query-engine', queryEngine);
     context.set('filter-groups', filterGroups);

package/dist/spec/types.d.ts

@@ -133,6 +133,10 @@ export type MarkSpec = DotMarkSpec | BarXMarkSpec | BarYMarkSpec | LineMarkSpec
 interface BaseMarkSpec {
     table: string;
     selection?: string;
+    /** How the mark responds to selections in its group; see BaseMarkProps. Default 'auto'. */
+    selectionResponse?: 'auto' | 'filter';
+    /** What the mark does with NULL in its categorical channels; see BaseMarkProps. Default 'keep'. */
+    nulls?: 'keep' | 'drop';
     scheme?: ColorScheme;
     limit?: number;
     transforms?: TransformSpec[];

package/dist/theme.css

@@ -7,6 +7,11 @@
  * Or copy and customize the variables below in your own CSS.
  * All variables are optional — Fjader components have sensible
  * inline fallbacks and work without any CSS imports.
+ *
+ * The tooltip is not set here: it follows the color-scheme it inherits (the
+ * one below, or the app's own) by itself, in contrast or follow mode
+ * (data-fjader-tooltip on any ancestor, or ChartContainer's tooltipScheme).
+ * Set --fjader-tooltip-bg and --fjader-tooltip-text to override both modes.
  */
 
 :where(:root) {
@@ -16,8 +21,6 @@
 	--fjader-bg: #ffffff;
 	--fjader-primary: #3b82f6;
 	--fjader-accent: #93c5fd;
-	--fjader-tooltip-bg: rgba(0, 0, 0, 0.88);
-	--fjader-tooltip-text: #ffffff;
 	--fjader-palette-bg: rgba(0, 0, 0, 0.92);
 	--fjader-palette-text: #ffffff;
 	--fjader-palette-text-secondary: rgba(255, 255, 255, 0.5);
@@ -34,8 +37,6 @@
 		--fjader-bg: #111827;
 		--fjader-primary: #60a5fa;
 		--fjader-accent: #3b82f6;
-		--fjader-tooltip-bg: rgba(255, 255, 255, 0.92);
-		--fjader-tooltip-text: #111827;
 		--fjader-palette-bg: rgba(255, 255, 255, 0.95);
 		--fjader-palette-text: #111827;
 		--fjader-palette-text-secondary: rgba(17, 24, 39, 0.5);

package/dist/transforms/TransformCompiler.d.ts

@@ -1,4 +1,4 @@
-import type { SelectQuery } from '@uwdata/mosaic-sql';
+import type { ExprNode, SelectQuery } from '@uwdata/mosaic-sql';
 import type { Transform, SqlTransform, JsTransform, MarkConfig, ScaleMap } from '../types';
 import type { DataAccessor } from '../data/DataAccessor';
 export declare class TransformCompiler {
@@ -19,7 +19,40 @@ export declare class TransformCompiler {
      * than of the mark — its GROUP BY keys, say — merged over the mark config for
      * this call only, so the shared config object is never written per query.
      */
-    applyToQuery(query: SelectQuery, facts?: Partial<MarkConfig>): SelectQuery;
+    applyToQuery(query: SelectQuery, facts?: Partial<MarkConfig>, 
+    /** The row filters are already in the table the query reads (a preagg table). */
+    options?: {
+        skipRowFilters?: boolean;
+    }): SelectQuery;
+    /**
+     * Whether a SQL transform filters on the groups' aggregates (`having`). Its
+     * condition names aggregates over the source rows, which a pre-aggregated table
+     * would recompute over its own groups: `count(*)` counts the table's groups, not
+     * the rows, so it gives a different answer with no error.
+     *
+     * Only the user-facing `having()` does this. The built-ins (topN, rank, stack,
+     * normalize, dense) add no HAVING: each wraps the grouped query in a subquery
+     * (`Query.from({ __topn_base: query })`) and adds window functions or joins, and
+     * those work the same on a preagg table's aggregated result, which is why a topN
+     * mark is served from preagg. The only CTE is assembleQuery's window wrapper for
+     * window aggregates, applied after the transforms. A test in transforms.test.ts
+     * fails if a built-in starts to emit a HAVING; this then has to know it.
+     *
+     * Supporting `having()` on a preagg table would mean rewriting its condition the
+     * way a select channel is rewritten (sufficient-statistics: collectAggregates,
+     * sufficientStats, rewrite; an aggregate not in the select adds a partial
+     * column) and applying it to the inner grouped query BEFORE the transforms wrap
+     * it, so it ends up inside their subquery as it does on the base table.
+     */
+    hasHaving(): boolean;
+    /**
+     * The row predicates of the SQL transforms (`filter`), for a pre-aggregated
+     * table to be built with: its read cannot apply them (see SqlTransform.where).
+     * A row filter applies before grouping, so building the table with it gives the
+     * same rows the base query sees; only `filter()` is one (see hasHaving for the
+     * transforms that are not).
+     */
+    rowFilters(): ExprNode[];
     /**
      * Which channels a query with these aliases comes back aligned on, leading
      * term first, or null. Asked with the same facts as `applyToQuery`, so the
@@ -60,5 +93,7 @@ export declare class TransformCompiler {
      * before the transform can write it.
      */
     hasSyntheticOtherBucket(): boolean;
+    /** The `by` a topN Other bucket ranks by when stated explicitly, else null (its default). */
+    otherBy(): string | null;
     getCategoryTransformKey(): string | null;
 }

package/dist/transforms/TransformCompiler.js

@@ -35,10 +35,14 @@ export class TransformCompiler {
      * than of the mark — its GROUP BY keys, say — merged over the mark config for
      * this call only, so the shared config object is never written per query.
      */
-    applyToQuery(query, facts) {
+    applyToQuery(query, facts, 
+    /** The row filters are already in the table the query reads (a preagg table). */
+    options) {
         let result = query;
         const config = this.#configFor(facts);
         for (const transform of this.sqlTransforms) {
+            if (options?.skipRowFilters && transform.where !== undefined)
+                continue;
             try {
                 result = transform.apply(result, config);
             }
@@ -48,6 +52,39 @@ export class TransformCompiler {
         }
         return result;
     }
+    /**
+     * Whether a SQL transform filters on the groups' aggregates (`having`). Its
+     * condition names aggregates over the source rows, which a pre-aggregated table
+     * would recompute over its own groups: `count(*)` counts the table's groups, not
+     * the rows, so it gives a different answer with no error.
+     *
+     * Only the user-facing `having()` does this. The built-ins (topN, rank, stack,
+     * normalize, dense) add no HAVING: each wraps the grouped query in a subquery
+     * (`Query.from({ __topn_base: query })`) and adds window functions or joins, and
+     * those work the same on a preagg table's aggregated result, which is why a topN
+     * mark is served from preagg. The only CTE is assembleQuery's window wrapper for
+     * window aggregates, applied after the transforms. A test in transforms.test.ts
+     * fails if a built-in starts to emit a HAVING; this then has to know it.
+     *
+     * Supporting `having()` on a preagg table would mean rewriting its condition the
+     * way a select channel is rewritten (sufficient-statistics: collectAggregates,
+     * sufficientStats, rewrite; an aggregate not in the select adds a partial
+     * column) and applying it to the inner grouped query BEFORE the transforms wrap
+     * it, so it ends up inside their subquery as it does on the base table.
+     */
+    hasHaving() {
+        return this.sqlTransforms.some((t) => t.type === 'having');
+    }
+    /**
+     * The row predicates of the SQL transforms (`filter`), for a pre-aggregated
+     * table to be built with: its read cannot apply them (see SqlTransform.where).
+     * A row filter applies before grouping, so building the table with it gives the
+     * same rows the base query sees; only `filter()` is one (see hasHaving for the
+     * transforms that are not).
+     */
+    rowFilters() {
+        return this.sqlTransforms.flatMap((t) => (t.where === undefined ? [] : [t.where]));
+    }
     /**
      * Which channels a query with these aliases comes back aligned on, leading
      * term first, or null. Asked with the same facts as `applyToQuery`, so the
@@ -147,6 +184,12 @@ export class TransformCompiler {
     hasSyntheticOtherBucket() {
         return this.transforms.some((t) => t.type === 'topN' && t.spec?.includeOthers === true);
     }
+    /** The `by` a topN Other bucket ranks by when stated explicitly, else null (its default). */
+    otherBy() {
+        const t = this.transforms.find((t) => t.type === 'topN' && t.spec?.includeOthers === true);
+        const by = t?.spec?.by;
+        return typeof by === 'string' ? by : null;
+    }
     getCategoryTransformKey() {
         const parts = [];
         for (const t of this.transforms) {

package/dist/transforms/index.d.ts

@@ -45,6 +45,33 @@ export declare function topN(n: number | (() => number), options?: TopNOptions):
  * the identity index columns in the same result.
  */
 export declare const RANK_COLUMN = "__dplot_rank";
+/**
+ * The Other row's members: the ids of the categories folded into it, and each
+ * one's measure, as two aligned lists ordered by id. NULL on every other row.
+ *
+ * Returned by the query rather than worked out on the client, because only the
+ * query knows exactly what Other summed: under every filter the chart receives,
+ * NULL (`-1`) included when it was folded. Clicking Other selects these, and
+ * its selected share is computed from them.
+ *
+ * `__dplot_`-prefixed, like the rank, so tooltips never show them; and the SQL
+ * tooltip table leaves out every `OTHER_MEMBER_PREFIX` column, so a hover never
+ * ships them back.
+ */
+export declare const OTHER_MEMBER_PREFIX = "__dplot_other_";
+export declare const OTHER_IDS_COLUMN = "__dplot_other_ids";
+export declare const OTHER_VALUES_COLUMN = "__dplot_other_values";
+/**
+ * `sql` without Other's member lists, for tables queried on every hover. A
+ * COLUMNS filter rather than EXCLUDE, which errors on a column that is absent,
+ * as it is on every mark without an Other bucket.
+ *
+ * The `lambda c:` form, not `c ->`: DuckDB deprecated the arrow lambda in 1.3,
+ * and every SQL tooltip table goes through this, so an upgrade dropping it would
+ * break tooltips on every mark. Both DuckDB-WASM 1.30 (DuckDB 1.3.2) and the
+ * DuckDB the tests run accept it.
+ */
+export declare function withoutOtherMembers(sql: string): string;
 /**
  * Most padded rows `dense()` will produce before refusing.
  *

package/dist/transforms/index.js

@@ -14,6 +14,7 @@ export function filter(condition) {
         stage: 'sql',
         type: 'filter',
         spec: { transform: 'filter', condition: condition.toString() },
+        where: condition,
         apply(query) {
             return query.where(condition);
         },
@@ -135,6 +136,37 @@ function resolveTopNColumns(aliases, options, config) {
  * the identity index columns in the same result.
  */
 export const RANK_COLUMN = '__dplot_rank';
+/**
+ * The Other row's members: the ids of the categories folded into it, and each
+ * one's measure, as two aligned lists ordered by id. NULL on every other row.
+ *
+ * Returned by the query rather than worked out on the client, because only the
+ * query knows exactly what Other summed: under every filter the chart receives,
+ * NULL (`-1`) included when it was folded. Clicking Other selects these, and
+ * its selected share is computed from them.
+ *
+ * `__dplot_`-prefixed, like the rank, so tooltips never show them; and the SQL
+ * tooltip table leaves out every `OTHER_MEMBER_PREFIX` column, so a hover never
+ * ships them back.
+ */
+export const OTHER_MEMBER_PREFIX = '__dplot_other_';
+export const OTHER_IDS_COLUMN = `${OTHER_MEMBER_PREFIX}ids`;
+export const OTHER_VALUES_COLUMN = `${OTHER_MEMBER_PREFIX}values`;
+/**
+ * `sql` without Other's member lists, for tables queried on every hover. A
+ * COLUMNS filter rather than EXCLUDE, which errors on a column that is absent,
+ * as it is on every mark without an Other bucket.
+ *
+ * The `lambda c:` form, not `c ->`: DuckDB deprecated the arrow lambda in 1.3,
+ * and every SQL tooltip table goes through this, so an upgrade dropping it would
+ * break tooltips on every mark. Both DuckDB-WASM 1.30 (DuckDB 1.3.2) and the
+ * DuckDB the tests run accept it.
+ */
+export function withoutOtherMembers(sql) {
+    return `SELECT COLUMNS(lambda c: NOT starts_with(c, '${OTHER_MEMBER_PREFIX}')) FROM (${sql})`;
+}
+/** The original band id, carried through bucketing, which rewrites the band column. */
+const BAND_SOURCE_COLUMN = '__dplot_band_src';
 /**
  * Give every category in the dim a row, at zero past the cutoff.
  *
@@ -189,6 +221,12 @@ function densify(inner, aliases, plan) {
             // missing (category, series) pair carries that series' real id.
             select[alias] = rawSql(`${crossed}."id"`);
         }
+        else if (alias.startsWith(OTHER_MEMBER_PREFIX)) {
+            // Other's member lists: NULL on a padded row, as on every row but
+            // Other's. Never COALESCEd to 0 like a measure, which is a type error on
+            // a list.
+            select[alias] = rawSql(`a.${column(alias)}`);
+        }
         else if (plan.identity[alias]?.dim === dim) {
             // Same dim as the band, so this channel IS the category — the ordinary
             // "colour the bars by their own category" chart. Its value for a row
@@ -235,13 +273,13 @@ function densify(inner, aliases, plan) {
     // a missing category. Each key's ids get -1 appended: a row whose series is
     // NULL carries -1, and a join over the dim's ids alone would drop it.
     const joins = cross
-        .map(([, keyDim], i) => ` CROSS JOIN (SELECT "id" FROM ${quoteTable(keyDim)} UNION ALL SELECT -1) AS k${i}`)
+        .map(([key, keyDim], i) => ` CROSS JOIN (SELECT "id" FROM ${padIds(plan.identity[key], keyDim)} UNION ALL SELECT -1) AS k${i}`)
         .join('');
     const on = [
         `a.${column(band)} = d."id"`,
         ...cross.map(([key], i) => `a.${column(key)} = k${i}."id"`)
     ].join(' AND ');
-    return Query.from(rawSql(`${quoteTable(dim)} AS d${joins} LEFT JOIN (${inner}) AS a ON ${on}`)).select(select);
+    return Query.from(rawSql(`${padIds(plan.identity[band], dim)} AS d${joins} LEFT JOIN (${inner}) AS a ON ${on}`)).select(select);
 }
 /**
  * Most padded rows `dense()` will produce before refusing.
@@ -254,6 +292,25 @@ function densify(inner, aliases, plan) {
  * before any of this existed.
  */
 export const DENSE_ROW_LIMIT = 10_000;
+/**
+ * The ids a channel pads from: the ids its mark's own table holds, plus every
+ * Other bucket of the dim, when the table's ids are known; the whole dim before.
+ *
+ * The dim spans every table registering the field, so padding from all of it
+ * gave a chart a zero row, and a slot on a sorted axis, for every category only
+ * another table has. Other buckets stay in: an Other row must find its padding
+ * row, and another mark's bucket is kept off the axis by its NaN rank, as
+ * before.
+ */
+function padIds(id, dim) {
+    const present = id?.present;
+    // A mark that drops NULL pads no row for it: its rows were filtered out.
+    const notNull = id?.dropNullId != null ? ` WHERE "id" <> ${id.dropNullId}` : '';
+    if (!present)
+        return `(SELECT "id" FROM ${quoteTable(dim)}${notNull})`;
+    return (`(SELECT "id" FROM ${quoteTable(present)}${notNull} UNION ALL ` +
+        `SELECT "id" FROM ${quoteTable(dim)} WHERE "label" IS NOT NULL)`);
+}
 /**
  * Whether `dense()` applies to a query with these aliases, and how.
  *
@@ -680,7 +737,37 @@ function collapseIntoOther(ranked, aliases, o) {
         }
     }
     bucket[RANK_COLUMN] = sqlTag `CASE WHEN ${kept} THEN ${rank} ELSE ${n + 1} END`;
+    // The band column is rewritten to the Other id above, so the category each
+    // folded row came from is carried beside it for the member lists.
+    bucket[BAND_SOURCE_COLUMN] = column(band);
     const bucketed = Query.from({ __topn_ranked: ranked }).select(bucket);
+    // PER MEMBER first: one row per group key and folded category. A grouped mark
+    // already has one row per (category, series), so this changes nothing there;
+    // an ungrouped one (raw rows, no groupKeys) would otherwise list one entry per
+    // RAW ROW past the cutoff — ids repeated, and a list that grows with the table
+    // rather than the field. Every aggregate below (SUM, MAX, MIN) gives the same
+    // answer over these rows as over the raw ones, so Other's values are unchanged.
+    const src = column(BAND_SOURCE_COLUMN);
+    const member = {};
+    const memberKeys = [src];
+    for (const alias of aliases) {
+        const col = column(alias);
+        if (isKey(alias)) {
+            member[alias] = col;
+            memberKeys.push(col);
+        }
+        else if (alias === by) {
+            member[alias] = sqlTag `SUM(${col})`;
+        }
+        else {
+            member[alias] = sqlTag `MAX(${col})`;
+        }
+    }
+    member[RANK_COLUMN] = sqlTag `MIN(${rank})`;
+    member[BAND_SOURCE_COLUMN] = src;
+    const members = Query.from({ __topn_bucketed: bucketed })
+        .select(member)
+        .groupby(...memberKeys);
     const collapse = {};
     const keys = [];
     for (const alias of aliases) {
@@ -697,7 +784,17 @@ function collapseIntoOther(ranked, aliases, o) {
         }
     }
     collapse[RANK_COLUMN] = sqlTag `MIN(${rank})`;
-    return Query.from({ __topn_bucketed: bucketed })
+    // Other's members, from the rows the bucket step moved past the cutoff (their
+    // rank is n + 1 there): one entry per folded category, from the step above. A
+    // kept row's group has none, so its lists are NULL. Cast so they arrive as
+    // Int32Array and Float64Array children: ids are REAL in the channel, and a
+    // COUNT measure is BIGINT, which would arrive as BigInt64Array.
+    const past = sqlTag `${rank} > ${n}`;
+    collapse[OTHER_IDS_COLUMN] =
+        sqlTag `list(CAST(${src} AS INTEGER) ORDER BY ${src}) FILTER (WHERE ${past})`;
+    collapse[OTHER_VALUES_COLUMN] =
+        sqlTag `list(CAST(${column(by)} AS DOUBLE) ORDER BY ${src}) FILTER (WHERE ${past})`;
+    return Query.from({ __topn_members: members })
         .select(collapse)
         .groupby(...keys);
 }
@@ -712,7 +809,9 @@ export function stackX(options = {}) {
     return stackSQL('x', options);
 }
 /** Resolve band (group) / value column aliases for a stack direction, validated against the select list. */
-function resolveStackColumns(aliases, config, direction) {
+function resolveStackColumns(aliases, config, direction, 
+/** Called when there is no series column; the caller decides whether that is worth saying. */
+onNoSeries) {
     const bandAxis = direction === 'y' ? 'x' : 'y';
     const band = config?.[bandAxis];
     const value = config?.[direction];
@@ -726,20 +825,31 @@ function resolveStackColumns(aliases, config, direction) {
     }
     const fill = config?.fill;
     const series = typeof fill === 'string' && aliases.includes(fill) ? fill : null;
-    // With no series column there is one row per band, so the cumulative sum equals
-    // that row's own value and the stack is arithmetically a no-op — the output is
-    // identical to an unstacked mark. That is the correct result, but it is
-    // indistinguishable from a broken stack to anyone looking at the chart, so say
-    // what is missing rather than silently drawing an ordinary bar.
-    if (!series) {
-        console.warn(`stack${direction === 'y' ? 'Y' : 'X'}: no series column, so stacking has no effect ` +
-            `(one row per band). Stacking groups rows within a band by the ordinal ` +
-            `fill channel — add fill="<field>" to the mark. Select list: [${aliases.join(', ')}].`);
-    }
+    if (!series)
+        onNoSeries(aliases);
     return { band, value, series };
 }
-function stackSQL(direction, options) {
+/**
+ * `implicit`: added by the mark (withImplicitStack), not written by the user.
+ *
+ * With no series column there is one row per band, so the cumulative sum equals
+ * that row's own value and the stack is arithmetically a no-op. For a stack the
+ * user wrote, that is indistinguishable from a broken one on screen, so it says
+ * what is missing, once per transform rather than on every query assembled. An
+ * implicit stack says nothing: every bar mark without a fill gets one, and it is
+ * the ordinary bar it draws, not a mistake.
+ */
+function stackSQL(direction, options, implicit = false) {
     const [loName, hiName] = direction === 'y' ? ['y0', 'y1'] : ['x0', 'x1'];
+    let warned = implicit;
+    const onNoSeries = (aliases) => {
+        if (warned)
+            return;
+        warned = true;
+        console.warn(`stack${direction === 'y' ? 'Y' : 'X'}: no series column, so stacking has no effect ` +
+            `(one row per band). Stacking groups rows within a band by the ordinal ` +
+            `fill channel — add fill="<field>" to the mark. Select list: [${aliases.join(', ')}].`);
+    };
     return {
         stage: 'sql',
         type: 'stack',
@@ -750,7 +860,7 @@ function stackSQL(direction, options) {
         channels: [loName, hiName],
         apply(query, config) {
             const aliases = getSelectAliases(query);
-            const { band, value, series } = resolveStackColumns(aliases, config, direction);
+            const { band, value, series } = resolveStackColumns(aliases, config, direction, onNoSeries);
             const valueCol = column(value);
             const bandCol = column(band);
             const notNaN = sqlTag `NOT isnan(${valueCol})`;
@@ -1091,9 +1201,7 @@ export function withImplicitStack(transforms, hasExplicitBounds, direction) {
         ? direction === 'y'
             ? stackY({ engine: 'js' })
             : stackX({ engine: 'js' })
-        : direction === 'y'
-            ? stackY()
-            : stackX();
+        : stackSQL(direction, {}, true);
     return [...transforms, implicitStack];
 }
 export { TransformCompiler } from './TransformCompiler';

package/dist/types.d.ts

@@ -3,6 +3,9 @@ import type { DataAccessor } from './data/DataAccessor';
 import type { ChartConfig } from './config/ChartConfig.svelte';
 import type { DimValue } from './query-engine/categorical-identity';
 import type { AutoBinNode } from './sql/bin';
+import type { SelectionResponse } from './components/rendering/activity-reads';
+/** What a mark does with NULL in its categorical channels; see BaseMarkProps.nulls. */
+export type NullsResponse = 'keep' | 'drop';
 import type { RollingAvgNode } from './sql/rolling-avg';
 export type ContinuousScaleType = 'linear' | 'log' | 'symlog' | 'pow' | 'identity';
 export type DiscreteScaleType = 'band' | 'point';
@@ -57,6 +60,13 @@ export interface SqlTransform {
     apply(query: SelectQuery, config?: MarkConfig): SelectQuery;
     /** Channel aliases this transform adds to the result beyond the base select (e.g. stack's y0/y1). */
     channels?: string[];
+    /**
+     * The row predicate this transform adds to the query, when that is all it does
+     * (`filter`). It applies to the source rows, before any grouping, so a query
+     * over a pre-aggregated table cannot apply it (the columns it names are gone):
+     * the table is built with it instead, and the read leaves it out.
+     */
+    where?: unknown;
     /**
      * The channels whose values identify each row, leading term first, when this
      * transform guarantees exactly one row per combination of them — or null when
@@ -96,6 +106,18 @@ export interface ChannelIdentity {
     positional: boolean;
     /** The reserved id past-the-cutoff rows are bucketed into, once reserved. */
     otherId?: number;
+    /**
+     * The table of ids the mark's own table holds, which `dense()` pads from: the
+     * dim spans every table on the field, and a chart must not pad a slot for a
+     * category only another table has. Absent before that table has folded in,
+     * when dense() pads from the whole dim as it did before.
+     */
+    present?: string;
+    /**
+     * The NULL category's id, when the mark drops NULL (`nulls="drop"`): `dense()`
+     * pads no row for it, as its rows are filtered out.
+     */
+    dropNullId?: number;
 }
 export interface MarkConfig {
     markType: string;
@@ -166,6 +188,55 @@ export interface DomainConfig {
 export interface BaseMarkProps {
     table: string;
     selection?: string;
+    /**
+     * How this mark responds to selections in its filter group.
+     *
+     * - `'auto'` (the default): a categorical selection (a legend, a Toggle, a
+     *   band label) on a field this mark draws by, its band axis or its ordinal
+     *   colour, dims it: it keeps its data and the unselected categories fade.
+     *   Any other selection filters it.
+     * - `'filter'`: every selection filters it, even on a field it draws by, so
+     *   its aggregates are recomputed for the subset: top N within the selected
+     *   region, shares within the selected groups.
+     *
+     * A `'filter'` mark never dims. A legend, Toggle or band label filters it
+     * in its own chart too: every such control on the same fields shares one
+     * selection, so any chart with one would otherwise ignore it, and this
+     * chart's legend re-ranks its own top N. A Toggle on its own bars therefore
+     * filters them: the unselected bars leave the chart. Known limit: on a band
+     * axis drawn from the data (a sorted mark), clicking a label filters the
+     * other categories out, their labels go with them, and a second category
+     * cannot be added from this chart; clicking the label again clears it. A brush still skips its
+     * own chart, so the marks under it do not move while it is dragged.
+     */
+    selectionResponse?: SelectionResponse;
+    /**
+     * Whether this mark adds its categories to a band axis's domain (default
+     * `true`). `false`: the mark follows the axis the other marks on it decide
+     * (their categories, their order); rows of categories the axis does not show
+     * are not drawn. For a layer that gives context to another, such as the whole
+     * behind a part. It cannot rank or reduce its own categories, so `topN`, `sort`
+     * and an explicit `domain` are refused with it (an error is logged and the
+     * mark contributes).
+     *
+     * Known limit: when the axis shows an Other bucket (another mark's topN with
+     * `includeOthers`), a follower has no Other row of its own. Its bars of
+     * categories that leave the axis walk to Other's slot and are gone when the
+     * transition ends, and nothing draws the whole behind Other. Folding such
+     * categories into an Other row would need the follower's query to depend on
+     * the axis's current categories.
+     */
+    contributeDomain?: boolean;
+    /**
+     * What this mark does with NULL in its categorical channels: its band axis,
+     * ordinal colour, series and facet.
+     *
+     * - `'keep'` (the default): NULL is a category like any other. It is ranked
+     *   by its measure, drawn, and labelled "(null)", in the null colour.
+     * - `'drop'`: rows whose value in any of those channels is NULL are left out
+     *   before any transform, so a top N ranks, and Other sums, without them.
+     */
+    nulls?: NullsResponse;
     scheme?: ColorScheme;
     limit?: number;
     transforms?: Transform[];

package/package.json

@@ -18,7 +18,7 @@
 		"type": "git",
 		"url": "git+https://github.com/dlyngman/fjader.git"
 	},
-	"version": "0.2.2",
+	"version": "0.2.4",
 	"type": "module",
 	"svelte": "./dist/index.js",
 	"exports": {
@@ -60,6 +60,7 @@
 		"@types/d3-color": "^3.1.3",
 		"@types/d3-scale": "^4.0.9",
 		"@types/d3-scale-chromatic": "^3.1.0",
+		"@uwdata/mosaic-sql": "^0.35.0",
 		"@webgpu/types": "^0.1.69",
 		"duckdb": "^1.4.4",
 		"eslint": "^10.0.0",
@@ -80,12 +81,12 @@
 		"vitest": "^4.0.18"
 	},
 	"peerDependencies": {
+		"@uwdata/mosaic-sql": "^0.34.2 || ^0.35.0",
 		"svelte": "^5.0.0"
 	},
 	"dependencies": {
 		"@duckdb/duckdb-wasm": "1.30.0",
 		"@uwdata/flechette": "2.3.0",
-		"@uwdata/mosaic-sql": "^0.34.2",
 		"d3-array": "^3.2.4",
 		"d3-color": "^3.1.0",
 		"d3-format": "^3.1.0",