@fjader/svelte 0.2.2 → 0.2.3

package/dist/scales/ActivityTable.d.ts

@@ -0,0 +1,99 @@
+import { TransitionClock, type ClockLoop } from '../animation';
+/**
+ * Stiffness for a selection fade: ~0.25 s to settle, against ~0.32 s for a data
+ * transition (TRANSITION_STIFFNESS, 240). A click should feel immediate; the
+ * charts it filters take their own time to re-query and morph.
+ */
+export declare const SELECTION_STIFFNESS = 400;
+/**
+ * How visible an inactive category is, by default: marks are drawn at this
+ * opacity (the shaders' SELECTION_DIM_STRENGTH is 1 - this), and
+ * band labels fade to it.
+ */
+export declare const DEFAULT_INACTIVE_OPACITY = 0.25;
+/**
+ * How visible a category is for its activity: `inactiveOpacity` when
+ * unselected, 1 when selected, and in between mid-fade.
+ *
+ * The CPU twin of the shaders' `selectionDim`, which computes the same thing as
+ * `1 - dimStrength * (1 - activity)` with `dimStrength = 1 - inactiveOpacity`.
+ * Band labels and legend entries use this, so they match the marks.
+ */
+export declare function selectionOpacity(activity: number, inactiveOpacity?: number): number;
+/**
+ * Which categories of a scale are selected, and how far each one has faded.
+ *
+ * One float per identity id: 1 active, 0 inactive. A categorical scale owns one
+ * of these beside its slots, and the shaders read it through the same id they
+ * already resolve to a slot, so every mark drawn against the scale dims its
+ * inactive categories without knowing whether it is the source of the
+ * selection, filtered by it, or outside the filter group.
+ *
+ * The same shape as SlotTransition, on its own clock: `from` and `to` are the
+ * two ends of the fade, the value NOW is `mix(from, to, t)`, the GPU computes it
+ * for every id, and `activityOf` for the few a CPU consumer asks about. A
+ * SEPARATE clock from the slots', because a click changes what is selected
+ * without changing any data, and a data update has nothing to do with dimming.
+ * One `t` for every id, not a spring per category: everything fading because of
+ * one click arrives together, and there is one moment of rest.
+ */
+export declare class ActivityTable {
+    #private;
+    /**
+     * Bumped whenever `from` or `to` change: a selection, a resize, a settle. The
+     * packer compares this rather than the contents, so a frame where only `t`
+     * moved uploads nothing.
+     */
+    version: number;
+    readonly clock: TransitionClock;
+    /**
+     * `charts` is required: the loop redraws only the charts a clock names, so a
+     * fade whose clock named none would animate without anything redrawing it.
+     * `loop` is null in unit tests and before a coordinator exists, and then a
+     * fade lands at once. `onFrame` is called for every driven frame and once
+     * more at rest, for CPU consumers such as axis labels.
+     */
+    constructor(loop: ClockLoop | null, options: {
+        charts: () => string[];
+        onFrame?: () => void;
+        stiffness?: number;
+    });
+    /** How many ids the table covers. */
+    get count(): number;
+    get from(): Float32Array;
+    get to(): Float32Array;
+    /** Extrapolated for the frame being drawn. 1 when settled. */
+    get t(): number;
+    /** True while the clock is in the loop. */
+    get isAnimating(): boolean;
+    /**
+     * How active one id is now, 0..1. An id outside the table is fully active,
+     * the same answer the shader gives for an id past the block's count.
+     */
+    activityOf(id: number): number;
+    /**
+     * Cover `count` ids. Existing ids keep their fade; new ones snap to their
+     * state rather than fading in.
+     *
+     * `active` is the selection the new ids join, as ids: null for none, so
+     * every new id is active. Without it, a new id is inactive while something
+     * is selected, since a category that did not exist when the selection was
+     * made is not part of it. Passing it matters when the selection was made
+     * before the ids existed (before identity landed, or across a reload): the
+     * table has not seen it, and a new id it names must start selected rather
+     * than fade in from 0, and one it does not name must start dim rather than
+     * fade down from 1.
+     *
+     * `resize(0)` drops every id, for ids that stopped meaning their category.
+     */
+    resize(count: number, active?: readonly number[] | null): void;
+    /**
+     * Select exactly these ids; every other id fades out. Ids outside the table
+     * are ignored. Does nothing when the selection is the one already headed to.
+     */
+    setActive(ids: Iterable<number>): void;
+    /** Nothing selected: every id fades back to active. */
+    clear(): void;
+    /** Leave the loop, for an owner being torn down. Later changes land at once. */
+    destroy(): void;
+}

