layerchart 2.0.0-next.50 → 2.0.0-next.52

package/dist/server/index.d.ts

@@ -0,0 +1,137 @@
+import type { Component } from 'svelte';
+import type { ChartState } from '../states/chart.svelte.js';
+import type { ComponentNode } from '../states/chart.svelte.js';
+import type { CaptureTarget } from './captureStore.js';
+export { renderTree } from './renderTree.js';
+export { default as ServerChart } from './ServerChart.svelte';
+export { getSSRCapture, setSSRCapture, type CaptureTarget, type SSRCapture, } from './captureStore.js';
+export type CapturedChart = {
+    chartState: ChartState;
+    rootNode: ComponentNode;
+};
+export type CanvasRenderContext = Omit<CanvasRenderingContext2D, 'drawFocusIfNeeded' | 'canvas'> & {
+    canvas?: unknown;
+};
+export type CanvasFactory = (width: number, height: number) => {
+    getContext(type: '2d'): unknown;
+    toBuffer(mimeType: string, ...args: any[]): Buffer | Uint8Array;
+};
+export type RenderOptions = {
+    /** Pixel ratio for high-DPI output. @default 1 */
+    devicePixelRatio?: number;
+    /** Output format. @default 'png' */
+    format?: 'png' | 'jpeg';
+    /** JPEG quality (0-1). Only used when format is 'jpeg'. @default 0.92 */
+    quality?: number;
+    /**
+     * Background color to fill before rendering the chart.
+     * When omitted, PNG output is transparent.
+     * Set to `'white'` (or any CSS color) for an opaque background —
+     * recommended for JPEG which does not support transparency.
+     */
+    background?: string;
+    /**
+     * Canvas factory function.
+     *
+     * Example with \@napi-rs/canvas:
+     * ```ts
+     * import { createCanvas } from '\@napi-rs/canvas';
+     * createCanvas: (w, h) => createCanvas(w, h)
+     * ```
+     */
+    createCanvas: CanvasFactory;
+};
+export type RenderChartOptions = RenderOptions & {
+    /** Width of the output image in pixels. */
+    width: number;
+    /** Height of the output image in pixels. */
+    height: number;
+    /** Additional props to pass to the chart component. */
+    props?: Record<string, any>;
+};
+/**
+ * Create a capture callback for use with `render()` from `svelte/server`.
+ * Pass the returned `onCapture` as the `onCapture` prop to your chart component.
+ * After `render()` completes, call `getCapture()` to retrieve the chart state and
+ * component tree.
+ *
+ * @example
+ * ```ts
+ * import { render } from 'svelte/server';
+ * import { createCaptureCallback, renderCapturedChart } from '../index.js/server';
+ * import MyChart from './MyChart.svelte';
+ *
+ * const { onCapture, getCapture } = createCaptureCallback();
+ * const rendered = render(MyChart, { props: { data, width: 800, height: 400, onCapture } });
+ * rendered.body; // Force the SSR render to fully flush before reading capture state
+ * const capture = getCapture();
+ * ```
+ */
+export declare function createCaptureCallback(): {
+    onCapture: (data: CaptureTarget) => void;
+    getCapture: () => CaptureTarget | null;
+};
+/**
+ * Render a chart component to an image buffer in a single call.
+ *
+ * This is a convenience function that handles SSR rendering, capture, and
+ * canvas rendering in one step. The component should use `<ServerChart>`
+ * internally and accept `width`, `height`, and `capture` props.
+ *
+ * @example
+ * ```ts
+ * import { createCanvas, Path2D } from '\@napi-rs/canvas';
+ * import { renderChart } from '../index.js/server';
+ * import MyChart from './MyChart.svelte';
+ *
+ * // Register Path2D globally for canvas rendering
+ * if (typeof globalThis.Path2D === 'undefined') (globalThis as any).Path2D = Path2D;
+ *
+ * const buffer = renderChart(MyChart, {
+ *   width: 800,
+ *   height: 400,
+ *   props: { data: myData },
+ *   createCanvas: (w, h) => createCanvas(w, h),
+ * });
+ *
+ * // Use as a Response in a SvelteKit endpoint
+ * return new Response(buffer, {
+ *   headers: { 'Content-Type': 'image/png' }
+ * });
+ * ```
+ */
+export declare function renderChart(component: Component<any>, options: RenderChartOptions): Buffer | Uint8Array;
+/**
+ * Render a captured chart component tree to an image buffer.
+ * Call this after `render()` from `svelte/server` has been used to build
+ * the component tree with a capture callback.
+ *
+ * For most use cases, prefer {@link renderChart} which handles the full pipeline.
+ *
+ * @example
+ * ```ts
+ * import { render } from 'svelte/server';
+ * import { createCanvas, Path2D } from '\@napi-rs/canvas';
+ * import { createCaptureCallback, renderCapturedChart } from '../index.js/server';
+ * import MyChart from './MyChart.svelte';
+ *
+ * // Register canvas globals
+ * if (typeof globalThis.Path2D === 'undefined') (globalThis as any).Path2D = Path2D;
+ *
+ * // Build component tree via SSR render
+ * const { onCapture, getCapture } = createCaptureCallback();
+ * const rendered = render(MyChart, { props: { data, width: 800, height: 400, onCapture } });
+ * rendered.body; // Force the SSR render to fully flush before reading capture state
+ *
+ * // Render to image
+ * const buffer = renderCapturedChart(getCapture()!, {
+ *   width: 800,
+ *   height: 400,
+ *   createCanvas: (w, h) => createCanvas(w, h),
+ * });
+ * ```
+ */
+export declare function renderCapturedChart(capture: CapturedChart, options: RenderOptions & {
+    width: number;
+    height: number;
+}): Buffer | Uint8Array;

