@fjader/svelte 0.2.2 → 0.2.4

package/dist/interactors/TooltipManager.svelte.js

@@ -35,8 +35,8 @@ export class TooltipManager {
     currentChannelFields = $state(null);
     currentDisplayFields = $state(null);
     visible = $state(false);
-    pointerScreenX = $state(0);
-    pointerScreenY = $state(0);
+    pointerClientX = $state(0);
+    pointerClientY = $state(0);
     matchedRadius = $state(null);
     // Focused point getters — used by Tooltip and HoverIndicator
     get focusedPoint() {
@@ -45,6 +45,12 @@ export class TooltipManager {
     get focusedMatch() {
         return this.matchedPoints[this.focusedIndex] ?? null;
     }
+    /** The focused point's Other numbers, or null where it is not an Other bar. */
+    get focusedOtherStats() {
+        const point = this.focusedPoint;
+        const stats = this.currentMarkId ? this.#marks.get(this.currentMarkId)?.otherStats : null;
+        return point && stats ? stats(point) : null;
+    }
     // Backwards-compat getters
     get currentPoint() {
         return this.currentPoints[0] ?? null;
@@ -81,6 +87,15 @@ export class TooltipManager {
         this.#pendingY = yData;
         this.#hasPending = true;
     }
+    /**
+     * Run the hover query again at the last position, if the pointer is still
+     * in the chart: a mark's tooltip table was rewritten under a still pointer,
+     * so the row it shows is the old data's. The next frame runs it.
+     */
+    refresh() {
+        if (this.#cursorActive)
+            this.#hasPending = true;
+    }
     /**
      * Cycle the focused point index by delta. Wraps around.
      * Remembers the focused category so it persists across cursor moves.
@@ -129,12 +144,13 @@ export class TooltipManager {
         return this.#chartConfig.getMarkLOD(this.currentMarkId) ?? null;
     }
     /**
-     * Update raw screen position for tooltip positioning.
-     * Called from chart container's pointer move handler.
+     * The pointer's viewport (client) position, where the tooltip is placed: it
+     * renders in the top layer, outside the chart's clipping ancestors. Called from
+     * the chart's pointer move handler.
      */
-    updatePointerScreen(x, y) {
-        this.pointerScreenX = x;
-        this.pointerScreenY = y;
+    updatePointerClient(x, y) {
+        this.pointerClientX = x;
+        this.pointerClientY = y;
     }
     // =========================================================================
     // QUERY SCHEDULING (driven by animation loop)
@@ -440,7 +456,8 @@ export class TooltipManager {
             if (index == null)
                 return null;
             const category = this.#bandScale(axis)?.categoryAt(index);
-            if (category == null)
+            // undefined is no category; null is the NULL category, which has a band.
+            if (category === undefined)
                 return null;
             const pos = scale(category);
             const bandwidth = 'bandwidth' in scale ? scale.bandwidth() : 0;
@@ -492,7 +509,8 @@ export class TooltipManager {
         const { scaleTypes, bandDomains } = config;
         // Band channel → category label
         if ((key === 'x' || key === 'y') && scaleTypes[key] === 'band' && bandDomains?.[key]) {
-            return this.#bandScale(key)?.categoryAt(value) ?? value;
+            const category = this.#bandScale(key)?.categoryAt(value);
+            return category === undefined ? value : category;
         }
         // Time offset → formatted datetime
         if (key.startsWith(axis) && isTemporalScale(scaleTypes[axis]) && typeof value === 'number') {
@@ -560,6 +578,12 @@ export class TooltipManager {
         let rangeInsertIndex = -1;
         for (let i = 0; i < entries.length; i++) {
             const [key, value] = entries[i];
+            // The facet cell's dim id, kept for a click (Toggle reads it to pick the
+            // clicked cell's Other); not displayed: `_` keys never are.
+            if (key === '__facet') {
+                point.__facetId = value;
+                continue;
+            }
             // Skip internal columns
             if (key.startsWith('_') || key.startsWith('__dplot_'))
                 continue;
@@ -577,7 +601,13 @@ export class TooltipManager {
             // field name to build its filter tuples, so this is also what makes a
             // click on a reordered band axis filter the right category.
             if ((key === 'x' || key === 'y') && scaleTypes[key] === 'band' && bandDomains?.[key]) {
-                point[fieldName] = this.#bandScale(key)?.categoryAt(value) ?? value;
+                // Not `??`: the NULL category decodes to null, which must stay null
+                // (Toggle selects it) rather than fall back to the raw id.
+                const category = this.#bandScale(key)?.categoryAt(value);
+                point[fieldName] = category === undefined ? value : category;
+                // The raw id beside it: a label can't name an Other bucket (several
+                // share one, and it is no value), so a click on Other reads this.
+                point[key === 'x' ? '__bandIdX' : '__bandIdY'] = value;
                 continue;
             }
             // Resolve time offset to formatted datetime string

package/dist/interactors/other-tooltip.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The rows an Other bar's tooltip adds: how many categories it holds, and,
+ * while a selection reaches into it, how much of it is selected.
+ */
+import type { OtherRowStats } from '../components/marks/lifecycle/other-rows.svelte';
+export interface OtherTooltipRow {
+    key: string;
+    value: string;
+}
+/**
+ * `format` writes a sum the way the chart writes its value axis. Rows:
+ * - categories: "41", or "3 of 41" while a selection is active;
+ * - selected: "1,234 of 5,678 (22%)", only while a selection is active.
+ * A share that rounds to 0 but is not 0 reads "<1%", so a sliver is not "0%".
+ */
+export declare function otherTooltipRows(stats: OtherRowStats, format: (value: number) => string): OtherTooltipRow[];

package/dist/interactors/other-tooltip.js

@@ -0,0 +1,22 @@
+/**
+ * The rows an Other bar's tooltip adds: how many categories it holds, and,
+ * while a selection reaches into it, how much of it is selected.
+ */
+/**
+ * `format` writes a sum the way the chart writes its value axis. Rows:
+ * - categories: "41", or "3 of 41" while a selection is active;
+ * - selected: "1,234 of 5,678 (22%)", only while a selection is active.
+ * A share that rounds to 0 but is not 0 reads "<1%", so a sliver is not "0%".
+ */
+export function otherTooltipRows(stats, format) {
+    const count = String(stats.memberCount);
+    if (!stats.active)
+        return [{ key: 'categories', value: count }];
+    const percent = stats.total === 0 ? 0 : (100 * stats.picked) / stats.total;
+    const rounded = Math.round(percent);
+    const share = rounded === 0 && stats.picked > 0 ? '<1%' : `${rounded}%`;
+    return [
+        { key: 'categories', value: `${stats.pickedCount} of ${count}` },
+        { key: 'selected', value: `${format(stats.picked)} of ${format(stats.total)} (${share})` }
+    ];
+}

package/dist/interactors/relay-clauses.d.ts

@@ -0,0 +1,23 @@
+import type { FilterGroup } from '../query-engine/FilterGroup.svelte';
+/**
+ * Mirrors one group's clauses into another, for DerivedInterval1D: every
+ * clause but the range brush on the derived axis, which the interactor
+ * replaces with its shifted copy.
+ *
+ * `sync` runs on every change in the source group, which is every brush frame
+ * there. It relays the source's clause objects themselves, so an unchanged
+ * one is the object the target already holds, which it ignores: a brush in the
+ * source re-queries nothing in the target for the clauses it did not touch.
+ */
+export declare class ClauseRelay {
+    #private;
+    constructor(source: FilterGroup, target: FilterGroup);
+    /**
+     * Relay the source's clauses (all of them but the range on `axisColumn`),
+     * and remove relayed clauses the source no longer has. With `relay` false,
+     * only the removal. Call untracked: it reads the target group it writes.
+     */
+    sync(relay: boolean, axisColumn: string): void;
+    /** Remove every relayed clause, for an interactor going away. */
+    clear(): void;
+}

package/dist/interactors/relay-clauses.js

@@ -0,0 +1,60 @@
+/**
+ * Mirrors one group's clauses into another, for DerivedInterval1D: every
+ * clause but the range brush on the derived axis, which the interactor
+ * replaces with its shifted copy.
+ *
+ * `sync` runs on every change in the source group, which is every brush frame
+ * there. It relays the source's clause objects themselves, so an unchanged
+ * one is the object the target already holds, which it ignores: a brush in the
+ * source re-queries nothing in the target for the clauses it did not touch.
+ */
+export class ClauseRelay {
+    #source;
+    #target;
+    #relayed = new Set();
+    /** Reused as the next pass's key set, swapped with #relayed after each. */
+    #current = new Set();
+    #axisColumn = '';
+    constructor(source, target) {
+        this.#source = source;
+        this.#target = target;
+    }
+    /**
+     * Relay the source's clauses (all of them but the range on `axisColumn`),
+     * and remove relayed clauses the source no longer has. With `relay` false,
+     * only the removal. Call untracked: it reads the target group it writes.
+     */
+    sync(relay, axisColumn) {
+        this.#current.clear();
+        if (relay) {
+            this.#axisColumn = axisColumn;
+            this.#source.selection.forEach(this.#visit);
+        }
+        for (const key of this.#relayed) {
+            if (!this.#current.has(key))
+                this.#target.removeManual(key);
+        }
+        const done = this.#relayed;
+        this.#relayed = this.#current;
+        this.#current = done;
+    }
+    /** Remove every relayed clause, for an interactor going away. */
+    clear() {
+        for (const key of this.#relayed)
+            this.#target.removeManual(key);
+        this.#relayed.clear();
+    }
+    #visit = (clause, sourceId) => {
+        const { schema } = clause;
+        if (schema?.kind === 'range' && schema.column === this.#axisColumn)
+            return;
+        if (!clause.predicate)
+            return;
+        const key = `relay:${sourceId}`;
+        this.#current.add(key);
+        // The clause itself: nothing in it depends on its group, so a relayed
+        // toggle routes and dims in the target as a native one would, and an
+        // unchanged clause is the same object, which the target ignores.
+        this.#target.relayClause(key, clause);
+    };
+}

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

@@ -2,12 +2,19 @@
  * 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 type { ExprNode } from '@uwdata/mosaic-sql';
 export type FilterExpr = ExprNode | string | boolean;
@@ -18,52 +25,118 @@ export interface FilterSchema {
     values?: unknown[];
     [key: string]: unknown;
 }
-/** A clause stored in the selection. */
+/**
+ * A single-field categorical selection, as a clause states it: the field's
+ * identity key and the selected values. Brushes, tuples and manual clauses have
+ * none.
+ */
+export interface CategoricalSelection {
+    key: string;
+    values: ReadonlySet<unknown>;
+}
+/** A clause stored in the selection. Nothing in it depends on its group. */
 export interface Clause {
     predicate: FilterExpr;
-    excludeMarkIds: Set<string>;
     value: unknown;
     schema?: FilterSchema;
+    /** Set when the clause selects categories of one field; written with the clause. */
+    categorical?: CategoricalSelection | null;
+}
+/**
+ * What routing needs to know about a mark: the identity keys of the
+ * categorical fields its renderer reads selection activity for, its chart, and
+ * its selectionResponse. One object per mark, owned by its lifecycle and
+ * handed around by reference.
+ *
+ * A categorical selection on a field in `reads` dims the mark instead of
+ * filtering it. `chart` is the chart's ChartConfig, compared by reference: a
+ * faceted chart's cells have ids of their own, but share one config.
+ * `response` 'filter' makes every selection filter the mark, and a click
+ * control's (a discrete registration's) in its own chart too; brushes still
+ * skip their own chart.
+ */
+export interface MarkRoute {
+    readonly reads: readonly string[];
+    readonly chart: object | null;
+    readonly response?: 'auto' | 'filter';
 }
+/**
+ * What routing reads from one registration of a source: the chart it skips,
+ * if it opted into skipping one. Compared by reference with a mark's route.
+ */
+export interface SourceRegistration {
+    readonly chart?: object | null;
+    /**
+     * The source writes its clauses on a click (a Toggle, a legend, a band
+     * label), not under a dragged pointer. A 'filter' mark in the chart it
+     * skips is filtered by it all the same.
+     */
+    readonly discrete?: boolean;
+}
+/** A mark with no route: it reads no activity and is in no chart. */
+export declare const NO_ROUTE: MarkRoute;
 /** A clause with its source identifier, for external consumers. */
 export interface ClauseEntry extends Clause {
     sourceId: string;
 }
 export declare class CrossfilterSelection {
     #private;
+    /** Add a registration of `sourceId`. */
+    addRegistration(sourceId: string, registration: SourceRegistration): void;
+    /** Remove a registration of `sourceId`; the last one removes the source. */
+    removeRegistration(sourceId: string, registration: SourceRegistration): void;
+    /** The live registrations of `sourceId`, or undefined when it has none. */
+    registrationsOf(sourceId: string): ReadonlySet<SourceRegistration> | undefined;
     /**
-     * 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: string): FilterExpr[];
+    filters(route: MarkRoute, sourceId: string, key: string | null): boolean;
+    /** Whether `clause`, written by `sourceId`, filters the mark with `route`. */
+    applies(sourceId: string, clause: Clause, route: MarkRoute): boolean;
+    /** Every predicate that filters the mark with `route`. */
+    predicate(route: MarkRoute): FilterExpr[];
     /**
      * 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: string, clause: Clause | null): void;
+    update(sourceId: string, clause: Clause | null): Clause | undefined;
     /** Whether a given source has an active (non-null) clause. */
     isActive(sourceId: string): boolean;
     /** O(1) lookup of a clause by source ID. */
     get(sourceId: string): Clause | undefined;
+    /**
+     * 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: (clause: Clause, sourceId: string) => void): void;
     /** Reactive list of all active clauses with their source IDs. */
     get items(): ClauseEntry[];
     /**
      * The clause objects a preagg table bakes in, in map insertion order.
      * Stored at build time so bakedClausesMatch() can compare by reference.
      */
-    bakedClauses(markId: string, activeSourceId: string): Clause[];
+    bakedClauses(route: MarkRoute, activeSourceId: string): Clause[];
     /**
      * 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: string, activeSourceId: string): FilterExpr[];
+    bakedPredicates(route: MarkRoute, activeSourceId: string): FilterExpr[];
     /**
      * Whether the clauses baked into a preagg table are still the ones in force.
      * Every filter change replaces its Clause object, so an unchanged filter
      * keeps its reference. Runs every brush frame, so it allocates nothing.
      */
-    bakedClausesMatch(markId: string, activeSourceId: string, then: Clause[]): boolean;
+    bakedClausesMatch(route: MarkRoute, activeSourceId: string, then: Clause[]): boolean;
     /** Number of active clauses. */
     get activeCount(): number;
     /** Remove all clauses. */

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;