@fjader/svelte 0.2.2 → 0.2.4

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

@@ -0,0 +1,128 @@
+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. */
+/** One mark's Other rows for one bucket: what a click on it selects. */
+export interface OtherEntry {
+    /** The mark's filter group, or null when it is filtered by the selection (`'filter'`). */
+    group: number | null;
+    /** One per Other row: a facet cell (null without facets) and its folded ids. */
+    rows: {
+        facetId: number | null;
+        ids: ArrayLike<number>;
+    }[];
+}
+/** What a click on Other does to a selection: values to set, add or remove. */
+export interface OtherClick {
+    action: 'replace' | 'add' | 'remove';
+    values: unknown[];
+}
+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.
+ */
+/**
+ * THE FREE SLOT. Each group's table holds one slot past the field's ids: 1 while
+ * the group selects nothing on the field, 0 while it selects anything, faded on
+ * the same clock as every id. The shader reads it as the last slot of the
+ * group's run (identityFreeActivity): an Other bar's unselected part dims by it,
+ * so clearing a selection fades it back in with the other bars, rather than its
+ * split sliding.
+ */
+export declare class FieldActivity {
+    #private;
+    readonly key: string;
+    constructor(key: string, host?: FieldActivityHost);
+    /**
+     * How many slots the tables cover: one per id of the applied identity, and
+     * one past them (FREE_SLOT); 0 without an identity.
+     */
+    get count(): number;
+    /**
+     * Group `index`'s selected values, or null when it selects nothing on this
+     * field. Reactive: a reader re-runs when the selection changes.
+     */
+    selectedValues(index: number): ReadonlySet<unknown> | null;
+    /** 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;
+    /** Register `markId`'s Other rows under `otherId`; null removes them. */
+    setOther(otherId: number, markId: string, entry: OtherEntry | null): void;
+    /**
+     * What a click on Other `otherId` does to group `group`'s selection, given
+     * the values it holds now (`current`), and records it. Null when nothing is
+     * registered under the id (no result yet) or it holds no members.
+     *
+     * - The members: every registered row under the id, or only facet cell
+     *   `facetId`'s when the click came from a cell.
+     * - Shift-click adds them, or takes back what this Other added before if it
+     *   is still selected.
+     * - A plain click on an Other whose marks all filter by the selection (no
+     *   group: `'filter'`) drills down, replacing the selection: such an Other is
+     *   computed inside the selection, so a second click means "the rest of it".
+     * - Otherwise a plain click toggles: it takes back what this Other added if
+     *   that is still selected, and replaces the selection with the members if not.
+     */
+    otherClick(group: number, otherId: number, facetId: number | null, current: ReadonlySet<unknown>, multi: boolean): OtherClick | null;
+}

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