package/dist/server/index.js

@@ -0,0 +1,141 @@
+import { render } from 'svelte/server';
+import { renderTree } from './renderTree.js';
+export { renderTree } from './renderTree.js';
+export { default as ServerChart } from './ServerChart.svelte';
+export { getSSRCapture, setSSRCapture, } from './captureStore.js';
+/**
+ * Create a capture callback for use with `render()` from `svelte/server`.
+ * Pass the returned `onCapture` as the `onCapture` prop to your chart component.
+ * After `render()` completes, call `getCapture()` to retrieve the chart state and
+ * component tree.
+ *
+ * @example
+ * ```ts
+ * import { render } from 'svelte/server';
+ * import { createCaptureCallback, renderCapturedChart } from '../index.js/server';
+ * import MyChart from './MyChart.svelte';
+ *
+ * const { onCapture, getCapture } = createCaptureCallback();
+ * const rendered = render(MyChart, { props: { data, width: 800, height: 400, onCapture } });
+ * rendered.body; // Force the SSR render to fully flush before reading capture state
+ * const capture = getCapture();
+ * ```
+ */
+export function createCaptureCallback() {
+    let captured = null;
+    return {
+        onCapture: (data) => {
+            captured = data;
+        },
+        getCapture: () => captured,
+    };
+}
+/**
+ * Render a chart component to an image buffer in a single call.
+ *
+ * This is a convenience function that handles SSR rendering, capture, and
+ * canvas rendering in one step. The component should use `<ServerChart>`
+ * internally and accept `width`, `height`, and `capture` props.
+ *
+ * @example
+ * ```ts
+ * import { createCanvas, Path2D } from '\@napi-rs/canvas';
+ * import { renderChart } from '../index.js/server';
+ * import MyChart from './MyChart.svelte';
+ *
+ * // Register Path2D globally for canvas rendering
+ * if (typeof globalThis.Path2D === 'undefined') (globalThis as any).Path2D = Path2D;
+ *
+ * const buffer = renderChart(MyChart, {
+ *   width: 800,
+ *   height: 400,
+ *   props: { data: myData },
+ *   createCanvas: (w, h) => createCanvas(w, h),
+ * });
+ *
+ * // Use as a Response in a SvelteKit endpoint
+ * return new Response(buffer, {
+ *   headers: { 'Content-Type': 'image/png' }
+ * });
+ * ```
+ */
+export function renderChart(component, options) {
+    const { width, height, props = {}, ...renderOptions } = options;
+    const captureTarget = {};
+    // SSR render to build the component tree and capture chart state
+    const rendered = render(component, {
+        props: { ...props, width, height, capture: captureTarget }
+    });
+    // Force the SSR render to fully flush
+    void rendered.body;
+    if (!captureTarget.chartState || !captureTarget.rootNode) {
+        throw new Error('Failed to capture chart state. Ensure the component uses <ServerChart> with a `capture` prop.');
+    }
+    return renderCapturedChart(captureTarget, {
+        width,
+        height,
+        ...renderOptions,
+    });
+}
+/**
+ * Render a captured chart component tree to an image buffer.
+ * Call this after `render()` from `svelte/server` has been used to build
+ * the component tree with a capture callback.
+ *
+ * For most use cases, prefer {@link renderChart} which handles the full pipeline.
+ *
+ * @example
+ * ```ts
+ * import { render } from 'svelte/server';
+ * import { createCanvas, Path2D } from '\@napi-rs/canvas';
+ * import { createCaptureCallback, renderCapturedChart } from '../index.js/server';
+ * import MyChart from './MyChart.svelte';
+ *
+ * // Register canvas globals
+ * if (typeof globalThis.Path2D === 'undefined') (globalThis as any).Path2D = Path2D;
+ *
+ * // Build component tree via SSR render
+ * const { onCapture, getCapture } = createCaptureCallback();
+ * const rendered = render(MyChart, { props: { data, width: 800, height: 400, onCapture } });
+ * rendered.body; // Force the SSR render to fully flush before reading capture state
+ *
+ * // Render to image
+ * const buffer = renderCapturedChart(getCapture()!, {
+ *   width: 800,
+ *   height: 400,
+ *   createCanvas: (w, h) => createCanvas(w, h),
+ * });
+ * ```
+ */
+export function renderCapturedChart(capture, options) {
+    const { width, height, devicePixelRatio = 1, format = 'png', quality = 0.92, background, createCanvas, } = options;
+    // Create canvas
+    const canvasWidth = Math.round(width * devicePixelRatio);
+    const canvasHeight = Math.round(height * devicePixelRatio);
+    const canvas = createCanvas(canvasWidth, canvasHeight);
+    const ctx = canvas.getContext('2d');
+    // Fill background (canvas is transparent by default)
+    if (background) {
+        ctx.fillStyle = background;
+        ctx.fillRect(0, 0, canvasWidth, canvasHeight);
+    }
+    // Apply DPI scaling
+    if (devicePixelRatio !== 1) {
+        ctx.scale(devicePixelRatio, devicePixelRatio);
+    }
+    // Apply padding translation (mirrors what Canvas.svelte's update() does)
+    if (capture.chartState) {
+        const padding = capture.chartState.padding;
+        if (padding) {
+            ctx.translate(padding.left ?? 0, padding.top ?? 0);
+        }
+    }
+    // Render the component tree onto the canvas
+    renderTree(ctx, capture.rootNode);
+    // Export to buffer
+    const mimeType = format === 'jpeg' ? 'image/jpeg' : 'image/png';
+    if (format === 'jpeg') {
+        return canvas.toBuffer(mimeType, quality);
+    }
+    return canvas.toBuffer(mimeType);
+}

