svelteplot 0.14.2-pr-551.3 → 0.14.2-pr-552.0

package/dist/marks/Hexgrid.svelte

@@ -0,0 +1,92 @@
+<!-- @component
+    Renders a hexagonal grid decoration, typically used alongside hexbin-transformed data.
+    A data-less mark similar to Frame.
+-->
+<script lang="ts">
+    interface HexgridMarkProps {
+        /** the hexagon bin width in pixels */
+        binWidth?: number;
+        /** the stroke color of the grid lines */
+        stroke?: string;
+        /** the stroke opacity of the grid lines */
+        strokeOpacity?: number;
+        /** the stroke width of the grid lines */
+        strokeWidth?: number;
+        /** the fill color of the hexagons */
+        fill?: string;
+        /** the fill opacity of the hexagons */
+        fillOpacity?: number;
+        /** CSS class name */
+        class?: string;
+    }
+
+    import Mark from '../Mark.svelte';
+    import type { MarkType } from '../types/index.js';
+    import { usePlot } from '../hooks/usePlot.svelte.js';
+
+    let markProps: HexgridMarkProps = $props();
+
+    const {
+        binWidth = 20,
+        stroke = 'currentColor',
+        strokeOpacity = 0.1,
+        strokeWidth = 1,
+        fill = 'none',
+        fillOpacity,
+        class: className = 'hexgrid'
+    }: HexgridMarkProps = $derived({ ...markProps });
+
+    const plot = usePlot();
+
+    const sqrt3 = Math.sqrt(3);
+
+    function r3(x: number) {
+        return Math.round(x * 1000) / 1000;
+    }
+
+    const pathData = $derived.by(() => {
+        // Hex offset constants matching hexbin transform
+        const ox = 0.5;
+        const oy = 0;
+        const rx = binWidth / 2;
+        const ry = (rx * 2) / sqrt3;
+        const dx = binWidth;
+        const dy = ry * 1.5;
+
+        const w = plot.facetWidth;
+        const h = plot.facetHeight;
+        const ml = plot.options.marginLeft;
+        const mt = plot.options.marginTop;
+
+        const cols = Math.ceil(w / dx) + 1;
+        const rows = Math.ceil(h / dy) + 1;
+
+        let path = '';
+        for (let j = -1; j <= rows; j++) {
+            for (let i = -1; i <= cols; i++) {
+                const cx = r3((i + (j & 1) / 2 + ox) * dx + ml);
+                const cy = r3((j + oy) * dy + mt);
+                // Pointy-topped hexagon path
+                path += `M${cx},${r3(cy - ry)}`;
+                path += `l${r3(rx)},${r3(ry / 2)}`;
+                path += `v${r3(ry)}`;
+                path += `l${r3(-rx)},${r3(ry / 2)}`;
+                path += `l${r3(-rx)},${r3(-ry / 2)}`;
+                path += `v${r3(-ry)}Z`;
+            }
+        }
+        return path;
+    });
+</script>
+
+<Mark type={'hexgrid' as MarkType}>
+    <g class={className}>
+        <path
+            d={pathData}
+            {fill}
+            fill-opacity={fillOpacity}
+            {stroke}
+            stroke-opacity={strokeOpacity}
+            stroke-width={strokeWidth} />
+    </g>
+</Mark>

package/dist/marks/Hexgrid.svelte.d.ts

@@ -0,0 +1,23 @@
+interface HexgridMarkProps {
+    /** the hexagon bin width in pixels */
+    binWidth?: number;
+    /** the stroke color of the grid lines */
+    stroke?: string;
+    /** the stroke opacity of the grid lines */
+    strokeOpacity?: number;
+    /** the stroke width of the grid lines */
+    strokeWidth?: number;
+    /** the fill color of the hexagons */
+    fill?: string;
+    /** the fill opacity of the hexagons */
+    fillOpacity?: number;
+    /** CSS class name */
+    class?: string;
+}
+/**
+ * Renders a hexagonal grid decoration, typically used alongside hexbin-transformed data.
+ * A data-less mark similar to Frame.
+ */
+declare const Hexgrid: import("svelte").Component<HexgridMarkProps, {}, "">;
+type Hexgrid = ReturnType<typeof Hexgrid>;
+export default Hexgrid;