package/dist/scales/ActivityTable.js

@@ -0,0 +1,211 @@
+import { TransitionClock } from '../animation';
+/**
+ * Stiffness for a selection fade: ~0.25 s to settle, against ~0.32 s for a data
+ * transition (TRANSITION_STIFFNESS, 240). A click should feel immediate; the
+ * charts it filters take their own time to re-query and morph.
+ */
+export const SELECTION_STIFFNESS = 400;
+/**
+ * How visible an inactive category is, by default: marks are drawn at this
+ * opacity (the shaders' SELECTION_DIM_STRENGTH is 1 - this), and
+ * band labels fade to it.
+ */
+export const DEFAULT_INACTIVE_OPACITY = 0.25;
+/**
+ * How visible a category is for its activity: `inactiveOpacity` when
+ * unselected, 1 when selected, and in between mid-fade.
+ *
+ * The CPU twin of the shaders' `selectionDim`, which computes the same thing as
+ * `1 - dimStrength * (1 - activity)` with `dimStrength = 1 - inactiveOpacity`.
+ * Band labels and legend entries use this, so they match the marks.
+ */
+export function selectionOpacity(activity, inactiveOpacity = DEFAULT_INACTIVE_OPACITY) {
+    return inactiveOpacity + (1 - inactiveOpacity) * activity;
+}
+/**
+ * Which categories of a scale are selected, and how far each one has faded.
+ *
+ * One float per identity id: 1 active, 0 inactive. A categorical scale owns one
+ * of these beside its slots, and the shaders read it through the same id they
+ * already resolve to a slot, so every mark drawn against the scale dims its
+ * inactive categories without knowing whether it is the source of the
+ * selection, filtered by it, or outside the filter group.
+ *
+ * The same shape as SlotTransition, on its own clock: `from` and `to` are the
+ * two ends of the fade, the value NOW is `mix(from, to, t)`, the GPU computes it
+ * for every id, and `activityOf` for the few a CPU consumer asks about. A
+ * SEPARATE clock from the slots', because a click changes what is selected
+ * without changing any data, and a data update has nothing to do with dimming.
+ * One `t` for every id, not a spring per category: everything fading because of
+ * one click arrives together, and there is one moment of rest.
+ */
+export class ActivityTable {
+    #from = new Float32Array(0);
+    #to = new Float32Array(0);
+    /**
+     * Where a new selection is computed before it is compared with `to`. Reused,
+     * because `setActive` is called on every filter update, and most of those
+     * (every brush move on some other field) change nothing here.
+     */
+    #scratch = new Float32Array(0);
+    /** Whether some categories are selected, which decides what a new id starts as. */
+    #selecting = false;
+    /**
+     * Bumped whenever `from` or `to` change: a selection, a resize, a settle. The
+     * packer compares this rather than the contents, so a frame where only `t`
+     * moved uploads nothing.
+     */
+    version = 0;
+    clock;
+    #onFrame;
+    /**
+     * `charts` is required: the loop redraws only the charts a clock names, so a
+     * fade whose clock named none would animate without anything redrawing it.
+     * `loop` is null in unit tests and before a coordinator exists, and then a
+     * fade lands at once. `onFrame` is called for every driven frame and once
+     * more at rest, for CPU consumers such as axis labels.
+     */
+    constructor(loop, options) {
+        this.#onFrame = options.onFrame ?? null;
+        this.clock = new TransitionClock({
+            loop,
+            charts: options.charts,
+            stiffness: options.stiffness ?? SELECTION_STIFFNESS,
+            onRest: () => this.#onClockRest(),
+            onFrame: this.#onFrame ?? undefined
+        });
+    }
+    /** How many ids the table covers. */
+    get count() {
+        return this.#to.length;
+    }
+    get from() {
+        return this.#from;
+    }
+    get to() {
+        return this.#to;
+    }
+    /** Extrapolated for the frame being drawn. 1 when settled. */
+    get t() {
+        return this.clock.t;
+    }
+    /** True while the clock is in the loop. */
+    get isAnimating() {
+        return this.clock.running;
+    }
+    /**
+     * How active one id is now, 0..1. An id outside the table is fully active,
+     * the same answer the shader gives for an id past the block's count.
+     */
+    activityOf(id) {
+        const f = this.#from[id];
+        if (f === undefined)
+            return 1;
+        return f + (this.#to[id] - f) * this.clock.t;
+    }
+    /**
+     * Cover `count` ids. Existing ids keep their fade; new ones snap to their
+     * state rather than fading in.
+     *
+     * `active` is the selection the new ids join, as ids: null for none, so
+     * every new id is active. Without it, a new id is inactive while something
+     * is selected, since a category that did not exist when the selection was
+     * made is not part of it. Passing it matters when the selection was made
+     * before the ids existed (before identity landed, or across a reload): the
+     * table has not seen it, and a new id it names must start selected rather
+     * than fade in from 0, and one it does not name must start dim rather than
+     * fade down from 1.
+     *
+     * `resize(0)` drops every id, for ids that stopped meaning their category.
+     */
+    resize(count, active) {
+        if (count === this.#to.length)
+            return;
+        const keep = Math.min(this.#to.length, count);
+        const selecting = active === undefined ? this.#selecting : active !== null;
+        const fill = selecting ? 0 : 1;
+        const grown = (old) => {
+            const next = new Float32Array(count);
+            next.fill(fill);
+            next.set(old.subarray(0, keep), 0);
+            if (active) {
+                for (const id of active)
+                    if (id >= keep && id < count)
+                        next[id] = 1;
+            }
+            return next;
+        };
+        this.#from = grown(this.#from);
+        this.#to = grown(this.#to);
+        this.#scratch = new Float32Array(count);
+        this.version++;
+    }
+    /**
+     * Select exactly these ids; every other id fades out. Ids outside the table
+     * are ignored. Does nothing when the selection is the one already headed to.
+     */
+    setActive(ids) {
+        const next = this.#scratch;
+        next.fill(0);
+        for (const id of ids) {
+            if (id >= 0 && id < next.length)
+                next[id] = 1;
+        }
+        this.#selecting = true;
+        this.#retarget(next);
+    }
+    /** Nothing selected: every id fades back to active. */
+    clear() {
+        const next = this.#scratch;
+        next.fill(1);
+        this.#selecting = false;
+        this.#retarget(next);
+    }
+    /** Leave the loop, for an owner being torn down. Later changes land at once. */
+    destroy() {
+        this.clock.stop();
+    }
+    /**
+     * Fold, point every id at its new state, and wake the loop.
+     *
+     * Returns early when `next` equals `to`: the fade already in flight (or the
+     * rest already reached) is headed exactly there, and restarting it would
+     * re-fold and bump the version for nothing, on every filter update.
+     */
+    #retarget(next) {
+        const from = this.#from;
+        const to = this.#to;
+        let changed = false;
+        for (let id = 0; id < to.length; id++) {
+            if (to[id] !== next[id]) {
+                changed = true;
+                break;
+            }
+        }
+        if (!changed)
+            return;
+        // THE FOLD: every id continues from where it is now, so a click landing
+        // mid-fade reverses or redirects it in place instead of jumping.
+        const t = this.clock.t;
+        for (let id = 0; id < to.length; id++) {
+            from[id] += (to[id] - from[id]) * t;
+            to[id] = next[id];
+        }
+        this.clock.restart();
+        this.version++;
+    }
+    /**
+     * Land exactly on `to`. A spring rests at an epsilon, and a table left at
+     * 0.0003 would start its next fold from a value that was never a state.
+     */
+    #settle() {
+        this.clock.settle();
+        this.#from.set(this.#to);
+    }
+    #onClockRest() {
+        this.#settle();
+        this.version++;
+        // The last frame, at exactly t = 1, which the loop's final frame was not.
+        this.#onFrame?.();
+    }
+}

