@svgrid/grid 2.6.20 → 2.6.22

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

package/src/column-groups.ts

@@ -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.