package/dist/marks/index.d.ts

@@ -31,6 +31,7 @@ export { default as Geo } from './Geo.svelte';
 export { default as Graticule } from './Graticule.svelte';
 export { default as GridX } from './GridX.svelte';
 export { default as GridY } from './GridY.svelte';
+export { default as Hexgrid } from './Hexgrid.svelte';
 export { default as Hull } from './Hull.svelte';
 export { default as Image } from './Image.svelte';
 export { default as Line } from './Line.svelte';

package/dist/marks/index.js

@@ -31,6 +31,7 @@ export { default as Geo } from './Geo.svelte';
 export { default as Graticule } from './Graticule.svelte';
 export { default as GridX } from './GridX.svelte';
 export { default as GridY } from './GridY.svelte';
+export { default as Hexgrid } from './Hexgrid.svelte';
 export { default as Hull } from './Hull.svelte';
 export { default as Image } from './Image.svelte';
 export { default as Line } from './Line.svelte';

package/dist/transforms/hexbin.d.ts

@@ -0,0 +1,37 @@
+import { type ReducerName } from '../helpers/reduce.js';
+import type { DataRecord, RawValue, TransformArg } from '../types/index.js';
+type ReducerOption = ReducerName | ((group: DataRecord[]) => RawValue);
+type HexbinOutputChannels = Partial<{
+    fill: ReducerOption;
+    stroke: ReducerOption;
+    r: ReducerOption;
+    opacity: ReducerOption;
+    fillOpacity: ReducerOption;
+    strokeOpacity: ReducerOption;
+}>;
+export type HexbinOptions = HexbinOutputChannels & {
+    /**
+     * Approximate number of hex bins along the x-axis.
+     * The actual bin width is computed from the data extent.
+     * Default: 20.
+     */
+    bins?: number;
+    /**
+     * Explicit bin width in data units. Overrides `bins` if set.
+     */
+    binWidth?: number;
+};
+/**
+ * Bins data points into hexagonal cells and applies reducers to produce
+ * aggregated output channels (e.g. fill="count", r="count").
+ *
+ * Usage:
+ * ```svelte
+ * <Dot {...hexbin(
+ *     { data: penguins, x: "culmen_length_mm", y: "culmen_depth_mm" },
+ *     { fill: "count", r: "count", bins: 15 }
+ * )} symbol="hexagon" />
+ * ```
+ */
+export declare function hexbin({ data, ...channels }: TransformArg<DataRecord>, options?: HexbinOptions): TransformArg<DataRecord>;
+export {};

package/dist/transforms/hexbin.js

