@fjader/svelte 0.2.1 → 0.2.3

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

@@ -2,44 +2,110 @@
  * CrossfilterSelection — Svelte 5-native crossfilter predicate engine.
  *
  * Replaces Mosaic's Selection.intersect({ cross: true }) with a reactive
- * $state Map. Marks derive their filter via predicate(markId), which
- * returns all active predicates except those that exclude that mark.
+ * $state Map of clauses, plus the registrations of the sources that write
+ * them. Marks derive their filter via predicate(route): every clause that
+ * filters the mark.
  *
- * Cross-filtering is chart-level: interactors pass excludeMarkIds (the set
- * of all marks in the source chart). When a brush in chart A fires, all
- * marks in chart A skip that clause. All other marks receive it.
+ * WHICH CLAUSES FILTER A MARK. The mark decides, not the control that wrote
+ * the clause. A clause filters a mark unless:
+ * - it is a categorical selection on a field the mark reads selection
+ *   activity for (the mark dims by it instead), or
+ * - the mark's chart holds a registration of the clause's source that opted
+ *   into skipping its chart (crossfilter: a brush does not filter its own
+ *   chart).
+ * Both are computed when asked, from the clause, the mark's route and the
+ * live registrations: nothing is cached, so nothing goes stale.
  */
 import { SvelteMap } from 'svelte/reactivity';