@@ -0,0 +1,378 @@
+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.
+ */
+/**
+ * THE FREE SLOT. Each group's table holds one slot past the field's ids: 1 while
+ * the group selects nothing on the field, 0 while it selects anything, faded on
+ * the same clock as every id. The shader reads it as the last slot of the
+ * group's run (identityFreeActivity): an Other bar's unselected part dims by it,
+ * so clearing a selection fades it back in with the other bars, rather than its
+ * split sliding.
+ */
+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 slots the tables cover: one per id of the applied identity, and
+     * one past them (FREE_SLOT); 0 without an identity.
+     */
+    get count() {
+        return this.#identity ? this.#identity.values.length + 1 : 0;
+    }
+    /**
+     * Group `index`'s selected values, or null when it selects nothing on this
+     * field. Reactive: a reader re-runs when the selection changes.
+     */
+    selectedValues(index) {
+        void this.#groupsVersion;
+        return this.#groups[index]?.values ?? null;
+    }
+    /** 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;
+    }
+    // -----------------------------------------------------------------
+    // Other buckets: what each one holds, for a click to select
+    // -----------------------------------------------------------------
+    /**
+     * Every Other bucket's members, by its id and the mark that drew it. Each
+     * mark registers its Other rows per result (`setOther`): the folded ids its
+     * query returned, per facet cell. A click on Other reads them, so what it
+     * selects is exactly what the bar summed.
+     */
+    #others = new Map();
+    /**
+     * What an Other click contributed to a group's selection, by `group:otherId`:
+     * how a second click on the same Other knows what to take back. Dropped with
+     * the id's last entry, so a reused id starts with no memory.
+     */
+    #otherMemory = new Map();
+    /** Register `markId`'s Other rows under `otherId`; null removes them. */
+    setOther(otherId, markId, entry) {
+        let byMark = this.#others.get(otherId);
+        const before = byMark?.get(markId)?.group;
+        if (entry) {
+            if (!byMark)
+                this.#others.set(otherId, (byMark = new Map()));
+            byMark.set(markId, entry);
+        }
+        else {
+            if (!byMark?.delete(markId))
+                return;
+            if (byMark.size === 0) {
+                this.#others.delete(otherId);
+                for (const memKey of [...this.#otherMemory.keys()]) {
+                    if (memKey.endsWith(`:${otherId}`))
+                        this.#otherMemory.delete(memKey);
+                }
+            }
+        }
+        // The bucket's members moved (a new result), or it came or went: whether it
+        // is lit may have changed in the group its marks dim under. A fade it does
+        // not change costs nothing (#retarget returns early).
+        this.#reapply(before);
+        if (entry && entry.group !== before)
+            this.#reapply(entry.group);
+    }
+    #reapply(index) {
+        if (index == null)
+            return;
+        const group = this.#groups[index];
+        if (group && group.values != null)
+            this.#apply(group);
+    }
+    /**
+     * What a click on Other `otherId` does to group `group`'s selection, given
+     * the values it holds now (`current`), and records it. Null when nothing is
+     * registered under the id (no result yet) or it holds no members.
+     *
+     * - The members: every registered row under the id, or only facet cell
+     *   `facetId`'s when the click came from a cell.
+     * - Shift-click adds them, or takes back what this Other added before if it
+     *   is still selected.
+     * - A plain click on an Other whose marks all filter by the selection (no
+     *   group: `'filter'`) drills down, replacing the selection: such an Other is
+     *   computed inside the selection, so a second click means "the rest of it".
+     * - Otherwise a plain click toggles: it takes back what this Other added if
+     *   that is still selected, and replaces the selection with the members if not.
+     */
+    otherClick(group, otherId, facetId, current, multi) {
+        const entries = this.#others.get(otherId);
+        const identity = this.#host.identityOf(this.key);
+        if (!entries || entries.size === 0 || !identity)
+            return null;
+        const members = new Set();
+        let drill = true;
+        for (const entry of entries.values()) {
+            if (entry.group !== null)
+                drill = false;
+            for (const row of entry.rows) {
+                if (facetId !== null && row.facetId !== facetId)
+                    continue;
+                for (let i = 0; i < row.ids.length; i++) {
+                    const id = row.ids[i];
+                    if (identity.synthetic.has(id))
+                        continue;
+                    const value = identity.values[id];
+                    if (value !== undefined)
+                        members.add(value);
+                }
+            }
+        }
+        if (members.size === 0)
+            return null;
+        const memKey = `${group}:${otherId}`;
+        const before = this.#otherMemory.get(memKey);
+        const stillSelected = !!before && before.size > 0 && [...before].every((v) => current.has(v));
+        if (stillSelected && (multi || !drill)) {
+            this.#otherMemory.delete(memKey);
+            return { action: 'remove', values: [...before] };
+        }
+        if (!multi) {
+            // A replace: what any other Other added is gone from the selection.
+            for (const key of [...this.#otherMemory.keys()]) {
+                if (key.startsWith(`${group}:`))
+                    this.#otherMemory.delete(key);
+            }
+        }
+        this.#otherMemory.set(memKey, members);
+        return { action: multi ? 'add' : 'replace', values: [...members] };
+    }
+    #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;
+        }
+        // Every id, and the free slot past them: clear() sets it to 1 and
+        // setActive() leaves it out, so it fades to 0 while anything is selected
+        // and back to 1 once nothing is (see FieldActivity's FREE_SLOT note).
+        const count = identity.values.length + 1;
+        const values = group.values;
+        if (values == null) {
+            group.table.resize(count, null, true);
+            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);
+        }
+        this.#lightOthers(this.#groups.indexOf(group), ids, count);
+        group.table.resize(count, ids, true);
+        group.table.setActive(ids);
+    }
+    /**
+     * Add to `ids` (the selected ids) every Other bucket that holds one of them,
+     * by the members its marks in group `index` registered: a bucket is lit while
+     * the selection reaches into it. In the same pass as the rest of the group's
+     * fade, so it is one retarget per update, never two. Marks filtered by the
+     * selection (no group) are skipped: they never dim.
+     */
+    #lightOthers(index, ids, count) {
+        if (this.#others.size === 0 || index < 0)
+            return;
+        let mask = this.#selectedMask;
+        if (mask.length < count)
+            mask = this.#selectedMask = new Uint8Array(count);
+        const selected = ids.length;
+        for (let i = 0; i < selected; i++)
+            mask[ids[i]] = 1;
+        for (const [otherId, entries] of this.#others) {
+            if (otherId >= count)
+                continue;
+            let lit = false;
+            for (const entry of entries.values()) {
+                if (entry.group !== index)
+                    continue;
+                for (const row of entry.rows) {
+                    for (let i = 0; i < row.ids.length && !lit; i++)
+                        lit = mask[row.ids[i]] === 1;
+                    if (lit)
+                        break;
+                }
+                if (lit)
+                    break;
+            }
+            if (lit)
+                ids.push(otherId);
+        }
+        // Unmark only what was marked: the selected ids, not the Others pushed after.
+        for (let i = 0; i < selected; i++)
+            mask[ids[i]] = 0;
+    }
+    /** Reused by #lightOthers: 1 at each selected id, 0 elsewhere between calls. */
+    #selectedMask = new Uint8Array(0);
+}

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,24 @@ 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;
-    };
+    /**
+     * The source's clause was removed by someone other than this registration:
+     * `clearAll`, a `clearSource` from outside (a filter pill's remove button), or
+     * another registration under the same id clearing it. A control that keeps what
+     * it drew (a brush's rectangle) resets it here, because it reads no clause. Not
+     * called for the registration's own `clear()` or `destroy()`, which it initiated;
+     * and a control that clears itself from here does not loop, since the clause is
+     * already gone.
+     */
+    onCleared?: () => void;
 }
 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. */
@@ -77,12 +91,34 @@ export interface ToggleHandle extends Omit<SourceHandle, 'update'> {
     toggle(tuple: unknown[], multi: boolean, total?: number): void;
     /** Select exactly these tuples; empty clears. */
     set(tuples: unknown[][]): void;
+    /**
+     * A click on Other bucket `otherId` (from facet cell `facetId`, or null):
+     * selects, adds or takes back the categories it holds, as its field's
+     * registry says (FieldActivity.otherClick). A one-field toggle only: a
+     * bucket names no value in a tuple of several.
+     */
+    toggleOther(otherId: number, facetId: number | null, multi: boolean): void;
 }
 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 +126,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,16 +138,27 @@ 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
      * 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: string): void;
+    clearSource(sourceId: string, by?: SourceOpts): void;
+    /** Remove every clause, and tell the controls that drew them (`onCleared`). */
     clearAll(): void;
 }