@fjader/svelte 0.2.2 → 0.2.3

package/dist/query-engine/FilterGroup.svelte.js

@@ -2,8 +2,8 @@
  * FilterGroup — visual concerns layer on top of CrossfilterSelection.
  *
  * Manages the interactor API (register, registerToggle), schema augmentation
- * for UI filter pills, and scale projection (dimming unselected categories in
- * legends/axes).
+ * for UI filter pills, and this group's selection on each categorical field
+ * (FieldActivity), which marks, legends and band axes dim by.
  *
  * Owns clauses: a clause lives while at least one registration for its id
  * exists. Components own their registrations through their own lifecycle.
@@ -14,6 +14,34 @@
 import { column, sql as sqlTag } from '@uwdata/mosaic-sql';
 import { CrossfilterSelection } from './CrossfilterSelection.svelte';
 import { togglePredicate } from './toggle-predicate';
+import { identityKeyFor } from './identity-key';
+import { FieldActivity } from './FieldActivity.svelte';
+/**
+ * A source's declaration of `key`: the writer's, or another registration's
+ * when the writer has none. Every registration under one id is one source, so
+ * any of them can say what its clause is.
+ */
+function declared(registrations, writer, key) {
+    if (writer[key])
+        return writer[key];
+    for (const opts of registrations ?? [])
+        if (opts[key])
+            return opts[key];
+    return undefined;
+}
+/**
+ * A clause's schema, computed once when it is written rather than on every
+ * read of `items`, and stored on the clause, so a reader of raw clauses (the
+ * relay looking for a range brush) sees it too.
+ */
+function schemaOf(registrations, writer, value) {
+    return declared(registrations, writer, 'augment')?.(value) ?? undefined;
+}
+/** A clause's categorical selection: the field's identity key and the selected values. */
+function categoricalOf(registrations, writer, value) {
+    const categorical = declared(registrations, writer, 'categorical');
+    return categorical ? { key: categorical.key, values: categorical.values(value) } : null;
+}
 // ---------------------------------------------------------------------------
 // Toggles
 // ---------------------------------------------------------------------------
