@svgrid/grid 2.6.19 → 2.6.21

package/src/SvGrid.types.ts

@@ -1029,7 +1029,21 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
    * work; the shortcut wins only when it is explicitly set.
    */
   sortable?: boolean;
+  /**
+   * Click a header to filter that column. Injects `columnFilteringFeature`,
+   * so you do not import it yourself. Which filter surface appears is a
+   * separate question - see `filterMode` (default `'menu'`).
+   *
+   *   <SvGrid {data} {columns} filterable />
+   */
   filterable?: boolean;
+  /**
+   * Inline cell editing. Alias of `enableInlineEditing`, and wins over it when
+   * both are set. A column also needs an `editorType` to be editable; without
+   * one it falls back to a text editor.
+   *
+   *   <SvGrid {data} {columns} editable />
+   */
   editable?: boolean;
   /**
    * Cell selection - click a cell to select it, drag or shift-click to extend
@@ -1081,6 +1095,16 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
     /** Indent per depth level, in px. Default `12`. */
     indentPx?: number;
   };
+  /**
+   * Show the grouping controls: "Group by this column" in the column menu, and
+   * the group panel when `showGroupPanel` is on. Alias of
+   * `showGroupingControls`, and also injects `columnGroupingFeature`.
+   *
+   * This turns on the UI for grouping. To group without asking the user, set
+   * `groupBy` instead.
+   *
+   *   <SvGrid {data} {columns} groupable />
+   */
   groupable?: boolean;
   /**
    * Group the rows by these column ids, outermost first - `['region',
@@ -1158,7 +1182,19 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
   autoGroupColumnHeader?: string;
   /** Width (px) of each auto-group column. Default `220`. */
   autoGroupColumnWidth?: number;
+  /**
+   * Show the pagination footer. Alias of `showPagination`, and wins over it
+   * when both are set. Page size starts at `pageSize` (default 10).
+   *
+   *   <SvGrid {data} {columns} pageable pageSize={25} />
+   */
   pageable?: boolean;
+  /**
+   * Show the loading state instead of the rows. By default this replaces the
+   * grid body with "Loading..."; set `loadingOverlay` to keep the current rows
+   * visible under a dimmed overlay instead, which is what you usually want for
+   * a server-paged grid.
+   */
   loading?: boolean;
   /**
    * Render `loading` as a non-blocking overlay instead of replacing the
@@ -1170,7 +1206,16 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
   loadingOverlay?: boolean;
   /** Skeleton placeholder rows to show on first load. Defaults to 8. */
   loadingSkeletonRows?: number;
+  /**
+   * Render an error message in place of the rows. `null` or omitted means no
+   * error. Takes precedence over `loading` and over the empty state.
+   */
   error?: string | null;
+  /**
+   * Text shown when there are no rows to display - either the data is empty or
+   * a filter matched nothing. Defaults to the localized `noRows` string, so
+   * prefer `localization.text.noRows` when you are translating the whole grid.
+   */
   emptyMessage?: string;
   /**
    * The single place to localize the grid. One object with two fields:
@@ -1190,7 +1235,21 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
    * Omitting it (or any field) is a no-op. See {@link GridMessages}.
    */
   localization?: GridLocalization;
+  /**
+   * Show the single search box that filters across every column. Explicitly
+   * setting this wins over `filterMode`; leaving it unset means it appears only
+   * when `filterMode` is `'global'`.
+   */
   showGlobalFilter?: boolean;
+  /**
+   * Show the filter section inside each column's menu. Explicitly setting this
+   * wins over `filterMode`; unset, it follows `filterMode` (default `'menu'`,
+   * so this is normally on).
+   *
+   * Setting it `true` also adds the inline "floating filter" input under each
+   * header - that surface requires the explicit opt-in, since it otherwise
+   * duplicates the menu's own filter popover.
+   */
   showColumnFilters?: boolean;
   /**
    * Quick way to pick a single filtering UI. When set it controls which of
@@ -1199,8 +1258,23 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
    * Defaults to `'menu'` (only the column menu's filter section is shown).
    */
   filterMode?: "row" | "menu" | "global" | "none";