package/dist/scales/BandScaleState.svelte.d.ts

@@ -1,5 +1,5 @@
 import type { ScaleBand } from 'd3-scale';
-import type { DimValue, FieldIdentity } from '../query-engine/categorical-identity';
+import type { DimValue, FieldIdentity, SyntheticId } from '../query-engine/categorical-identity';
 import type { ClockLoop } from '../animation';
 import { type BandSlots } from './SlotTransition';
 /**
@@ -77,10 +77,6 @@ export declare class BandScaleState {
     currentDataPoint: number | null;
     constructor(name: string, domain?: DimValue[], config?: BandScaleConfig);
     setReady(): void;
-    get activeValues(): Set<DimValue> | null;
-    setActiveValues(values: Iterable<DimValue>): void;
-    clearActiveValues(): void;
-    isActive(value: DimValue): boolean;
     /**
      * Marks the scale dead. Clears nothing, deliberately.
      *
@@ -121,6 +117,12 @@ export declare class BandScaleState {
      * where name is "__facet__species" but sourceField is "species").
      */
     get sourceField(): string;
+    /**
+     * The identity key of the dim this scale adopted, or null before it has one.
+     * Selection activity is kept per identity key, so this is what the packer
+     * points the scale's block at.
+     */
+    get identityKey(): string | null;
     /**
      * Enable or disable scale updates
      * When disabled, domain is frozen at current state
@@ -209,6 +211,24 @@ export declare class BandScaleState {
      * undisplayed Other is ignored.
      */
     setOtherId(id: number | null): void;
