@fjader/svelte 0.2.3 → 0.2.5

package/dist/types.d.ts

@@ -4,6 +4,8 @@ import type { ChartConfig } from './config/ChartConfig.svelte';
 import type { DimValue } from './query-engine/categorical-identity';
 import type { AutoBinNode } from './sql/bin';
 import type { SelectionResponse } from './components/rendering/activity-reads';
+/** What a mark does with NULL in its categorical channels; see BaseMarkProps.nulls. */
+export type NullsResponse = 'keep' | 'drop';
 import type { RollingAvgNode } from './sql/rolling-avg';
 export type ContinuousScaleType = 'linear' | 'log' | 'symlog' | 'pow' | 'identity';
 export type DiscreteScaleType = 'band' | 'point';
@@ -37,13 +39,27 @@ export type FieldRef = string | ExprNode;
  * resolves against the chart's state, such as bin() or a rolling average.
  */
 export type ChannelRef = FieldRef | AutoBinNode | RollingAvgNode;
-/** Color prop: CSS constant, column name, object wrapper {field, scheme?, type?}, SQL node, or null. */
+/** A category value a colour can be pinned to. */
+export type ColorDomainValue = string | number | boolean | null;
+/**
+ * Color prop: CSS constant, column name, object wrapper, SQL node, or null.
+ *
+ * The object wrapper takes a scheme and type, or explicit ordinal colours:
+ *
+ *   { field: 'won', domain: [0, 1], range: ['#d62728', '#2ca02c'] }
+ *
+ * `range` replaces the scheme's colours, which go to the values in sorted
+ * order. `domain` pins values to them instead: domain[i] draws range[i], and
+ * values outside it draw the null colour. Either one makes the scale ordinal.
+ */
 export type ColorProp = FieldRef | {
     field: string;
     scheme?: ColorScheme;
     type?: ColorScaleType;
     constant?: number;
     exponent?: number;
+    domain?: readonly ColorDomainValue[];
+    range?: readonly string[];
 } | null;
 /**
  * A SQL transform modifies the Mosaic Query AST before execution.
@@ -58,6 +74,13 @@ export interface SqlTransform {
     apply(query: SelectQuery, config?: MarkConfig): SelectQuery;
     /** Channel aliases this transform adds to the result beyond the base select (e.g. stack's y0/y1). */
     channels?: string[];
+    /**
+     * The row predicate this transform adds to the query, when that is all it does
+     * (`filter`). It applies to the source rows, before any grouping, so a query
+     * over a pre-aggregated table cannot apply it (the columns it names are gone):
+     * the table is built with it instead, and the read leaves it out.
+     */
+    where?: unknown;
     /**
      * The channels whose values identify each row, leading term first, when this
      * transform guarantees exactly one row per combination of them — or null when
@@ -68,6 +91,12 @@ export interface SqlTransform {
      * band a mark may morph along.
      */
     alignment?(aliases: string[], config?: MarkConfig): string[] | null;
+    /**
+     * The rows this transform would add to a result to pad it, as a SELECT of
+     * every alias, or null when it pads nothing. A pre-aggregated table is
+     * built with them, so its reads need no padding of their own (`padded`).
+     */
+    padRows?(aliases: string[], config?: MarkConfig): string | null;
     describe?(): string;
 }
 /** A JS transform processes client-side data after the query returns. */