+/** A mark with no route: it reads no activity and is in no chart. */
+export const NO_ROUTE = { reads: [], chart: null };
 // ---------------------------------------------------------------------------
 // CrossfilterSelection
 // ---------------------------------------------------------------------------
 export class CrossfilterSelection {
     #clauses = new SvelteMap();
+    /** Registrations per source id. Several under one id are one source. Not reactive. */
+    #sources = new Map();
+    /** Add a registration of `sourceId`. */
+    addRegistration(sourceId, registration) {
+        let registrations = this.#sources.get(sourceId);
+        if (!registrations) {
+            registrations = new Set();
+            this.#sources.set(sourceId, registrations);
+        }
+        registrations.add(registration);
+    }
+    /** Remove a registration of `sourceId`; the last one removes the source. */
+    removeRegistration(sourceId, registration) {
+        const registrations = this.#sources.get(sourceId);
+        if (!registrations?.delete(registration))
+            return;
+        if (registrations.size === 0)
+            this.#sources.delete(sourceId);
+    }
+    /** The live registrations of `sourceId`, or undefined when it has none. */
+    registrationsOf(sourceId) {
+        return this.#sources.get(sourceId);
+    }
     /**
-     * Compute the filter predicate for a given mark.
-     * Returns all active predicates except those whose excludeMarkIds
-     * contains the given markId.
+     * Whether a clause of `sourceId` filters the mark with `route`. `key` is
+     * the clause's categorical field (its identity key), or null for a brush,
+     * a tuple or a manual clause; before the source has written a clause, its
+     * registrations' key, which preagg activation needs on hover.
+     *
+     * A plain loop over the registrations, which are one to three: no closure,
+     * no allocation, as it runs per mark per clause on every brush frame.
      */
-    predicate(markId) {
+    filters(route, sourceId, key) {
+        if (key !== null && route.reads.includes(key))
+            return false;
+        const chart = route.chart;
+        if (chart) {
+            // Every chart with a Toggle or legend on the same fields registers
+            // their one source, so a chart skip would let a 'filter' mark ignore
+            // those fields wherever it has such a control. A click does not move
+            // under the pointer, so filtering the own chart is safe for it.
+            const filterMark = route.response === 'filter';
+            const registrations = this.#sources.get(sourceId);
+            if (registrations) {
+                for (const registration of registrations) {
+                    if (registration.chart === chart && !(filterMark && registration.discrete)) {
+                        return false;
+                    }
+                }
+            }
+        }
+        return true;
+    }
+    /** Whether `clause`, written by `sourceId`, filters the mark with `route`. */
+    applies(sourceId, clause, route) {
+        return !!clause.predicate && this.filters(route, sourceId, clause.categorical?.key ?? null);
+    }
+    /** Every predicate that filters the mark with `route`. */
+    predicate(route) {
         const result = [];
-        for (const clause of this.#clauses.values()) {
-            if (!clause.excludeMarkIds.has(markId) && clause.predicate) {
+        for (const [sourceId, clause] of this.#clauses) {
+            if (this.applies(sourceId, clause, route))
                 result.push(clause.predicate);
-            }
         }
         return result;
     }
     /**
      * Update or remove a clause.
      * Pass null to remove (clear) the clause for the given source.
+     *
+     * Returns the clause it replaced or removed, so the caller can re-query the
+     * marks either one applies to.
      */
     update(sourceId, clause) {
+        const prev = this.#clauses.get(sourceId);
         if (clause) {
             this.#clauses.set(sourceId, clause);
         }
         else {
             this.#clauses.delete(sourceId);
         }
+        return prev;
     }
     /** Whether a given source has an active (non-null) clause. */
     isActive(sourceId) {
@@ -49,6 +115,14 @@ export class CrossfilterSelection {
     get(sourceId) {
         return this.#clauses.get(sourceId);
     }
+    /**
+     * Visit every active clause: the stored objects themselves, not copies, so a
+     * caller can tell an unchanged clause by reference. Reactive like `items`,
+     * without building an entry object per clause.
+     */
+    forEach(visit) {
+        this.#clauses.forEach(visit);
+    }
     /** Reactive list of all active clauses with their source IDs. */
     get items() {
         const result = [];
@@ -61,17 +135,17 @@ export class CrossfilterSelection {
      * Whether a clause is baked into a mark's preagg table: every clause that
      * filters the mark, except the active brush, which the table bins instead.
      */
-    #isBaked(sourceId, clause, markId, activeSourceId) {
-        return sourceId !== activeSourceId && !clause.excludeMarkIds.has(markId) && !!clause.predicate;
+    #isBaked(sourceId, clause, route, activeSourceId) {
+        return sourceId !== activeSourceId && this.applies(sourceId, clause, route);
     }
     /**
      * The clause objects a preagg table bakes in, in map insertion order.
      * Stored at build time so bakedClausesMatch() can compare by reference.
      */
-    bakedClauses(markId, activeSourceId) {
+    bakedClauses(route, activeSourceId) {
         const result = [];
         for (const [sourceId, clause] of this.#clauses) {
-            if (this.#isBaked(sourceId, clause, markId, activeSourceId))
+            if (this.#isBaked(sourceId, clause, route, activeSourceId))
                 result.push(clause);
         }
         return result;
@@ -80,10 +154,10 @@ export class CrossfilterSelection {
      * The baked predicates sorted by source ID, so the same filters always
      * produce the same preagg SQL whatever order their clauses were added in.
      */
-    bakedPredicates(markId, activeSourceId) {
+    bakedPredicates(route, activeSourceId) {
         const entries = [];
         for (const [sourceId, clause] of this.#clauses) {
-            if (this.#isBaked(sourceId, clause, markId, activeSourceId)) {
+            if (this.#isBaked(sourceId, clause, route, activeSourceId)) {
                 entries.push([sourceId, clause.predicate]);
             }
         }
@@ -95,10 +169,10 @@ export class CrossfilterSelection {
      * Every filter change replaces its Clause object, so an unchanged filter
      * keeps its reference. Runs every brush frame, so it allocates nothing.
      */
-    bakedClausesMatch(markId, activeSourceId, then) {
+    bakedClausesMatch(route, activeSourceId, then) {
         let i = 0;
         for (const [sourceId, clause] of this.#clauses) {
-            if (!this.#isBaked(sourceId, clause, markId, activeSourceId))
+            if (!this.#isBaked(sourceId, clause, route, activeSourceId))
                 continue;
             if (i >= then.length || clause !== then[i++])
                 return false;

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

@@ -0,0 +1,79 @@
+import type { ClockLoop } from '../animation';
+import { ActivityTable } from '../scales/ActivityTable';
+import type { FieldIdentity } from './categorical-identity';
+/** What a FieldActivity needs from the page around it. */
+export interface FieldActivityHost {
+    /** Drives the fades; null in unit tests and before a coordinator exists, and fades land at once. */
+    readonly loop: ClockLoop | null;
+    /** Fill `out` with the charts drawing any scale on `key`, for the fade's redraws. */
+    chartsFor(key: string, out: string[]): string[];
+    /** The field's live identity, or null; must never create one. */
+    identityOf(key: string): FieldIdentity | null;
+}
+/** A host with no page: no loop, no charts, no identity. */
+export declare const DETACHED_HOST: FieldActivityHost;
+/**
+ * Which categories of one field are selected, per filter group, and how far
+ * each one has faded.
+ *
+ * Activity is indexed by the field's identity id, and FieldIdentity is one per
+ * field, so it belongs to the field, not to any scale on it: the carrier colour
+ * scale and every carrier band scale read the same activity. One fade per
+ * filter group, indexed by the group's page-wide index, because a selection
+ * belongs to the group it was made in: a click in group A dims group A's marks
+ * and leaves group B's alone.
+ *
+ * The packer writes these tables into the field's activity block, and legends
+ * and band labels read them through `opacityOfValue`.
+ *
+ * IDS AND IDENTITY. Ids are only meaningful within one identity: across a
+ * reload the same id can name another category. So the tables follow the
+ * field's LIVE identity, which `reconcile` compares with the one last applied:
+ * a different object is a reload, and every fade is dropped and snapped to its
+ * selection; the same object at a higher version is a dim that grew, and the
+ * existing ids keep their fades while new ones start in their state.
+ * `reconcile` runs from the packer and from `set`, never from a reader, so
+ * nothing is resized or retargeted while a template renders.
+ */
+export declare class FieldActivity {
+    #private;
+    readonly key: string;
+    constructor(key: string, host?: FieldActivityHost);
+    /** How many ids the tables cover: the applied identity's, 0 without one. */
+    get count(): number;
+    /** Group `index`'s fade, or null when that group never selected on this field. */
+    fadeOf(index: number): ActivityTable | null;
+    /**
+     * Select `values` in group `index`, or nothing for null.
+     *
+     * The table is first brought up to the live identity under the selection it
+     * had, so the change from that selection to this one fades. Sizing it with
+     * the new values instead would put every id straight into its new state: a
+     * group's first click, or the first one after the dim grew, would snap.
+     */
+    set(index: number, values: ReadonlySet<unknown> | null): void;
+    /**
+     * Follow the field's live identity: snap every fade on a reload, extend them
+     * when the dim grew. Two comparisons when nothing moved, no allocation.
+     * Returns whether it re-applied the groups.
+     */
+    reconcile(): boolean;
+    /**
+     * How visible a category is now in group `index`: its fade when the value
+     * has an id in the current identity, and otherwise simply selected or not.
+     * Pure, so it is safe in a template: it never reconciles, and a table that
+     * belongs to an identity no longer live is not trusted.
+     */
+    opacityOfValue(index: number, value: unknown, inactiveOpacity?: number): number;
+    /**
+     * How visible the category with dim id `id` is now in group `index`: its fade.
+     * The id form of `opacityOfValue`, and the only one that reaches a synthetic
+     * id (an Other bucket): a bucket has a label, not a value, and several may
+     * share one label. Pure, so it is safe in a template.
+     *
+     * Before the group's table covers the id, falls back to the selected values
+     * for a real id, and to fully visible for a bucket or an identity that is not
+     * live: a label is never dimmed on a guess.
+     */
+    opacityOfId(index: number, id: number, inactiveOpacity?: number): number;
+}

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

@@ -0,0 +1,207 @@
+import { ActivityTable, DEFAULT_INACTIVE_OPACITY, selectionOpacity } from '../scales/ActivityTable';
+/** A host with no page: no loop, no charts, no identity. */
+export const DETACHED_HOST = {
+    loop: null,
+    chartsFor: (_key, out) => out,
+    identityOf: () => null
+};
+/** One filter group's selection on one field, and its fade. */
+class GroupFade {
+    table;
+    /** The selected values, or null for none. State, for the by-value fallback. */
+    values = $state.raw(null);
+    /** Bumped on every frame the fade is driven, and once at rest. */
+    frame = $state(0);
+    constructor(host, key, charts) {
+        this.table = new ActivityTable(host.loop, {
+            charts: () => {
+                charts.length = 0;
+                return host.chartsFor(key, charts);
+            },
+            onFrame: () => this.frame++
+        });
+    }
+}
+/**
+ * Which categories of one field are selected, per filter group, and how far
+ * each one has faded.
+ *
+ * Activity is indexed by the field's identity id, and FieldIdentity is one per
+ * field, so it belongs to the field, not to any scale on it: the carrier colour
+ * scale and every carrier band scale read the same activity. One fade per
+ * filter group, indexed by the group's page-wide index, because a selection
+ * belongs to the group it was made in: a click in group A dims group A's marks
+ * and leaves group B's alone.
+ *
+ * The packer writes these tables into the field's activity block, and legends
+ * and band labels read them through `opacityOfValue`.
+ *
+ * IDS AND IDENTITY. Ids are only meaningful within one identity: across a
+ * reload the same id can name another category. So the tables follow the
+ * field's LIVE identity, which `reconcile` compares with the one last applied:
+ * a different object is a reload, and every fade is dropped and snapped to its
+ * selection; the same object at a higher version is a dim that grew, and the
+ * existing ids keep their fades while new ones start in their state.
+ * `reconcile` runs from the packer and from `set`, never from a reader, so
+ * nothing is resized or retargeted while a template renders.
+ */
+export class FieldActivity {
+    key;
+    #host;
+    #groups = [];
+    /**
+     * Bumped when a group's fade is created, so a reader that found none runs
+     * again once it exists. Fades are created by `set`, never while rendering.
+     */
+    #groupsVersion = $state(0);
+    /** The identity the tables' ids belong to, or null when they have none. */
+    #identity = null;
+    #version = -1;
+    /** Reused id list: selections are applied on every categorical click. */
+    #ids = [];
+    constructor(key, host = DETACHED_HOST) {
+        this.key = key;
+        this.#host = host;
+    }
+    /** How many ids the tables cover: the applied identity's, 0 without one. */
+    get count() {
+        return this.#identity ? this.#identity.values.length : 0;
+    }
+    /** Group `index`'s fade, or null when that group never selected on this field. */
+    fadeOf(index) {
+        return this.#groups[index]?.table ?? null;
+    }
+    /**
+     * Select `values` in group `index`, or nothing for null.
+     *
+     * The table is first brought up to the live identity under the selection it
+     * had, so the change from that selection to this one fades. Sizing it with
+     * the new values instead would put every id straight into its new state: a
+     * group's first click, or the first one after the dim grew, would snap.
+     */
+    set(index, values) {
+        const group = this.#group(index);
+        this.reconcile();
+        if (group.table.count !== this.count)
+            this.#apply(group);
+        group.values = values;
+        this.#apply(group);
+    }
+    /**
+     * Follow the field's live identity: snap every fade on a reload, extend them
+     * when the dim grew. Two comparisons when nothing moved, no allocation.
+     * Returns whether it re-applied the groups.
+     */
+    reconcile() {
+        const live = this.#host.identityOf(this.key);
+        const usable = live && live.values.length > 0 ? live : null;
+        if (usable === this.#identity) {
+            if (!usable || usable.version === this.#version)
+                return false;
+            // The same identity, grown.
+            this.#version = usable.version;
+            for (const group of this.#groups)
+                this.#apply(group);
+            return true;
+        }
+        // Another identity, or none: the old ids mean nothing now.
+        this.#identity = usable;
+        this.#version = usable ? usable.version : -1;
+        for (const group of this.#groups) {
+            group.table.resize(0);
+            this.#apply(group);
+        }
+        return true;
+    }
+    /**
+     * How visible a category is now in group `index`: its fade when the value
+     * has an id in the current identity, and otherwise simply selected or not.
+     * Pure, so it is safe in a template: it never reconciles, and a table that
+     * belongs to an identity no longer live is not trusted.
+     */
+    opacityOfValue(index, value, inactiveOpacity = DEFAULT_INACTIVE_OPACITY) {
+        void this.#groupsVersion;
+        const group = this.#groups[index];
+        if (!group)
+            return 1;
+        // Read first, so a reader that ran before identity landed already depends
+        // on the frame counter for the fade that follows.
+        void group.frame;
+        const identity = this.#identity;
+        if (identity && identity === this.#host.identityOf(this.key)) {
+            const id = identity.ids.get(value);
+            if (id != null)
+                return this.opacityOfId(index, id, inactiveOpacity);
+        }
+        const values = group.values;
+        return values == null || values.has(value) ? 1 : inactiveOpacity;
+    }
+    /**
+     * How visible the category with dim id `id` is now in group `index`: its fade.
+     * The id form of `opacityOfValue`, and the only one that reaches a synthetic
+     * id (an Other bucket): a bucket has a label, not a value, and several may
+     * share one label. Pure, so it is safe in a template.
+     *
+     * Before the group's table covers the id, falls back to the selected values
+     * for a real id, and to fully visible for a bucket or an identity that is not
+     * live: a label is never dimmed on a guess.
+     */
+    opacityOfId(index, id, inactiveOpacity = DEFAULT_INACTIVE_OPACITY) {
+        void this.#groupsVersion;
+        const group = this.#groups[index];
+        if (!group)
+            return 1;
+        void group.frame;
+        const values = group.values;
+        const identity = this.#identity;
+        if (!identity || identity !== this.#host.identityOf(this.key))
+            return 1;
+        if (id >= 0 && id < group.table.count) {
+            return selectionOpacity(group.table.activityOf(id), inactiveOpacity);
+        }
+        if (values == null || identity.synthetic.has(id) || id < 0 || id >= identity.values.length) {
+            return 1;
+        }
+        return values.has(identity.values[id]) ? 1 : inactiveOpacity;
+    }
+    #group(index) {
+        let group = this.#groups[index];
+        if (!group) {
+            // Fill any gap below it too: the packer walks the groups by index.
+            for (let i = this.#groups.length; i <= index; i++) {
+                this.#groups[i] = new GroupFade(this.#host, this.key, []);
+            }
+            group = this.#groups[index];
+            this.#groupsVersion++;
+        }
+        return group;
+    }
+    /**
+     * Point a group's table at its selection under the applied identity. A new
+     * id starts in its state rather than fading in, which is what keeps a
+     * selection made before its ids existed from fading on arrival.
+     */
+    #apply(group) {
+        const identity = this.#identity;
+        if (!identity) {
+            group.table.resize(0);
+            return;
+        }
+        const count = identity.values.length;
+        const values = group.values;
+        if (values == null) {
+            group.table.resize(count, null);
+            group.table.clear();
+            return;
+        }
+        const ids = this.#ids;
+        ids.length = 0;
+        for (const value of values) {
+            const id = identity.ids.get(value);
+            if (id != null)
+                ids.push(id);
+        }
+        group.table.resize(count, ids);
+        group.table.setActive(ids);
+    }
+}

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

@@ -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.
@@ -12,16 +12,9 @@
  * objects, no event listeners.
  */
 import { CrossfilterSelection } from './CrossfilterSelection.svelte';
-import type { FilterExpr, FilterSchema } from './CrossfilterSelection.svelte';
+import type { Clause, FilterExpr, FilterSchema, SourceRegistration } from './CrossfilterSelection.svelte';
 import type { ActiveDim, QueryEngine } from './QueryEngine';
-/**
- * Narrow protocol for scale states that support active-value projection.
- * Implemented by ColorScaleState and BandScaleState.
- */
-export interface ActiveValueScale {
-    setActiveValues(values: Set<unknown>): void;
-    clearActiveValues(): void;
-}
+import { FieldActivity } from './FieldActivity.svelte';
 export interface FilterItem {
     sourceId: string;
     predicate: FilterExpr;
@@ -29,10 +22,23 @@ export interface FilterItem {
     schema?: FilterSchema;
 }
 /** One registration of a selection source: a brush, a legend, a Toggle. */
-export interface SourceOpts {
-    /** Getter for mark IDs this registration's writes exclude (chart-level cross-filtering).
-     *  A getter rather than a static Set so it stays current if marks are added/removed. */
-    excludeMarkIds: () => Set<string>;
+export interface SourceOpts extends SourceRegistration {
+    /**
+     * The chart this registration skips: its ChartConfig, or nothing. A chart
+     * holding a control for a selection is not filtered by it (crossfilter), so
+     * its marks that do not read the field keep their data; those that do, dim.
+     * Opt-in: a control that wants its own chart filtered passes none.
+     */
+    chart?: object | null;
+    /**
+     * For a source that selects categories of one field: that field's identity
+     * key, and how to read the selected values from a write. Every clause the
+     * source writes carries both (`Clause.categorical`).
+     */
+    categorical?: {
+        key: string;
+        values: (value: unknown) => ReadonlySet<unknown>;
+    };
     /** How the source selects, read at hover time for preagg activation. */
     activeDims?: () => ActiveDim[];
     /**
@@ -41,16 +47,14 @@ export interface SourceOpts {
      * while its bins are as fine as the pixels.
      */
     view?: (out: Float64Array) => void;
-    /** Schema metadata for UI filter pills, derived from the clause value. */
+    /**
+     * Schema metadata for UI filter pills, derived from the clause value. Run
+     * once per write and stored on the clause.
+     */
     augment?: (value: unknown) => FilterSchema | null;
-    /** The scales to dim, and the values to dim them by, taken from the clause value. */
-    projection?: {
-        scales: () => ActiveValueScale[];
-        values: (value: unknown) => Set<unknown> | null;
-    };
 }
 export interface SourceHandle {
-    /** Write the clause, excluding this registration's marks. */
+    /** Write the source's clause. */
     update(predicate: FilterExpr, value: unknown): void;
     clear(): void;
     /** Prepare preagg tables for this source, ahead of its first use. */
@@ -81,8 +85,23 @@ export interface ToggleHandle extends Omit<SourceHandle, 'update'> {
 export declare class FilterGroup {
     #private;
     readonly selection: CrossfilterSelection;
+    /**
+     * 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.
+     */
+    readonly index: number;
+    /**
+     * A group made outside a registry (unit tests) keeps its field activity to
+     * itself, with no loop: its fades land at once.
+     */
+    constructor(index?: number, activityOf?: (key: string) => FieldActivity);
+    /** The selection state of a categorical field, by identity key: this group's fade is `index`. */
+    activity(key: string): FieldActivity;
     setEngine(engine: QueryEngine): void;
-    /** 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(): FilterItem[];
     /** Number of active filters. */
     get activeCount(): number;
@@ -90,8 +109,7 @@ export declare class FilterGroup {
     fieldSql(field: string): string | null;
     /**
      * 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: string, opts: SourceOpts): SourceHandle;
     /**
@@ -103,11 +121,17 @@ export declare class FilterGroup {
      * as the selection. Nothing else writes those ids (`upsertManual` prefixes
      * its own with `manual:`).
      */
-    registerToggle(fields: string | string[], opts: {
-        excludeMarkIds: () => Set<string>;
-        scales?: () => ActiveValueScale[];
+    registerToggle(fields: string | string[], opts?: {
+        chart?: object | null;
     }): ToggleHandle;
-    upsertManual(key: string, predicate: FilterExpr, value: unknown, excludeMarkIds: Set<string> | (() => Set<string>), schema?: FilterSchema): void;
+    upsertManual(key: string, predicate: FilterExpr, value: unknown, schema?: FilterSchema): void;
+    /**
+     * 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: string, clause: Clause): void;
     removeManual(key: string): void;
     /**
      * Remove a source's clause. Re-queries only when there was a clause to