@@ -0,0 +1,109 @@
+import { resolveChannel } from '../helpers/resolve.js';
+import { extent } from 'd3-array';
+import { reduceOutputs } from '../helpers/reduce.js';
+import { groupFacetsAndZ } from '../helpers/group.js';
+const sqrt3 = Math.sqrt(3);
+const CHANNELS = {
+    x: Symbol('hexbin_x'),
+    y: Symbol('hexbin_y')
+};
+/**
+ * Bins data points into hexagonal cells and applies reducers to produce
+ * aggregated output channels (e.g. fill="count", r="count").
+ *
+ * Usage:
+ * ```svelte
+ * <Dot {...hexbin(
+ *     { data: penguins, x: "culmen_length_mm", y: "culmen_depth_mm" },
+ *     { fill: "count", r: "count", bins: 15 }
+ * )} symbol="hexagon" />
+ * ```
+ */
+export function hexbin({ data, ...channels }, options = {}) {
+    const { bins = 20, binWidth: explicitBinWidth, ...reducerOptions } = options;
+    if (channels.x == null || channels.y == null) {
+        throw new Error('hexbin requires both x and y channels');
+    }
+    // Resolve x, y values from data
+    const xValues = data.map((d) => resolveChannel('x', d, channels));
+    const yValues = data.map((d) => resolveChannel('y', d, channels));
+    const [xMin, xMax] = extent(xValues);
+    const [yMin, yMax] = extent(yValues);
+    if (xMin == null || yMin == null) {
+        return { data: [], ...channels, x: CHANNELS.x, y: CHANNELS.y };
+    }
+    // Compute hex cell width in data units
+    const dx = explicitBinWidth ?? (xMax - xMin) / Math.max(1, bins);
+    // Vertical spacing between hex centers (pointy-topped hexagons)
+    const dy = (dx * 1.5) / sqrt3;
+    // Hex offset to avoid edge alignment
+    const ox = dx * 0.5;
+    const oy = 0;
+    // Bin data into hex cells
+    const binMap = new Map();
+    for (let i = 0; i < data.length; i++) {
+        const px = xValues[i];
+        const py = yValues[i];
+        if (px == null || py == null || isNaN(px) || isNaN(py))
+            continue;
+        // Convert to hex grid coordinates
+        let pj = Math.round((py - yMin - oy) / dy);
+        let pi = Math.round((px - xMin - ox - (pj & 1) * (dx / 2)) / dx);
+        // Snap to nearest hex center and check if an adjacent cell is closer
+        const cx0 = (pi + (pj & 1) / 2) * dx + ox + xMin;
+        const cy0 = pj * dy + oy + yMin;
+        // Check the two candidate rows
+        const pj1 = pj + 1;
+        const pi1 = Math.round((px - xMin - ox - (pj1 & 1) * (dx / 2)) / dx);
+        const cx1 = (pi1 + (pj1 & 1) / 2) * dx + ox + xMin;
+        const cy1 = pj1 * dy + oy + yMin;
+        const pj2 = pj - 1;
+        const pi2 = Math.round((px - xMin - ox - (pj2 & 1) * (dx / 2)) / dx);
+        const cx2 = (pi2 + (pj2 & 1) / 2) * dx + ox + xMin;
+        const cy2 = pj2 * dy + oy + yMin;
+        const d0 = (px - cx0) ** 2 + (py - cy0) ** 2;
+        const d1 = (px - cx1) ** 2 + (py - cy1) ** 2;
+        const d2 = (px - cx2) ** 2 + (py - cy2) ** 2;
+        if (d1 < d0 && d1 < d2) {
+            pj = pj1;
+            pi = pi1;
+        }
+        else if (d2 < d0 && d2 < d1) {
+            pj = pj2;
+            pi = pi2;
+        }
+        const key = `${pi},${pj}`;
+        let bin = binMap.get(key);
+        if (!bin) {
+            const cx = (pi + (pj & 1) / 2) * dx + ox + xMin;
+            const cy = pj * dy + oy + yMin;
+            bin = { index: [], cx, cy };
+            binMap.set(key, bin);
+        }
+        bin.index.push(i);
+    }
+    // Build output data from bins
+    const xChannel = typeof channels.x === 'string' ? channels.x : '__hexbin_x';
+    const yChannel = typeof channels.y === 'string' ? channels.y : '__hexbin_y';
+    let newChannels = {
+        ...channels,
+        x: xChannel,
+        y: yChannel
+    };
+    const outputs = ['fill', 'stroke', 'r', 'opacity', 'fillOpacity', 'strokeOpacity'];
+    const newData = [];
+    for (const [, bin] of binMap) {
+        const items = bin.index.map((i) => data[i]);
+        const newGroupChannels = groupFacetsAndZ(items, channels, (groupItems, groupProps) => {
+            const item = {
+                [xChannel]: bin.cx,
+                [yChannel]: bin.cy,
+                ...groupProps
+            };
+            reduceOutputs(item, groupItems, reducerOptions, outputs, channels, newChannels);
+            newData.push(item);
+        });
+        newChannels = { ...newChannels, ...newGroupChannels };
+    }
+    return { data: newData, ...newChannels };
+}

