svelteplot 0.0.1-alpha.8 → 0.1.3-next.3

package/LICENSE.md

@@ -0,0 +1,5 @@
+Copyright 2024, Gregor Aisch
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,38 +1,5 @@
-# create-svelte
+# SveltePlot
 
-Everything you need to build a Svelte project, powered by [`create-svelte`](https://github.com/sveltejs/kit/tree/master/packages/create-svelte).
+SveltePlot is a new reactive visualization framework based on the [layered grammar of graphics](https://vita.had.co.nz/papers/layered-grammar.html) ideas. It's API is heavily inspired by [Observable Plot](https://github.com/observablehq/plot). Created by Gregor Aisch.
 
-## Creating a project
-
-If you're seeing this, you've probably already done this step. Congrats!
-
-```bash
-# create a new project in the current directory
-npm create svelte@latest
-
-# create a new project in my-app
-npm create svelte@latest my-app
-```
-
-## Developing
-
-Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
-
-```bash
-npm run dev
-
-# or start the server and open the app in a new browser tab
-npm run dev -- --open
-```
-
-## Building
-
-To create a production version of your app:
-
-```bash
-npm run build
-```
-
-You can preview the production build with `npm run preview`.
-
-> To deploy your app, you may need to install an [adapter](https://kit.svelte.dev/docs/adapters) for your target environment.
+<img src="static/logo.png" alt="logo" width="400" />

package/dist/Mark.svelte

@@ -0,0 +1,292 @@
+<script lang="ts">
+    import { getContext, untrack, type Snippet } from 'svelte';
+
+    import { CHANNEL_SCALE } from './constants.js';
+    import type {
+        ScaledChannelName,
+        MarkType,
+        DataRecord,
+        PlotContext,
+        ChannelName,
+        GenericMarkOptions,
+        ChannelAccessor,
+        BaseMarkProps,
+        FacetContext,
+        ScaleName,
+        RawValue,
+        ResolvedDataRecord,
+        ScaledDataRecord,
+        ScaleType
+    } from './types.js';
+    import { getUsedScales, projectXY, projectX, projectY } from './helpers/scales.js';
+    import { testFilter, isValid } from './helpers/index.js';
+    import { resolveChannel, resolveProp } from './helpers/resolve.js';
+
+    type MarkProps = {
+        data?: DataRecord[];
+        automatic?: boolean;
+        type: MarkType;
+        channels?: ScaledChannelName[];
+        required?: ScaledChannelName[];
+        requiredScales?: Partial<Record<ScaleName, ScaleType[]>>;
+        children?: Snippet<
+            [
+                {
+                    mark: Mark<GenericMarkOptions>;
+                    usedScales: ReturnType<typeof getUsedScales>;
+                    scaledData: ScaledDataRecord[];
+                }
+            ]
+        >;
+        defaults?: Partial<Record<ScaledChannelName, RawValue>>;
+    } & Partial<Record<ChannelName, ChannelAccessor>> &
+        Partial<BaseMarkProps>;
+
+    let {
+        data = [],
+        children,
+        type,
+        channels = [],
+        required = [],
+        requiredScales = {},
+        defaults = {},
+        ...options
+    }: MarkProps = $props();
+
+    const channelsWithFacets: ScaledChannelName[] = $derived([...channels, 'fx', 'fy']);
+
+    const { addMark, updateMark, updatePlotState, removeMark, getTopLevelFacet, getPlotState } =
+        getContext<PlotContext>('svelteplot');
+
+    const plot = $derived(getPlotState());
+    const facet = $derived(getTopLevelFacet());
+
+    const { getFacetState } = getContext<FacetContext>('svelteplot/facet');
+    const { left, top } = $derived(getFacetState());
+
+    class Mark {
+        id;
+        type;
+        channels: ScaledChannelName[] = $state.raw([]);
+        scales: Set<ScaleName> = $state.raw(new Set());
+        data: DataRecord[] = $state.raw([]);
+        options: GenericMarkOptions = $state.raw({});
+
+        constructor(type: MarkType) {
+            this.id = Symbol();
+            this.type = type;
+        }
+    }
+
+    const mark = new Mark(type);
+
+    $effect(() => {
+        return () => {
+            removeMark(mark);
+            added = false;
+        };
+    });
+
+    // let mark2 = $state(mark);
+    const facetMode = $derived(options.facet || 'auto');
+
+    const optionsWithAutoFacet = $derived({
+        ...options,
+        __firstFacet: left && top,
+        ...(facet &&
+        facet.data &&
+        ((facetMode === 'auto' && facet.data === data) || facetMode === 'include')
+            ? {
+                  fx: facet.x,
+                  fy: facet.y
+              }
+            : {})
+    });
+
+    let added = false;
+
+    $effect(() => {
+        if (added) return;
+        // without using untrack() here we end up with inexplicable
+        // circular dependency updates resulting in a stack overflow
+        const channels = untrack(() => channelsWithFacets);
+        mark.channels = channels;
+        mark.scales = new Set(
+            channels
+                .filter((channel) => options[channel] !== 0)
+                .map((channel) => CHANNEL_SCALE[channel])
+        );
+        mark.data = untrack(() => data);
+        mark.options = untrack(() => optionsWithAutoFacet);
+        addMark(mark);
+        added = true;
+    });
+
+    const { getTestFacet } = getContext<FacetContext>('svelteplot/facet');
+    const testFacet = $derived(getTestFacet());
+
+    const resolvedData: ResolvedDataRecord[] = $derived(
+        data.flatMap((row) => {
+            const channels = options as Record<ChannelName, ChannelAccessor>;
+            if (!testFacet(row, channels) || !testFilter(row, channels)) return [];
+            const out: ResolvedDataRecord = {
+                datum: row
+            };
+            for (const [channel] of Object.entries(CHANNEL_SCALE) as [
+                ScaledChannelName,
+                ScaleName
+            ][]) {
+                // check if the mark has defined an accessor for this channel
+                if (options?.[channel] !== undefined && out[channel] === undefined) {
+                    // resolve value
+                    out[channel] = resolveChannel(channel, row, options);
+                }
+            }
+            return [out];
+        })
+    );
+
+    let prevResolvedData: ResolvedDataRecord[] = [];
+
+    $effect(() => {
+        if (isDifferent(resolvedData, prevResolvedData)) {
+            prevResolvedData = resolvedData;
+            // data has changed
+            mark.data = data;
+        }
+    });
+
+    function isDifferent(array1: ResolvedDataRecord[], array2: ResolvedDataRecord[]) {
+        if (array1.length !== array2.length) return true;
+        for (let i = 0; i < array1.length; i++) {
+            for (const [channel] of Object.entries(CHANNEL_SCALE) as [
+                ScaledChannelName,
+                ScaleName
+            ][]) {
+                if (array1[i][channel] !== array2[i][channel]) return true;
+            }
+        }
+        return false;
+    }
+
+    const errors = $derived([
+        ...required
+            .filter((name) => options[name] == null)
+            .map((name) => `missing channel value for ${mark.type} mark: ${name}`),
+        ...Object.entries(requiredScales)
+            .filter(([scale, types]) => {
+                return !types.includes(plot.scales[scale].type);
+            })
+            .map(
+                ([scale, types]) => `scale type mismatch for ${scale} (needs ${types.join(' or ')})`
+            )
+    ]);
+
+    $effect(() => {
+        for (const name of required) {
+            if (options[name] == null) throw new Error(`missing channel value: ${name}`);
+        }
+    });
+
+    const usedScales = $derived(getUsedScales(plot, optionsWithAutoFacet, mark));
+    /**
+     * based on the data and the global scales we can now map the data
+     * elements to the scales
+     */
+    const scaledData = $derived(
+        resolvedData.flatMap((row) => {
+            const out: ScaledDataRecord = {
+                datum: row.datum,
+                valid: true
+            };
+            // compute dx/dy
+            const dx = Number(resolveProp<number>(options.dx, out.datum, 0));
+            const dy = Number(resolveProp<number>(options.dy, out.datum, 0));
+
+            // special handling if there's a projection
+            if (plot.scales.projection && mark.type !== 'geo') {
+                for (const suffix of ['', '1', '2']) {
+                    if (
+                        options?.[`x${suffix}`] !== undefined &&
+                        options?.[`y${suffix}`] !== undefined
+                    ) {
+                        // we have two-dimensional accessors
+                        // for the x and y channels
+                        const rx = resolveChannel(`x${suffix}`, row, options);
+                        const ry = resolveChannel(`y${suffix}`, row, options);
+                        const [x, y] =
+                            mark.type === 'line'
+                                ? [rx, ry] // line paths are projected later
+                                : projectXY(
+                                      plot.scales,
+                                      rx,
+                                      ry,
+                                      usedScales.x,
+                                      usedScales.y,
+                                      suffix
+                                  );
+                        out[`x${suffix}`] = x;
+                        out[`y${suffix}`] = y;
+                        out.valid = out.valid && isValid(rx) && isValid(ry);
+                    }
+                }
+            }
+
+            // iterate over all scaled channels
+            for (const [channel, scale] of Object.entries(CHANNEL_SCALE) as [
+                ScaledChannelName,
+                ScaleName
+            ][]) {
+                // check if the mark has defined an accessor for this channel
+                if (options?.[channel] !== undefined && out[channel] === undefined) {
+                    // resolve value
+                    const value = row[channel];
+
+                    const scaled = usedScales[channel]
+                        ? scale === 'x'
+                            ? projectX(channel as 'x' | 'x1' | 'x2', plot.scales, value)
+                            : scale === 'y'
+                              ? projectY(channel as 'y' | 'y1' | 'y1', plot.scales, value)
+                              : plot.scales[scale].fn(value)
+                        : value;
+
+                    out.valid = out.valid && isValid(value);
+                    // apply dx/dy transform
+                    out[channel] =
+                        scale === 'x' && Number.isFinite(scaled) ? (scaled as number) + dx : scaled;
+                    out[channel] =
+                        scale === 'y' && Number.isFinite(scaled) ? (scaled as number) + dy : scaled;
+                } else if (defaults[channel]) {
+                    out[channel] = defaults[channel];
+                }
+            }
+
+            return [out];
+        })
+    );
+</script>
+
+{#if errors.length}
+    <text transform="translate(10,10)">
+        {#each errors as error, i}
+            <tspan x="0" dy={i ? 14 : 0}>{error}</tspan>
+        {/each}
+    </text>
+{:else if children}
+    {@render children({
+        mark,
+        usedScales,
+        scaledData
+    })}
+{/if}
+
+<style>
+    text {
+        stroke: var(--plot-bg);
+        fill: crimson;
+        font-size: 11px;
+        stroke-width: 3px;
+        font-weight: bold;
+        paint-order: stroke fill;
+    }
+</style>

package/dist/Mark.svelte.d.ts

@@ -0,0 +1,22 @@
+import { type Snippet } from 'svelte';
+import type { ScaledChannelName, MarkType, DataRecord, ChannelName, GenericMarkOptions, ChannelAccessor, BaseMarkProps, ScaleName, RawValue, ScaledDataRecord, ScaleType } from './types.js';
+import { getUsedScales } from './helpers/scales.js';
+type MarkProps = {
+    data?: DataRecord[];
+    automatic?: boolean;
+    type: MarkType;
+    channels?: ScaledChannelName[];
+    required?: ScaledChannelName[];
+    requiredScales?: Partial<Record<ScaleName, ScaleType[]>>;
+    children?: Snippet<[
+        {
+            mark: Mark<GenericMarkOptions>;
+            usedScales: ReturnType<typeof getUsedScales>;
+            scaledData: ScaledDataRecord[];
+        }
+    ]>;
+    defaults?: Partial<Record<ScaledChannelName, RawValue>>;
+} & Partial<Record<ChannelName, ChannelAccessor>> & Partial<BaseMarkProps>;
+declare const Mark: import("svelte").Component<MarkProps, {}, "">;
+type Mark = ReturnType<typeof Mark>;
+export default Mark;

package/dist/Plot.svelte

@@ -1,168 +1,163 @@
-<script>import { setContext } from "svelte";
-import { Frame, GridX, GridY, AxisX, AxisY, ColorLegend, SymbolLegend } from "./index.js";
-import { DEFAULT_PLOT_OPTIONS, Plot } from "./classes/Plot.svelte";
-import mergeDeep from "./helpers/mergeDeep.js";
-let {
-  // snippets
-  header,
-  footer,
-  overlay,
-  children,
-  // props
-  height = "auto",
-  marginLeft = 30,
-  marginRight = 10,
-  marginTop = 20,
-  marginBottom = 40,
-  inset = null,
-  grid = false,
-  frame = false,
-  maxWidth = null,
-  title = "",
-  subtitle = "",
-  caption = "",
-  // scales
-  radius = null,
-  color = null,
-  symbol = null,
-  x = null,
-  y = null,
-  onmousemove = null
-} = $props();
-let width = $state(400);
-const plot = new Plot(600, height || defaultPlotHeight, {
-  marginTop,
-  marginLeft,
-  marginRight,
-  marginBottom,
-  // scales
-  symbol,
-  radius,
-  x,
-  y,
-  color,
-  // other
-  title,
-  subtitle,
-  caption
-});
-setContext("svelteplot", plot);
-$effect(() => {
-  plot.width = width;
-  plot._height = height;
-  plot.options = mergeDeep({}, DEFAULT_PLOT_OPTIONS, {
-    marginBottom,
-    marginLeft,
-    marginRight,
-    marginTop,
-    inset,
-    symbol,
-    radius,
-    color,
-    x,
-    y,
-    title,
-    subtitle,
-    caption
-  });
-});
-function onMouseMove(evt) {
-  if (onmousemove)
-    onmousemove({ ...evt, plot });
-}
-$inspect(plot.x.domain);
-let hasLegend = $derived(color?.legend || symbol?.legend);
+<!--
+    @component
+    The Plot component is the container for plots. It collects the marks with
+    their data and channels and computes the shared scales.
+
+    The Plot component is split into two parts. This is the outer Plot which 
+    provides convenient defaults and automatically adds axes etc to the grapihcs.
+    The downside is that it adds a bunch of imports that you may not be using.
+    To help with this you can use the core/Plot component directly for a more
+    low-level Plot wrapper.
+-->
+<script lang="ts">
+    import Plot from './core/Plot.svelte';
+
+    import type { PlotOptions } from './types.js';
+
+    // implicit marks
+    import AxisX from './marks/AxisX.svelte';
+    import AxisY from './marks/AxisY.svelte';
+    import ColorLegend from './marks/ColorLegend.svelte';
+    import Frame from './marks/Frame.svelte';
+    import GridX from './marks/GridX.svelte';
+    import GridY from './marks/GridY.svelte';
+    import SymbolLegend from './marks/SymbolLegend.svelte';
+    import FacetAxes from './core/FacetAxes.svelte';
+
+    // automatic scales
+    import { autoScale, autoScaleColor } from './helpers/autoScales.js';
+    import { namedProjection } from './helpers/autoProjection.js';
+    import { isObject } from './helpers/index.js';
+
+    let {
+        header: userHeader,
+        footer: userFooter,
+        overlay,
+        underlay,
+        children: parentChildren,
+        testid,
+        facet,
+        projection,
+        ...restOptions
+    }: Partial<PlotOptions> = $props();
+
+    const projectionOpts = $derived.by(() => {
+        if (
+            projection &&
+            typeof projection !== 'function' &&
+            typeof projection?.type !== 'function'
+        ) {
+            const { type: projFactory, aspectRatio } = namedProjection(
+                isObject(projection) ? projection.type : projection
+            );
+            return {
+                ...(isObject(projection) ? projection : {}),
+                type: projFactory,
+                aspectRatio
+            };
+        }
+        return projection;
+    });
+
+    const scales = $derived(
+        Object.fromEntries(
+            ['x', 'y', 'r', 'color', 'opacity', 'symbol', 'length', 'fx', 'fy'].map((scale) => {
+                const scaleOpts = restOptions[scale] || {};
+                const scaleFn = scaleOpts.scale || (scale === 'color' ? autoScaleColor : autoScale);
+                return [scale, { ...scaleOpts, scale: scaleFn }];
+            })
+        )
+    );
 </script>
 
-<figure class="svelteplot" bind:clientWidth={width} style:max-width={maxWidth}>
-    <svg
-        role="document"
-        {width}
-        height={plot.height}
-        onmousemove={onmousemove ? onMouseMove : null}
-    >
-        <!-- automatic grids -->
-        {#if grid || x?.grid}<GridX automatic />{/if}
-        {#if grid || y?.grid}<GridY automatic />{/if}
+{#snippet header()}
+    {#if restOptions.title}<h2>{restOptions.title}</h2>{/if}
+    {#if restOptions.subtitle}<h3>{restOptions.subtitle}</h3>{/if}
+    <!-- also pass on user header -->
+    {#if userHeader}{@render userHeader()}{/if}
+    {#if restOptions.color?.legend}
+        <ColorLegend />
+    {/if}
+    {#if restOptions.symbol?.legend}
+        <SymbolLegend />
+    {/if}
+{/snippet}
+
+{#snippet footer()}
+    {#if restOptions.caption}<div>{restOptions.caption}</div>{/if}
+    {#if userFooter}{@render userFooter()}{/if}
+{/snippet}
 
-        {#if !plot.hasAxisXMark && plot.hasChannelX}
-            <!-- automatic x axis -->
-            {#if plot.options.x.axis === 'bottom' || plot.options.x.axis === 'both'}
-                <AxisX anchor="bottom" automatic />
-            {/if}
-            {#if plot.options.x.axis === 'top' || plot.options.x.axis === 'both'}
+<!-- There's a bug triggering RangeError: Maximum call stack size exceeded 
+     when using SveltePlot in ssr, so for now, we're disabling it -->
+
+<Plot
+    {overlay}
+    {underlay}
+    {...restOptions}
+    header={userHeader ||
+    restOptions.title ||
+    restOptions.subtitle ||
+    restOptions.color?.legend ||
+    restOptions.symbol?.legend
+        ? header
+        : null}
+    footer={userFooter || restOptions?.caption ? footer : null}
+    projection={projectionOpts}
+    implicitScales
+    {...scales}>
+    {#snippet children({
+        hasProjection,
+        hasExplicitAxisX,
+        hasExplicitAxisY,
+        hasExplicitGridX,
+        hasExplicitGridY,
+        options,
+        scales,
+        ...restProps
+    })}
+        <!-- implicit axes -->
+        {#if !hasProjection && !hasExplicitAxisX}
+            {#if options.axes && (options.x.axis === 'top' || options.x.axis === 'both')}
                 <AxisX anchor="top" automatic />
             {/if}
+            {#if options.axes && (options.x.axis === 'bottom' || options.x.axis === 'both')}
+                <AxisX anchor="bottom" automatic />
+            {/if}
         {/if}
-        {#if !plot.hasAxisYMark && plot.hasChannelY}
-            <!-- automatic y axis -->
-            {#if plot.options.y.axis === 'left' || plot.options.y.axis === 'both'}
+        {#if !hasProjection && !hasExplicitAxisY}
+            {#if options.axes && (options.y.axis === 'left' || options.y.axis === 'both')}
                 <AxisY anchor="left" automatic />
             {/if}
-            {#if plot.options.y.axis === 'right' || plot.options.y.axis === 'both'}
+            {#if options.axes && (options.y.axis === 'right' || options.y.axis === 'both')}
                 <AxisY anchor="right" automatic />
             {/if}
         {/if}
-        <!-- automatic frame -->
-        {#if frame}<Frame />{/if}
-        {#if children}{@render children(plot)}{/if}
-    </svg>
-
-    {#if plot.options.title || plot.options.subtitle || header || hasLegend}
-        <div class="plot-header">
-            {#if plot.options.title}
-                <h2>{@html plot.options.title}</h2>
-            {/if}
-            {#if plot.options.subtitle}
-                <h3>{@html plot.options.subtitle}</h3>
-            {/if}
-            {#if color?.legend}
-                <ColorLegend />
-            {/if}
-            {#if symbol?.legend}
-                <SymbolLegend />
-            {/if}
-            {#if header}{@render header(plot)}{/if}
-        </div>
-    {/if}
-
-    {#if footer || plot.options.caption}
-        <div class="plot-footer">
-            {#if plot.options.caption}
-                <figcaption>{@html plot.options.caption}</figcaption>
-            {/if}
-            {#if footer}{@render footer(plot)}{/if}
-        </div>
-    {/if}
-
-    <div class="overlay">
-        {#if overlay}{@render overlay(plot)}{/if}
-    </div>
-</figure>
+        <!-- implicit grids -->
+        {#if !hasExplicitGridX && (options.grid || options.x.grid)}
+            <GridX automatic />
+        {/if}
+        {#if !hasExplicitGridY && (options.grid || options.y.grid)}
+            <GridY automatic />
+        {/if}
+        <!-- implicit frame -->
+        {#if options.frame}
+            <Frame automatic />
+        {/if}
+        {@render parentChildren?.({
+            options,
+            scales,
+            ...restProps
+        })}
+    {/snippet}
+    {#snippet facetAxes()}
+        <FacetAxes />
+    {/snippet}
+</Plot>
 
 <style>
-    figure {
-        margin: 1em 0;
-        position: relative;
-        display: flex;
-        flex-direction: column;
-    }
-    figure .plot-header {
-        order: 1;
-    }
-    svg {
-        order: 2;
-        overflow: visible;
-    }
-    figure .plot-footer {
-        order: 3;
-    }
-    .overlay {
-        position: absolute;
-        pointer-events: none;
-        top: 0;
-        left: 0;
-        bottom: 0;
-        right: 0;
+    :root {
+        --plot-bg: white;
+        --plot-fg: currentColor;
     }
 </style>