@fjader/svelte 0.2.2 → 0.2.4

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,75 @@ 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),
+            // The registration's own clear: it already reset what it drew.
+            clear: () => this.clearSource(sourceId, opts),
             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;
-                this.#sources.delete(sourceId);
-                this.#engine?.forgetSource(this, sourceId);
-                this.clearSource(sourceId);
+                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);
+                    // Quietly: the registration is going away, nothing of it to reset.
+                    this.clearSource(sourceId, opts);
+                    selection.removeRegistration(sourceId, opts);
+                    return;
+                }
+                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 +204,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 +229,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)) };
             }
@@ -213,6 +277,24 @@ export class FilterGroup {
                 write([...next.values()]);
             },
             set: (tuples) => write(tuples),
+            toggleOther: (otherId, facetId, multi) => {
+                if (list.length !== 1 || categoricalKey === null)
+                    return;
+                const click = this.activity(categoricalKey).otherClick(this.index, otherId, facetId, keysOf(selection.get(sourceId)), multi);
+                if (!click)
+                    return;
+                const next = new Map(tuplesOf(selection.get(sourceId)).map((t) => [tupleKey(t), t]));
+                if (click.action === 'replace')
+                    next.clear();
+                for (const value of click.values) {
+                    const tuple = [value];
+                    if (click.action === 'remove')
+                        next.delete(tupleKey(tuple));
+                    else
+                        next.set(tupleKey(tuple), tuple);
+                }
+                write([...next.values()]);
+            },
             clear: () => write([]),
             activate: source.activate,
             destroy: source.destroy
@@ -233,19 +315,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
@@ -253,72 +342,82 @@ export class FilterGroup {
     /**
      * Remove a source's clause. Re-queries only when there was a clause to
      * remove: an unmount or a clear with nothing selected changes no mark's data.
+     *
+     * The source's registrations are told (`onCleared`) so a control that drew the
+     * selection resets it, all of them from outside, and all but `by` when a
+     * registration is the one clearing (it has reset itself).
      */
-    clearSource(sourceId) {
+    clearSource(sourceId, by) {
         if (!this.selection.isActive(sourceId))
             return;
-        this.selection.update(sourceId, null);
-        this.#afterUpdate();
+        this.#afterUpdate(sourceId, this.selection.update(sourceId, null), null);
+        this.#notifyCleared(sourceId, by);
     }
+    /** Remove every clause, and tell the controls that drew them (`onCleared`). */
     clearAll() {
+        const cleared = this.selection.items.map((item) => item.sourceId);
         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);
+        for (const sourceId of cleared)
+            this.#notifyCleared(sourceId);
+    }
+    /** Tell a source's registrations, but `except`, that its clause is gone. */
+    #notifyCleared(sourceId, except) {
+        const registrations = this.selection.registrationsOf(sourceId);
+        if (!registrations)
+            return;
+        // A copy: a control resetting itself may register or destroy while this runs.
+        for (const opts of [...registrations]) {
+            if (opts !== except)
+                opts.onCleared?.();
+        }
     }
     // -----------------------------------------------------------------
-    // 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));
-                    }
-                }
+    #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;
             }
-        }
-        // 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();
-            }
-        }
-        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,85 @@
  * 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;
-    /** Get or create a FilterGroup by name. Undefined/null → "default". */
+    /**
+     * 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".
+     *
+     * Untracked: a reader does not re-run because it called `get`. For a reactive
+     * read use `find`, `has` or `isActive`, which create nothing: a group created
+     * inside the derived that reads it is state that derived cannot track, so
+     * `$derived(get('brush').activeCount)` before any chart made the group never
+     * updates. Create groups from init, effects and handlers.
+     */
     get(name?: string | null): FilterGroup;
-    /** Check if a named group exists (without creating it). */
-    has(name: string): boolean;
+    /**
+     * The named group, or undefined if no chart has made it yet. Creates nothing.
+     * Reactive: a reader re-runs when the group is created.
+     */
+    find(name?: string | null): FilterGroup | undefined;
+    /** Whether a named group exists, without creating it. Reactive, as `find`. */
+    has(name?: string | null): boolean;
+    /**
+     * Whether a named group has a selection (a brush, a toggle, a legend), without
+     * creating it: false for a group no chart has made yet. Reactive in both the
+     * group appearing and its clauses changing, so `$derived(groups.isActive('brush'))`
+     * is safe before any chart exists.
+     */
+    isActive(name?: string | null): boolean;
+    /**
+     * The names of the groups, in creation order. Reactive: a reader re-runs when a
+     * group is created. A new array on each read. For app code that must reach every group the page's marks
+     * use, such as a clause that applies to the whole page.
+     */
+    get names(): readonly string[];
+    /** The groups, in the order of `names`. Reactive in the same way. */
+    get groups(): readonly FilterGroup[];
+    /** 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[];
 }