+    /**
+     * This axis's Other bucket, shared by every mark on it that has one.
+     *
+     * One id per band scale, not per mark or per chart: marks share a band scale
+     * only when they agree on what Other is — the scale's key carries the table
+     * and the category-reducing transform (its `transformKey`), N included — so
+     * everything drawn on one axis lines up in one Other band. A bar and its
+     * value labels, or two charts with the identical topN, share it.
+     *
+     * Reference-counted by mark id. The first holder acquires; holders arriving
+     * while that is in flight share it; the last to release gives it back.
+     */
+    retainOther(holder: string, acquire: () => Promise<SyntheticId>): Promise<SyntheticId>;
+    /**
+     * Drop `holder`'s claim on the Other bucket. The last one out hands the id to
+     * `release` — once the acquire has landed, if it is still in flight.
+     */
+    releaseOther(holder: string, release: (other: SyntheticId) => void): void;
     /**
      * Identity id currently displayed at `slot`, or null when the slot holds no
      * category. Use this to compare a display position — what invertScreenToData
@@ -375,6 +395,9 @@ export declare class BandScaleState {
      * so it fades out over the half slot before that centre reaches the axis end
      * (the animated count), and is gone from there; the same at the start. An
      * entrant's label appears as its band crosses in.
+     *
+     * A selection's dimming is not here: it belongs to the filter groups of the
+     * marks the axis labels, so the axis multiplies it in (BandAxisTicks).
      */
     tickOpacity(key: number): number;
     /**
@@ -393,8 +416,6 @@ export declare class BandScaleState {
      * re-derived by such a caller.
      */
     slotPosition(slot: number, rangeSize: number, axis: 'x' | 'y'): number;
-    /** Whether a tick's category is outside the current selection. */
-    isTickDimmed(tick: BandTick): boolean;
     /**
      * Centre of a (possibly fractional) slot, measured from the start of the
      * range — the same layout the shader's computeBandLayout uses, so a label

package/dist/scales/BandScaleState.svelte.js

@@ -47,7 +47,6 @@ export class BandScaleState {
     // =========================================================================
     // SELECTION STATE
     // =========================================================================
-    #activeValues = $state(null); // null = all active, Set = only these active
     // =========================================================================
     // POINTER STATE
     // =========================================================================
@@ -104,21 +103,6 @@ export class BandScaleState {
     setReady() {
         this.ready = true;
     }
-    // =========================================================================
-    // ACTIVE VALUES (selection feedback)
-    // =========================================================================
-    get activeValues() {
-        return this.#activeValues;
-    }
-    setActiveValues(values) {
-        this.#activeValues = values instanceof Set ? values : new Set(values);
-    }
-    clearActiveValues() {
-        this.#activeValues = null;
-    }
-    isActive(value) {
-        return this.#activeValues == null || this.#activeValues.has(value);
-    }
     /**
      * Marks the scale dead. Clears nothing, deliberately.
      *
@@ -186,6 +170,15 @@ export class BandScaleState {
     get sourceField() {
         return this.#sourceField ?? this.name;
     }
+    /**
+     * The identity key of the dim this scale adopted, or null before it has one.
+     * Selection activity is kept per identity key, so this is what the packer
+     * points the scale's block at.
+     */
+    get identityKey() {
+        // Only while the channel carries ids, as for colour.
+        return this.hasIdentity ? this.#resolver.identity.key || null : null;
+    }
     // =========================================================================
     // FREEZE/DEBOUNCE CONTROL
     // =========================================================================