package/dist/server/renderChart.ssr.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server/renderChart.ssr.test.js

@@ -0,0 +1,205 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import { render } from 'svelte/server';
+import { createCanvas, Path2D } from '@napi-rs/canvas';
+import { renderChart, renderCapturedChart, createCaptureCallback, } from './index.js';
+import TestLineChart from './TestLineChart.svelte';
+import TestBarChart from './TestBarChart.svelte';
+// Register Path2D globally for canvas rendering
+beforeAll(() => {
+    if (typeof globalThis.Path2D === 'undefined') {
+        globalThis.Path2D = Path2D;
+    }
+});
+const createNodeCanvas = (w, h) => createCanvas(w, h);
+const lineData = Array.from({ length: 20 }, (_, i) => ({
+    date: i,
+    value: 50 + 30 * Math.sin(i / 5),
+}));
+const barData = [
+    { category: 'A', value: 28 },
+    { category: 'B', value: 55 },
+    { category: 'C', value: 43 },
+    { category: 'D', value: 91 },
+];
+describe('renderChart', () => {
+    it('renders a line chart to PNG buffer', () => {
+        const buffer = renderChart(TestLineChart, {
+            width: 400,
+            height: 200,
+            props: { data: lineData },
+            createCanvas: createNodeCanvas,
+        });
+        expect(buffer).toBeInstanceOf(Buffer);
+        expect(buffer.length).toBeGreaterThan(0);
+        // PNG magic bytes
+        expect(buffer[0]).toBe(0x89);
+        expect(buffer[1]).toBe(0x50); // P
+        expect(buffer[2]).toBe(0x4e); // N
+        expect(buffer[3]).toBe(0x47); // G
+    });
+    it('renders a bar chart to PNG buffer', () => {
+        const buffer = renderChart(TestBarChart, {
+            width: 400,
+            height: 200,
+            props: { data: barData },
+            createCanvas: createNodeCanvas,
+        });
+        expect(buffer).toBeInstanceOf(Buffer);
+        expect(buffer.length).toBeGreaterThan(0);
+        // PNG magic bytes
+        expect(buffer[0]).toBe(0x89);
+    });
+    it('renders to JPEG format', () => {
+        const buffer = renderChart(TestLineChart, {
+            width: 400,
+            height: 200,
+            format: 'jpeg',
+            props: { data: lineData },
+            createCanvas: createNodeCanvas,
+        });
+        expect(buffer).toBeInstanceOf(Buffer);
+        // JPEG magic bytes (SOI marker)
+        expect(buffer[0]).toBe(0xff);
+        expect(buffer[1]).toBe(0xd8);
+    });
+    it('respects custom dimensions', () => {
+        const buffer1 = renderChart(TestLineChart, {
+            width: 200,
+            height: 100,
+            props: { data: lineData },
+            createCanvas: createNodeCanvas,
+        });
+        const buffer2 = renderChart(TestLineChart, {
+            width: 800,
+            height: 600,
+            props: { data: lineData },
+            createCanvas: createNodeCanvas,
+        });
+        // Larger image should produce a larger buffer
+        expect(buffer2.length).toBeGreaterThan(buffer1.length);
+    });
+    it('supports devicePixelRatio', () => {
+        const buffer1x = renderChart(TestLineChart, {
+            width: 400,
+            height: 200,
+            devicePixelRatio: 1,
+            props: { data: lineData },
+            createCanvas: createNodeCanvas,
+        });
+        const buffer2x = renderChart(TestLineChart, {
+            width: 400,
+            height: 200,
+            devicePixelRatio: 2,
+            props: { data: lineData },
+            createCanvas: createNodeCanvas,
+        });
+        // 2x DPI should produce a larger buffer (more pixels)
+        expect(buffer2x.length).toBeGreaterThan(buffer1x.length);
+    });
+    it('supports background color', () => {
+        const transparentBuffer = renderChart(TestLineChart, {
+            width: 400,
+            height: 200,
+            props: { data: lineData },
+            createCanvas: createNodeCanvas,
+        });
+        const whiteBuffer = renderChart(TestLineChart, {
+            width: 400,
+            height: 200,
+            background: 'white',
+            props: { data: lineData },
+            createCanvas: createNodeCanvas,
+        });
+        // Both should be valid PNGs but different content
+        expect(transparentBuffer[0]).toBe(0x89);
+        expect(whiteBuffer[0]).toBe(0x89);
+        expect(Buffer.compare(transparentBuffer, whiteBuffer)).not.toBe(0);
+    });
+    it('throws on missing ServerChart', () => {
+        // A bare component that doesn't use ServerChart should fail
+        expect(() => renderChart(
+        // Use a dummy component-like object
+        (() => { }), {
+            width: 400,
+            height: 200,
+            createCanvas: createNodeCanvas,
+        })).toThrow('Failed to capture chart state');
+    });
+});
+describe('renderCapturedChart', () => {
+    it('renders a captured chart tree to a buffer', () => {
+        const captureTarget = {};
+        const rendered = render(TestLineChart, {
+            props: { data: lineData, width: 400, height: 200, capture: captureTarget },
+        });
+        void rendered.body;
+        expect(captureTarget.chartState).toBeDefined();
+        expect(captureTarget.rootNode).toBeDefined();
+        const buffer = renderCapturedChart(captureTarget, {
+            width: 400,
+            height: 200,
+            createCanvas: createNodeCanvas,
+        });
+        expect(buffer).toBeInstanceOf(Buffer);
+        expect(buffer[0]).toBe(0x89); // PNG
+    });
+});
+describe('createCaptureCallback', () => {
+    it('captures chart state via callback', () => {
+        const { onCapture, getCapture } = createCaptureCallback();
+        const rendered = render(TestLineChart, {
+            props: { data: lineData, width: 400, height: 200, onCapture },
+        });
+        void rendered.body;
+        const capture = getCapture();
+        expect(capture).not.toBeNull();
+        expect(capture?.chartState).toBeDefined();
+        expect(capture?.rootNode).toBeDefined();
+    });
+    it('returns null before render', () => {
+        const { getCapture } = createCaptureCallback();
+        expect(getCapture()).toBeNull();
+    });
+});
+describe('ServerChart capture prop', () => {
+    it('populates capture target via prop', () => {
+        const captureTarget = {};
+        const rendered = render(TestLineChart, {
+            props: { data: lineData, width: 400, height: 200, capture: captureTarget },
+        });
+        void rendered.body;
+        expect(captureTarget.chartState).toBeDefined();
+        expect(captureTarget.rootNode).toBeDefined();
+        expect(captureTarget.rootNode.children.length).toBeGreaterThan(0);
+    });
+    it('captures chart state with correct padding', () => {
+        const captureTarget = {};
+        const rendered = render(TestLineChart, {
+            props: { data: lineData, width: 800, height: 400, capture: captureTarget },
+        });
+        void rendered.body;
+        const state = captureTarget.chartState;
+        expect(state.padding).toEqual({ top: 20, right: 20, bottom: 20, left: 20 });
+    });
+    it('captures component tree with children', () => {
+        const captureTarget = {};
+        const rendered = render(TestLineChart, {
+            props: { data: lineData, width: 400, height: 200, capture: captureTarget },
+        });
+        void rendered.body;
+        // Root node (Canvas) should have children
+        const root = captureTarget.rootNode;
+        expect(root.kind).toBe('group');
+        expect(root.children.length).toBeGreaterThan(0);
+        // Count all marks in the tree (may be nested in composite-marks)
+        function countMarks(node) {
+            let count = node.kind === 'mark' ? 1 : 0;
+            for (const child of node.children) {
+                count += countMarks(child);
+            }
+            return count;
+        }
+        // Should have at least 2 marks (Area and Spline)
+        expect(countMarks(root)).toBeGreaterThanOrEqual(2);
+    });
+});

