@fjader/svelte 0.2.4 → 0.2.5

package/dist/sql/bin.js

@@ -1,5 +1,43 @@
-import { binDate, binHistogram, column } from '@uwdata/mosaic-sql';
+import { binDate, binHistogram, binSpec, column, interval, sql, timeInterval } from '@uwdata/mosaic-sql';
 import { isTemporalScale } from '../scales/scale-categories';
+/**
+ * Numeric bins over [min, max]: binHistogram's own derivation (binSpec, with
+ * the linear transform it is given), as the first edge and the width.
+ */
+function numericBins(min, max, options) {
+    const b = binSpec(min, max, options);
+    return { min: b.min, alpha: (b.max - b.min) / b.steps || 1 };
+}
+/**
+ * The edge of numeric bin `index` (SQL), `min + alpha * (index + offset)`, in
+ * DOUBLE arithmetic. The one formula both `bin()` and `dense()`'s padding
+ * write, so a bin's edge is the same bits whichever produced it: a padded row
+ * then merges with a real one, and a mark's rows are the same bits whether
+ * they came from the base table or a preagg table.
+ */
+export function numericBinEdgeSQL(min, alpha, offset, index) {
+    return `(${sqlDouble(min)} + ${sqlDouble(alpha)} * (${index} + ${offset}))`;
+}
+/** A JS number as a DOUBLE literal: a bare 0.1 would be read as a DECIMAL. */
+function sqlDouble(n) {
+    return `CAST(${JSON.stringify(n)} AS DOUBLE)`;
+}
+/** Engine-built SQL text as an expression node. Never user input. */
+function sqlFragment(text) {
+    return sql([text]);
+}
+/** A time unit's typical length, for estimating a bucket count. */
+const UNIT_MS = {
+    year: 365 * 86_400_000,
+    quarter: 91 * 86_400_000,
+    month: 30 * 86_400_000,
+    day: 86_400_000,
+    hour: 3_600_000,
+    minute: 60_000,
+    second: 1000,
+    millisecond: 1,
+    microsecond: 0.001
+};
 export function bin(field, options = {}) {
     return new AutoBinNode(field, options);
 }
@@ -19,6 +57,70 @@ export class AutoBinNode {
         };
     }
     resolve(fieldInfo, scaleType, timeOffset = null, currentDomain = null, binStepMultiplier = 1.0) {
+        const { col, min, max, isTemporal, binOptions } = this.#plan(fieldInfo, scaleType, currentDomain, binStepMultiplier);
+        if (isTemporal)
+            return binDate(col, [min, max], binOptions);
+        // A single value: binHistogram floors it rather than binning.
+        if (max === min)
+            return binHistogram(col, [min, max], binOptions);
+        // binHistogram's bins, written with the formula dense() pads with, so a
+        // real row's edge and a padded row's are the same bits (see
+        // numericBinEdgeSQL).
+        const { min: lo, alpha } = numericBins(min, max, binOptions);
+        const index = `floor((CAST(${col} AS DOUBLE) - ${sqlDouble(lo)}) / ${sqlDouble(alpha)})`;
+        return sqlFragment(numericBinEdgeSQL(lo, alpha, binOptions.offset ?? 0, index));
+    }
+    /**
+     * The bins `resolve` produces with the same arguments: every bin a value of
+     * the field can fall in. What `dense()` pads a histogram from, so a bin
+     * emptied by a filter stays as a zero row and the bars can morph.
+     *
+     * Numeric bins as numbers, edge k at `min + alpha * (k + offset)`. Time
+     * buckets as the interval `time_bucket` steps by, and the field's extent;
+     * those need `t0`, the time scale's origin in epoch seconds, because a time
+     * channel is drawn as seconds from it, and are null without it (before the
+     * scale has one, the channel is not rewritten either).
+     *
+     * Null for a field with a single value, which binHistogram floors instead
+     * of binning.
+     */
+    padding(fieldInfo, scaleType, currentDomain = null, binStepMultiplier = 1.0, t0 = null) {
+        const { col, min, max, isTemporal, binOptions } = this.#plan(fieldInfo, scaleType, currentDomain, binStepMultiplier);
+        const offset = binOptions.offset ?? 0;
+        const source = String(col);
+        if (isTemporal) {
+            if (t0 === null)
+                return null;
+            // binDate's own choice of unit and step.
+            const { unit, step = 1 } = binOptions.interval
+                ? { unit: binOptions.interval, step: binOptions.step }
+                : timeInterval(min, max, binOptions.steps || 40);
+            const width = (UNIT_MS[unit] ?? UNIT_MS.day) * step;
+            return {
+                kind: 'time',
+                source,
+                interval: String(interval(unit, step)),
+                minMs: min,
+                maxMs: max,
+                t0,
+                count: Math.ceil((max - min) / width) + 2,
+                offset
+            };
+        }
+        if (max === min)
+            return null;
+        const { min: lo, alpha } = numericBins(min, max, binOptions);
+        return {
+            kind: 'number',
+            source,
+            min: lo,
+            alpha,
+            count: Math.floor((max - lo) / alpha) + 1,
+            offset
+        };
+    }
+    /** The column, extent and options both `resolve` and `padding` bin with. */
+    #plan(fieldInfo, scaleType, currentDomain, binStepMultiplier) {
         const fieldName = typeof this.field === 'string' ? this.field : this.field.toString();
         const info = fieldInfo[fieldName] || {};
         const { min, max, type } = info;