+  /**
+   * Show the grouping affordances (the column menu's "Group by this column",
+   * and the group panel). The `groupable` shortcut sets this and registers the
+   * grouping feature in one go; prefer that unless you have already registered
+   * `columnGroupingFeature` yourself.
+   */
   showGroupingControls?: boolean;
+  /**
+   * Show the row-selection checkbox column, including the select-all checkbox
+   * in the header. Unset, it follows `selectionMode` (default `'both'`, so
+   * row selection is on).
+   */
   showRowSelection?: boolean;
+  /**
+   * Show the pagination footer. Off by default. `pageable` is the shortcut
+   * alias and wins when both are set.
+   */
   showPagination?: boolean;
   /** Initial page size when pagination is enabled. Defaults to 10. */
   pageSize?: number;
@@ -1230,6 +1304,14 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
    * is on. Fetch that page and update `data` / `rowCount` / `pageIndex`.
    */
   onPaginationChange?: (pagination: { pageIndex: number; pageSize: number }) => void;
+  /**
+   * Render only the rows in view instead of all of them. **On by default** -
+   * this is what keeps a 100,000-row grid responsive.
+   *
+   * Turn it off when a row's height cannot be known up front and must not be
+   * clipped, such as a variable-height master-detail panel. Expect the DOM to
+   * hold every row when you do.
+   */
   virtualization?: boolean;
   /** Row height in pixels. Pass a function `(rowIndex) => px` for
    *  per-row variable heights (e.g. an interactive row-resize feature).
@@ -1254,6 +1336,11 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
    * to their content (the default). Does not affect the filter row.
    */
   headerHeight?: number;
+  /**
+   * Extra rows rendered above and below the viewport, so fast scrolling does
+   * not reach empty space before the next batch renders. Defaults to 8.
+   * Raise it for very tall rows, lower it to trim DOM work.
+   */
   overscan?: number;
   /**
    * Height of the grid's scrollable shell. A number is treated as pixels;
@@ -1261,8 +1348,24 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
    * make the grid fill its parent. Defaults to 520 px.
    */
   containerHeight?: number | string;
+  /**
+   * Render only the columns in view, the horizontal counterpart of
+   * `virtualization`. **On by default**, which is what makes a 100-column grid
+   * scroll smoothly.
+   *
+   * It recycles column DOM nodes, so it cannot coexist with sticky pinned
+   * columns - turn it off if you need pinning to survive horizontal scrolling.
+   */
   columnVirtualization?: boolean;
+  /**
+   * Extra columns rendered either side of the viewport when
+   * `columnVirtualization` is on. Defaults to 3.
+   */
   columnOverscan?: number;
+  /**
+   * Fallback width in pixels for columns whose `ColumnDef` sets no `width`.
+   * Defaults to 140.
+   */
   columnWidth?: number;
   /**
    * Columns pinned to the left/right edge on mount. Each entry is a
@@ -1293,8 +1396,24 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
    * breakpoint; pass `{ breakpoint }` to change it. Off by default.
    */
   responsive?: boolean | { breakpoint?: number };
+  /**
+   * @deprecated Has no effect - nothing in the grid reads this prop. It is kept
+   * only so existing code keeps compiling. The column menu's filter section is
+   * controlled by `showColumnFilters`, or by `filterMode="menu"` (the default).
+   */
   showFilterMenu?: boolean;
+  /**
+   * Show the always-visible filter row under the header. Explicitly setting
+   * this wins over `filterMode`; unset, it appears only when `filterMode` is
+   * `'row'`.
+   */
   showFilterRow?: boolean;
+  /**
+   * Cell selection - click to select, drag or shift-click to extend to a range,
+   * which is what clipboard copy and the range fill handle operate on. Unset,
+   * it follows `selectionMode` (default `'both'`, so this is on). `selectable`
+   * is the shortcut alias and wins over it.
+   */
   enableCellSelection?: boolean;
   /**
    * Highlight the row under the pointer. Default **false** - the hover tint can
@@ -1320,6 +1439,14 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
     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.
+   *
+   * A column still needs an `editorType` to pick its editor (text, number,
+   * date, checkbox, list, ...); without one it gets a plain text editor.
+   * `editable` is the shortcut alias and wins over this.
+   */
   enableInlineEditing?: boolean;
   /**
    * Full-row editing. When `true`, starting an edit puts the WHOLE row into
@@ -1329,7 +1456,22 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
    * text / number / date / datetime / checkbox / list-select editor types.
    */
   fullRowEditing?: boolean;
