@fjader/svelte 0.2.4 → 0.2.5

package/dist/scales/SlotTransition.js

@@ -1,3 +1,4 @@
+import { noteTransition, transitionsObserved } from '../animation/transition-log';
 import { TransitionClock } from '../animation';
 export class SlotTransition {
     #target = new Float32Array(0);
@@ -197,7 +198,14 @@ export class SlotTransition {
      * one). The space is unchanged, existing ids keep their paths, and the copy
      * on resize is exactly right.
      */
-    layout(space, order, idCount) {
+    layout(space, order, idCount, 
+    /**
+     * Land at once rather than travel: every id takes its new slot, leavers
+     * go and entrants appear. For a catch-up result, a change nobody just
+     * made. It settles the clock, which the marks on this axis share: their
+     * values land with it, which is what the caller wants for its chart.
+     */
+    instant = false) {
         if (space !== this.#space) {
             this.#space = space;
             this.#discard();
@@ -211,8 +219,21 @@ export class SlotTransition {
             if (id >= 0 && id < target.length)
                 target[id] = slot;
         }
-        this.#retarget(shown);
+        this.#layouts++;
+        this.#landedLayout = instant ? this.#layouts : 0;
+        this.#retarget(shown, instant);
     }
+    /**
+     * The latest layout's number if it landed at once (an instant layout), 0
+     * otherwise. What follows from a layout, like a band grid's line opacity,
+     * lands with it, once: a number, so a consumer lands only its first write
+     * after that layout.
+     */
+    get landedLayout() {
+        return this.#landedLayout;
+    }
+    #layouts = 0;
+    #landedLayout = 0;
     /**
      * Start a transition without changing what is displayed.
      *
@@ -310,7 +331,7 @@ export class SlotTransition {
      * Fold, then point every id at its new slot, and wake the loop if anything
      * has somewhere to go. `shown` is how many slots are displayed.
      */
-    #retarget(shown) {
+    #retarget(shown, instant = false) {
         const target = this.#target;
         const from = this.#from;
         const to = this.#to;
@@ -383,9 +404,17 @@ export class SlotTransition {
             this.#hasLaidOut = true;
         // With no loop to drive it, the clock settles inside the restart, through
         // #onClockRest — the same landing the loop would reach.
-        if (moving) {
+        if (moving && transitionsObserved()) {
+            noteTransition('slots', instant || settled, () => this.clock._affectedChartsArray, 'band slots');
+        }
+        if (moving && !instant) {
             this.clock.restart();
         }
+        else if (moving) {
+            // Landed at once: the end the loop would reach, leavers retired now
+            // (finish calls #onClockRest).
+            this.clock.finish();
+        }
         else {
             this.#settle();
         }

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

@@ -25,13 +25,17 @@ export declare class TimeScaleState extends LinearScaleState {
      * Register a mark's datetime extent.
      * Computes t0, converts all extents to offsets, updates parent.
      */
-    addDatetimeExtent(datetimeRange: [Date | number | bigint | string, Date | number | bigint | string], markId: string): void;
+    addDatetimeExtent(datetimeRange: [Date | number | bigint | string, Date | number | bigint | string], markId: string, options?: {
+        instant?: boolean;
+    }): void;
     /**
      * Register a mark's extent using offset values (seconds from t0).
      * Useful when data is already in offset form (e.g., from binned queries).
      * Converts offsets back to datetimes and delegates to addDatetimeExtent.
      */
-    addOffsetExtent(offsetRange: [number, number], markId: string): void;
+    addOffsetExtent(offsetRange: [number, number], markId: string, options?: {
+        instant?: boolean;
+    }): void;
     /**
      * Remove a mark's datetime extent.
      */
@@ -40,7 +44,7 @@ export declare class TimeScaleState extends LinearScaleState {
      * Override: apply time-aware nice instead of linear nice.
      * Called by super.addMark via polymorphism.
      */
-    updateExtentFromExtents(nice?: boolean): void;
+    updateExtentFromExtents(nice?: boolean, instant?: boolean): void;
     /** The actual database column name (may differ from scale registry key). */
     get sourceField(): string;
     /** The derived column name for this time scale's offsets. */

package/dist/scales/TimeScaleState.svelte.js

@@ -62,7 +62,7 @@ export class TimeScaleState extends LinearScaleState {
      * Register a mark's datetime extent.
      * Computes t0, converts all extents to offsets, updates parent.
      */
-    addDatetimeExtent(datetimeRange, markId) {
+    addDatetimeExtent(datetimeRange, markId, options = {}) {
         const minDate = toDate(datetimeRange[0]);
         const maxDate = toDate(datetimeRange[1]);
         this.#datetimeExtents.set(markId, [minDate, maxDate]);
@@ -77,21 +77,21 @@ export class TimeScaleState extends LinearScaleState {
         }
         this.#suppressUpdate = false;
         // Single update with time-aware nice
-        this.updateExtentFromExtents();
+        this.updateExtentFromExtents(true, options.instant);
     }
     /**
      * Register a mark's extent using offset values (seconds from t0).
      * Useful when data is already in offset form (e.g., from binned queries).
      * Converts offsets back to datetimes and delegates to addDatetimeExtent.
      */
-    addOffsetExtent(offsetRange, markId) {
+    addOffsetExtent(offsetRange, markId, options = {}) {
         if (!this.#t0) {
             console.warn(`[TimeScaleState] Cannot add offset extent: t0 not set yet`);
             return;
         }
         const minDate = this.offsetToDate(offsetRange[0]);
         const maxDate = this.offsetToDate(offsetRange[1]);
-        this.addDatetimeExtent([minDate, maxDate], markId);
+        this.addDatetimeExtent([minDate, maxDate], markId, options);
     }
     /**
      * Remove a mark's datetime extent.
@@ -110,12 +110,12 @@ export class TimeScaleState extends LinearScaleState {
      * Override: apply time-aware nice instead of linear nice.
      * Called by super.addMark via polymorphism.
      */
-    updateExtentFromExtents(nice = true) {
+    updateExtentFromExtents(nice = true, instant = false) {
         if (this.#suppressUpdate)
             return;
         // If no datetime extents, fall through to linear behavior
         if (this.#datetimeExtents.size === 0) {
-            super.updateExtentFromExtents(nice);
+            super.updateExtentFromExtents(nice, instant);
             return;
         }
         // Compute global datetime range
@@ -141,7 +141,7 @@ export class TimeScaleState extends LinearScaleState {
             this._setExtent(minOffset, maxOffset);
         }
         this.resetDomainLimits();
-        this.resetZoom();
+        this.resetZoom(instant);
     }
     // ===========================================================================
     // VIEWMANAGER INTEGRATION

package/dist/scales/color-utils.d.ts

@@ -26,9 +26,6 @@ export declare function getInterpolator(scheme: string): Interpolator | null;
  * Get the color array for an ordinal scheme.
  */
 export declare function getOrdinalColors(scheme: string): readonly string[] | null;
-/**
- * Determine if a scheme is ordinal (discrete) or continuous.
- */
 /**
  * All available scheme names, grouped by type.
  */

package/dist/scales/color-utils.js

@@ -327,9 +327,6 @@ export function getOrdinalColors(scheme) {
     const key = scheme.toLowerCase();
     return ORDINAL_SCHEMES[key] || null;
 }
-/**
- * Determine if a scheme is ordinal (discrete) or continuous.
- */
 /**
  * All available scheme names, grouped by type.
  */

package/dist/scales/entered.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Whether a scale's domain is ready to show: a continuous scale only once a
+ * chart drawing it has its marks' first data in (LinearScaleState.entered).
+ * Before that its domain is a placeholder, and an axis or grid drawn from it
+ * shows [0, 100] for a moment. Scales without the notion (band, point) are
+ * always shown.
+ */
+export declare function hasEntered(scale: unknown): boolean;

package/dist/scales/entered.js

@@ -0,0 +1,10 @@
+/**
+ * Whether a scale's domain is ready to show: a continuous scale only once a
+ * chart drawing it has its marks' first data in (LinearScaleState.entered).
+ * Before that its domain is a placeholder, and an axis or grid drawn from it
+ * shows [0, 100] for a moment. Scales without the notion (band, point) are
+ * always shown.
+ */
+export function hasEntered(scale) {
+    return scale?.entered !== false;
+}

package/dist/spec/LazyQueryEngine.js

@@ -8,10 +8,7 @@
  * DuckDB runs in the browser via @duckdb/duckdb-wasm, loaded from jsDelivr.
  */
 import { QueryEngine } from '../query-engine/QueryEngine';
-// ---------------------------------------------------------------------------
-// Configuration (must be set before first getOrCreateQueryEngine call)
-// ---------------------------------------------------------------------------
-/** Inline WASM bytes + worker code (for environments where separate assets can't be served). */
+import { initDuckDB } from '../query-engine/duckdb';
 // ---------------------------------------------------------------------------
 // Singleton QueryEngine
 // ---------------------------------------------------------------------------
@@ -35,24 +32,10 @@ export async function getOrCreateQueryEngine(userEngine) {
     return _enginePromise;
 }
 async function initEngine() {
-    _engine = new QueryEngine(await initFromWasm());
+    _engine = new QueryEngine(await initDuckDB());
     return _engine;
 }
 // ---------------------------------------------------------------------------
-// WASM init (standard CDN bundles)
-// ---------------------------------------------------------------------------
-async function initFromWasm() {
-    const duckdb = await import('@duckdb/duckdb-wasm');
-    const bundles = duckdb.getJsDelivrBundles();
-    const bundle = await duckdb.selectBundle(bundles);
-    const workerUrl = URL.createObjectURL(new Blob([`importScripts("${bundle.mainWorker}");`], { type: 'text/javascript' }));
-    const worker = new Worker(workerUrl);
-    const db = new duckdb.AsyncDuckDB(new duckdb.VoidLogger(), worker);
-    await db.instantiate(bundle.mainModule, bundle.pthreadWorker);
-    URL.revokeObjectURL(workerUrl);
-    return (await db.connect());
-}
-// ---------------------------------------------------------------------------
 // Data loading (shared across all render calls)
 // ---------------------------------------------------------------------------
 const _loadedTables = new Set();

package/dist/spec/MarkRegistry.d.ts

@@ -3,7 +3,7 @@
  * and resolves mark spec objects into component props.
  */
 import type { Component } from 'svelte';
-import type { MarkSpec } from './types';
+import type { MarkSpec, ColorFieldSpec } from './types';
 export declare const MARK_REGISTRY: Record<string, Component<any>>;
 /** Channel prop names that hold FieldSpec values and need resolution. */
 export declare const FIELD_CHANNELS: Set<string>;
@@ -11,6 +11,8 @@ export declare const FIELD_CHANNELS: Set<string>;
 export declare const STROKE_AS_FIELD_MARKS: Set<string>;
 /** Internal mark type → spec mark type. Used by both resolveMarkEntry and exportSpec. */
 export declare const SPEC_MARK_TYPES: Record<string, string>;
+/** A colour channel with explicit `domain`/`range`, which is not a FieldSpec. */
+export declare function isColorFieldSpec(value: unknown): value is ColorFieldSpec;
 /**
  * Convert a MarkSpec into { component, props } for svelte:component rendering.
  * Resolves FieldSpecs, transforms, and selection references.

package/dist/spec/MarkRegistry.js

@@ -44,6 +44,13 @@ export const SPEC_MARK_TYPES = {
     rectx: 'rectX',
     text: 'text'
 };
+/** A colour channel with explicit `domain`/`range`, which is not a FieldSpec. */
+export function isColorFieldSpec(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.field === 'string' &&
+        ('domain' in value || 'range' in value));
+}
 /**
  * Convert a MarkSpec into { component, props } for svelte:component rendering.
  * Resolves FieldSpecs, transforms, and selection references.
@@ -62,11 +69,16 @@ export function resolveMarkEntry(markSpec) {
             // Numbers are constants (e.g. r=3), not field references — skip resolution
             if (typeof props[key] === 'number')
                 continue;
+            // Explicit colours pass through as the colour prop's object form
+            if (isColorFieldSpec(props[key]))
+                continue;
             props[key] = resolveFieldSpec(props[key]);
         }
     }
     // stroke is data-driven (FieldSpec) on lines, but a CSS constant on areas
-    if (STROKE_AS_FIELD_MARKS.has(markSpec.mark) && props.stroke != null) {
+    if (STROKE_AS_FIELD_MARKS.has(markSpec.mark) &&
+        props.stroke != null &&
+        !isColorFieldSpec(props.stroke)) {
         props.stroke = resolveFieldSpec(props.stroke);
     }
     // Resolve transforms

package/dist/spec/PlotFromSpec.svelte

@@ -74,6 +74,7 @@
 		yPanLimit={spec.yPanLimit}
 		xDisableZoom={spec.xDisableZoom}
 		yDisableZoom={spec.yDisableZoom}
+		entrance={spec.entrance}
 		{legendPosition}
 	>
 		{#snippet background()}

package/dist/spec/export.js

@@ -5,7 +5,7 @@
  * back to spec format using the same types as the spec renderer.
  */
 import { fieldRefToSpec } from './ExpressionParser';
-import { SPEC_MARK_TYPES, FIELD_CHANNELS, STROKE_AS_FIELD_MARKS } from './MarkRegistry';
+import { SPEC_MARK_TYPES, FIELD_CHANNELS, STROKE_AS_FIELD_MARKS, isColorFieldSpec } from './MarkRegistry';
 /** Props handled specially (not passthrough) or internal-only (skip entirely). */
 const SKIP_PROPS = new Set([
     // Internal — not part of the spec
@@ -67,13 +67,22 @@ function entryToMarkSpec(entry) {
         const val = entry[ch];
         if (val == null)
             continue;
+        // Explicit colours: the colour prop's object form is already spec-shaped
+        if (isColorFieldSpec(val)) {
+            spec[ch] = { ...val };
+            continue;
+        }
         const converted = fieldRefToSpec(val);
         if (converted != null)
             spec[ch] = converted;
     }
     // stroke: data-driven on lines, CSS constant on areas
     if (entry.stroke != null) {
-        if (STROKE_AS_FIELD_MARKS.has(entry.markType)) {
+        const stroke = entry.stroke;
+        if (STROKE_AS_FIELD_MARKS.has(entry.markType) && isColorFieldSpec(stroke)) {
+            spec.stroke = { ...stroke };
+        }
+        else if (STROKE_AS_FIELD_MARKS.has(entry.markType)) {
             const converted = fieldRefToSpec(entry.stroke);
             if (converted != null)
                 spec.stroke = converted;

package/dist/spec/types.d.ts

@@ -2,7 +2,7 @@
  * Fjader Spec Schema — TypeScript interfaces defining the JSON contract
  * between spec producers (Python wrapper, JS API) and the spec renderer.
  */
-import type { ColorScheme, CurveType, ScaleType, SortConfig } from '../types';
+import type { ColorDomainValue, ColorScheme, CurveType, EntranceMode, ScaleType, SortConfig } from '../types';
 import type { QueryEngine } from '../query-engine/QueryEngine';
 /** A layout item: either a single plot or a nested layout. */
 export type LayoutItem = PlotSpec | {
@@ -64,6 +64,8 @@ export interface PlotSpec {
     xDisableZoom?: boolean;
     yDisableZoom?: boolean;
     legend?: LegendSpec | boolean;
+    /** How the marks enter when data first draws; see ChartContainer. Default 'auto'. */
+    entrance?: EntranceMode;
 }
 export type InteractorSpec = IntervalXSpec | IntervalYSpec | Interval2DSpec | ToggleSpec | DerivedIntervalSpec;
 export interface IntervalXSpec {
@@ -97,6 +99,17 @@ export interface DerivedIntervalSpec {
 }
 /** A column name, aggregate shorthand ("count()"), or structured object. */
 export type FieldSpec = string | AggregateFieldSpec | BinFieldSpec | WindowFieldSpec | RawSqlFieldSpec;
+/**
+ * A colour channel with explicit ordinal colours, as on the Svelte colour prop:
+ * `{ "field": "won", "domain": [0, 1], "range": ["#d62728", "#2ca02c"] }`.
+ */
+export interface ColorFieldSpec {
+    field: string;
+    domain?: ColorDomainValue[];
+    range?: string[];
+}
+/** What a colour channel (fill, a line's stroke) accepts. */
+export type ColorChannelSpec = FieldSpec | ColorFieldSpec;
 export interface AggregateFieldSpec {
     aggregate: 'count' | 'sum' | 'avg' | 'min' | 'max' | 'median';
     field?: string;
@@ -134,9 +147,11 @@ interface BaseMarkSpec {
     table: string;
     selection?: string;
     /** How the mark responds to selections in its group; see BaseMarkProps. Default 'auto'. */
-    selectionResponse?: 'auto' | 'filter';
+    selectionResponse?: 'auto' | 'filter' | 'ignore';
     /** What the mark does with NULL in its categorical channels; see BaseMarkProps. Default 'keep'. */
     nulls?: 'keep' | 'drop';
+    /** Whether the chart's entrance waits for this mark's first data; see BaseMarkProps. Default true. */
+    holdsEntrance?: boolean;
     scheme?: ColorScheme;
     limit?: number;
     transforms?: TransformSpec[];
@@ -145,7 +160,10 @@ interface BaseMarkSpec {
         x?: string[];
         y?: string[];
     } | null;
-    tooltip?: boolean;
+    /** Hover tooltips, or options; see BaseMarkProps.tooltip. */
+    tooltip?: boolean | {
+        sortTable?: boolean;
+    };
     tooltipProximity?: 'x' | 'y' | 'xy';
     tip?: (string | '*' | AggregateFieldSpec | LabeledTipFieldSpec)[] | false;
     fitDomain?: 'x' | 'y' | boolean;
@@ -158,7 +176,7 @@ export interface DotMarkSpec extends BaseMarkSpec, ContinuousScaleTypeSpec {
     mark: 'dot';
     x: FieldSpec;
     y: FieldSpec;
-    fill?: FieldSpec | null;
+    fill?: ColorChannelSpec | null;
     opacity?: number;
     r?: number | FieldSpec;
     radiusRange?: [number, number];
@@ -169,7 +187,7 @@ export interface BarXMarkSpec extends BaseMarkSpec {
     x1?: FieldSpec;
     x2?: FieldSpec;
     y: FieldSpec;
-    fill?: FieldSpec | null;
+    fill?: ColorChannelSpec | null;
     opacity?: number;
     padding?: number;
     paddingInner?: number;
@@ -177,6 +195,11 @@ export interface BarXMarkSpec extends BaseMarkSpec {
     inset?: number;
     dx?: number;
     dy?: number;
+    /**
+     * `false`: follow the band axis the other marks on it decide, adding no
+     * categories to it; see BaseMarkProps. Default `true`.
+     */
+    contributeDomain?: boolean;
 }
 export interface BarYMarkSpec extends BaseMarkSpec {
     mark: 'barY';
@@ -184,7 +207,7 @@ export interface BarYMarkSpec extends BaseMarkSpec {
     y: FieldSpec;
     y1?: FieldSpec;
     y2?: FieldSpec;
-    fill?: FieldSpec | null;
+    fill?: ColorChannelSpec | null;
     opacity?: number;
     padding?: number;
     paddingInner?: number;
@@ -192,12 +215,17 @@ export interface BarYMarkSpec extends BaseMarkSpec {
     inset?: number;
     dx?: number;
     dy?: number;
+    /**
+     * `false`: follow the band axis the other marks on it decide, adding no
+     * categories to it; see BaseMarkProps. Default `true`.
+     */
+    contributeDomain?: boolean;
 }
 export interface LineMarkSpec extends BaseMarkSpec, ContinuousScaleTypeSpec {
     mark: 'line';
     x: FieldSpec;
     y: FieldSpec;
-    stroke?: FieldSpec | null;
+    stroke?: ColorChannelSpec | null;
     z?: FieldSpec | null;
     strokeWidth?: number;
     dotRadius?: number;
@@ -222,7 +250,7 @@ export interface AreaYMarkSpec extends BaseMarkSpec, ContinuousScaleTypeSpec {
     y: FieldSpec;
     y1?: FieldSpec;
     y2?: FieldSpec;
-    fill?: FieldSpec | null;
+    fill?: ColorChannelSpec | null;
     z?: FieldSpec | null;
     fillOpacity?: number;
     stroke?: string | null;
@@ -237,7 +265,7 @@ export interface AreaXMarkSpec extends BaseMarkSpec, ContinuousScaleTypeSpec {
     x: FieldSpec;
     x1?: FieldSpec;
     x2?: FieldSpec;
-    fill?: FieldSpec | null;
+    fill?: ColorChannelSpec | null;
     z?: FieldSpec | null;
     fillOpacity?: number;
     stroke?: string | null;
@@ -254,7 +282,7 @@ export interface RectMarkSpec extends BaseMarkSpec, ContinuousScaleTypeSpec {
     y?: FieldSpec | null;
     y1?: FieldSpec | null;
     y2?: FieldSpec | null;
-    fill?: FieldSpec | null;
+    fill?: ColorChannelSpec | null;
     opacity?: number;
     padding?: number;
     paddingInner?: number;
@@ -271,7 +299,7 @@ export interface RectXMarkSpec extends BaseMarkSpec {
     y?: FieldSpec | null;
     y1?: FieldSpec | null;
     y2?: FieldSpec | null;
-    fill?: FieldSpec | null;
+    fill?: ColorChannelSpec | null;
     opacity?: number;
     inset?: number;
     dx?: number;
@@ -287,7 +315,7 @@ export interface RectYMarkSpec extends BaseMarkSpec {
     y: FieldSpec;
     y1?: FieldSpec;
     y2?: FieldSpec;
-    fill?: FieldSpec | null;
+    fill?: ColorChannelSpec | null;
     opacity?: number;
     inset?: number;
     dx?: number;
@@ -300,7 +328,7 @@ export interface TextMarkSpec extends BaseMarkSpec, ContinuousScaleTypeSpec {
     x: FieldSpec;
     y: FieldSpec;
     text: FieldSpec;
-    fill?: FieldSpec | null;
+    fill?: ColorChannelSpec | null;
     fontSize?: number;
     fontWeight?: string;
     fontFamily?: string | null;

package/dist/sql/bin.d.ts

@@ -1,4 +1,5 @@
 import type { ExprNode, BinHistogramOptions, BinDateOptions } from '@uwdata/mosaic-sql';
+import type { BinPadding } from '../types';
 type BinOptions = BinHistogramOptions & BinDateOptions;
 interface FieldStats {
     column: string;
@@ -9,14 +10,38 @@ interface FieldInfo {
     max?: number;
     type?: string;
 }
+/**
+ * The edge of numeric bin `index` (SQL), `min + alpha * (index + offset)`, in
+ * DOUBLE arithmetic. The one formula both `bin()` and `dense()`'s padding
+ * write, so a bin's edge is the same bits whichever produced it: a padded row
+ * then merges with a real one, and a mark's rows are the same bits whether
+ * they came from the base table or a preagg table.
+ */
+export declare function numericBinEdgeSQL(min: number, alpha: number, offset: number, index: string): string;
 export declare function bin(field: string | ExprNode, options?: BinOptions): AutoBinNode;
 export declare class AutoBinNode {
+    #private;
     field: string | ExprNode;
     options: BinOptions;
     isAutoBinNode: true;
     constructor(field: string | ExprNode, options?: BinOptions);
     get stats(): FieldStats;
     resolve(fieldInfo: Record<string, FieldInfo>, scaleType: string, timeOffset?: number | null, currentDomain?: [number, number] | null, binStepMultiplier?: number): ExprNode;
+    /**
+     * The bins `resolve` produces with the same arguments: every bin a value of
+     * the field can fall in. What `dense()` pads a histogram from, so a bin
+     * emptied by a filter stays as a zero row and the bars can morph.
+     *
+     * Numeric bins as numbers, edge k at `min + alpha * (k + offset)`. Time
+     * buckets as the interval `time_bucket` steps by, and the field's extent;
+     * those need `t0`, the time scale's origin in epoch seconds, because a time
+     * channel is drawn as seconds from it, and are null without it (before the
+     * scale has one, the channel is not rewritten either).
+     *
+     * Null for a field with a single value, which binHistogram floors instead
+     * of binning.
+     */
+    padding(fieldInfo: Record<string, FieldInfo>, scaleType: string, currentDomain?: [number, number] | null, binStepMultiplier?: number, t0?: number | null): BinPadding | null;
     withOffset(offset: number): AutoBinNode;
 }
 export declare function isBinExpression(expr: unknown): expr is AutoBinNode;