@@ -104,6 +133,45 @@ export interface ChannelIdentity {
      * when dense() pads from the whole dim as it did before.
      */
     present?: string;
+    /**
+     * The NULL category's id, when the mark drops NULL (`nulls="drop"`): `dense()`
+     * pads no row for it, as its rows are filtered out.
+     */
+    dropNullId?: number;
+}
+/**
+ * One binned channel's bins, as `bin()` resolved them for a query, which
+ * `dense()` pads a histogram from. A rect's upper edge is the same bins with
+ * offset 1.
+ */
+export type BinPadding = NumericBinPadding | TimeBinPadding;
+/** Numeric bins: edge k is `min + alpha * (k + offset)` for k in [0, count). */
+export interface NumericBinPadding {
+    kind: 'number';
+    /** The binned column or expression, as SQL: a bin is NULL exactly where it is. */
+    source: string;
+    min: number;
+    alpha: number;
+    count: number;
+    offset: number;
+}
+/**
+ * Time buckets of `interval` (SQL, as `time_bucket` takes it) over the field's
+ * extent, minMs to maxMs. An edge is the bucket start plus `offset` intervals,
+ * drawn as seconds from the time scale's origin `t0` (epoch seconds), the form
+ * a time channel takes in the query. `count` estimates the buckets, for the
+ * row limit: months and years are not a fixed width.
+ */
+export interface TimeBinPadding {
+    kind: 'time';
+    /** The binned column or expression, as SQL: a bucket is NULL exactly where it is. */
+    source: string;
+    interval: string;
+    minMs: number;
+    maxMs: number;
+    t0: number;
+    count: number;
+    offset: number;
 }
 export interface MarkConfig {
     markType: string;
@@ -115,6 +183,10 @@ export interface MarkConfig {
     identity?: Record<string, ChannelIdentity>;
     /** The query's GROUP BY channels, or null when it does not aggregate. Per query. */
     groupKeys?: string[] | null;
+    /** The numeric `bin()` channels and their bins, which `dense()` pads from. Per query. */
+    bins?: Record<string, BinPadding> | null;
+    /** The query reads a table that already holds its padding rows. Per query. */
+    padded?: boolean;
     [key: string]: unknown;
 }
 export interface ScaleMap {
@@ -184,6 +256,32 @@ export interface BaseMarkProps {
      * - `'filter'`: every selection filters it, even on a field it draws by, so
      *   its aggregates are recomputed for the subset: top N within the selected
      *   region, shares within the selected groups.
+     * - `'ignore'`: no selection filters or dims it, its own chart's controls
+     *   included, and a selection change never re-queries it. For context: the
+     *   whole drawn faintly behind a filtered part, on the same scales, whose
+     *   extent then keeps the axis still while the part changes. A click on its
+     *   Other bar toggles, as under `'auto'`.
+     *
+     * Background totals are two layers of the same mark: an `'ignore'` one
+     * drawn faintly behind, the whole, and an `'auto'` one in front, the part a
+     * brush or click elsewhere leaves. Each bar shrinks over its total instead
+     * of losing it, and the y axis keeps the total's extent:
+     *
+     * ```svelte
+     * <BarMarkY table="flights" x="carrier" y={count()} selectionResponse="ignore" fillOpacity={0.2} />
+     * <BarMarkY table="flights" x="carrier" y={count()} />
+     * ```
+     *
+     * With a top N, choose which layer ranks; the other gets
+     * `contributeDomain={false}` and follows the axis:
+     *
+     * - the back layer, to rank once over the whole: the same N categories
+     *   stay while the front bars shrink;
+     * - the front layer, to re-rank within the selection: the N categories
+     *   change with it, and the whole is drawn for whichever are shown.
+     *
+     * Not with `includeOthers`: the follower has no Other row (see
+     * `contributeDomain`).
      *
      * A `'filter'` mark never dims. A legend, Toggle or band label filters it
      * in its own chart too: every such control on the same fields shares one
@@ -196,12 +294,59 @@ export interface BaseMarkProps {
      * own chart, so the marks under it do not move while it is dragged.
      */
     selectionResponse?: SelectionResponse;
+    /**
+     * Whether this mark adds its categories to a band axis's domain (default
+     * `true`). `false`: the mark follows the axis the other marks on it decide
+     * (their categories, their order); rows of categories the axis does not show
+     * are not drawn. For a layer that gives context to another, such as the whole
+     * behind a part. It cannot rank or reduce its own categories, so `topN`, `sort`
+     * and an explicit `domain` are refused with it (an error is logged and the
+     * mark contributes).
+     *
+     * Known limit: when the axis shows an Other bucket (another mark's topN with
+     * `includeOthers`), a follower has no Other row of its own. Its bars of
+     * categories that leave the axis walk to Other's slot and are gone when the
+     * transition ends, and nothing draws the whole behind Other. Folding such
+     * categories into an Other row would need the follower's query to depend on
+     * the axis's current categories.
+     */
+    contributeDomain?: boolean;
+    /**
+     * What this mark does with NULL in its categorical channels: its band axis,
+     * ordinal colour, series and facet.
+     *
+     * - `'keep'` (the default): NULL is a category like any other. It is ranked
+     *   by its measure, drawn, and labelled "(null)", in the null colour.
+     * - `'drop'`: rows whose value in any of those channels is NULL are left out
+     *   before any transform, so a top N ranks, and Other sums, without them.
+     */
+    nulls?: NullsResponse;
+    /**
+     * Whether the chart's entrance waits for this mark's first data. Default
+     * true: the chart enters once every mark has landed, so later marks cannot
+     * widen the axes mid-entrance. False for a mark known to be slower than
+     * the rest: the chart enters without it, and it joins the entrance where it
+     * is, or appears after it. A chart waits at most a second past its first
+     * mark either way.
+     */
+    holdsEntrance?: boolean;
     scheme?: ColorScheme;
     limit?: number;
     transforms?: Transform[];
     sort?: SortConfig | null;
     domain?: DomainConfig | null;
-    tooltip?: boolean;
+    /**
+     * Hover tooltips. `true` (the default) or `false`, or options:
+     *
+     * - `sortTable`: write the mark's tooltip table sorted by x, so a hover
+     *   lookup can skip DuckDB row groups outside the pointer's box. Off by
+     *   default: the sort delays the first hover (the table is written when the
+     *   pointer enters the chart), and measured up to 2M rows it did not make
+     *   lookups faster.
+     */
+    tooltip?: boolean | {
+        sortTable?: boolean;
+    };
     tooltipProximity?: 'x' | 'y' | 'xy';
     tip?: (FieldRef | '*')[] | false;
     fitDomain?: 'x' | 'y' | boolean;
@@ -272,6 +417,18 @@ export interface LODConfig {
     /** Callback fired on LOD state transitions (decimation toggle, dots appear/disappear). */
     onLODChange?: (state: LODChangeState) => void;
 }
+/**
+ * How a chart's marks enter when its data first draws.
+ *
+ * - `'auto'` (the default): bars, histograms and areas grow from 0 on their
+ *   measure axis, showing magnitude; everything else fades in.
+ * - `'fade'`: every mark fades in. Calmer, for dense small multiples.
+ * - `'none'`: marks appear at once.
+ *
+ * Under `prefers-reduced-motion: reduce`, `'auto'` becomes `'fade'`. The axes
+ * never move on load: the entrance is the data's, not the viewport's.
+ */
+export type EntranceMode = 'auto' | 'fade' | 'none';
 import type { Margin, Point, AxesResult } from './layout/ChartLayout.svelte';
 import type { LinearScaleState } from './scales/LinearScaleState.svelte';
 import type { BandScaleState } from './scales/BandScaleState.svelte';
@@ -331,6 +488,24 @@ export interface ChartContext {
     readonly currentXScreenPoint: number | null | undefined;
     readonly currentYScreenPoint: number | null | undefined;
     readonly xScaleState: ScaleStateInstance | null | undefined;
+    /**
+     * How many times the chart's x or y scale has been replaced by another (not
+     * its first resolution). Marks rebuild their lifecycle when it changes.
+     */
+    readonly scaleGeneration: number;
+    /**
+     * Whether any of the chart's cells is on screen (with a small margin).
+     * Marks stop re-querying while it is false; see MarkHandle.active.
+     */
+    readonly visible: boolean;
+    /**
+     * Whether a visible chart other than this one draws `scale`: a catch-up
+     * springs such a scale rather than snapping it. See
+     * ChartVisibility.shownElsewhere.
+     */
+    shownElsewhere(scale: object): boolean;
+    /** Whether the pointer is over any of the chart's cells (hover intent). */
+    readonly hovered: boolean;
     readonly yScaleState: ScaleStateInstance | null | undefined;
     readonly scaleTypes: {
         x: string;

package/package.json

@@ -18,7 +18,7 @@
 		"type": "git",
 		"url": "git+https://github.com/dlyngman/fjader.git"
 	},
-	"version": "0.2.3",
+	"version": "0.2.5",
 	"type": "module",
 	"svelte": "./dist/index.js",
 	"exports": {
@@ -41,7 +41,7 @@
 		"prepack": "svelte-package",
 		"prepare": "svelte-kit sync || echo ''",
 		"format": "prettier --write .",
-		"lint": "prettier --check . && eslint .",
+		"lint": "prettier --check . && eslint . && node scripts/check-doc-blocks.mjs",
 		"test": "vitest",
 		"typecheck": "svelte-check --tsconfig ./jsconfig.json",
 		"build:widget": "vite build --config vite.widget.config.js",
@@ -60,6 +60,7 @@
 		"@types/d3-color": "^3.1.3",
 		"@types/d3-scale": "^4.0.9",
 		"@types/d3-scale-chromatic": "^3.1.0",
+		"@uwdata/mosaic-sql": "^0.35.0",
 		"@webgpu/types": "^0.1.69",
 		"duckdb": "^1.4.4",
 		"eslint": "^10.0.0",
@@ -80,12 +81,12 @@
 		"vitest": "^4.0.18"
 	},
 	"peerDependencies": {
+		"@uwdata/mosaic-sql": "^0.34.2 || ^0.35.0",
 		"svelte": "^5.0.0"
 	},
 	"dependencies": {
 		"@duckdb/duckdb-wasm": "1.30.0",
 		"@uwdata/flechette": "2.3.0",
-		"@uwdata/mosaic-sql": "^0.34.2",
 		"d3-array": "^3.2.4",
 		"d3-color": "^3.1.0",
 		"d3-format": "^3.1.0",