package/dist/transforms/index.d.ts

@@ -6,6 +6,7 @@ export { filter } from './filter.js';
 export { map, mapX, mapY } from './map.js';
 export { normalizeX, normalizeY, normalizeParallelX, normalizeParallelY } from './normalize.js';
 export { group, groupX, groupY, groupZ } from './group.js';
+export { hexbin } from './hexbin.js';
 export { intervalX, intervalY } from './interval.js';
 export { jitter, jitterX, jitterY } from './jitter.js';
 export { recordizeX, recordizeY } from './recordize.js';

package/dist/transforms/index.js

@@ -6,6 +6,7 @@ export { filter } from './filter.js';
 export { map, mapX, mapY } from './map.js';
 export { normalizeX, normalizeY, normalizeParallelX, normalizeParallelY } from './normalize.js';
 export { group, groupX, groupY, groupZ } from './group.js';
+export { hexbin } from './hexbin.js';
 export { intervalX, intervalY } from './interval.js';
 export { jitter, jitterX, jitterY } from './jitter.js';
 export { recordizeX, recordizeY } from './recordize.js';

package/dist/types/mark.d.ts

@@ -6,7 +6,7 @@ export type Mark<T> = {
     data: DataRecord<T>[];
     options: T;
 };
-export type MarkType = 'area' | 'arrow' | 'axisX' | 'axisY' | 'barX' | 'barY' | 'cell' | 'contour' | 'custom' | 'delaunayLink' | 'delaunayMesh' | 'density' | 'dot' | 'vector' | 'frame' | 'geo' | 'gridX' | 'gridY' | 'hull' | 'image' | 'link' | 'line' | 'raster' | 'rect' | 'regression' | 'ruleX' | 'ruleY' | 'swoopyArrow' | 'text' | 'tickX' | 'tickY' | 'trail' | 'voronoi' | 'voronoiMesh' | 'waffleX' | 'waffleY';
+export type MarkType = 'area' | 'arrow' | 'axisX' | 'axisY' | 'barX' | 'barY' | 'cell' | 'contour' | 'custom' | 'delaunayLink' | 'delaunayMesh' | 'density' | 'dot' | 'vector' | 'frame' | 'geo' | 'gridX' | 'gridY' | 'hexgrid' | 'hull' | 'image' | 'link' | 'line' | 'raster' | 'rect' | 'regression' | 'ruleX' | 'ruleY' | 'swoopyArrow' | 'text' | 'tickX' | 'tickY' | 'trail' | 'voronoi' | 'voronoiMesh' | 'waffleX' | 'waffleY';
 export type MarkStyleProps = 'strokeDasharray' | 'strokeLinejoin' | 'strokeLinecap' | 'opacity' | 'cursor' | 'pointerEvents' | 'blend' | 'fill' | 'fillOpacity' | 'fontFamily' | 'fontWeight' | 'fontVariant' | 'fontSize' | 'fontStyle' | 'letterSpacing' | 'wordSpacing' | 'stroke' | 'strokeWidth' | 'strokeOpacity' | 'x' | 'y' | 'clipPath' | 'mask' | 'filter' | 'angle' | 'radius' | 'symbol' | 'textAnchor' | 'textTransform' | 'textDecoration' | 'width';
 import type { ChannelAccessor, ConstantAccessor, DataRecord, RawValue } from './index.js';
 import type * as CSS from 'csstype';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "svelteplot",
-    "version": "0.14.2-pr-551.3",
+    "version": "0.14.2-pr-552.0",
     "description": "A Svelte-native data visualization framework based on the layered grammar of graphics principles.",
     "keywords": [
         "svelte",