svelteplot 0.14.2-pr-555.10 → 0.14.2-pr-552.2

package/dist/constants.js

@@ -120,7 +120,7 @@ export const CHANNEL_SCALE = {
     strokeOpacity: 'opacity'
 };
 export const CSS_VAR = /^var\(--([a-z-0-9,\s]+)\)$/;
-export const CSS_COLOR = /^(?:color|light-dark)\(/;
+export const CSS_COLOR = /^color\(/;
 export const CSS_COLOR_MIX = /^color-mix\(/; // just check for prefix
 export const CSS_COLOR_CONTRAST = /^color-contrast\(/; // just check for prefix
 export const CSS_RGBA = /^rgba\(/; // just check for prefix

package/dist/helpers/hexLattice.d.ts

@@ -0,0 +1,20 @@
+export declare const HEX_DEFAULT_BIN_WIDTH = 20;
+export type HexLattice = {
+    rx: number;
+    ry: number;
+    dx: number;
+    dy: number;
+    originX: number;
+    originY: number;
+};
+export declare function hexLattice(binWidth: number, originX?: number, originY?: number): HexLattice;
+export declare function hexLatticeXY(dx: number, dy: number, originX?: number, originY?: number): HexLattice;
+export declare function hexCenter(i: number, j: number, lattice: HexLattice): [number, number];
+export declare function pointToHex(px: number, py: number, lattice: HexLattice): {
+    i: number;
+    j: number;
+    cx: number;
+    cy: number;
+};
+export declare function hexagonSubpath(cx: number, cy: number, rx: number, ry: number): string;
+export declare function hexCellsInRect(lattice: HexLattice, x0: number, y0: number, x1: number, y1: number): Generator<[number, number]>;

package/dist/helpers/hexLattice.js

@@ -0,0 +1,73 @@
+// Shared hex lattice math used by the `hexbin` transform and the `Hexgrid`
+// mark so binning and the grid overlay always tile the same lattice. Pointy-
+// topped hexagons; odd rows are offset horizontally by rx. The lattice is
+// unit-agnostic — callers pass pitches in pixels (Hexgrid pixel mode) or in
+// data units (data-space mode).
+const SQRT3 = Math.sqrt(3);
+export const HEX_DEFAULT_BIN_WIDTH = 20;
+// Build a regular pointy-topped hex lattice from a single pitch. dy is the
+// canonical dx*√3/2 row pitch for tiling regular hexagons — used by Hexgrid
+// pixel mode and any caller working in a single coordinate system.
+export function hexLattice(binWidth, originX = 0, originY = 0) {
+    const rx = binWidth / 2;
+    const ry = (rx * 2) / SQRT3;
+    return { rx, ry, dx: binWidth, dy: ry * 1.5, originX, originY };
+}
+// Build a lattice with independent column and row pitches. Use this when the
+// x and y axes have different units (data-space hexbin), so each axis's pitch
+// can be scaled by its own data extent and still tile cleanly.
+export function hexLatticeXY(dx, dy, originX = 0, originY = 0) {
+    // ry is the vertical half-bounding-box; row pitch dy = 1.5 * ry, so ry = 2/3 dy.
+    return { rx: dx / 2, ry: (dy * 2) / 3, dx, dy, originX, originY };
+}
+export function hexCenter(i, j, lattice) {
+    const cx = lattice.originX + (i + (j & 1) / 2) * lattice.dx;
+    const cy = lattice.originY + j * lattice.dy;
+    return [cx, cy];
+}
+// Snaps a pixel point to the nearest hex cell. Must check the rounded row and
+// both neighbors because the row-offset lattice lets an adjacent row be closer
+// than the rounded one.
+export function pointToHex(px, py, lattice) {
+    const { dx, dy, originX, originY } = lattice;
+    const rx = dx / 2;
+    const pj = Math.round((py - originY) / dy) || 0;
+    let best = { i: 0, j: 0, cx: 0, cy: 0, d2: Infinity };
+    for (const dj of [0, 1, -1]) {
+        const cj = pj + dj;
+        const ci = Math.round((px - originX - (cj & 1) * rx) / dx) || 0;
+        const cx = originX + (ci + (cj & 1) / 2) * dx;
+        const cy = originY + cj * dy;
+        const d2 = (px - cx) ** 2 + (py - cy) ** 2;
+        if (d2 < best.d2)
+            best = { i: ci, j: cj, cx, cy, d2 };
+    }
+    return { i: best.i, j: best.j, cx: best.cx, cy: best.cy };
+}
+// SVG subpath for a single pointy-topped hex, rounded to compact the output.
+export function hexagonSubpath(cx, cy, rx, ry) {
+    const r3 = (n) => Math.round(n * 1000) / 1000;
+    return (`M${r3(cx)},${r3(cy - ry)}` +
+        `l${r3(rx)},${r3(ry / 2)}` +
+        `v${r3(ry)}` +
+        `l${r3(-rx)},${r3(ry / 2)}` +
+        `l${r3(-rx)},${r3(-ry / 2)}` +
+        `v${r3(-ry)}Z`);
+}
+// Iterate hex cell centers covering the given pixel rect. Pads by one cell so
+// a clipPath can trim the edges cleanly without gaps.
+export function* hexCellsInRect(lattice, x0, y0, x1, y1) {
+    const { dx, dy, originX, originY, rx, ry } = lattice;
+    const jMin = Math.floor((y0 - originY - ry) / dy);
+    const jMax = Math.ceil((y1 - originY + ry) / dy);
+    for (let j = jMin; j <= jMax; j++) {
+        const xOffset = (j & 1) * (dx / 2);
+        const iMin = Math.floor((x0 - originX - xOffset - rx) / dx);
+        const iMax = Math.ceil((x1 - originX - xOffset + rx) / dx);
+        for (let i = iMin; i <= iMax; i++) {
+            const cx = originX + (i + (j & 1) / 2) * dx;
+            const cy = originY + j * dy;
+            yield [cx, cy];
+        }
+    }
+}

package/dist/marks/Hexbin.svelte

@@ -0,0 +1,374 @@
+<!-- @component
+    Renders a hexagonal binning of 2D scatter data: groups raw points into a
+    pixel-space hex lattice, runs a reducer per bin, and draws each non-empty
+    bin as a regular hexagonal cell. Cells are regular by construction because
+    the lattice is computed in pixel space (after scales exist) rather than in
+    data space, so they tile correctly under any axis aspect ratio.
+
+    Pairs naturally with the data-less `<Hexgrid />` mark for an empty-cell
+    backdrop — both default to `binWidth=20` (px), so a default `<Hexbin>` and
+    a default `<Hexgrid>` align by convention without user coordination.
+
+    The `fill` prop accepts a reducer name (`'count'`, `'mean'`, etc.) to map
+    aggregated values through the plot's color scale, or a CSS color for a
+    constant fill. Same shape for `stroke`.
+-->
+<script lang="ts" generics="Datum extends DataRecord">
+    interface HexbinMarkProps {
+        /** Input data — array of records with x/y positions. */
+        data?: Datum[] | null;
+        /** x position channel (data space). */
+        x?: ChannelAccessor<Datum>;
+        /** y position channel (data space). */
+        y?: ChannelAccessor<Datum>;
+        /** horizontal facet channel — bins are computed independently per facet. */
+        fx?: ChannelAccessor<Datum>;
+        /** vertical facet channel — bins are computed independently per facet. */
+        fy?: ChannelAccessor<Datum>;
+        /**
+         * Hex cell pitch in pixels (distance between adjacent cell centers
+         * along x). Default 20, matching `<Hexgrid />`.
+         */
+        binWidth?: number;
+        /**
+         * Fill: a reducer name (`'count'`, `'mean'`, …) to map aggregated
+         * values through the color scale, OR a CSS color for a constant fill.
+         * Default `'count'` (maps bin counts through the color scale).
+         */
+        fill?: ReducerName | string;
+        /** Stroke: same shape as `fill`. Default `'none'`. */
+        stroke?: ReducerName | string;
+        strokeWidth?: number;
+        fillOpacity?: number;
+        strokeOpacity?: number;
+        opacity?: number;
+        clipPath?: string;
+        class?: string;
+    }
+
+    import Mark from '../Mark.svelte';
+    import { usePlot } from '../hooks/usePlot.svelte.js';
+    import { getPlotDefaults } from '../hooks/plotDefaults.js';
+    import { reduceOutputs, type ReducerName } from '../helpers/reduce.js';
+    import { resolveProp } from '../helpers/resolve.js';
+    import { isColorOrNull } from '../helpers/typeChecks.js';
+    import {
+        hexLattice,
+        pointToHex,
+        hexagonSubpath,
+        HEX_DEFAULT_BIN_WIDTH
+    } from '../helpers/hexLattice.js';
+    import type {
+        ChannelAccessor,
+        DataRecord,
+        MarkType,
+        ScaledDataRecord
+    } from '../types/index.js';
+
+    // Per-record symbols for the synthetic data passed to <Mark>. Density
+    // uses the same pattern (Density.svelte:108-115) — the scale system reads
+    // channel values via Symbol-keyed accessors, so user data fields can't
+    // collide with our internal channels. Hexbin uses x/y point channels
+    // (not Density's x1/x2/y1/y2 range channels) because a bin IS a point;
+    // CHANNEL_SCALE maps both to the same x/y scale (see constants.ts:110).
+    const GEOM = Symbol('hexbin_geom');
+    const X_VAL = Symbol('hexbin_x');
+    const Y_VAL = Symbol('hexbin_y');
+    const FILL_VAL = Symbol('hexbin_fill');
+    const STROKE_VAL = Symbol('hexbin_stroke');
+    const FX_VAL = Symbol('hexbin_fx');
+    const FY_VAL = Symbol('hexbin_fy');
+
+    const DEFAULTS = {
+        ...getPlotDefaults().hexbin
+    };
+
+    let markProps: HexbinMarkProps = $props();
+
+    const {
+        data,
+        x: xAcc,
+        y: yAcc,
+        fx: fxAcc,
+        fy: fyAcc,
+        binWidth = HEX_DEFAULT_BIN_WIDTH,
+        fill: rawFill = 'count',
+        stroke: rawStroke = 'none',
+        strokeWidth,
+        fillOpacity,
+        strokeOpacity,
+        opacity,
+        clipPath,
+        class: className = 'hexbin',
+        ...options
+    }: HexbinMarkProps = $derived({ ...DEFAULTS, ...markProps });
+
+    const plot = usePlot();
+
+    // A fill/stroke value is a reducer when it's a function or a string that
+    // looks like a reducer name rather than a CSS color. Mirrors Density's
+    // isDensityAccessor logic (Density.svelte:159-175).
+    function isReducer(v: unknown): boolean {
+        if (typeof v === 'function') return true;
+        if (typeof v !== 'string') return false;
+        const lower = v.toLowerCase();
+        if (lower === 'none' || lower === 'inherit' || lower === 'currentcolor') return false;
+        return !isColorOrNull(v);
+    }
+
+    const fillIsReducer = $derived(isReducer(rawFill));
+    const strokeIsReducer = $derived(isReducer(rawStroke));
+
+    // Raw data extent in data units, used to bootstrap x/y scale domains
+    // before bins are computed (the chicken-and-egg: bins need pixel-space
+    // scales, scales need a domain). Same approach as Density.svelte:385-426.
+    const extent = $derived.by(() => {
+        if (!data?.length || xAcc == null || yAcc == null) return null;
+        let xMin = Infinity,
+            xMax = -Infinity,
+            yMin = Infinity,
+            yMax = -Infinity;
+        for (const d of data as any[]) {
+            const xv = resolveProp(xAcc as any, d);
+            const yv = resolveProp(yAcc as any, d);
+            if (typeof xv === 'number' && Number.isFinite(xv)) {
+                if (xv < xMin) xMin = xv;
+                if (xv > xMax) xMax = xv;
+            }
+            if (typeof yv === 'number' && Number.isFinite(yv)) {
+                if (yv < yMin) yMin = yv;
+                if (yv > yMax) yMax = yv;
+            }
+        }
+        if (!isFinite(xMin) || !isFinite(yMin)) return null;
+        return { x1: xMin, x2: xMax, y1: yMin, y2: yMax };
+    });
+
+    // Pixel-space binning. Builds a regular hex lattice from binWidth (px),
+    // projects each raw point through the live x/y scales to pixel space,
+    // and snaps to the nearest hex center via pointToHex. Returns null on
+    // the bootstrap pass (before scales are computable).
+    //
+    // Faceting: when fx/fy accessors are provided, raw records are partitioned
+    // by (fxVal, fyVal) before binning so each facet panel gets independent
+    // bin counts. The lattice itself stays single-source — Mark.svelte applies
+    // the per-facet group transform at render time, and pointToHex outputs in
+    // plot-global pixel space (same as scales.x/y.fn). Mirrors Density's
+    // group-by-facet pattern (Density.svelte:272-286).
+    type Bin = {
+        i: number;
+        j: number;
+        cx: number;
+        cy: number;
+        items: any[];
+        fxVal: any;
+        fyVal: any;
+    };
+    const binResult = $derived.by(() => {
+        if (!data?.length || xAcc == null || yAcc == null) return null;
+        const sx = plot.scales.x?.fn as ((v: any) => number) | undefined;
+        const sy = plot.scales.y?.fn as ((v: any) => number) | undefined;
+        if (!sx || !sy) return null;
+
+        const ml = plot.options.marginLeft ?? 0;
+        const mt = plot.options.marginTop ?? 0;
+        // Origin matches Hexgrid (Hexgrid.svelte:53) and the existing hexbin
+        // transform (transforms/hexbin.ts:85) so a default Hexbin and a default
+        // Hexgrid tile the same lattice without coordination. Cell (0,0)
+        // straddles the top-left corner — symmetric with the X half-pitch
+        // offset, which puts the cell half-inside the left edge.
+        const lattice = hexLattice(binWidth, ml + binWidth / 2, mt);
+
+        // Two-level map: (fxVal, fyVal) → (i, j) → bin. Single outer entry
+        // when not faceted.
+        const groups = new Map<string, Map<string, Bin>>();
+        const facetKeys: { key: string; fxVal: any; fyVal: any }[] = [];
+        for (const d of data as any[]) {
+            const xv = resolveProp(xAcc as any, d);
+            const yv = resolveProp(yAcc as any, d);
+            const px = sx(xv);
+            const py = sy(yv);
+            if (!Number.isFinite(px) || !Number.isFinite(py)) continue;
+            const fxVal = fxAcc != null ? resolveProp(fxAcc as any, d) : undefined;
+            const fyVal = fyAcc != null ? resolveProp(fyAcc as any, d) : undefined;
+            const groupKey = `${String(fxVal)}\0${String(fyVal)}`;
+            let group = groups.get(groupKey);
+            if (!group) {
+                group = new Map();
+                groups.set(groupKey, group);
+                facetKeys.push({ key: groupKey, fxVal, fyVal });
+            }
+            const { i, j, cx, cy } = pointToHex(px, py, lattice);
+            const binKey = `${i},${j}`;
+            let bin = group.get(binKey);
+            if (!bin) {
+                bin = { i, j, cx, cy, items: [], fxVal, fyVal };
+                group.set(binKey, bin);
+            }
+            bin.items.push(d);
+        }
+        const bins: Bin[] = [];
+        for (const g of groups.values()) for (const bin of g.values()) bins.push(bin);
+        return { lattice, bins, facetKeys };
+    });
+
+    // Synthetic records for <Mark>. Bootstrap pass emits corner records so
+    // x/y scales compute a domain before bins exist; result pass emits the
+    // persistent corner records plus one per bin carrying:
+    //   X_VAL / Y_VAL  raw data extent → x/y scale domain (one value per record;
+    //                  two records together span the extent)
+    //   FILL_VAL       reducer output  → color scale domain (when fill is a reducer)
+    //   STROKE_VAL     reducer output  → color scale domain (when stroke is a reducer)
+    //   FX_VAL / FY_VAL facet values   → Mark facet filtering (when faceted)
+    //   GEOM           pixel-space hex geometry → rendered by children snippet
+    //
+    // When faceted, we emit one corner-pair per unique (fxVal, fyVal) so no
+    // record carries an undefined facet value (which would create a spurious
+    // null facet panel). Mirrors Density.svelte:441-497.
+    const markData = $derived.by((): DataRecord[] => {
+        const ext = extent;
+        const br = binResult;
+        const isFaceted = fxAcc != null || fyAcc != null;
+        if (!ext) return [];
+
+        // Build the list of (fxVal, fyVal) pairs the corner records should be
+        // emitted for. binResult.facetKeys is the authoritative list once
+        // binning has happened; on the bootstrap pass we walk data ourselves
+        // since binResult is null.
+        type FK = { fxVal: any; fyVal: any };
+        let facetKeys: FK[];
+        if (br) {
+            facetKeys = br.facetKeys.map(({ fxVal, fyVal }) => ({ fxVal, fyVal }));
+            if (facetKeys.length === 0) facetKeys = [{ fxVal: undefined, fyVal: undefined }];
+        } else if (isFaceted && data?.length) {
+            const seen = new Set<string>();
+            facetKeys = [];
+            for (const d of data as any[]) {
+                const fxVal = fxAcc != null ? resolveProp(fxAcc as any, d) : undefined;
+                const fyVal = fyAcc != null ? resolveProp(fyAcc as any, d) : undefined;
+                const key = `${String(fxVal)}\0${String(fyVal)}`;
+                if (!seen.has(key)) {
+                    seen.add(key);
+                    facetKeys.push({ fxVal, fyVal });
+                }
+            }
+        } else {
+            facetKeys = [{ fxVal: undefined, fyVal: undefined }];
+        }
+
+        const records: any[] = [];
+        // Persistent corner records (one pair per facet) keep x/y scale domains
+        // anchored at [x1,x2]/[y1,y2] across re-derivations and ensure each
+        // facet panel registers a domain even when no data lands in some bin.
+        for (const { fxVal, fyVal } of facetKeys) {
+            const c1: any = { [X_VAL]: ext.x1, [Y_VAL]: ext.y1 };
+            const c2: any = { [X_VAL]: ext.x2, [Y_VAL]: ext.y2 };
+            if (isFaceted) {
+                if (fxAcc != null) {
+                    c1[FX_VAL] = fxVal;
+                    c2[FX_VAL] = fxVal;
+                }
+                if (fyAcc != null) {
+                    c1[FY_VAL] = fyVal;
+                    c2[FY_VAL] = fyVal;
+                }
+            }
+            records.push(c1, c2);
+        }
+
+        if (!br) return records;
+
+        const reducerOpts: any = {};
+        const outputs: string[] = [];
+        if (fillIsReducer) {
+            reducerOpts.fill = rawFill;
+            outputs.push('fill');
+        }
+        if (strokeIsReducer) {
+            reducerOpts.stroke = rawStroke;
+            outputs.push('stroke');
+        }
+
+        for (const bin of br.bins) {
+            const item: any = {
+                // Channel values irrelevant for rendering (GEOM drives that),
+                // but must be inside the extent so they don't expand the domain.
+                [X_VAL]: ext.x1,
+                [Y_VAL]: ext.y1,
+                [GEOM]: {
+                    cx: bin.cx,
+                    cy: bin.cy,
+                    rx: br.lattice.rx,
+                    ry: br.lattice.ry
+                }
+            };
+            if (isFaceted) {
+                if (fxAcc != null) item[FX_VAL] = bin.fxVal;
+                if (fyAcc != null) item[FY_VAL] = bin.fyVal;
+            }
+
+            // reduceOutputs writes item.__fill = countValue etc. (note the
+            // `__` prefix — see reduce.ts:113); copy onto Symbol keys so the
+            // channel accessors below resolve them and user-data field names
+            // can't collide.
+            if (outputs.length > 0) {
+                reduceOutputs(
+                    item,
+                    bin.items,
+                    reducerOpts,
+                    outputs as any,
+                    { x: xAcc, y: yAcc } as any,
+                    {} as any
+                );
+                if (fillIsReducer) item[FILL_VAL] = item['__fill'];
+                if (strokeIsReducer) item[STROKE_VAL] = item['__stroke'];
+            }
+
+            records.push(item);
+        }
+        return records;
+    });
+
+    const markChannels = $derived([
+        'x',
+        'y',
+        ...(fillIsReducer ? ['fill'] : []),
+        ...(strokeIsReducer ? ['stroke'] : []),
+        ...(fxAcc != null ? ['fx'] : []),
+        ...(fyAcc != null ? ['fy'] : [])
+    ] as const);
+
+    const markChannelProps = $derived({
+        x: X_VAL as any,
+        y: Y_VAL as any,
+        ...(fillIsReducer ? { fill: FILL_VAL as any } : {}),
+        ...(strokeIsReducer ? { stroke: STROKE_VAL as any } : {}),
+        ...(fxAcc != null ? { fx: FX_VAL as any } : {}),
+        ...(fyAcc != null ? { fy: FY_VAL as any } : {})
+    });
+</script>
+
+<Mark
+    type={'hexbin' as MarkType}
+    data={markData}
+    channels={markChannels as any}
+    {...options}
+    {...markChannelProps}>
+    {#snippet children({ scaledData }: { scaledData: ScaledDataRecord[] })}
+        <g class={className} clip-path={clipPath}>
+            {#each scaledData as d, i (i)}
+                {@const geom = (d.datum as any)?.[GEOM]}
+                {#if geom}
+                    <path
+                        d={hexagonSubpath(geom.cx, geom.cy, geom.rx, geom.ry)}
+                        fill={fillIsReducer ? ((d as any).fill ?? 'currentColor') : rawFill}
+                        stroke={strokeIsReducer ? ((d as any).stroke ?? 'none') : rawStroke}
+                        stroke-width={strokeWidth}
+                        fill-opacity={fillOpacity}
+                        stroke-opacity={strokeOpacity}
+                        {opacity} />
+                {/if}
+            {/each}
+        </g>
+    {/snippet}
+</Mark>

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

@@ -0,0 +1,71 @@
+import { type ReducerName } from '../helpers/reduce.js';
+import type { ChannelAccessor, DataRecord } from '../types/index.js';
+declare function $$render<Datum extends DataRecord>(): {
+    props: {
+        /** Input data — array of records with x/y positions. */
+        data?: Datum[] | null;
+        /** x position channel (data space). */
+        x?: ChannelAccessor<Datum>;
+        /** y position channel (data space). */
+        y?: ChannelAccessor<Datum>;
+        /** horizontal facet channel — bins are computed independently per facet. */
+        fx?: ChannelAccessor<Datum>;
+        /** vertical facet channel — bins are computed independently per facet. */
+        fy?: ChannelAccessor<Datum>;
+        /**
+         * Hex cell pitch in pixels (distance between adjacent cell centers
+         * along x). Default 20, matching `<Hexgrid />`.
+         */
+        binWidth?: number;
+        /**
+         * Fill: a reducer name (`'count'`, `'mean'`, …) to map aggregated
+         * values through the color scale, OR a CSS color for a constant fill.
+         * Default `'count'` (maps bin counts through the color scale).
+         */
+        fill?: ReducerName | string;
+        /** Stroke: same shape as `fill`. Default `'none'`. */
+        stroke?: ReducerName | string;
+        strokeWidth?: number;
+        fillOpacity?: number;
+        strokeOpacity?: number;
+        opacity?: number;
+        clipPath?: string;
+        class?: string;
+    };
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<Datum extends DataRecord> {
+    props(): ReturnType<typeof $$render<Datum>>['props'];
+    events(): ReturnType<typeof $$render<Datum>>['events'];
+    slots(): ReturnType<typeof $$render<Datum>>['slots'];
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <Datum extends DataRecord>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<Datum>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<Datum>['props']>, ReturnType<__sveltets_Render<Datum>['events']>, ReturnType<__sveltets_Render<Datum>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<Datum>['bindings']>;
+    } & ReturnType<__sveltets_Render<Datum>['exports']>;
+    <Datum extends DataRecord>(internal: unknown, props: ReturnType<__sveltets_Render<Datum>['props']> & {}): ReturnType<__sveltets_Render<Datum>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+/**
+ * Renders a hexagonal binning of 2D scatter data: groups raw points into a
+ * pixel-space hex lattice, runs a reducer per bin, and draws each non-empty
+ * bin as a regular hexagonal cell. Cells are regular by construction because
+ * the lattice is computed in pixel space (after scales exist) rather than in
+ * data space, so they tile correctly under any axis aspect ratio.
+ *
+ * Pairs naturally with the data-less `<Hexgrid />` mark for an empty-cell
+ * backdrop — both default to `binWidth=20` (px), so a default `<Hexbin>` and
+ * a default `<Hexgrid>` align by convention without user coordination.
+ *
+ * The `fill` prop accepts a reducer name (`'count'`, `'mean'`, etc.) to map
+ * aggregated values through the plot's color scale, or a CSS color for a
+ * constant fill. Same shape for `stroke`.
+ */
+declare const Hexbin: $$IsomorphicComponent;
+type Hexbin<Datum extends DataRecord> = InstanceType<typeof Hexbin<Datum>>;
+export default Hexbin;

package/dist/marks/Hexgrid.svelte

@@ -0,0 +1,72 @@
+<!-- @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';
+    import {
+        hexLattice,
+        hexCellsInRect,
+        hexagonSubpath,
+        HEX_DEFAULT_BIN_WIDTH
+    } from '../helpers/hexLattice.js';
+
+    let markProps: HexgridMarkProps = $props();
+
+    const {
+        binWidth = HEX_DEFAULT_BIN_WIDTH,
+        stroke = 'currentColor',
+        strokeOpacity = 0.1,
+        strokeWidth = 1,
+        fill = 'none',
+        fillOpacity,
+        class: className = 'hexgrid'
+    }: HexgridMarkProps = $derived({ ...markProps });
+
+    const plot = usePlot();
+
+    const pathData = $derived.by(() => {
+        const ml = plot.options.marginLeft;
+        const mt = plot.options.marginTop;
+        const w = plot.facetWidth;
+        const h = plot.facetHeight;
+
+        const lattice = hexLattice(binWidth, ml + binWidth / 2, mt);
+        let path = '';
+        for (const [cx, cy] of hexCellsInRect(lattice, ml, mt, ml + w, mt + h)) {
+            path += hexagonSubpath(cx, cy, lattice.rx, lattice.ry);
+        }
+        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,8 @@ 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 Hexbin } from './Hexbin.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,8 @@ 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 Hexbin } from './Hexbin.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,81 @@
+import { resolveChannel } from '../helpers/resolve.js';
+import { extent } from 'd3-array';
+import { reduceOutputs } from '../helpers/reduce.js';
+import { groupFacetsAndZ } from '../helpers/group.js';
+import { hexLattice, pointToHex } from '../helpers/hexLattice.js';
+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 };
+    }
+    // Cell pitch in data units. Pointy-topped hex with regular geometry — dy
+    // derived from dx, so dy is in the same data units as dx. Cells are visually
+    // regular only when the data units happen to match across axes; for
+    // pixel-correct cells under arbitrary data extents, use the <Hexbin> mark
+    // instead, which builds its lattice in pixel space after scales exist.
+    const dx = explicitBinWidth ?? (xMax - xMin) / Math.max(1, bins);
+    const lattice = hexLattice(dx, xMin + dx / 2, yMin);
+    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;
+        const { i: pi, j: pj, cx, cy } = pointToHex(px, py, lattice);
+        const key = `${pi},${pj}`;
+        let bin = binMap.get(key);
+        if (!bin) {
+            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' | 'hexbin' | '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/dist/types/plot.d.ts

@@ -5,7 +5,7 @@ import type { ChannelAccessor, ChannelName, ColorScaleOptions, DataRecord, Legen
 import type { Snippet } from 'svelte';
 import type { GenericMarkOptions, Mark } from './index.js';
 import type { Clip } from '../helpers/projection.js';
-import type { Area, AreaX, AreaY, Arrow, AxisX, AxisY, BarX, BarY, BoxX, BoxY, Brush, BrushX, BrushY, Cell, Contour, DelaunayLink, DelaunayMesh, Density, DifferenceY, Dot, Frame, Geo, Graticule, GridX, GridY, Hull, Image, Line, Link, Pointer, Raster, Rect, RectX, RectY, RuleX, RuleY, Sphere, Spike, Text, TickX, TickY, Trail, Vector, Voronoi, VoronoiMesh } from '../marks/index.js';
+import type { Area, AreaX, AreaY, Arrow, AxisX, AxisY, BarX, BarY, BoxX, BoxY, Brush, BrushX, BrushY, Cell, Contour, DelaunayLink, DelaunayMesh, Density, DifferenceY, Dot, Frame, Geo, Graticule, GridX, GridY, Hexbin, Hull, Image, Line, Link, Pointer, Raster, Rect, RectX, RectY, RuleX, RuleY, Sphere, Spike, Text, TickX, TickY, Trail, Vector, Voronoi, VoronoiMesh } from '../marks/index.js';
 import type WaffleX from '../marks/WaffleX.svelte';
 import type WaffleY from '../marks/WaffleY.svelte';
 import type BaseAxisX from '../marks/helpers/BaseAxisX.svelte';
@@ -260,6 +260,10 @@ export type PlotDefaults = {
     gridY: Partial<Omit<ComponentProps<typeof GridY>, IgnoreDefaults> & {
         implicit: boolean;
     }> | true;
+    /**
+     * default props for hexbin marks
+     */
+    hexbin: Partial<Omit<ComponentProps<typeof Hexbin>, IgnoreDefaults>>;
     /**
      * default props for hull marks
      */

package/package.json

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