+  /**
+   * Append a sticky footer row aggregating every filtered row: the sum of a
+   * numeric column, `Count: N` otherwise. Choose a different aggregate per
+   * column with that column's own `summary` option, or set it to `false` there
+   * to leave the cell blank.
+   *
+   * Off by default. `summary` is the shortcut alias and wins when both are set.
+   *
+   *   <SvGrid {data} {columns} summary />
+   */
   enableRowSummaries?: boolean;
+  /**
+   * Shortcut alias for {@link enableRowSummaries}. Wins over it when both are
+   * set, the same precedence `selectable` has over `enableCellSelection`.
+   */
+  summary?: boolean;
   /**
    * Excel-style status bar under the grid showing live aggregates of the
    * selected cell range (count, numeric count, sum, average, min, max).
@@ -1544,6 +1686,14 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
    *   filter.
    */
   conditionalStatScope?: "filtered" | "visible" | "all";
+  /**
+   * Fires after an inline edit commits, with the cell's old and new value and
+   * the row it belongs to. This is where you persist the change.
+   *
+   * The grid has already applied the edit to its own state by the time this
+   * runs, so it is a notification, not a veto - reject a value with the
+   * column's `valueParser` or a validation rule instead.
+   */
   onCellValueChange?: (event: {
     rowIndex: number;
     columnId: string;

package/src/ai.ts

@@ -48,6 +48,7 @@ type ExportFormat = 'xlsx' | 'xls' | 'pdf' | 'csv' | 'tsv' | 'html' | 'json' | '
  */
 export type AIProvider = (request: AIRequest) => Promise<string>
 
+/** One call out to the model, as the grid builds it. Providers receive this. */
 export type AIRequest = {
   /** Full prompt the grid built for the model. Already includes column
    *  schema and any sampled rows where applicable. */
@@ -66,6 +67,7 @@ export type AIRequest = {
   maxOutputTokens?: number
 }
 
+/** Which helper produced a request - carried on {@link AIRequest} for routing and telemetry. */
 export type AITask = 'filter' | 'smart-fill' | 'summarize' | 'classify' | 'export' | 'anomaly' | 'chart'
 
 let provider: AIProvider | null = null
@@ -79,10 +81,12 @@ export function setAIProvider(p: AIProvider | null): void {
   provider = p
 }
 
+/** The provider registered with `setAIProvider`, or null when none is. */
 export function getAIProvider(): AIProvider | null {
   return provider
 }
 
+/** Whether an AI provider is registered. Gate AI affordances on this so the UI stays honest. */
 export function hasAIProvider(): boolean {
   return provider != null
 }
@@ -198,13 +202,16 @@ function schemaToPromptBlock(schema: ColumnSchemaEntry[]): string {
 // 1. Natural-language filter / sort
 // ---------------------------------------------------------------------------
 
+/** One condition in a filter plan: a column, a comparison, and the value to match. */
 export type AIFilterClause = {
   field: string
   operator: 'contains' | 'equals' | 'startsWith' | 'greaterThan' | 'lessThan' | 'isBlank'
   value?: string
 }
+/** One ordering clause in a filter plan. */
 export type AISortClause = { field: string; desc: boolean }
 
+/** A natural-language query turned into filters and sorting, plus the model's reasoning. */
 export type AIFilterResult = {
   filters: AIFilterClause[]
   sort: AISortClause[]
@@ -213,6 +220,7 @@ export type AIFilterResult = {
   rationale: string
 }
 
+/** Options for `aiFilter` - preview the plan, or apply it straight to the grid. */
 export type AIFilterOptions = {
   /**
    * When true, the helper not only RETURNS the plan but also applies it
@@ -284,14 +292,17 @@ export async function aiFilter<
 // 2. Smart fill
 // ---------------------------------------------------------------------------
 
+/** One worked example teaching smart-fill what to produce for a row. */
 export type AISmartFillExample = { input: Record<string, unknown>; output: unknown }
 
+/** Proposed values for the blank cells of one column, each with a confidence score. */
 export type AISmartFillResult<TValue = unknown> = {
   field: string
   predictions: Array<{ rowIndex: number; value: TValue; confidence: number }>
   rationale: string
 }
 
+/** Options for `aiSmartFill` - which column to fill, which rows, and the examples to learn from. */
 export type AISmartFillOptions = {
   /** Target column - the one whose values we want filled. */
   field: string
@@ -379,12 +390,14 @@ export async function aiSmartFill<
 // 3. Summarise
 // ---------------------------------------------------------------------------
 
+/** What to summarise: one row, the selection, a group, or the whole set. */
 export type AISummarizeTarget =
   | { kind: 'row'; rowIndex: number }
   | { kind: 'all' }
   | { kind: 'selection'; rowIndices: number[] }
   | { kind: 'group'; field: string; value: unknown }
 
+/** A generated summary: prose, bullets, and the columns the model leaned on. */
 export type AISummary = {
   text: string
   bullets: string[]
@@ -393,6 +406,7 @@ export type AISummary = {
   highlightedFields: string[]
 }
 
+/** Options for `aiSummarize` - the target, and optionally the question to answer. */
 export type AISummarizeOptions = {
   target: AISummarizeTarget
   /** Optional question the user is trying to answer. Helps the model
@@ -468,6 +482,7 @@ export async function aiSummarize<
 // 4. Classify (free-text -> bucketed value)
 // ---------------------------------------------------------------------------
 
+/** Options for `aiClassify` - the column to label and the categories to choose from. */
 export type AIClassifyOptions = {
   /** Column whose free-text we're classifying. */
   inputField: string
@@ -482,6 +497,7 @@ export type AIClassifyOptions = {
   signal?: AbortSignal
 }
 
+/** Proposed category labels per row, with the model's reasoning. */
 export type AIClassifyResult = {
   inputField: string
   outputField: string
@@ -545,6 +561,7 @@ export async function aiClassify<
 
 const EXPORT_FORMATS: ExportFormat[] = ['xlsx', 'xls', 'pdf', 'csv', 'tsv', 'html', 'json', 'xml', 'md']
 
+/** An export the model derived from a request: format, columns, and scope. */
 export type AIExportPlan = {
   format: ExportFormat
   filters: AIFilterClause[]
@@ -554,6 +571,7 @@ export type AIExportPlan = {
   rationale: string
 }
 
+/** Options for `aiExport` - preview the plan, or run the export it describes. */
 export type AIExportOptions = {
   /**
    * Also apply the filter / sort / grouping to the grid (mutating the view) so
@@ -719,6 +737,7 @@ function applyPlanToRows<TData extends RowData>(
 // 6. Find anomalies
 // ---------------------------------------------------------------------------
 
+/** One flagged value, with why it stands out and how strongly. */
 export type AIAnomaly = {
   /** Index into the SCANNED rows (target order), when the model pins one row. */
   rowIndex?: number
@@ -728,11 +747,13 @@ export type AIAnomaly = {
   severity: 'low' | 'medium' | 'high'
 }
 
+/** Everything an anomaly scan flagged across the rows it looked at. */
 export type AIAnomalyResult = {
   anomalies: AIAnomaly[]
   summary: string
 }
 
+/** Options for `aiFindAnomalies` - which rows and columns to scan. */
 export type AIAnomalyOptions = {
   /** Which rows to scan. Defaults to the whole dataset. */
   target?: AISummarizeTarget
@@ -814,8 +835,10 @@ export async function aiFindAnomalies<
 // 7. Natural-language chart ("chart this")
 // ---------------------------------------------------------------------------
 
+/** Chart shapes the model may choose from when planning a visualisation. */
 export type AIChartType = 'bar' | 'line' | 'area' | 'pie'
 
+/** A chart the model proposed: its type, and the fields to plot. */
 export type AIChartPlan = {
   type: AIChartType
   /** Group-by (category-axis) column field, or null. */
@@ -832,6 +855,7 @@ export type AIChartPlan = {
   rationale: string
 }
 
+/** Options for `aiChart` - preview the plan, or render it into the grid. */
 export type AIChartOptions = {
   /** Apply the plan to the grid's chart panel (open + configure). Default false. */
   apply?: boolean
@@ -951,6 +975,10 @@ export function enableAiCharting<
   })
 }
 
+/**
+ * Remove the natural-language chart handler, hiding the AI button in the chart
+ * panel. The inverse of `enableAiCharting`; safe to call when none was set.
+ */
 export function disableAiCharting<
   TFeatures extends TableFeatures,
   TData extends RowData,

package/src/cell-formatting.ts

@@ -106,6 +106,8 @@ function getNumberFormatter(
 
 /** Cache of `Intl.DateTimeFormat` by `(locale, options)` signature. */
 const dateFormatterCache = new Map<string, Intl.DateTimeFormat>()
+/** A cached `Intl.DateTimeFormat` for the locale and options given. Cached because
+ *  constructing one per cell is the dominant cost when formatting a date column. */
 export function getDateFormatter(
   locales: string | readonly string[] | undefined,
   options: Intl.DateTimeFormatOptions,

package/src/chart-export.ts

@@ -21,6 +21,7 @@ function cssVar(el: Element, name: string, fallback: string): string {
   return v || fallback
 }
 
+/** Options for exporting a chart: the filename, and the background to paint behind it. */
 export type ChartExportOptions = {
   /** Background color of the exported image. Default: the grid background. */
   background?: string

package/src/chart.ts

@@ -36,9 +36,8 @@ 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[]
@@ -95,6 +94,12 @@ export type ChartReferenceLine = {
   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
@@ -326,6 +331,7 @@ export type ChartHeatmapCell = {
   colLabel: string
 }
 
+/** A computed bar rectangle in SVG coordinates. Output of {@link buildChart}, not an input. */
 export type ChartBar = {
   x: number
   y: number
@@ -338,6 +344,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
@@ -346,6 +353,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
@@ -356,6 +364,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
@@ -366,12 +375,17 @@ 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; color: string; dashed: boolean }
 /** A vertical reference line (horizontal bar charts) positioned by `x`. */
 export type ChartRefLineGeoV = { x: number; label: string; color: string; dashed: boolean }
+/** A computed scatter point in SVG coordinates. */
 export type ChartScatterDot = {
   cx: number
   cy: number
@@ -383,6 +397,11 @@ export type ChartScatterDot = {
   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
@@ -455,6 +474,7 @@ export type ChartGeometry = {
   sankeyLinks: ChartSankeyLink[]
 }
 
+/** Series colours used when a {@link ChartSeries} sets none, in order. */
 export const DEFAULT_PALETTE = [
   '#2563eb',
   '#16a34a',
@@ -480,6 +500,7 @@ function niceNum(range: number, roundIt: boolean): number {
   return nf * Math.pow(10, exp)
 }
 
+/** An axis range rounded to human-friendly bounds and tick spacing. */
 export type NiceScale = { min: number; max: number; step: number; ticks: number[] }
 
 // ---- Color helpers for heatmap / pattern fills ----------------------
@@ -574,9 +595,6 @@ function project(value: number, min: number, max: number, isLog: boolean): numbe
 
 // ---- 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. */
@@ -655,6 +673,9 @@ function monotoneCubicPath(pts: Array<{ x: number; y: number }>): string {
   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: number[]): number[] {
   let n = 0, sumX = 0, sumY = 0, sumXX = 0, sumXY = 0
   for (let i = 0; i < values.length; i += 1) {
@@ -835,6 +856,11 @@ function axisDomain(
   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: ChartSpec, theme: 'light' | 'dark' = 'light'): ChartGeometry {
   const width = spec.width ?? 520
   const height = spec.height ?? 300