@@ -334,6 +327,49 @@ export class BandScaleState {
     setOtherId(id) {
         this.#slots.otherId = id;
     }
+    /**
+     * This axis's Other bucket, shared by every mark on it that has one.
+     *
+     * One id per band scale, not per mark or per chart: marks share a band scale
+     * only when they agree on what Other is — the scale's key carries the table
+     * and the category-reducing transform (its `transformKey`), N included — so
+     * everything drawn on one axis lines up in one Other band. A bar and its
+     * value labels, or two charts with the identical topN, share it.
+     *
+     * Reference-counted by mark id. The first holder acquires; holders arriving
+     * while that is in flight share it; the last to release gives it back.
+     */
+    retainOther(holder, acquire) {
+        this.#otherHolders.add(holder);
+        if (!this.#other) {
+            const pending = acquire();
+            this.#other = pending;
+            pending.then((other) => {
+                if (this.#other === pending)
+                    this.setOtherId(other.id);
+            }, () => {
+                if (this.#other === pending)
+                    this.#other = null;
+            });
+        }
+        return this.#other;
+    }
+    /**
+     * Drop `holder`'s claim on the Other bucket. The last one out hands the id to
+     * `release` — once the acquire has landed, if it is still in flight.
+     */
+    releaseOther(holder, release) {
+        if (!this.#otherHolders.delete(holder) || this.#otherHolders.size > 0)
+            return;
+        const pending = this.#other;
+        this.#other = null;
+        this.setOtherId(null);
+        pending?.then(release, () => { });
+    }
+    /** The marks holding this axis's Other bucket. */
+    #otherHolders = new Set();
+    /** The bucket they share, while any holds it. */
+    #other = null;
     // -------------------------------------------------------------------------
     // IDENTITY <-> DISPLAY, FOR CPU CONSUMERS
     // -------------------------------------------------------------------------
@@ -709,6 +745,9 @@ export class BandScaleState {
      * so it fades out over the half slot before that centre reaches the axis end
      * (the animated count), and is gone from there; the same at the start. An
      * entrant's label appears as its band crosses in.
+     *
+     * A selection's dimming is not here: it belongs to the filter groups of the
+     * marks the axis labels, so the axis multiplies it in (BandAxisTicks).
      */
     tickOpacity(key) {
         void this.#slotFrame;
@@ -738,10 +777,6 @@ export class BandScaleState {
         const centre = this.slotCenter(slot, rangeSize);
         return axis === 'y' ? rangeSize - centre : centre;
     }
-    /** Whether a tick's category is outside the current selection. */
-    isTickDimmed(tick) {
-        return tick.value != null && !this.isActive(tick.value);
-    }
     /**
      * Centre of a (possibly fractional) slot, measured from the start of the
      * range — the same layout the shader's computeBandLayout uses, so a label

package/dist/scales/ChartScales.svelte.d.ts

@@ -65,8 +65,8 @@ export declare class ChartScales {
     };
     get xScaleState(): ScaleStateInstance | null;
     get yScaleState(): ScaleStateInstance | null;
-    baseXScale: import("d3-scale").ScaleContinuousNumeric<number, number, never> | import("d3-scale").ScaleBand<import("../query-engine/categorical-identity").DimValue>;
-    baseYScale: import("d3-scale").ScaleContinuousNumeric<number, number, never> | import("d3-scale").ScaleBand<import("../query-engine/categorical-identity").DimValue>;
+    baseXScale: import("d3-scale").ScaleBand<import("../query-engine/categorical-identity").DimValue> | import("d3-scale").ScaleContinuousNumeric<number, number, never>;
+    baseYScale: import("d3-scale").ScaleBand<import("../query-engine/categorical-identity").DimValue> | import("d3-scale").ScaleContinuousNumeric<number, number, never>;
     get xScale(): D3Scale | null;
     get yScale(): D3Scale | null;
     get xTargetScale(): D3Scale | null;

package/dist/scales/ColorScaleState.svelte.d.ts

@@ -25,7 +25,21 @@ export declare class ColorScaleState {
     domain: (string | number)[];
     ready: boolean;
     _version: number;
+    /**
+     * Read by the packer every frame. The rank table covers the ids the field had
+     * when it was built, and the field's identity grows in place: another table
+     * appends categories, and a chart acquiring an Other bucket appends its id,
+     * any chart, since this scale is shared per field. An id past the table's end
+     * reads as unranked and draws transparent, so a grown identity rebuilds it
+     * here, once per growth.
+     */
     get slots(): SlotSource;
+    /**
+     * Reactive: changes whenever the palette ranks are rebuilt, which is also when
+     * identity is adopted. A reader of `identityKey` or `getColor` in a derived
+     * reads this to re-run then.
+     */
+    get ranksRevision(): number;
     /**
      * Called by the packer when this scale's block moves, and told its own base
      * rather than having it written into its config from outside.
@@ -51,9 +65,14 @@ export declare class ColorScaleState {
     setSlotBase(base: number): void;
     constructor(config: ColorScaleConfig, registry: ScaleRegistry, gpuCoordinator: GPUCoordinator | null);
     get field(): string;
+    /**
+     * The identity key of the dim this scale adopted, or null before it has one.
+     * Selection activity is kept per identity key, so this is what the packer
+     * points the scale's block at.
+     */
+    get identityKey(): string | null;
     get scheme(): string;
     get scaleType(): ColorScaleType;
-    get activeValues(): Set<string | number> | null;
     get isOrdinal(): boolean;
     get isContinuous(): boolean;
     /**
@@ -73,9 +92,14 @@ export declare class ColorScaleState {
      */
     get d3Scale(): D3ColorScale | null;
     /**
-     * Unique scale ID for ViewManager registration.
+     * The id the coordinator tracks this scale by, as it does every scale.
+     *
+     * Tracking is what puts the scale in front of the identity slot packer
+     * (see tracked-scales.ts). Without an id, its rank table and selection
+     * activity were never packed: the shader read the channel's dim id as a
+     * palette index, and selection dimming had nothing to read.
      */
-    get scaleId(): string;
+    get id(): string;
     /**
      * Converts raw data into GPU-ready values.
      * - Ordinal: string -> 0-based index (-1 = null/unknown, 0+ = categories)
@@ -95,13 +119,15 @@ export declare class ColorScaleState {
      */
     setIdentity(identity: FieldIdentity): void;
     /** True once this scale's channel carries dim ids rather than palette indices. */
+    /** The field's live id <-> value bijection, once adopted. */
+    get identity(): FieldIdentity | null;
     get hasIdentity(): boolean;
     /**
      * Source value for a channel id — the decode side of the encode the query
      * performs, for tooltips and legends. Undefined without identity, where the
      * channel carries a palette index and the caller should read the domain.
      */
-    categoryAt(id: number): string | number | undefined;
+    categoryAt(id: number): string | number | null | undefined;
     /** Update the domain. Triggers GPU re-upload. */
     setDomain(newDomain: (string | number)[]): void;
     /**
@@ -139,14 +165,16 @@ export declare class ColorScaleState {
      * Returns NULL_COLOR for values that are unmappable under the current
      * transform (e.g. non-positive values under log), mirroring the GPU shader.
      */
-    getColor(value: string | number): string;
+    getColor(value: string | number | null): string;
     /**
      * Get color as RGBA array (0-1 range).
      */
     getColorRGBA(value: string | number): RGBA;
-    setActiveValues(values: Iterable<string | number>): void;
-    clearActiveValues(): void;
-    isActive(value: string | number): boolean;
+    /**
+     * Charts drawing this scale. Asked of the registry, as BandScaleState does,
+     * so it is current when charts come and go.
+     */
+    get _affectedChartsArray(): string[];
     /**
      * Marks the scale dead. Clears nothing, deliberately — see
      * BandScaleState.destroy for the full argument.