package/dist/server/renderTree.d.ts

@@ -0,0 +1,8 @@
+import type { ComponentNode } from '../states/chart.svelte.js';
+/**
+ * Recursively render the component tree onto a canvas context.
+ * Group nodes: save → render → recurse children → restore
+ * Leaf nodes: save → render → restore
+ * Non-rendering nodes: just recurse children
+ */
+export declare function renderTree(ctx: CanvasRenderingContext2D, node: ComponentNode): void;

package/dist/server/renderTree.js

@@ -0,0 +1,29 @@
+/**
+ * Recursively render the component tree onto a canvas context.
+ * Group nodes: save → render → recurse children → restore
+ * Leaf nodes: save → render → restore
+ * Non-rendering nodes: just recurse children
+ */
+export function renderTree(ctx, node) {
+    if (node.kind === 'group' && node.canvasRender) {
+        // Group: save state, apply transform, render children, restore
+        ctx.save();
+        node.canvasRender.render(ctx);
+        for (const child of node.children) {
+            renderTree(ctx, child);
+        }
+        ctx.restore();
+    }
+    else if (node.canvasRender) {
+        // Leaf mark: save, render, restore
+        ctx.save();
+        node.canvasRender.render(ctx);
+        ctx.restore();
+    }
+    else {
+        // Non-rendering node (e.g. root, composite-mark): just recurse children
+        for (const child of node.children) {
+            renderTree(ctx, child);
+        }
+    }
+}