@@ -39,33 +67,47 @@ function toggleSourceId(fields) {
 export class FilterGroup {
     selection = new CrossfilterSelection();
     #engine = null;
+    /**
+     * This group's page-wide index, assigned by FilterGroupRegistry and never
+     * reused: a mark stores it to read this group's half of an activity block.
+     */
+    index;
+    /** The selection state of a field, shared with the other groups on the page. */
+    #activityOf;
+    /** Fields this group has an active categorical selection on, for clearAll. */
+    #selectedFields = new Set();
+    /**
+     * A group made outside a registry (unit tests) keeps its field activity to
+     * itself, with no loop: its fades land at once.
+     */
+    constructor(index = 0, activityOf) {
+        this.index = index;
+        if (activityOf) {
+            this.#activityOf = activityOf;
+        }
+        else {
+            const own = new Map();
+            this.#activityOf = (key) => {
+                let activity = own.get(key);
+                if (!activity)
+                    own.set(key, (activity = new FieldActivity(key)));
+                return activity;
+            };
+        }
+    }
+    /** The selection state of a categorical field, by identity key: this group's fade is `index`. */
+    activity(key) {
+        return this.#activityOf(key);
+    }
     setEngine(engine) {
         this.#engine = engine;
     }
-    /** Registrations per source id. Several under one id are one source. */
-    #sources = new Map();
-    // Track which scales we projected to, so we can clear them
-    #projectedScales = new Set();
-    /** Active filter items with schema metadata, for UI consumption. */
+    /**
+     * Active filter items with schema metadata, for UI consumption. The schema
+     * is the clause's own, computed when it was written (see `update`).
+     */
     get items() {
-        const clauses = this.selection.items;
-        const result = [];
-        for (const entry of clauses) {
-            let schema = entry.schema;
-            for (const opts of this.#sources.get(entry.sourceId) ?? []) {
-                if (!opts.augment)
-                    continue;
-                schema = opts.augment(entry.value) ?? entry.schema;
-                break;
-            }
-            result.push({
-                sourceId: entry.sourceId,
-                predicate: entry.predicate,
-                value: entry.value,
-                schema
-            });
-        }
-        return result;
+        return this.selection.items;
     }
     /** Number of active filters. */
     get activeCount() {
@@ -80,60 +122,73 @@ export class FilterGroup {
     // -----------------------------------------------------------------
     /**
      * Register a selection source. Several registrations under one id are one
-     * source: each writes the clause with its own exclusions, and the scales the
-     * source dims are the union of theirs.
+     * source and write one clause.
      */
     register(sourceId, opts) {
-        let registrations = this.#sources.get(sourceId);
-        if (!registrations) {
-            registrations = new Set();
-            this.#sources.set(sourceId, registrations);
+        const { selection } = this;
+        selection.addRegistration(sourceId, opts);
+        // A chart that starts skipping a selection already in force has marks
+        // whose filters just changed.
+        if (opts.chart && selection.isActive(sourceId)) {
+            this.#engine?.onChartRouteChange(this, opts.chart);
         }
-        registrations.add(opts);
+        const registrations = () => selection.registrationsOf(sourceId);
+        let registered = true;
         return {
             update: (predicate, value) => {
-                this.selection.update(sourceId, {
+                const next = {
                     predicate,
-                    excludeMarkIds: opts.excludeMarkIds(),
-                    value
-                });
-                this.#afterUpdate();
+                    value,
+                    schema: schemaOf(registrations(), opts, value),
+                    categorical: categoricalOf(registrations(), opts, value)
+                };
+                this.#afterUpdate(sourceId, selection.update(sourceId, next), next);
             },
             clear: () => this.clearSource(sourceId),
             activate: () => this.#activate(sourceId),
             destroy: () => {
-                registrations.delete(opts);
-                if (registrations.size > 0)
+                // Once only: a second call must not remove a newer registration
+                // under the same id, or clear its clause.
+                if (!registered)
+                    return;
+                registered = false;
+                if (registrations()?.size === 1) {
+                    // The last one: drop the source's preagg tables first, so the
+                    // re-query below cannot start reading one about to go. Then clear
+                    // while the registration is still in place, so the removal is
+                    // routed by it: the marks re-queried are those the clause filtered.
+                    this.#engine?.forgetSource(this, sourceId);
+                    this.clearSource(sourceId);
+                    selection.removeRegistration(sourceId, opts);
                     return;
-                this.#sources.delete(sourceId);
-                this.#engine?.forgetSource(this, sourceId);
-                this.clearSource(sourceId);
+                }
+                selection.removeRegistration(sourceId, opts);
+                // Another registration keeps the clause; its chart may stop skipping it.
+                if (opts.chart && selection.isActive(sourceId)) {
+                    this.#engine?.onChartRouteChange(this, opts.chart);
+                }
             }
         };
     }
     /**
-     * Hand the engine a snapshot of the source. It activates every mark some
-     * registration filters: a table for the source is correct for a mark whether
-     * or not the clause currently excludes it, so only marks that every
-     * registration excludes are left out.
+     * Hand the engine a snapshot of the source: its dims, its view, and its
+     * categorical field, so activation can tell which marks it would filter
+     * before it has written a clause.
      */
     #activate(sourceId) {
-        const registrations = this.#sources.get(sourceId);
+        const registrations = this.selection.registrationsOf(sourceId);
         if (!this.#engine || !registrations?.size)
             return;
-        let excludedByAll = null;
         let dims = [];
         let view;
+        let categoricalKey = null;
         for (const opts of registrations) {
-            const excluded = opts.excludeMarkIds();
-            excludedByAll = excludedByAll
-                ? new Set([...excludedByAll].filter((id) => excluded.has(id)))
-                : excluded;
             if (opts.activeDims && dims.length === 0)
                 dims = opts.activeDims();
             view ??= opts.view;
+            categoricalKey ??= opts.categorical?.key ?? null;
         }
-        this.#engine.activate(this, { sourceId, excludedByAll: excludedByAll, dims, view });
+        this.#engine.activate(this, { sourceId, categoricalKey, dims, view });
     }
     // -----------------------------------------------------------------
     // Toggles (legend/axis categorical selection)
@@ -147,22 +202,24 @@ export class FilterGroup {
      * as the selection. Nothing else writes those ids (`upsertManual` prefixes
      * its own with `manual:`).
      */
-    registerToggle(fields, opts) {
+    registerToggle(fields, opts = {}) {
         const list = Array.isArray(fields) ? fields : [fields];
         const sourceId = toggleSourceId(list);
         const { selection } = this;
         const schema = { kind: 'toggle', column: list[0], label: list.join(', ') };
+        // One field selects categories; a tuple does not (see Clause.categorical).
+        const categoricalKey = list.length === 1 ? (identityKeyFor(list[0])?.key ?? null) : null;
         const source = this.register(sourceId, {
-            excludeMarkIds: opts.excludeMarkIds,
-            activeDims: () => list.map((field) => ({ kind: 'value', field })),
-            augment: () => schema,
-            // Projection only makes sense for single-field toggles.
-            projection: list.length === 1 && opts.scales
+            chart: opts.chart ?? null,
+            discrete: true,
+            categorical: categoricalKey
                 ? {
-                    scales: opts.scales,
+                    key: categoricalKey,
                     values: (value) => new Set(value.map((t) => t[0]))
                 }
-                : undefined
+                : undefined,
+            activeDims: () => list.map((field) => ({ kind: 'value', field })),
+            augment: () => schema
         });
         const tuplesOf = (clause) => clause?.value ?? [];
         /**
@@ -170,11 +227,16 @@ export class FilterGroup {
          * map's version, so a toggle with nothing selected is re-read on every one;
          * returning the same set while the clause is unchanged (and one shared
          * empty set without a clause) keeps that from re-rendering its readers.
+         *
+         * One field's values are the clause's own categorical set, built once per
+         * write. A tuple's keys are built here, once per clause.
          */
         let last = null;
         const keysOf = (clause) => {
             if (!clause)
                 return NOTHING_SELECTED;
+            if (clause.categorical)
+                return clause.categorical.values;
             if (last?.clause !== clause) {
                 last = { clause, keys: new Set(tuplesOf(clause).map(tupleKey)) };
             }
@@ -233,19 +295,26 @@ export class FilterGroup {
     // -----------------------------------------------------------------
     // Manual entries (for DerivedInterval1D relay, programmatic filters)
     // -----------------------------------------------------------------
-    upsertManual(key, predicate, value, excludeMarkIds, schema) {
-        const resolved = typeof excludeMarkIds === 'function' ? excludeMarkIds() : excludeMarkIds;
-        this.selection.update(`manual:${key}`, {
-            predicate,
-            excludeMarkIds: resolved,
-            value,
-            schema
-        });
-        this.#afterUpdate();
+    upsertManual(key, predicate, value, schema) {
+        const next = { predicate, value, schema, categorical: null };
+        const sourceId = `manual:${key}`;
+        this.#afterUpdate(sourceId, this.selection.update(sourceId, next), next);
+    }
+    /**
+     * Hold `clause` under a manual key, as given: the relay passes another
+     * group's clause on. The clause it already holds there changes nothing, so
+     * it neither re-projects nor re-queries: the relay runs on every change in
+     * its source group, on every brush frame there.
+     */
+    relayClause(key, clause) {
+        const sourceId = `manual:${key}`;
+        if (this.selection.get(sourceId) === clause)
+            return;
+        this.#afterUpdate(sourceId, this.selection.update(sourceId, clause), clause);
     }
     removeManual(key) {
-        this.selection.update(`manual:${key}`, null);
-        this.#afterUpdate();
+        const sourceId = `manual:${key}`;
+        this.#afterUpdate(sourceId, this.selection.update(sourceId, null), null);
     }
     // -----------------------------------------------------------------
     // Clear
@@ -257,68 +326,58 @@ export class FilterGroup {
     clearSource(sourceId) {
         if (!this.selection.isActive(sourceId))
             return;
-        this.selection.update(sourceId, null);
-        this.#afterUpdate();
+        this.#afterUpdate(sourceId, this.selection.update(sourceId, null), null);
     }
     clearAll() {
         this.selection.clear();
-        this.#clearAllScaleProjections();
+        for (const key of this.#selectedFields)
+            this.#activityOf(key).set(this.index, null);
+        this.#selectedFields.clear();
         this.#engine?.onFilterChange(this);
     }
     // -----------------------------------------------------------------
-    // Scale projection
+    // After a change
     // -----------------------------------------------------------------
     /**
-     * After any filter update: project to scales (visual dimming) and notify
-     * the engine to re-query affected marks.
+     * After a clause went from `prev` to `next`: update this group's selection on
+     * the field of either if it is categorical, and have the engine re-query the
+     * marks either clause applies to. A brush, which writes on every pointer
+     * move, touches no selection.
      */
-    #afterUpdate() {
-        this.#projectToScales();
-        this.#engine?.onFilterChange(this);
+    #afterUpdate(sourceId, prev, next) {
+        if (prev?.categorical)
+            this.#syncActivity(prev.categorical.key);
+        if (next?.categorical && next.categorical.key !== prev?.categorical?.key) {
+            this.#syncActivity(next.categorical.key);
+        }
+        if (prev || next)
+            this.#engine?.onClauseChange(this, sourceId, prev, next);
     }
     /**
-     * Project active filter values onto scales (dim unselected categories).
+     * Set this group's selection on field `key` from its clauses: the
+     * intersection of the selected values of every categorical clause on that
+     * field, because the filters AND, or nothing when there is none. Usually one
+     * clause; a native toggle and a relayed one make two. Runs on categorical
+     * clause changes only, never on a brush frame.
      */
-    #projectToScales() {
-        const activeByScale = new Map();
-        for (const [sourceId, registrations] of this.#sources) {
-            const clause = this.selection.get(sourceId);
-            if (!clause)
-                continue;
-            for (const { projection } of registrations) {
-                if (!projection)
-                    continue;
-                const values = projection.values(clause.value);
-                if (!values?.size)
-                    continue;
-                for (const scale of projection.scales()) {
-                    const existing = activeByScale.get(scale);
-                    if (existing) {
-                        for (const v of values)
-                            existing.add(v);
-                    }
-                    else {
-                        activeByScale.set(scale, new Set(values));
-                    }
-                }
-            }
-        }
-        // Set active values on scales that have them
-        for (const [scale, values] of activeByScale) {
-            scale.setActiveValues(values);
-        }
-        // Clear scales that are no longer active
-        for (const scale of this.#projectedScales) {
-            if (!activeByScale.has(scale)) {
-                scale.clearActiveValues();
+    #syncActivity(key) {
+        let active = null;
+        this.selection.forEach((clause) => {
+            const categorical = clause.categorical;
+            if (!categorical || categorical.key !== key)
+                return;
+            if (!active) {
+                active = new Set(categorical.values);
+                return;
             }
-        }
-        this.#projectedScales = new Set(activeByScale.keys());
-    }
-    #clearAllScaleProjections() {
-        for (const scale of this.#projectedScales) {
-            scale.clearActiveValues();
-        }
-        this.#projectedScales.clear();
+            for (const value of active)
+                if (!categorical.values.has(value))
+                    active.delete(value);
+        });
+        if (active)
+            this.#selectedFields.add(key);
+        else
+            this.#selectedFields.delete(key);
+        this.#activityOf(key).set(this.index, active);
     }
 }

package/dist/query-engine/FilterGroupRegistry.svelte.d.ts

@@ -4,15 +4,57 @@
  * Marks and interactors specify which group to use via their `selection`
  * prop (e.g. selection="brush"). Groups are created on first access.
  * Routes that don't use named selections get the "default" group.
+ *
+ * Also owns what is shared between the groups: each group's page-wide index,
+ * and one FieldActivity per categorical field, which holds every group's
+ * selection fade on that field.
  */
+import type { ClockLoop } from '../animation';
 import { FilterGroup } from './FilterGroup.svelte';
+import { FieldActivity } from './FieldActivity.svelte';
 import type { QueryEngine } from './QueryEngine';
 export declare class FilterGroupRegistry {
     #private;
+    constructor();
     /** Wire the engine to all existing and future groups. */
     setEngine(engine: QueryEngine): void;
+    /**
+     * Wire the fades to the animation loop and to the charts to redraw while
+     * they run. Called by the GPU coordinator. A fade created before this lands
+     * at once.
+     */
+    setAnimation(loop: ClockLoop, chartsFor: (key: string, out: string[]) => string[]): void;
     /** Get or create a FilterGroup by name. Undefined/null → "default". */
     get(name?: string | null): FilterGroup;
     /** Check if a named group exists (without creating it). */
     has(name: string): boolean;
+    /** How many groups the page has: the packer writes one activity half per group. */
+    get groupCount(): number;
+    /**
+     * The selection state of a categorical field, by identity key. Created on
+     * first ask, by a selection or by the coordinator for a field a scale draws.
+     *
+     * Never removed: a session that switches through many categorical columns
+     * keeps every field it drew, each one step of the coordinator's per-frame
+     * reconcile loop. Their buffer space is freed (the packer gives a block only
+     * to fields a scale draws), so this costs a loop step, not memory on the GPU.
+     * Dropping a field once no scale draws it and no group selects on it is a
+     * possible follow-up.
+     */
+    field(key: string): FieldActivity;
+    /**
+     * How visible `value` of field `key` is now, for a label shown for marks of
+     * several groups: the least visible over `groups`, so it dims when any of
+     * those groups dims it. 1 for a field no group ever selected on. Pure, so
+     * safe in a template: it creates nothing and reconciles nothing.
+     */
+    opacityOfValue(key: string, groups: readonly number[], value: unknown): number;
+    /**
+     * How visible the category with dim id `id` of field `key` is now: the id form
+     * of `opacityOfValue`, and the one a label for an Other bucket must use. The
+     * least visible over `groups`. Pure, so safe in a template.
+     */
+    opacityOfId(key: string, groups: readonly number[], id: number): number;
+    /** Every field's activity, in creation order. Read every frame; do not mutate. */
+    get fields(): readonly FieldActivity[];
 }

package/dist/query-engine/FilterGroupRegistry.svelte.js

@@ -4,11 +4,40 @@
  * Marks and interactors specify which group to use via their `selection`
  * prop (e.g. selection="brush"). Groups are created on first access.
  * Routes that don't use named selections get the "default" group.
+ *
+ * Also owns what is shared between the groups: each group's page-wide index,
+ * and one FieldActivity per categorical field, which holds every group's
+ * selection fade on that field.
  */
 import { FilterGroup } from './FilterGroup.svelte';
+import { FieldActivity } from './FieldActivity.svelte';
 export class FilterGroupRegistry {
     #groups = new Map();
     #engine = null;
+    #fields = new Map();
+    /**
+     * Bumped when a field is created, so a reader that found none (and so read
+     * no fade) runs again once it exists. Fields are created by selections and by
+     * the coordinator for every field a scale draws, never while a template
+     * renders.
+     */
+    #fieldsVersion = $state(0);
+    /** The same activities as an array, for the packer's per-frame loop. */
+    #fieldList = [];
+    #loop = null;
+    #chartsFor = (_key, out) => out;
+    /** Shared by every FieldActivity: reads the registry's current wiring. */
+    #host;
+    constructor() {
+        const registry = this;
+        this.#host = {
+            get loop() {
+                return registry.#loop;
+            },
+            chartsFor: (key, out) => this.#chartsFor(key, out),
+            identityOf: (key) => this.#engine?.peekIdentity(key) ?? null
+        };
+    }
     /** Wire the engine to all existing and future groups. */
     setEngine(engine) {
         this.#engine = engine;
@@ -16,12 +45,23 @@ export class FilterGroupRegistry {
             group.setEngine(engine);
         }
     }
+    /**
+     * Wire the fades to the animation loop and to the charts to redraw while
+     * they run. Called by the GPU coordinator. A fade created before this lands
+     * at once.
+     */
+    setAnimation(loop, chartsFor) {
+        this.#loop = loop;
+        this.#chartsFor = chartsFor;
+    }
     /** Get or create a FilterGroup by name. Undefined/null → "default". */
     get(name) {
         const key = name ?? 'default';
         let g = this.#groups.get(key);
         if (!g) {
-            g = new FilterGroup();
+            // Indices are never reused or compacted: a mark keeps its group's
+            // index from mount, so renumbering would point it at another group.
+            g = new FilterGroup(this.#groups.size, (field) => this.field(field));
             if (this.#engine)
                 g.setEngine(this.#engine);
             this.#groups.set(key, g);
@@ -32,4 +72,66 @@ export class FilterGroupRegistry {
     has(name) {
         return this.#groups.has(name);
     }
+    /** How many groups the page has: the packer writes one activity half per group. */
+    get groupCount() {
+        return this.#groups.size;
+    }
+    /**
+     * The selection state of a categorical field, by identity key. Created on
+     * first ask, by a selection or by the coordinator for a field a scale draws.
+     *
+     * Never removed: a session that switches through many categorical columns
+     * keeps every field it drew, each one step of the coordinator's per-frame
+     * reconcile loop. Their buffer space is freed (the packer gives a block only
+     * to fields a scale draws), so this costs a loop step, not memory on the GPU.
+     * Dropping a field once no scale draws it and no group selects on it is a
+     * possible follow-up.
+     */
+    field(key) {
+        let activity = this.#fields.get(key);
+        if (!activity) {
+            activity = new FieldActivity(key, this.#host);
+            this.#fields.set(key, activity);
+            this.#fieldList.push(activity);
+            this.#fieldsVersion++;
+        }
+        return activity;
+    }
+    /**
+     * How visible `value` of field `key` is now, for a label shown for marks of
+     * several groups: the least visible over `groups`, so it dims when any of
+     * those groups dims it. 1 for a field no group ever selected on. Pure, so
+     * safe in a template: it creates nothing and reconciles nothing.
+     */
+    opacityOfValue(key, groups, value) {
+        void this.#fieldsVersion;
+        const activity = this.#fields.get(key);
+        if (!activity)
+            return 1;
+        let opacity = 1;
+        for (let i = 0; i < groups.length; i++) {
+            opacity = Math.min(opacity, activity.opacityOfValue(groups[i], value));
+        }
+        return opacity;
+    }
+    /**
+     * How visible the category with dim id `id` of field `key` is now: the id form
+     * of `opacityOfValue`, and the one a label for an Other bucket must use. The
+     * least visible over `groups`. Pure, so safe in a template.
+     */
+    opacityOfId(key, groups, id) {
+        void this.#fieldsVersion;
+        const activity = this.#fields.get(key);
+        if (!activity)
+            return 1;
+        let opacity = 1;
+        for (let i = 0; i < groups.length; i++) {
+            opacity = Math.min(opacity, activity.opacityOfId(groups[i], id));
+        }
+        return opacity;
+    }
+    /** Every field's activity, in creation order. Read every frame; do not mutate. */
+    get fields() {
+        return this.#fieldList;
+    }
 }

package/dist/query-engine/MarkHandle.svelte.d.ts

@@ -24,7 +24,15 @@ export declare class MarkHandle {
     /** Called by mark lifecycle when sort/limit change. */
     updateParams(params: QueryParams): void;
     _onParamsChange: (() => void) | null;
-    /** Engine-internal: called to deliver query results. */
+    /**
+     * Engine-internal: called to deliver query results.
+     *
+     * The table it already holds changes nothing, so it bumps nothing: a cache
+     * hit hands back the same object, and bumping `dataVersion` for it reran
+     * every effect that reads it (the tooltip table, data-following domains).
+     * The error is cleared either way, so a success after a failure still
+     * clears it.
+     */
     _setResult(table: Table): void;
     /** Engine-internal: called on query error. */
     _setError(error: Error): void;

package/dist/query-engine/MarkHandle.svelte.js

@@ -21,11 +21,21 @@ export class MarkHandle {
     // Engine sets this callback during registration.
     // Conventional underscore — engine needs external access.
     _onParamsChange = null;
-    /** Engine-internal: called to deliver query results. */
+    /**
+     * Engine-internal: called to deliver query results.
+     *
+     * The table it already holds changes nothing, so it bumps nothing: a cache
+     * hit hands back the same object, and bumping `dataVersion` for it reran
+     * every effect that reads it (the tooltip table, data-following domains).
+     * The error is cleared either way, so a success after a failure still
+     * clears it.
+     */
     _setResult(table) {
+        this.error = null;
+        if (table === this.arrowTable)
+            return;
         this.arrowTable = table;
         this.dataVersion++;
-        this.error = null;
     }
     /** Engine-internal: called on query error. */
     _setError(error) {