@svgrid/grid 3.0.3 → 4.0.0

package/dist/SvGrid.types.d.ts

@@ -1,8 +1,10 @@
 import type { Snippet } from "svelte";
+import type { GridRowModel } from "./row-model.js";
 import type { CellEditorType, ColumnDef, RowData, SvGridApi, TableFeatures } from "./index.js";
 import type { ConditionalFormat } from "./conditional-formatting.js";
 import type { GroupDisplayType } from "./group-display.js";
 import type { GridMessages } from "./grid-messages.js";
+import type { ChartMessages } from "./chart-messages.js";
 import type { GridIconName, GridIcons } from "./grid-icons.js";
 import type { GridPivotConfig } from "./pivot-view.svelte.js";
 import type { GridPredicateExpr } from "./filtering/predicate-expr.js";
@@ -52,7 +54,18 @@ export type SchedulerResource = {
         }>;
     }>;
 };
-import type { ChartType, ChartSpec, ChartAnnotation, ChartReferenceLine, ChartValueFormat } from "./chart.js";
+import type { ChartType, ChartSpec, ChartAnnotation, ChartReducer, ChartReferenceLine, ChartValueFormat } from "./chart.js";
+import type { ChartRangePreset } from "./chart-zoom.js";
+import type { ChartAnimateConfig, ChartContextTarget, ChartZoomConfig } from "./SvGridChart.types.js";
+/** What the chart panel's lifecycle events carry. */
+export type ChartPanelInfo = {
+    /** Tab index in the panel's strip. */
+    index: number;
+    title: string;
+    type: ChartType;
+    /** The spec the panel is rendering, or null while it cannot build one. */
+    spec: ChartSpec | null;
+};
 /** One aggregated bucket returned by a server-side `getAggregate`. */
 export type ChartAggregateBucket = {
     category: string;
@@ -64,7 +77,7 @@ export type ChartAggregateRequest = {
     dimension: string | undefined;
     measure: string | null;
     series?: string;
-    reduce: "sum" | "avg" | "count";
+    reduce: ChartReducer;
     filterModel: Record<string, unknown>;
 };
 /**
@@ -91,7 +104,7 @@ export type ChartingConfig<TData extends RowData = RowData> = {
     series?: string;
     /** Measure column, or several for a multi-series chart. */
     measures?: string | string[];
-    reduce?: "sum" | "avg" | "count";
+    reduce?: ChartReducer;
     stacked?: boolean;
     stacked100?: boolean;
     /** Per-series-label type override (combo). */
@@ -100,7 +113,10 @@ export type ChartingConfig<TData extends RowData = RowData> = {
     seriesAxes?: Record<string, "left" | "right">;
     referenceLines?: ChartReferenceLine[];
     averageLine?: boolean;
-    trend?: "sma" | "ema" | "linear";
+    /** An overlay on every series: a 7-point moving average, or a regression
+     *  (`linear`, `poly` for a quadratic, `exp`, `log`, `power`) whose
+     *  R-squared the tooltip reads. */
+    trend?: "sma" | "ema" | "linear" | "poly" | "exp" | "log" | "power";
     annotations?: ChartAnnotation[];
     yScale?: "linear" | "log";
     timeAxis?: boolean;
@@ -121,10 +137,37 @@ export type ChartingConfig<TData extends RowData = RowData> = {
     otherLabel?: string;
     sort?: "value-desc" | "value-asc" | "category" | "none";
     dataLabels?: boolean;
-    zoom?: boolean;
+    /** Zooming: `true` for drag-to-zoom, or an object choosing wheel, pinch,
+     *  pan and the axes (see `ChartZoomConfig`). The window survives tab
+     *  switches and round-trips through `getChartsState`. */
+    zoom?: boolean | ChartZoomConfig;
     brush?: boolean;
+    /** Range buttons (1W / 1M / 3M / 6M / YTD / 1Y / All, or your own) when the
+     *  dimension is a date. */
+    rangePresets?: boolean | ChartRangePreset[];
+    /** Share crosshair and zoom with other charts on the page (any `SvChart`
+     *  with the same `syncGroup`). */
+    syncGroup?: string;
+    /** All chart tabs of this grid share one zoom window: zoom in one tab and
+     *  the others open at the same range. */
+    syncTabs?: boolean;
+    /** Right-click menu on the chart: `true` for the built-in items, your own
+     *  `MenuItem`s appended after them, or a function of the clicked point. */
+    contextMenu?: boolean | MenuItem[] | ((target: ChartContextTarget) => MenuItem[]);
+    /** Motion: `true` for the default data-update tween, or an object choosing
+     *  the enter effect and duration. */
+    animate?: boolean | ChartAnimateConfig;
+    /** Translations for the chart's own strings (toolbar, menu, legend hints,
+     *  what it says to assistive technology); the panel passes them to every
+     *  chart it draws. See `ChartMessages`. */
+    localeText?: Partial<ChartMessages>;
     /** Show the chart's PNG/SVG export toolbar. */
     export?: boolean;
+    /** A chart tab was added (the first one counts, once the panel opens). */
+    onChartCreated?: (info: ChartPanelInfo) => void;
+    /** The active chart's spec changed: a picker, the builder, a filter, an
+     *  edit, new rows. Debounced to one call per burst of changes. */
+    onChartChanged?: (info: ChartPanelInfo) => void;
     /** Escape hatch: build a fully custom ChartSpec from the (scoped) rows. */
     buildSpec?: (rows: TData[]) => ChartSpec | null;
     /** Server-side aggregation: chart the whole dataset, not just loaded rows. */
@@ -189,15 +232,44 @@ export type ContextMenuTarget<TData extends RowData = RowData> = {
  * "chart"`. The `"chart"` item (chart the selected range) is only shown when
  * `charting` is enabled; it is appended to the default menu automatically.
  */
+/**
+ * An icon of your own for a context-menu item: path data on a 16 x 16 grid,
+ * drawn in the text colour with a 1.4px round stroke (`fill` for a solid
+ * part, `width` and `dash` to vary the stroke). The same shape a
+ * spreadsheet ribbon's icon set uses, so one set serves both.
+ */
+export type ContextMenuIcon = {
+    paths: ReadonlyArray<{
+        d: string;
+        fill?: boolean;
+        width?: number;
+        dash?: string;
+    }>;
+};
 export type ContextMenuItem<TData extends RowData = RowData> = string | {
     key: string;
-    label: string;
+    /**
+     * The text. An object whose `key` names a built-in (`copy`, `cut`,
+     * `paste`, `clear`, `row_above`, `row_below`, `remove_row`,
+     * `remove_col`, `comment`, `chart`) keeps the built-in's own label
+     * when this is omitted.
+     */
+    label?: string;
+    /**
+     * A glyph before the label: one of the grid's icons by name, or path
+     * data of your own. Items without one keep the gutter, so the labels
+     * line up.
+     */
+    icon?: GridIconName | ContextMenuIcon;
     /** Hide the item entirely for this target. */
     hidden?: (target: ContextMenuTarget<TData>) => boolean;
     /** Render the item greyed-out and non-clickable for this target. */
     disabled?: (target: ContextMenuTarget<TData>) => boolean;
-    /** Invoked on click. The menu closes afterwards. */
-    action: (target: ContextMenuTarget<TData>) => void;
+    /**
+     * Invoked on click. The menu closes afterwards. Omit it on a built-in
+     * key to keep what the built-in does and only give it an icon.
+     */
+    action?: (target: ContextMenuTarget<TData>) => void;
 };
 /** What a {@link SelectionBarAction} is handed when it runs. */
 export type SelectionBarTarget<TData extends RowData = RowData> = {
@@ -377,7 +449,7 @@ export type ChartViewConfig<TFeatures extends TableFeatures = TableFeatures, TDa
     /** Pivot dimension: one series per distinct value of this field. */
     series?: keyof TData & string;
     /** Aggregation when several rows share a category. Default `'sum'`. */
-    reduce?: "sum" | "avg" | "count";
+    reduce?: ChartReducer;
     /** Stack bar / area series instead of grouping them. */
     stacked?: boolean;
     /** Stack to 100% (implies `stacked`). */
@@ -1004,7 +1076,13 @@ export type SchedulerConfig<TFeatures extends TableFeatures = TableFeatures, TDa
     searchPlaceholder?: string;
 };
 export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends RowData = RowData> = {
-    data: ReadonlyArray<TData>;
+    /**
+     * The rows to render.
+     *
+     * Optional only because `rowModel` can supply them instead; a grid with
+     * neither renders empty. When both are present `data` wins.
+     */
+    data?: ReadonlyArray<TData>;
     columns: Array<ColumnDef<TFeatures, TData>>;
     /**
      * Kanban board mode. When set, the grid renders its rows as cards in
@@ -1516,6 +1594,23 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
      * that leaves this off never fetches that code.
      */
     columnResize?: boolean;
+    /**
+     * The user dragged a column's edge (or double-clicked it to autosize).
+     * Programmatic `api.setColumnWidth` does not fire it.
+     */
+    onColumnResize?: (event: {
+        columnId: string;
+        width: number;
+    }) => void;
+    /**
+     * The user dragged a row's edge, or double-clicked it: `height` is then
+     * `null`, the row back at its declared height. Programmatic
+     * `api.setRowHeight` does not fire it.
+     */
+    onRowResize?: (event: {
+        rowIndex: number;
+        height: number | null;
+    }) => void;
     /**
      * Make the grid usable on narrow screens. When the grid's own width drops
      * below the breakpoint (default `640`px), pinned columns are un-pinned so the
@@ -1580,6 +1675,25 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
      * currency symbols, expand codes to labels, or redact. Receives the display
      * value plus the row/column context; return the string (or value) to copy.
      */
+    /**
+     * Decide what the fill handle writes into one cell, ahead of the grid's
+     * own pattern rules (series, weekdays, "Item 1"). Receives the source
+     * cell's value and how far the target sits from it; return the value to
+     * write, or `undefined` to let the pattern decide. A spreadsheet uses it
+     * to move a formula's references by the distance filled, which the
+     * pattern rules would otherwise mangle ("=A1+B1" reads as "Item 1").
+     */
+    processCellForFill?: (params: {
+        /** The source cell's value the target cycles back to. */
+        value: unknown;
+        /** Rows and columns from that source cell to the target. */
+        delta: {
+            rows: number;
+            cols: number;
+        };
+        rowIndex: number;
+        columnId: string;
+    }) => unknown;
     processCellForClipboard?: (params: {
         value: unknown;
         column: unknown;
@@ -1587,6 +1701,65 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
         rowIndex: number;
         columnId: string;
     }) => unknown;
+    /**
+     * An HTML rendering of what Ctrl+C copies, written to the clipboard as
+     * `text/html` beside the TSV. Excel and Google Sheets read the HTML
+     * first, so a table with inline styles pastes into them with its formats,
+     * and the same markup can carry what the text cannot (a formula in a
+     * `data-` attribute) for a round trip back into a grid that reads it.
+     * Called after every cell has been through `processCellForClipboard`,
+     * with the rectangles copied and the text about to be written. Return
+     * nothing to write text alone. Runs synchronously inside the key press,
+     * which is what the clipboard needs.
+     */
+    clipboardHtml?: (params: {
+        rects: ReadonlyArray<{
+            minRow: number;
+            maxRow: number;
+            minCol: number;
+            maxCol: number;
+        }>;
+        text: string;
+    }) => string | null | undefined;
+    /**
+     * Take over a paste. Receives the clipboard's `text/plain` and, when the
+     * source put one there, its `text/html` (Excel's carries formats and
+     * formulas; a grid's own `clipboardHtml` carries whatever it chose to).
+     * Return `true` to say the paste was applied; anything else lets the grid
+     * paste the text as it always has. Runs inside one history group, so
+     * every `setCellValue` and `recordUndo` the handler makes is one Ctrl+Z.
+     *
+     * With this set, Ctrl+V lets the browser's own `paste` event through
+     * (that is where the unsanitised HTML is), and the async Clipboard API is
+     * the fallback for a browser that does not deliver it. `source` says
+     * which path the payload came by.
+     */
+    onPasteClipboard?: (payload: {
+        text: string;
+        html: string | null;
+        source: "event" | "async";
+    }) => boolean | void;
+    /**
+     * Transform each cell on its way IN from the clipboard, before the grid
+     * coerces it for the column's editor. Symmetric with
+     * `processCellForClipboard`: the pair is what lets a round trip survive.
+     *
+     * Receives the raw clipboard text for the cell plus where it is landing.
+     * Return the value to write, or `undefined` to leave the cell untouched.
+     *
+     * This is also the seam a feature pack uses to take over a paste entirely:
+     * `@svgrid/enterprise`'s paste-special reads the clipboard's `text/html`
+     * for formats and formulas and writes through here.
+     */
+    processCellFromClipboard?: (params: {
+        /** The raw text from the clipboard for this cell. */
+        text: string;
+        /** What the grid would have written after its own coercion. */
+        parsedValue: unknown;
+        row: TData;
+        rowIndex: number;
+        columnId: string;
+    }) => unknown;
     /**
      * Inline cell editing: F2 or double-click opens an editor in the active cell,
      * Enter commits, Esc cancels. Off by default.
@@ -1596,6 +1769,14 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
      * `editable` is the shortcut alias and wins over this.
      */
     enableInlineEditing?: boolean;
+    /**
+     * A click on the cell that is already active opens its editor, the way a
+     * second click on a selected file name starts renaming it. On by default.
+     * A spreadsheet turns it off: Excel edits on double-click or F2 only, and
+     * a user clicking the cell they are on to get back to it after a dialog
+     * would otherwise find the next shortcut typed into an editor.
+     */
+    editOnSecondClick?: boolean;
     /**
      * Full-row editing. When `true`, starting an edit puts the WHOLE row into
      * edit mode - every editable cell shows an inline editor at once - and a
@@ -1904,6 +2085,99 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
         scrollHeight: number;
         clientHeight: number;
     }) => void;
+    /**
+     * Fires when the range of rows on screen changes, with the first and last
+     * row INDEX (not pixels). Coalesced to one call per frame, so it is cheap
+     * to wire to something that fetches.
+     *
+     * This is the hook a block-loading data source needs and
+     * `onScrollBottomReached` cannot give it: "the user is looking at rows
+     * 4,000-4,020" answers which block to fetch and which to keep, while
+     * "they hit the bottom" only ever means "append more". Both are free; use
+     * this one with `createServerDataSource({ mode: 'infinite' })`, or let
+     * `rowModel` wire it for you.
+     *
+     * Reports `0, data.length - 1` when virtualization is off, since every row
+     * really is rendered.
+     */
+    onVisibleRangeChange?: (range: {
+        startIndex: number;
+        endIndex: number;
+    }) => void;
+    /**
+     * Marks a row as one whose data has not arrived: `"loading"` draws a
+     * shimmer in every cell, `"failed"` draws a full-width "could not load"
+     * row with a Retry button, and `null` (the default for every row) renders
+     * normally.
+     *
+     * Placeholder rows are inert - not selectable, not editable, and skipped
+     * by cell navigation - because there is nothing there to act on yet.
+     *
+     * `createServerDataSource` in `infinite` mode fills the gaps with rows this
+     * recognises, so the usual wiring is `rowPlaceholder={rowPlaceholderState}`
+     * (or nothing at all, via `rowModel`).
+     */
+    rowPlaceholder?: (row: TData, rowIndex: number) => "loading" | "failed" | null;
+    /** Called by the Retry button on a `"failed"` placeholder row. */
+    onRetryRow?: (row: TData, rowIndex: number) => void;
+    /**
+     * Hand selection over to an external model.
+     *
+     * The grid normally tracks selection as a record of the row ids it has
+     * seen, which is right until the rows it has seen are a window onto a
+     * million on a server: "select all" then means 20 ticked checkboxes rather
+     * than a million, and the header checkbox cannot honestly say `all`. A
+     * model that stores the RULE ("everything except these three") can answer
+     * both, so when this is set the header checkbox, the row checkboxes and
+     * `api.selectAllRows()` all route through it instead.
+     *
+     * `@svgrid/enterprise` ships one for the server-side row model; this is the
+     * seam it plugs into.
+     */
+    /**
+     * Drive the grid from a row model instead of wiring a dozen props.
+     *
+     * `createServerDataSource` returns one, and so does the Enterprise
+     * server-side row model, so server-backed grids become:
+     *
+     * ```svelte
+     * <SvGrid rowModel={ctl} {columns} />
+     * ```
+     *
+     * The model supplies `data`, `loading`, `getRowId`, the external sort
+     * and filter wiring, the visible range, placeholder rows, group
+     * accessors, selection and paging - each one only if it implements that
+     * part. A prop written explicitly on the grid always wins, so you can
+     * adopt it and still override one piece.
+     */
+    rowModel?: GridRowModel<TData>;
+    /**
+     * Columns that REPLACE `columns` while set. The server-side row model
+     * supplies them in pivot mode - one column per pivoted value, grouped
+     * under a header per pivot key - and clears them when pivot mode ends,
+     * so `columns` stays the app's own list. Rarely set by hand.
+     */
+    pivotResultColumns?: Array<ColumnDef<TFeatures, TData>> | null;
+    rowSelectionModel?: {
+        isSelected: (rowId: string, row: TData) => boolean;
+        /** Whether the header checkbox shows empty, indeterminate, or ticked. */
+        headerState: () => "none" | "some" | "all";
+        toggle: (rowId: string, row: TData, next: boolean) => void;
+        /** The header checkbox: select or clear everything, loaded or not. */
+        toggleAll: (next: boolean) => void;
+        /**
+         * How many rows the rule selects, counting the ones the grid never
+         * loaded; `null` when it cannot say. The selection bar shows this
+         * instead of counting ticked rows on screen.
+         */
+        selectedCount?: () => number | null;
+        /**
+         * Apply one patch to every selected row, loaded or not. When present,
+         * the bulk-edit drawer sends its edits here instead of writing the
+         * loaded cells. Resolves with how many rows changed.
+         */
+        bulkUpdate?: (patch: Record<string, unknown>) => Promise<number>;
+    };
     /**
      * Marks a row as an expandable "detail row". When this returns true the
      * grid renders that row as a SINGLE full-width cell (colspan across every
@@ -1927,8 +2201,10 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
      * Server-side group / tree keyboard + accessibility, built into the grid. When
      * set, the grid uses the treegrid role and marks matching rows with
      * `aria-level` / `aria-expanded`, and ArrowRight / ArrowLeft expand / collapse
-     * the focused group row (no app-level key handling). Pair with `serverGroupRows`
-     * + `SvGroupCell` for the visual expander. Every accessor receives the row data.
+     * the focused group row (no app-level key handling). Pair with
+     * `serverGroupRows` + `SvGroupCell` from `@svgrid/enterprise` for the visual
+     * expander, or drive it from your own tree state. Every accessor receives the
+     * row data.
      */
     serverGroup?: {
         /** Whether a row is an expandable group / branch. */
@@ -1957,6 +2233,33 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
      * main grid; field/format/cell/cellClass all apply.
      */
     pinnedTopRows?: ReadonlyArray<TData>;
+    /**
+     * Freeze the first N rows: they stay under the header while the body
+     * scrolls, and unlike `pinnedTopRows` they are the grid's own rows,
+     * still editable, selectable and numbered as rows 1..N. Excel's Freeze
+     * Panes, for the row half; the column half is `columnPinning`. Under
+     * `virtualization` the frozen rows are always rendered and the window
+     * skips them.
+     */
+    frozenRows?: number;
+    /**
+     * Merged cells: rectangles drawn as one cell, a spreadsheet's Merge &
+     * Center. Each entry is the top-left cell (display indices) and how many
+     * rows and columns it covers. The origin's td takes the span and shows
+     * the origin's value; the covered cells are not drawn, a selection grows
+     * to whole merges, the active cell inside a merge is its origin, and the
+     * arrow keys step over a merge as one cell. A merge that crosses the
+     * frozen boundary or the rendered window is drawn in parts, one per
+     * band. The grid does not write into covered cells on its own; a
+     * consumer that merges cells keeps them empty or marks them read-only
+     * through the column's `editable`.
+     */
+    mergedCells?: ReadonlyArray<{
+        rowIndex: number;
+        colIndex: number;
+        rowSpan: number;
+        colSpan: number;
+    }>;
     /**
      * Rows to pin to the BOTTOM of the grid - rendered below the regular
      * rows and sticky-positioned (sticks to the bottom of the viewport

package/dist/SvGridCellEditor.svelte

@@ -715,6 +715,23 @@
       {@const _reg = getCellEditor(String(ctrl.editingCell?.editorType))!}
       {@const CustomCellEditor = _reg.component}
       <CustomCellEditor {...resolveEditorProps(_reg, buildRegisteredEditorContext())} />
+    {:else if (ctrl.editingCell?.editorType ?? "text") === "text" && column?.columnDef.editorMultiline}
+      <!-- The text editor with room for line breaks: Alt+Enter inserts one
+           (handled in onEditorKeyDown), Enter commits like the input's, and
+           the height follows the lines. -->
+      <textarea
+        use:focusOnMount
+        class="sv-grid-cell-editor sv-grid-cell-editor-text sv-grid-cell-editor-multiline"
+        rows={Math.max(1, String(ctrl.editingCell?.value ?? "").split("\n").length)}
+        value={String(ctrl.editingCell?.value ?? "")}
+        oninput={(event) => {
+          const area = event.currentTarget as HTMLTextAreaElement;
+          area.rows = Math.max(1, area.value.split("\n").length);
+          updateEditingCellValue(area.value);
+        }}
+        onblur={() => saveEditingCell()}
+        onkeydown={onEditorKeyDown}
+      ></textarea>
     {:else}
       {@const editorType = ctrl.editingCell?.editorType ?? "text"}
       {@const isNumberEditor = getCellEditorInputType(editorType) === "text" &&