package/dist/states/chart.svelte.d.ts

@@ -64,7 +64,11 @@ export declare class ChartState<TData = any, XScale extends AnyScale = AnyScale,
     private _markInfosVersion;
     private _nextMarkId;
     /** Reactive accessor — reads _markInfosVersion to create a reactive dependency,
-     * returns the plain array so items are never wrapped in Svelte proxies. */
+     * returns the plain array so items are never wrapped in Svelte proxies.
+     *
+     * When a geo projection is active, strips x/y/data from mark info — those
+     * values are geographic coordinates handled by the projection, not xScale/yScale.
+     * seriesKey/color/label are preserved so marks can still contribute to legends. */
     private get _markInfos();
     /**
      * Register a mark with the chart. The MarkInfo snapshot is stored directly

package/dist/states/chart.svelte.js

@@ -48,10 +48,24 @@ export class ChartState {
     _markInfosVersion = $state(0);
     _nextMarkId = 0;
     /** Reactive accessor — reads _markInfosVersion to create a reactive dependency,
-     * returns the plain array so items are never wrapped in Svelte proxies. */
+     * returns the plain array so items are never wrapped in Svelte proxies.
+     *
+     * When a geo projection is active, strips x/y/data from mark info — those
+     * values are geographic coordinates handled by the projection, not xScale/yScale.
+     * seriesKey/color/label are preserved so marks can still contribute to legends. */
     get _markInfos() {
         // eslint-disable-next-line @typescript-eslint/no-unused-expressions
         this._markInfosVersion;
+        if (this.geoState.props.projection) {
+            return this._markInfosRaw.map(({ _id, info }) => ({
+                _id,
+                info: {
+                    seriesKey: info.seriesKey,
+                    color: info.color,
+                    label: info.label,
+                },
+            }));
+        }
         return this._markInfosRaw;
     }
     /**
@@ -147,8 +161,9 @@ export class ChartState {
     meta = $derived(this.props.meta ?? {});
     constructor(propsGetter) {
         this._propsGetter = propsGetter;
-        // Create GeoState instance
-        this.geoState = new GeoState(() => this.props.geo ?? {});
+        // Create GeoState instance — pass a dimensions getter so projection
+        // is available during SSR (where $effect doesn't run)
+        this.geoState = new GeoState(() => this.props.geo ?? {}, () => ({ width: this.width, height: this.height }));
         // Create SeriesState internally from series/seriesLayout props.
         // When no explicit series are provided, derive implicit series from mark registrations.
         this.seriesState = new SeriesState(() => {