@@ -50,12 +152,13 @@ export class AutoBinNode {
                 binOptions.steps = Math.max(1, Math.round(binOptions.steps * binStepMultiplier));
             }
             if (binOptions.step) {
-                binOptions.step = binOptions.step / binStepMultiplier;
+                // A time interval counts whole units: `INTERVAL 6.78 day` is not SQL.
+                binOptions.step = binOptions.interval
+                    ? Math.max(1, Math.round(binOptions.step / binStepMultiplier))
+                    : binOptions.step / binStepMultiplier;
             }
         }
-        return isTemporal
-            ? binDate(col, [min, max], binOptions)
-            : binHistogram(col, [min, max], binOptions);
+        return { col, min, max, isTemporal, binOptions };
     }
     withOffset(offset) {
         return new AutoBinNode(this.field, {

package/dist/transforms/TransformCompiler.d.ts

@@ -24,6 +24,16 @@ export declare class TransformCompiler {
     options?: {
         skipRowFilters?: boolean;
     }): SelectQuery;
+    /**
+     * The padding rows of this mark's queries (see SqlTransform.padRows), for a
+     * pre-aggregated table to hold, or null when they cannot live in a table.
+     *
+     * Only when padding is the last thing that changes which rows exist: every
+     * other SQL transform is one that runs the same over a padded table as over
+     * a padded result. A topN ranks before padding, so zero rows in its table
+     * would enter the ranking; anything else not listed is not known to be safe.
+     */
+    padRows(aliases: string[], facts?: Partial<MarkConfig>): string | null;
     /**
      * Whether a SQL transform filters on the groups' aggregates (`having`). Its
      * condition names aggregates over the source rows, which a pre-aggregated table

package/dist/transforms/TransformCompiler.js

@@ -1,3 +1,9 @@
+/**
+ * SQL transforms that give the same rows over a table holding its padding as
+ * padding gives their result: row filters (applied to the table's build), and
+ * what runs after padding (rank, stack, normalize).
+ */
+const PAD_SAFE = new Set(['dense', 'filter', 'rank', 'stack', 'normalize']);
 export class TransformCompiler {
     transforms;
     sqlTransforms;
@@ -52,6 +58,26 @@ export class TransformCompiler {
         }
         return result;
     }
+    /**
+     * The padding rows of this mark's queries (see SqlTransform.padRows), for a
+     * pre-aggregated table to hold, or null when they cannot live in a table.
+     *
+     * Only when padding is the last thing that changes which rows exist: every
+     * other SQL transform is one that runs the same over a padded table as over
+     * a padded result. A topN ranks before padding, so zero rows in its table
+     * would enter the ranking; anything else not listed is not known to be safe.
+     */
+    padRows(aliases, facts) {
+        if (!this.sqlTransforms.every((t) => PAD_SAFE.has(t.type)))
+            return null;
+        const config = this.#configFor(facts);
+        for (const transform of this.sqlTransforms) {
+            const rows = transform.padRows?.(aliases, config);
+            if (rows)
+                return rows;
+        }
+        return null;
+    }
     /**
      * Whether a SQL transform filters on the groups' aggregates (`having`). Its
      * condition names aggregates over the source rows, which a pre-aggregated table

package/dist/transforms/index.js

@@ -6,6 +6,7 @@
  * - JS: Process data via the DataAccessor interface (zero-copy on Arrow data)
  */
 import { Query, column, sql as sqlTag } from '@uwdata/mosaic-sql';
+import { numericBinEdgeSQL } from '../sql/bin';
 // =============================================================================
 // SQL TRANSFORMS (Query Modifiers)
 // =============================================================================
@@ -208,18 +209,29 @@ const BAND_SOURCE_COLUMN = '__dplot_band_src';
  * instead, and the query assembler orders the outermost query by it.
  */
 function densify(inner, aliases, plan) {
-    const { band, dim, cross } = plan;
+    const { band, dim, cross, bins } = plan;
     const crossAlias = new Map(cross.map(([key], i) => [key, `k${i}`]));
+    const binOf = new Map(bins);
     const select = {};
     for (const alias of aliases) {
         const crossed = crossAlias.get(alias);
-        if (alias === band) {
-            select[alias] = sqlTag `d."id"`;
+        const bin = binOf.get(alias);
+        if (bin) {
+            // Every row's edge from its bin index, real and padded alike, so the
+            // edges are the same bits on every update: they are what tells the
+            // renderer the row set has not changed (alignmentKey).
+            select[alias] = rawSql(binEdge(bin, 'd.k'));
+        }
+        else if (alias === band) {
+            // REAL, as the inner query's id columns are: an INTEGER column would
+            // reach the GPU through a copy, and hand the renderer other bits than
+            // a preagg read, which keeps the REAL ids.
+            select[alias] = rawSql(`CAST(d."id" AS REAL)`);
         }
         else if (crossed) {
             // Another group key, enumerated from its own dim: the padded row for a
             // missing (category, series) pair carries that series' real id.
-            select[alias] = rawSql(`${crossed}."id"`);
+            select[alias] = rawSql(`CAST(${crossed}."id" AS REAL)`);
         }
         else if (alias.startsWith(OTHER_MEMBER_PREFIX)) {
             // Other's member lists: NULL on a padded row, as on every row but
@@ -227,7 +239,7 @@ function densify(inner, aliases, plan) {
             // a list.
             select[alias] = rawSql(`a.${column(alias)}`);
         }
-        else if (plan.identity[alias]?.dim === dim) {
+        else if (!bins && 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
             // with no data is not unknown, it is that category's id, so take it
@@ -236,7 +248,7 @@ function densify(inner, aliases, plan) {
             // This is what keeps a DEPARTING bar its colour. It is still on screen
             // while it shrinks, and a sentinel would turn it grey on the frame its
             // data disappeared — the one frame where the colour matters most.
-            select[alias] = sqlTag `d."id"`;
+            select[alias] = rawSql(`CAST(d."id" AS REAL)`);
         }
         else if (plan.identity[alias]) {
             // A category id from some OTHER field that is not a group key — an
@@ -244,7 +256,7 @@ function densify(inner, aliases, plan) {
             // so the absent sentinel it is. Never 0, which is a real category: it
             // would enter the colour scale's domain, shift every palette rank after
             // it, and repaint bars that had not changed.
-            select[alias] = sqlTag `COALESCE(a.${column(alias)}, -1)`;
+            select[alias] = sqlTag `COALESCE(a.${column(alias)}, CAST(-1 AS REAL))`;
         }
         else {
             // A measure. 0 is the point: it is what makes a departing bar shrink to
@@ -275,11 +287,52 @@ function densify(inner, aliases, plan) {
     const joins = cross
         .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(`${padIds(plan.identity[band], dim)} AS d${joins} LEFT JOIN (${inner}) AS a ON ${on}`)).select(select);
+    const bandBin = binOf.get(band);
+    const bandOn = bandBin ? binMatch(bandBin, `a.${column(band)}`) : `a.${column(band)} = d."id"`;
+    const on = [bandOn, ...cross.map(([key], i) => `a.${column(key)} = k${i}."id"`)].join(' AND ');
+    const source = bandBin ? binSource(bandBin) : `${padIds(plan.identity[band], dim)} AS d`;
+    return Query.from(rawSql(`${source}${joins} LEFT JOIN (${inner}) AS a ON ${on}`)).select(select);
+}
+/**
+ * Every bin, as `d.k`: an index for numeric bins, a bucket start for time
+ * buckets. Time buckets come from `time_bucket` itself over the field's
+ * extent, so they are exactly the buckets the query's own expression makes,
+ * months and years included, which are not a fixed width.
+ */
+function binSource(bin) {
+    if (bin.kind === 'number')
+        return `range(0, ${bin.count}) AS d(k)`;
+    const first = `time_bucket(${bin.interval}, epoch_ms(${Math.round(bin.minMs)}))`;
+    const last = `time_bucket(${bin.interval}, epoch_ms(${Math.round(bin.maxMs)}))`;
+    return `range(${first}, ${last} + ${bin.interval}, ${bin.interval}) AS d(k)`;
+}
+/**
+ * Bin `k`'s edge as the REAL the query draws. Numeric: `min + alpha * (k +
+ * offset)`, in DOUBLE arithmetic. Time: the bucket start plus `offset`
+ * intervals, as seconds from `t0`, the form the mark's time channels take.
+ */
+function binEdge(bin, k) {
+    if (bin.kind === 'number') {
+        return `CAST(${numericBinEdgeSQL(bin.min, bin.alpha, bin.offset, k)} AS REAL)`;
+    }
+    return `CAST((epoch(${k} + (${bin.interval}) * ${bin.offset}) - ${bin.t0}) AS REAL)`;
+}
+/**
+ * Whether the result row's edge `edge` is bin `d.k`. Numeric bins match by
+ * index, recovered from the edge: the edge is a REAL in the result (and in a
+ * preagg table), so comparing it to an edge computed here could miss by a
+ * rounding. A time edge is computed by the same expression on both sides, so
+ * the REALs are equal.
+ */
+function binMatch(bin, edge) {
+    if (bin.kind === 'number') {
+        return `round((CAST(${edge} AS DOUBLE) - ${sqlNumber(bin.min)}) / ${sqlNumber(bin.alpha)}) - ${bin.offset} = d.k`;
+    }
+    return `${edge} = ${binEdge(bin, 'd.k')}`;
+}
+/** A JS number as a DOUBLE literal: a bare 0.1 would be read as a DECIMAL. */
+function sqlNumber(n) {
+    return `CAST(${JSON.stringify(n)} AS DOUBLE)`;
 }
 /**
  * Most padded rows `dense()` will produce before refusing.
@@ -347,20 +400,24 @@ function densePlan(aliases, config, enabled, reported) {
         if (reported.has(key))
             return;
         reported.add(key);
-        console.info(`[dense] ${reason} Categories on this mark will snap between updates ` +
-            `rather than morphing, and a category leaving will vanish rather than shrink out.`);
+        console.info(`[dense] ${reason} Categories or bins on this mark will snap between updates ` +
+            `rather than morphing, and one leaving will vanish rather than shrink out.`);
     };
     if (!enabled)
         return null;
-    const identity = config?.identity;
-    if (!identity)
-        return null;
     // Stated by whoever built the select, because it cannot be recovered from
     // the query by the time this runs: topN has already wrapped it, and the
     // GROUP BY is several levels down.
     const groupKeys = config?.groupKeys;
     if (!groupKeys)
         return null;
+    // A histogram: its bins are enumerable like a dim's ids.
+    const binned = binPlan(aliases, groupKeys, config, say);
+    if (binned !== undefined)
+        return binned;
+    const identity = config?.identity;
+    if (!identity)
+        return null;
     const candidates = aliases.filter((ch) => identity[ch]?.positional);
     if (candidates.length !== 1) {
         if (candidates.length > 1) {
@@ -400,7 +457,59 @@ function densePlan(aliases, config, enabled, reported) {
             `(${size} categories${cross.length > 0 ? ` across ${cross.length + 1} group keys` : ''}).`);
         return null;
     }
-    return { band, dim, cross, identity };
+    return { band, dim, cross, bins: null, identity };
+}
+/**
+ * The plan for a binned axis: one row per bin, from the bins `bin()`
+ * resolved, crossed with each other group key's ids as for a categorical band.
+ * Null with nothing binned. Refuses, saying why, what it cannot enumerate: bins
+ * on both axes (a 2D histogram) or beside a categorical axis, a group key with
+ * no dim, and too many rows. Silent while identity has not landed for a group
+ * key that will get it.
+ */
+function binPlan(aliases, groupKeys, config, say) {
+    const specs = config?.bins;
+    if (!specs)
+        return undefined;
+    const bins = aliases
+        .filter((ch) => specs[ch] && groupKeys.includes(ch))
+        .map((ch) => [ch, specs[ch]])
+        .sort((a, b) => a[1].offset - b[1].offset);
+    if (bins.length === 0)
+        return undefined;
+    const identity = config?.identity ?? null;
+    if (new Set(bins.map(([ch]) => ch[0])).size > 1) {
+        say('Bins on both axes (a 2D histogram), and padding is defined for one.');
+        return null;
+    }
+    const categorical = identity ? aliases.filter((ch) => identity[ch]?.positional) : [];
+    if (categorical.length > 0) {
+        say(`A binned axis beside a categorical one (${categorical.join(', ')}).`);
+        return null;
+    }
+    const binned = new Set(bins.map(([ch]) => ch));
+    const cross = [];
+    let rows = bins[0][1].count;
+    for (const key of groupKeys) {
+        if (binned.has(key) || !aliases.includes(key))
+            continue;
+        const keyIdentity = identity?.[key];
+        // Before identity setup a series has no dim yet; it will.
+        if (!identity)
+            return null;
+        if (!keyIdentity) {
+            say(`the group key "${key}" has no dim, so its missing combinations cannot be enumerated.`);
+            return null;
+        }
+        cross.push([key, keyIdentity.dim]);
+        rows *= keyIdentity.size + 1;
+    }
+    if (rows > DENSE_ROW_LIMIT) {
+        say(`padding would produce about ${rows} rows, over the ${DENSE_ROW_LIMIT} limit ` +
+            `(${bins[0][1].count} bins${cross.length > 0 ? ` across ${cross.length + 1} group keys` : ''}).`);
+        return null;
+    }
+    return { band: bins[0][0], dim: '', cross, bins, identity: identity ?? {} };
 }
 /**
  * Return a row for every category, not only the ones that survived.
@@ -440,10 +549,27 @@ export function dense(options = {}) {
             return plan ? [plan.band, ...plan.cross.map(([key]) => key)] : null;
         },
         apply(query, config) {
+            // A preagg table built with padRows() below: its rows are already one
+            // per category or bin, and only the order is left, which the query's
+            // ORDER BY takes from alignment() as for any other read.
+            if (config?.padded)
+                return query;
             const aliases = getSelectAliases(query);
             const plan = densePlan(aliases, config, enabled, reported);
             return plan ? densify(query, aliases, plan) : query;
         },
+        /**
+         * The rows apply() would add, as the padding of an empty result: the same
+         * join and the same rules for every channel, so a table built with them
+         * holds exactly what padding its reads would have added.
+         */
+        padRows(aliases, config) {
+            const plan = densePlan(aliases, config, enabled, reported);
+            if (!plan)
+                return null;
+            const empty = Query.select(Object.fromEntries(aliases.map((alias) => [alias, rawSql('NULL')]))).where(rawSql('false'));
+            return String(densify(empty, aliases, plan));
+        },
         describe() {
             return 'Dense categories';
         }
@@ -970,12 +1096,6 @@ function stackXJS(options) {
         }
     };
 }
-/**
- * Core stacking computation on DataAccessor columns.
- *
- * Single O(n) pass: detects group boundaries in the sorted group column,
- * accumulates value offsets, writes lo/hi Float32Arrays, applies offset mode.
- */
 /**
  * Core stacking computation on DataAccessor columns.
  *

package/dist/types.d.ts

@@ -39,13 +39,27 @@ export type FieldRef = string | ExprNode;
  * resolves against the chart's state, such as bin() or a rolling average.
  */
 export type ChannelRef = FieldRef | AutoBinNode | RollingAvgNode;
-/** Color prop: CSS constant, column name, object wrapper {field, scheme?, type?}, SQL node, or null. */
+/** A category value a colour can be pinned to. */
+export type ColorDomainValue = string | number | boolean | null;
+/**
+ * Color prop: CSS constant, column name, object wrapper, SQL node, or null.
+ *
+ * The object wrapper takes a scheme and type, or explicit ordinal colours:
+ *
+ *   { field: 'won', domain: [0, 1], range: ['#d62728', '#2ca02c'] }
+ *
+ * `range` replaces the scheme's colours, which go to the values in sorted
+ * order. `domain` pins values to them instead: domain[i] draws range[i], and
+ * values outside it draw the null colour. Either one makes the scale ordinal.
+ */
 export type ColorProp = FieldRef | {
     field: string;
     scheme?: ColorScheme;
     type?: ColorScaleType;
     constant?: number;
     exponent?: number;
+    domain?: readonly ColorDomainValue[];
+    range?: readonly string[];
 } | null;
 /**
  * A SQL transform modifies the Mosaic Query AST before execution.
@@ -77,6 +91,12 @@ export interface SqlTransform {
      * band a mark may morph along.
      */
     alignment?(aliases: string[], config?: MarkConfig): string[] | null;
+    /**
+     * The rows this transform would add to a result to pad it, as a SELECT of
+     * every alias, or null when it pads nothing. A pre-aggregated table is
+     * built with them, so its reads need no padding of their own (`padded`).
+     */
+    padRows?(aliases: string[], config?: MarkConfig): string | null;
     describe?(): string;
 }
 /** A JS transform processes client-side data after the query returns. */
@@ -119,6 +139,40 @@ export interface ChannelIdentity {
      */
     dropNullId?: number;
 }
+/**
+ * One binned channel's bins, as `bin()` resolved them for a query, which
+ * `dense()` pads a histogram from. A rect's upper edge is the same bins with
+ * offset 1.
+ */
+export type BinPadding = NumericBinPadding | TimeBinPadding;
+/** Numeric bins: edge k is `min + alpha * (k + offset)` for k in [0, count). */
+export interface NumericBinPadding {
+    kind: 'number';
+    /** The binned column or expression, as SQL: a bin is NULL exactly where it is. */
+    source: string;
+    min: number;
+    alpha: number;
+    count: number;
+    offset: number;
+}
+/**
+ * Time buckets of `interval` (SQL, as `time_bucket` takes it) over the field's
+ * extent, minMs to maxMs. An edge is the bucket start plus `offset` intervals,
+ * drawn as seconds from the time scale's origin `t0` (epoch seconds), the form
+ * a time channel takes in the query. `count` estimates the buckets, for the
+ * row limit: months and years are not a fixed width.
+ */
+export interface TimeBinPadding {
+    kind: 'time';
+    /** The binned column or expression, as SQL: a bucket is NULL exactly where it is. */
+    source: string;
+    interval: string;
+    minMs: number;
+    maxMs: number;
+    t0: number;
+    count: number;
+    offset: number;
+}
 export interface MarkConfig {
     markType: string;
     table: string;
@@ -129,6 +183,10 @@ export interface MarkConfig {
     identity?: Record<string, ChannelIdentity>;
     /** The query's GROUP BY channels, or null when it does not aggregate. Per query. */
     groupKeys?: string[] | null;
+    /** The numeric `bin()` channels and their bins, which `dense()` pads from. Per query. */
+    bins?: Record<string, BinPadding> | null;
+    /** The query reads a table that already holds its padding rows. Per query. */
+    padded?: boolean;
     [key: string]: unknown;
 }
 export interface ScaleMap {
@@ -198,6 +256,32 @@ export interface BaseMarkProps {
      * - `'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.
+     * - `'ignore'`: no selection filters or dims it, its own chart's controls
+     *   included, and a selection change never re-queries it. For context: the
+     *   whole drawn faintly behind a filtered part, on the same scales, whose
+     *   extent then keeps the axis still while the part changes. A click on its
+     *   Other bar toggles, as under `'auto'`.
+     *
+     * Background totals are two layers of the same mark: an `'ignore'` one
+     * drawn faintly behind, the whole, and an `'auto'` one in front, the part a
+     * brush or click elsewhere leaves. Each bar shrinks over its total instead
+     * of losing it, and the y axis keeps the total's extent:
+     *
+     * ```svelte
+     * <BarMarkY table="flights" x="carrier" y={count()} selectionResponse="ignore" fillOpacity={0.2} />
+     * <BarMarkY table="flights" x="carrier" y={count()} />
+     * ```
+     *
+     * With a top N, choose which layer ranks; the other gets
+     * `contributeDomain={false}` and follows the axis:
+     *
+     * - the back layer, to rank once over the whole: the same N categories
+     *   stay while the front bars shrink;
+     * - the front layer, to re-rank within the selection: the N categories
+     *   change with it, and the whole is drawn for whichever are shown.
+     *
+     * Not with `includeOthers`: the follower has no Other row (see
+     * `contributeDomain`).
      *
      * 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
@@ -237,12 +321,32 @@ export interface BaseMarkProps {
      *   before any transform, so a top N ranks, and Other sums, without them.
      */
     nulls?: NullsResponse;
+    /**
+     * Whether the chart's entrance waits for this mark's first data. Default
+     * true: the chart enters once every mark has landed, so later marks cannot
+     * widen the axes mid-entrance. False for a mark known to be slower than
+     * the rest: the chart enters without it, and it joins the entrance where it
+     * is, or appears after it. A chart waits at most a second past its first
+     * mark either way.
+     */
+    holdsEntrance?: boolean;
     scheme?: ColorScheme;
     limit?: number;
     transforms?: Transform[];
     sort?: SortConfig | null;
     domain?: DomainConfig | null;
-    tooltip?: boolean;
+    /**
+     * Hover tooltips. `true` (the default) or `false`, or options:
+     *
+     * - `sortTable`: write the mark's tooltip table sorted by x, so a hover
+     *   lookup can skip DuckDB row groups outside the pointer's box. Off by
+     *   default: the sort delays the first hover (the table is written when the
+     *   pointer enters the chart), and measured up to 2M rows it did not make
+     *   lookups faster.
+     */
+    tooltip?: boolean | {
+        sortTable?: boolean;
+    };
     tooltipProximity?: 'x' | 'y' | 'xy';
     tip?: (FieldRef | '*')[] | false;
     fitDomain?: 'x' | 'y' | boolean;
@@ -313,6 +417,18 @@ export interface LODConfig {
     /** Callback fired on LOD state transitions (decimation toggle, dots appear/disappear). */
     onLODChange?: (state: LODChangeState) => void;
 }
+/**
+ * How a chart's marks enter when its data first draws.
+ *
+ * - `'auto'` (the default): bars, histograms and areas grow from 0 on their
+ *   measure axis, showing magnitude; everything else fades in.
+ * - `'fade'`: every mark fades in. Calmer, for dense small multiples.
+ * - `'none'`: marks appear at once.
+ *
+ * Under `prefers-reduced-motion: reduce`, `'auto'` becomes `'fade'`. The axes
+ * never move on load: the entrance is the data's, not the viewport's.
+ */
+export type EntranceMode = 'auto' | 'fade' | 'none';
 import type { Margin, Point, AxesResult } from './layout/ChartLayout.svelte';
 import type { LinearScaleState } from './scales/LinearScaleState.svelte';
 import type { BandScaleState } from './scales/BandScaleState.svelte';
@@ -372,6 +488,24 @@ export interface ChartContext {
     readonly currentXScreenPoint: number | null | undefined;
     readonly currentYScreenPoint: number | null | undefined;
     readonly xScaleState: ScaleStateInstance | null | undefined;
+    /**
+     * How many times the chart's x or y scale has been replaced by another (not
+     * its first resolution). Marks rebuild their lifecycle when it changes.
+     */
+    readonly scaleGeneration: number;
+    /**
+     * Whether any of the chart's cells is on screen (with a small margin).
+     * Marks stop re-querying while it is false; see MarkHandle.active.
+     */
+    readonly visible: boolean;
+    /**
+     * Whether a visible chart other than this one draws `scale`: a catch-up
+     * springs such a scale rather than snapping it. See
+     * ChartVisibility.shownElsewhere.
+     */
+    shownElsewhere(scale: object): boolean;
+    /** Whether the pointer is over any of the chart's cells (hover intent). */
+    readonly hovered: boolean;
     readonly yScaleState: ScaleStateInstance | null | undefined;
     readonly scaleTypes: {
         x: string;

package/package.json

@@ -18,7 +18,7 @@
 		"type": "git",
 		"url": "git+https://github.com/dlyngman/fjader.git"
 	},
-	"version": "0.2.4",
+	"version": "0.2.5",
 	"type": "module",
 	"svelte": "./dist/index.js",
 	"exports": {
@@ -41,7 +41,7 @@
 		"prepack": "svelte-package",
 		"prepare": "svelte-kit sync || echo ''",
 		"format": "prettier --write .",
-		"lint": "prettier --check . && eslint .",
+		"lint": "prettier --check . && eslint . && node scripts/check-doc-blocks.mjs",
 		"test": "vitest",
 		"typecheck": "svelte-check --tsconfig ./jsconfig.json",
 		"build:widget": "vite build --config vite.widget.config.js",