@svgrid/grid 2.6.20 → 2.6.22

package/dist/chart.d.ts

@@ -34,8 +34,7 @@ export type SeriesOverlay = 'linear' | `sma:${number}` | `ema:${number}`;
 /** A texture fill applied in addition to (and on top of) the series color.
  *  Helps colorblind readers distinguish series at a glance. */
 export type SeriesPattern = 'solid' | 'stripe' | 'crosshatch' | 'dots' | 'diagonal';
-/** Cycle used when `ChartSpec.patternFallback` is true and a series has no
- *  explicit `pattern` set. Skips `'solid'` so every series gets a texture. */
+/** One plotted series: its label, its values (one per category), and how to draw it. */
 export type ChartSeries = {
     label: string;
     values: number[];
@@ -93,6 +92,12 @@ export type ChartReferenceLine = {
     color?: string;
     dashed?: boolean;
 };
+/**
+ * What to plot - the input you build and hand to a chart. Categories are the
+ * x-axis labels and every series supplies one value per category.
+ *
+ * {@link buildChart} turns this into a {@link ChartGeometry} for rendering.
+ */
 export type ChartSpec = {
     /** Default type for series that don't set their own `type`. */
     type: ChartType;
@@ -362,6 +367,7 @@ export type ChartHeatmapCell = {
     rowLabel: string;
     colLabel: string;
 };
+/** A computed bar rectangle in SVG coordinates. Output of {@link buildChart}, not an input. */
 export type ChartBar = {
     x: number;
     y: number;
@@ -374,6 +380,7 @@ export type ChartBar = {
     series: string;
     value: number;
 };
+/** One computed point on a line, with whether the series has a value there. */
 export type ChartLinePoint = {
     x: number;
     y: number;
@@ -382,6 +389,7 @@ export type ChartLinePoint = {
     /** False for null / NaN values - the line breaks (gap), no dot is drawn. */
     defined: boolean;
 };
+/** A computed line series: its points and the path drawn through them. */
 export type ChartLine = {
     path: string;
     areaPath: string;
@@ -392,6 +400,7 @@ export type ChartLine = {
      *  series, when both arrays are supplied. Empty otherwise. */
     bandPath?: string;
 };
+/** A computed pie slice, as an SVG arc plus its label placement. */
 export type ChartPieSlice = {
     path: string;
     color: string;
@@ -402,19 +411,23 @@ export type ChartPieSlice = {
     cx: number;
     cy: number;
 };
+/** A value-axis tick: the number, where it sits vertically, and its label. */
 export type ChartAxisTick = {
     value: number;
     y: number;
     label: string;
 };
+/** A category-axis tick: the label and its horizontal position. */
 export type ChartCategoryTick = {
     label: string;
     x: number;
 };
+/** One legend entry, paired with the series colour it stands for. */
 export type ChartLegendItem = {
     label: string;
     color: string;
 };
+/** A computed reference line (target, average, threshold) at its plotted height. */
 export type ChartRefLineGeo = {
     y: number;
     label: string;
@@ -428,6 +441,7 @@ export type ChartRefLineGeoV = {
     color: string;
     dashed: boolean;
 };
+/** A computed scatter point in SVG coordinates. */
 export type ChartScatterDot = {
     cx: number;
     cy: number;
@@ -438,6 +452,11 @@ export type ChartScatterDot = {
     x: number;
     y: number;
 };
+/**
+ * Everything needed to render a chart: the plot rectangle plus every mark
+ * already positioned in SVG coordinates. Produced by {@link buildChart} from a
+ * {@link ChartSpec}, so a renderer does no maths of its own.
+ */
 export type ChartGeometry = {
     type: ChartType;
     width: number;
@@ -542,7 +561,9 @@ export type ChartGeometry = {
     /** Sankey links (type === 'sankey'). */
     sankeyLinks: ChartSankeyLink[];
 };
+/** Series colours used when a {@link ChartSeries} sets none, in order. */
 export declare const DEFAULT_PALETTE: string[];
+/** An axis range rounded to human-friendly bounds and tick spacing. */
 export type NiceScale = {
     min: number;
     max: number;
@@ -559,9 +580,6 @@ export declare function pickContrastText(bgHex: string): string;
  *  the smallest that covers the top, then enumerate decade boundaries. Used
  *  by log-scale axes (yScale: 'log'). */
 export declare function niceLogScale(min: number, max: number): NiceScale;
-/** Ordinary least-squares regression on (i, values[i]) pairs (i = x index).
- *  Returns the fitted value at each x index, or NaN where the source value
- *  was non-finite. */
 /** Build an SVG path from a list of (x,y) pairs, optionally smoothed via
  *  monotone cubic interpolation (preserves local extrema - no overshoots).
  *  Breaks the path at `defined === false` gaps. */
@@ -570,6 +588,9 @@ export declare function buildLinePath(pts: Array<{
     y: number;
     defined: boolean;
 }>, smooth: boolean): string;
+/** Ordinary least-squares regression on (i, values[i]) pairs (i = x index).
+ *  Returns the fitted value at each x index, or NaN where the source value
+ *  was non-finite. */
 export declare function linearTrend(values: number[]): number[];
 /** Simple moving average over a window of `period` values. Window centres
  *  trail to the right (typical for time-series). NaN for points before the
@@ -590,6 +611,11 @@ export type ChartValueFormat = 'number' | 'currency' | 'percent' | 'compact';
  * `'compact'` = the plain compact form.
  */
 export declare function formatChartValue(n: number, format?: ChartValueFormat): string;
+/**
+ * Lay out a {@link ChartSpec} into renderable {@link ChartGeometry} - scales,
+ * ticks, and the position of every bar, line, slice and dot. Pure: no DOM, so
+ * it runs during SSR and can be unit-tested directly.
+ */
 export declare function buildChart(spec: ChartSpec, theme?: 'light' | 'dark'): ChartGeometry;
 /**
  * Aggregate flat rows into a chart spec. Group by a category field, reduce a

package/dist/chart.js

@@ -1,3 +1,4 @@
+/** Series colours used when a {@link ChartSeries} sets none, in order. */
 export const DEFAULT_PALETTE = [
     '#2563eb',
     '#16a34a',
@@ -112,9 +113,6 @@ function project(value, min, max, isLog) {
     return (value - min) / (max - min);
 }
 // ---- Overlay math: trendline + moving averages -----------------------
-/** Ordinary least-squares regression on (i, values[i]) pairs (i = x index).
- *  Returns the fitted value at each x index, or NaN where the source value
- *  was non-finite. */
 /** Build an SVG path from a list of (x,y) pairs, optionally smoothed via
  *  monotone cubic interpolation (preserves local extrema - no overshoots).
  *  Breaks the path at `defined === false` gaps. */
@@ -205,6 +203,9 @@ function monotoneCubicPath(pts) {
     }
     return path;
 }
+/** Ordinary least-squares regression on (i, values[i]) pairs (i = x index).
+ *  Returns the fitted value at each x index, or NaN where the source value
+ *  was non-finite. */
 export function linearTrend(values) {
     let n = 0, sumX = 0, sumY = 0, sumXX = 0, sumXY = 0;
     for (let i = 0; i < values.length; i += 1) {
@@ -403,6 +404,11 @@ function axisDomain(list, categories, stacked, extra = [], isLog = false) {
     }
     return isLog ? niceLogScale(dMin, dMax) : niceScale(dMin, dMax);
 }
+/**
+ * Lay out a {@link ChartSpec} into renderable {@link ChartGeometry} - scales,
+ * ticks, and the position of every bar, line, slice and dot. Pure: no DOM, so
+ * it runs during SSR and can be unit-tested directly.
+ */
 export function buildChart(spec, theme = 'light') {
     const width = spec.width ?? 520;
     const height = spec.height ?? 300;

package/dist/column-groups.js

@@ -1,4 +1,4 @@
-// Collapsible column groups (AG-Grid `columnGroupShow`). A column group can
+// Collapsible column groups (a per-column `columnGroupShow` flag). A column group can
 // carry a collapse toggle: its child columns tagged `columnGroupShow: 'open'`
 // show only when the group is expanded, `'closed'` show only when collapsed,
 // and untagged children always show.

package/dist/column-resize.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Column-resize Svelte action - drag a header's right edge to widen / narrow
+ * the column. Counterpart of `rowResize`, and built the same way for the same
+ * reason: `<SvGrid columnResize>` is opt-in, so the code behind it must not sit
+ * in the base bundle of every grid that leaves it off. The grid pulls this
+ * module through `import()` the first time a consumer turns the prop on.
+ *
+ * Handles are injected rather than rendered, so nothing about them compiles
+ * into `SvGrid.svelte`. A header cell is keyed by `data-svgrid-header-col` -
+ * body cells use `data-col-id`, which is a different attribute on purpose, and
+ * matching the wrong one finds nothing. One handle goes into every such `th`
+ * under `node`, and a MutationObserver keeps up with virtualized columns
+ * scrolling in and out.
+ *
+ *   <div use:columnResize={{ getWidth, onResize }}>
+ *     <SvGrid ... />
+ *   </div>
+ *
+ * Visual: a 5px strip on the header's right edge with an accent centre pill,
+ * from SvGrid.css. Cursor is `col-resize`.
+ */
+export type ColumnResizeOptions = {
+    /** Current width of a column, in px. Read when a drag starts. */
+    getWidth: (columnId: string) => number;
+    /** Called on every animation frame of the drag, and once at the end. */
+    onResize: (columnId: string, width: number) => void;
+    /** Accessible name for the handle. Defaults to the column id. */
+    label?: (columnId: string) => string;
+    /**
+     * Per-column opt-out, backing `ColumnDef.resizable`. Returning false means no
+     * handle is created for that column at all - which is what makes the drag,
+     * the arrow keys and the double-click autosize go away together, rather than
+     * each needing its own guard.
+     */
+    canResize?: (columnId: string) => boolean;
+    /** Size the column to its content. Bound to a double-click on the handle. */
+    onAutosize?: (columnId: string) => void;
+    /** Minimum width in px. Default 40. */
+    min?: number;
+    /** When true, the action removes its handles and ignores events. */
+    disabled?: boolean;
+};
+export declare function columnResize(node: HTMLElement, opts: ColumnResizeOptions): {
+    update(next: ColumnResizeOptions): void;
+    destroy(): void;
+};

package/dist/column-resize.js

@@ -0,0 +1,205 @@
+/**
+ * Column-resize Svelte action - drag a header's right edge to widen / narrow
+ * the column. Counterpart of `rowResize`, and built the same way for the same
+ * reason: `<SvGrid columnResize>` is opt-in, so the code behind it must not sit
+ * in the base bundle of every grid that leaves it off. The grid pulls this
+ * module through `import()` the first time a consumer turns the prop on.
+ *
+ * Handles are injected rather than rendered, so nothing about them compiles
+ * into `SvGrid.svelte`. A header cell is keyed by `data-svgrid-header-col` -
+ * body cells use `data-col-id`, which is a different attribute on purpose, and
+ * matching the wrong one finds nothing. One handle goes into every such `th`
+ * under `node`, and a MutationObserver keeps up with virtualized columns
+ * scrolling in and out.
+ *
+ *   <div use:columnResize={{ getWidth, onResize }}>
+ *     <SvGrid ... />
+ *   </div>
+ *
+ * Visual: a 5px strip on the header's right edge with an accent centre pill,
+ * from SvGrid.css. Cursor is `col-resize`.
+ */
+const HANDLE_CLASS = 'sv-grid-resize-handle';
+export function columnResize(node, opts) {
+    let current = opts;
+    let drag = null;
+    // Coalesce onto the animation frame: pointermove fires many times per frame
+    // and each width write triggers a full recompute of the column-layout
+    // pipeline. Without this the grid stutters for the whole drag.
+    let raf = null;
+    let pendingWidth = 0;
+    const minWidth = () => current.min ?? 40;
+    function columnIdOf(el) {
+        return el.closest('[data-svgrid-header-col]')?.dataset.svgridHeaderCol ?? null;
+    }
+    function commit() {
+        if (!drag)
+            return;
+        current.onResize(drag.columnId, pendingWidth);
+    }
+    function onPointerMove(e) {
+        if (!drag)
+            return;
+        pendingWidth = Math.max(minWidth(), drag.startWidth + (e.clientX - drag.startX));
+        if (raf !== null)
+            return;
+        raf = requestAnimationFrame(() => {
+            raf = null;
+            commit();
+        });
+    }
+    function onPointerUp(e) {
+        if (!drag)
+            return;
+        if (raf !== null) {
+            cancelAnimationFrame(raf);
+            raf = null;
+        }
+        // Commit the final width even if the last frame was cancelled mid-flight.
+        pendingWidth = Math.max(minWidth(), drag.startWidth + (e.clientX - drag.startX));
+        commit();
+        drag.handle.classList.remove('is-resizing');
+        syncAria(drag.handle, drag.columnId);
+        try {
+            drag.handle.releasePointerCapture(e.pointerId);
+        }
+        catch {
+            /* release is best-effort */
+        }
+        drag = null;
+        window.removeEventListener('pointermove', onPointerMove);
+        window.removeEventListener('pointerup', onPointerUp);
+        window.removeEventListener('pointercancel', onPointerUp);
+        document.body.style.cursor = '';
+    }
+    function onPointerDown(e) {
+        if (current.disabled)
+            return;
+        const t = e.target;
+        if (!t?.classList.contains(HANDLE_CLASS))
+            return;
+        const columnId = columnIdOf(t);
+        if (!columnId || current.canResize?.(columnId) === false)
+            return;
+        e.preventDefault();
+        e.stopPropagation();
+        t.classList.add('is-resizing');
+        pendingWidth = current.getWidth(columnId);
+        drag = { columnId, startX: e.clientX, startWidth: pendingWidth, handle: t };
+        try {
+            t.setPointerCapture(e.pointerId);
+        }
+        catch {
+            /* capture is best-effort */
+        }
+        document.body.style.cursor = 'col-resize';
+        window.addEventListener('pointermove', onPointerMove);
+        window.addEventListener('pointerup', onPointerUp);
+        window.addEventListener('pointercancel', onPointerUp);
+    }
+    /**
+     * Keyboard resize (#79). The handle is a focusable `role="separator"` acting
+     * as a splitter, so it has to answer the arrow keys. Left/Right shrink/grow,
+     * Shift gives a 1px step - the same contract `rowResize` uses vertically.
+     */
+    function onKeyDown(e) {
+        if (current.disabled)
+            return;
+        const t = e.target;
+        if (!t?.classList.contains(HANDLE_CLASS))
+            return;
+        const step = e.shiftKey ? 1 : 10;
+        let delta = 0;
+        if (e.key === 'ArrowLeft')
+            delta = -step;
+        else if (e.key === 'ArrowRight')
+            delta = step;
+        else
+            return;
+        const columnId = columnIdOf(t);
+        if (!columnId || current.canResize?.(columnId) === false)
+            return;
+        e.preventDefault();
+        e.stopPropagation();
+        const next = Math.max(minWidth(), Math.round(current.getWidth(columnId) + delta));
+        current.onResize(columnId, next);
+        syncAria(t, columnId);
+    }
+    /** A focusable separator is a widget, so ARIA wants a current value. */
+    function syncAria(handle, columnId) {
+        const w = Math.round(current.getWidth(columnId));
+        handle.setAttribute('aria-valuenow', String(w));
+        handle.setAttribute('aria-valuemin', String(minWidth()));
+        handle.setAttribute('aria-valuetext', `${w} pixels`);
+    }
+    /** One handle per header cell. Skips group headers and spacer columns,
+     *  which have no id to resize. */
+    function decorate() {
+        if (current.disabled) {
+            removeAll();
+            return;
+        }
+        const heads = node.querySelectorAll('th.sv-grid-column[data-svgrid-header-col]');
+        for (const th of heads) {
+            if (th.classList.contains('sv-grid-column-spacer'))
+                continue;
+            const columnId = th.dataset.svgridHeaderCol;
+            if (!columnId)
+                continue;
+            if (current.canResize?.(columnId) === false) {
+                // The column may have been resizable a moment ago - a re-decorate has
+                // to take the handle away, not just stop adding one.
+                th.querySelector(`:scope > .${HANDLE_CLASS}`)?.remove();
+                continue;
+            }
+            if (th.querySelector(`:scope > .${HANDLE_CLASS}`))
+                continue;
+            const handle = document.createElement('div');
+            handle.className = HANDLE_CLASS;
+            handle.setAttribute('role', 'separator');
+            handle.setAttribute('aria-orientation', 'vertical');
+            handle.setAttribute('aria-label', `Resize ${current.label?.(columnId) ?? columnId}`);
+            handle.tabIndex = 0;
+            syncAria(handle, columnId);
+            // Double-click the handle to size the column to its content - the
+            // spreadsheet gesture. Stop it there so it does not also reach the
+            // header, where a double-click would toggle the sort twice.
+            handle.addEventListener('dblclick', (ev) => {
+                ev.stopPropagation();
+                ev.preventDefault();
+                if (current.disabled)
+                    return;
+                current.onAutosize?.(columnId);
+                syncAria(handle, columnId);
+            });
+            th.appendChild(handle);
+        }
+    }
+    function removeAll() {
+        node.querySelectorAll(`.${HANDLE_CLASS}`).forEach((el) => el.remove());
+    }
+    node.addEventListener('pointerdown', onPointerDown, { capture: true });
+    node.addEventListener('keydown', onKeyDown, { capture: true });
+    const observer = new MutationObserver(() => decorate());
+    observer.observe(node, { childList: true, subtree: true });
+    decorate();
+    return {
+        update(next) {
+            const wasDisabled = current.disabled;
+            current = next;
+            if (wasDisabled !== current.disabled)
+                decorate();
+        },
+        destroy() {
+            node.removeEventListener('pointerdown', onPointerDown, { capture: true });
+            node.removeEventListener('keydown', onKeyDown, { capture: true });
+            window.removeEventListener('pointermove', onPointerMove);
+            window.removeEventListener('pointerup', onPointerUp);
+            window.removeEventListener('pointercancel', onPointerUp);
+            if (raf !== null)
+                cancelAnimationFrame(raf);
+            observer.disconnect();
+            removeAll();
+        },
+    };
+}

package/dist/columns.d.ts

@@ -20,9 +20,6 @@ export declare function createColumns<TFeatures extends TableFeatures = TableFea
     toggleGroupInPanel: (columnId: string) => void;
     getColumnBaseWidth: (columnId: string) => any;
     getColumnWidth: (columnId: string) => any;
-    startColumnResize: (event: PointerEvent, columnId: string) => void;
-    onColumnResizeMove: (event: PointerEvent) => void;
-    endColumnResize: () => void;
     measureText: (text: string, font: string) => number;
     autosizeColumn: (columnId: string) => void;
     autosizeAllColumns: () => void;

package/dist/columns.js

@@ -156,60 +156,6 @@ export function createColumns(ctx) {
             return fitted;
         return getColumnBaseWidth(columnId);
     }
-    function startColumnResize(event, columnId) {
-        event.stopPropagation();
-        event.preventDefault();
-        ctx.resizingColumnId = columnId;
-        ctx.resizeStartX = event.clientX;
-        ctx.resizeStartWidth = getColumnWidth(columnId);
-        // Capture the pointer so the drag keeps tracking when it leaves the 4px
-        // handle - without this, touch (and fast mouse) drags drop mid-resize (#59).
-        try {
-            event.currentTarget?.setPointerCapture?.(event.pointerId);
-        }
-        catch { /* capture is best-effort */ }
-        document.addEventListener("pointermove", onColumnResizeMove);
-        document.addEventListener("pointerup", endColumnResize);
-        document.addEventListener("pointercancel", endColumnResize);
-    }
-    function onColumnResizeMove(event) {
-        if (!ctx.resizingColumnId)
-            return;
-        // Coalesce updates onto the animation frame: pointermove can fire many
-        // times per frame, and each $state mutation triggers a full reactive
-        // recompute of the column-layout pipeline. Without rAF coalescing the
-        // grid stutters during the drag.
-        ctx.resizePendingWidth = Math.max(ctx.MIN_COLUMN_WIDTH, ctx.resizeStartWidth + (event.clientX - ctx.resizeStartX));
-        if (ctx.resizeRaf !== null)
-            return;
-        ctx.resizeRaf = requestAnimationFrame(() => {
-            ctx.resizeRaf = null;
-            if (!ctx.resizingColumnId)
-                return;
-            ctx.columnWidths = {
-                ...ctx.columnWidths,
-                [ctx.resizingColumnId]: ctx.resizePendingWidth,
-            };
-        });
-    }
-    function endColumnResize() {
-        if (ctx.resizeRaf !== null) {
-            cancelAnimationFrame(ctx.resizeRaf);
-            ctx.resizeRaf = null;
-        }
-        if (ctx.resizingColumnId && ctx.resizePendingWidth) {
-            // Make sure the final width is committed even if the last rAF was
-            // canceled mid-flight.
-            ctx.columnWidths = {
-                ...ctx.columnWidths,
-                [ctx.resizingColumnId]: ctx.resizePendingWidth,
-            };
-        }
-        ctx.resizingColumnId = null;
-        document.removeEventListener("pointermove", onColumnResizeMove);
-        document.removeEventListener("pointerup", endColumnResize);
-        document.removeEventListener("pointercancel", endColumnResize);
-    }
     function measureText(text, font) {
         if (!text)
             return 0;
@@ -280,9 +226,6 @@ export function createColumns(ctx) {
         toggleGroupInPanel,
         getColumnBaseWidth,
         getColumnWidth,
-        startColumnResize,
-        onColumnResizeMove,
-        endColumnResize,
         measureText,
         autosizeColumn,
         autosizeAllColumns,