@svgrid/grid 3.0.2 → 3.0.4

package/src/ai.ts

@@ -27,6 +27,9 @@
 
 import type { RowData, SvGridApi, TableFeatures } from './index'
 import { getExportProvider } from './export-provider'
+import { validateChartSpec, type ChartDiagnostic } from './chart-validate'
+import { chartSummary } from './chart-summary'
+import type { ChartSpec } from './chart-types'
 
 // Export formats an AI export can plan. WRITING the enterprise formats (xlsx /
 // pdf / html / xml / md) needs the export engine from `@svgrid/enterprise`
@@ -68,7 +71,7 @@ export type AIRequest = {
 }
 
 /** Which helper produced a request - carried on {@link AIRequest} for routing and telemetry. */
-export type AITask = 'filter' | 'smart-fill' | 'summarize' | 'classify' | 'export' | 'anomaly' | 'chart'
+export type AITask = 'filter' | 'smart-fill' | 'summarize' | 'classify' | 'export' | 'anomaly' | 'chart' | 'explain-chart'
 
 let provider: AIProvider | null = null
 
@@ -839,16 +842,21 @@ export async function aiFindAnomalies<
  * Chart shapes the model may choose from when planning a visualisation.
  *
  * These are exactly the types the built-in panel can build from a dimension, a
- * measure and an optional split - which is all a chart plan carries. Two
- * families are deliberately absent, because a plan cannot express them:
- * scatter needs a SECOND measure for its y axis, and candlestick / OHLC need
- * four under first/max/min/last. Asking for either would produce a plan the
- * panel renders as an empty frame, which is worse than not offering it.
+ * measure and an optional split - which is all a chart plan carries. Scatter
+ * is deliberately absent, because a plan cannot express its SECOND measure.
+ * A candlestick can be asked for: the panel finds the open / high / low /
+ * close / volume columns by name, so the plan only needs a date dimension.
  */
 export type AIChartType =
   | 'bar' | 'line' | 'area' | 'pie'
   | 'treemap' | 'funnel' | 'waterfall' | 'radar'
   | 'heatmap' | 'boxplot' | 'gauge' | 'calendar' | 'sankey'
+  | 'histogram' | 'lollipop' | 'pareto' | 'sunburst' | 'radial-bar' | 'radial-column' | 'nightingale' | 'bullet' | 'chord' | 'stream'
+  | 'candlestick'
+
+/** The indicators a chart plan may ask for on a candlestick. */
+export type AIChartIndicator = 'volume' | 'rsi' | 'macd' | 'stochastic' | 'atr' | 'obv' | 'sma' | 'ema' | 'bb' | 'vwap'
+const AI_INDICATORS: AIChartIndicator[] = ['volume', 'rsi', 'macd', 'stochastic', 'atr', 'obv', 'sma', 'ema', 'bb', 'vwap']
 
 /** A chart the model proposed: its type, and the fields to plot. */
 export type AIChartPlan = {
@@ -859,14 +867,26 @@ export type AIChartPlan = {
   series: string | null
   /** Measure (value-axis) column field, or null. */
   measure: string | null
-  reduce: 'sum' | 'avg' | 'count'
+  reduce: AIChartReduce
   stacked: boolean
   logScale: boolean
   timeAxis: boolean
   valueFormat: 'number' | 'currency' | 'percent'
+  /** Calendar unit to group a date dimension by, or null for exact values. */
+  bucket: 'day' | 'week' | 'month' | 'quarter' | 'year' | null
+  /** Candlestick only: indicator panes and overlays to add. */
+  indicators?: AIChartIndicator[]
   rationale: string
+  /** With `apply`: what `validateChartSpec` flagged as an error on the spec
+   *  the panel built from the plan, empty when it drew cleanly. */
+  diagnostics?: ChartDiagnostic[]
 }
 
+/** The reducers a chart plan may name: the panel's full list. */
+export type AIChartReduce =
+  | 'sum' | 'avg' | 'count' | 'min' | 'max' | 'median' | 'p90' | 'first' | 'last' | 'countDistinct'
+const AI_REDUCERS: AIChartReduce[] = ['sum', 'avg', 'count', 'min', 'max', 'median', 'p90', 'first', 'last', 'countDistinct']
+
 /** 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. */
@@ -893,15 +913,17 @@ export async function aiChart<
     `into a strict-JSON chart plan the grid can render.\n\n` +
     `Columns:\n${schemaToPromptBlock(schema)}\n\n` +
     `Output JSON schema:\n` +
-    `{ "type": "bar"|"line"|"area"|"pie"|"treemap"|"funnel"|"waterfall"|"radar"|"heatmap"|"boxplot"|"gauge"|"calendar"|"sankey", ` +
+    `{ "type": "bar"|"line"|"area"|"pie"|"treemap"|"funnel"|"waterfall"|"radar"|"heatmap"|"boxplot"|"gauge"|"calendar"|"sankey"|"histogram"|"lollipop"|"pareto"|"sunburst"|"radial-bar"|"radial-column"|"nightingale"|"bullet"|"chord"|"stream"|"candlestick", ` +
     `"dimension": "<a categorical column to group by>", ` +
     `"series": "<a second categorical column to split into series, or null>", ` +
     `"measure": "<a numeric column to aggregate>", ` +
-    `"reduce": "sum"|"avg"|"count", ` +
+    `"reduce": "sum"|"avg"|"count"|"min"|"max"|"median"|"p90"|"first"|"last"|"countDistinct", ` +
+    `"bucket": "day"|"week"|"month"|"quarter"|"year"|null, ` +
     `"stacked": true|false, ` +
     `"logScale": true|false, ` +
     `"timeAxis": true|false, ` +
     `"valueFormat": "number"|"currency"|"percent", ` +
+    `"indicators": ["volume"|"rsi"|"macd"|"stochastic"|"atr"|"obv"|"sma"|"ema"|"bb"|"vwap", ...] (candlestick only, else omit), ` +
     `"rationale": "<one-sentence explanation>" }\n\n` +
     `Rules: pick "dimension" and "series" from text/date columns and "measure" ` +
     `from a numeric column; use only column names from the list above; ` +
@@ -914,9 +936,17 @@ export async function aiChart<
     `number vs a target -> gauge (leave "dimension" null); a year of daily ` +
     `activity -> calendar (dimension must be a date column); flow between two ` +
     `things -> sankey (needs "series": dimension is the source, series the ` +
-    `target). ` +
+    `target); flows between groups round a circle -> chord (needs "series"); ` +
+    `frequency/how many fall in each range -> histogram (leave "dimension" null); ` +
+    `vital few/80-20/biggest contributors -> pareto; drilldown/rings/nested share -> sunburst; ` +
+    `progress rings/circular -> radial-bar; polar/rose -> nightingale or radial-column; ` +
+    `actual vs target per item -> bullet; layered over time/stream -> stream (needs "series"); ` +
+    `price/candles/OHLC/stock/ticker -> candlestick (dimension is the date column; the open/high/low/close/volume columns are found by name), ` +
+    `with "volume"/"RSI"/"MACD"/"Bollinger"/"moving average" -> indicators. ` +
     `"stacked"/"stack" -> stacked:true; "log"/"logarithmic" -> logScale:true; ` +
     `"over time"/"by date"/a date dimension -> timeAxis:true; ` +
+    `"monthly"/"per month"/"by month" -> bucket:"month" (likewise daily/weekly/quarterly/yearly), else bucket:null; ` +
+    `"median"/"typical" -> reduce:"median"; "highest"/"peak" -> "max"; "lowest" -> "min"; "unique"/"distinct" -> "countDistinct"; ` +
     `money/revenue/price/$ -> valueFormat:"currency"; rate/%/share -> valueFormat:"percent"; ` +
     `else valueFormat:"number". default reduce is "sum". ` +
     `Return JSON only, no prose.\n\n` +
@@ -935,6 +965,8 @@ export async function aiChart<
     'bar', 'line', 'area', 'pie',
     'treemap', 'funnel', 'waterfall', 'radar',
     'heatmap', 'boxplot', 'gauge', 'calendar', 'sankey',
+    'histogram', 'lollipop', 'pareto', 'sunburst', 'radial-bar', 'radial-column', 'nightingale', 'bullet', 'chord', 'stream',
+    'candlestick',
   ]
   plan.type = CHART_TYPES.includes(plan.type) ? plan.type : 'bar'
   plan.dimension = plan.dimension && valid.has(plan.dimension) ? plan.dimension : null
@@ -948,14 +980,28 @@ export async function aiChart<
   // a chart the data cannot make. Fall back to a bar, which any dimension and
   // measure can draw, rather than showing nothing and blaming the request.
   const dateFields = new Set(schema.filter((c) => c.type === 'date').map((c) => c.field))
-  const needsSplit = plan.type === 'heatmap' || plan.type === 'sankey'
+  const needsSplit = plan.type === 'heatmap' || plan.type === 'sankey' || plan.type === 'chord' || plan.type === 'stream'
   if (needsSplit && !plan.series) plan.type = 'bar'
   if (plan.type === 'calendar' && !(plan.dimension && dateFields.has(plan.dimension))) plan.type = 'bar'
+  // A candlestick needs a date to run along and four prices to draw; the
+  // panel finds the price columns by name, so the shape check is the count.
+  if (plan.type === 'candlestick' && !(plan.dimension && dateFields.has(plan.dimension) && numericFields.size >= 4)) plan.type = 'bar'
+  plan.indicators = plan.type === 'candlestick' && Array.isArray(plan.indicators)
+    ? plan.indicators.filter((k): k is AIChartIndicator => AI_INDICATORS.includes(k))
+    : undefined
+  if (plan.indicators === undefined) delete plan.indicators
   // A gauge is one number: it has no category axis, so a dimension is noise.
-  if (plan.type === 'gauge') plan.dimension = null
-  if (plan.type !== 'gauge' && !plan.dimension) plan.type = 'bar'
-
-  plan.reduce = ['sum', 'avg', 'count'].includes(plan.reduce) ? plan.reduce : 'sum'
+  // A histogram bins the measure itself, so a dimension is noise there too.
+  if (plan.type === 'gauge' || plan.type === 'histogram') plan.dimension = null
+  if (plan.type !== 'gauge' && plan.type !== 'histogram' && !plan.dimension) plan.type = 'bar'
+
+  plan.reduce = AI_REDUCERS.includes(plan.reduce) ? plan.reduce : 'sum'
+  // A bucket only means something on a date dimension.
+  const BUCKETS = ['day', 'week', 'month', 'quarter', 'year'] as const
+  plan.bucket =
+    plan.bucket && (BUCKETS as ReadonlyArray<string>).includes(plan.bucket) && plan.dimension && dateFields.has(plan.dimension)
+      ? plan.bucket
+      : null
   plan.stacked = plan.stacked === true
   plan.logScale = plan.logScale === true
   plan.timeAxis = plan.timeAxis === true
@@ -975,12 +1021,61 @@ export async function aiChart<
       logScale: plan.logScale,
       timeAxis: plan.timeAxis,
       valueFormat: plan.valueFormat,
+      ...(plan.indicators ? { indicators: plan.indicators } : {}),
+      bucket: plan.bucket,
     })
+    // The panel built a spec from the plan; if it cannot draw as intended,
+    // say so on the plan rather than showing an empty frame in silence.
+    const spec = (api as unknown as { getChartSpec?: () => unknown }).getChartSpec?.()
+    if (spec) plan.diagnostics = validateChartSpec(spec).filter((d) => d.severity === 'error')
   }
 
   return plan
 }
 
+/** What `aiExplainChart` returns: the grounded summary and the model's insights. */
+export type AIChartExplanation = {
+  /** The plain-language reading of the chart (`chartSummary`), as the model saw it. */
+  summary: string
+  /** Two to three observations the model added: comparisons, outliers, what to look at next. */
+  insights: string[]
+}
+
+/** Options for `aiExplainChart`. */
+export type AIExplainChartOptions = {
+  /** The spec to explain. Default: the grid panel's active chart. */
+  spec?: ChartSpec
+  signal?: AbortSignal
+}
+
+/**
+ * Explain a chart in plain words. The prompt is grounded on `chartSummary`
+ * (the same sentence a screen reader hears) plus a compact table of the
+ * first 50 categories, so the model comments on numbers it was given rather
+ * than on an image. Returns the summary and up to three insights.
+ */
+export async function aiExplainChart<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(api: SvGridApi<TFeatures, TData>, opts: AIExplainChartOptions = {}): Promise<AIChartExplanation> {
+  const spec = opts.spec ?? (api as unknown as { getChartSpec?: () => ChartSpec | null }).getChartSpec?.() ?? null
+  if (!spec) return { summary: 'No chart to explain.', insights: [] }
+  const summary = chartSummary(spec)
+  const cats = spec.categories.slice(0, 50)
+  const table = cats.length
+    ? `${['category', ...spec.series.map((s) => s.label)].join('\t')}\n` +
+      cats.map((c, i) => [c, ...spec.series.map((s) => String(s.values[i] ?? ''))].join('\t')).join('\n')
+    : ''
+  const prompt =
+    `You are explaining a ${spec.type} chart to a busy reader.\n\n` +
+    `Reading of the chart: ${summary}\n\n` +
+    (table ? `Data (first ${cats.length} categories, tab separated):\n${table}\n\n` : '') +
+    `Return strict JSON only: { "insights": ["<2-3 short observations a reader would miss at a glance: comparisons, outliers, what to look at next>"] }`
+  const out = await callJSON<{ insights?: unknown }>({ prompt, task: 'explain-chart', signal: opts.signal, maxOutputTokens: 300 })
+  const insights = Array.isArray(out.insights) ? out.insights.filter((x): x is string => typeof x === 'string').slice(0, 3) : []
+  return { summary, insights }
+}
+
 /**
  * Wire the grid's chart-panel AI button to the model: registers a handler (via
  * `api.setChartAiHandler`) that runs `aiChart` and returns the plan for the
@@ -1008,9 +1103,13 @@ export function enableAiCharting<
       logScale: plan.logScale,
       timeAxis: plan.timeAxis,
       valueFormat: plan.valueFormat,
+      bucket: plan.bucket,
       rationale: plan.rationale,
     }
   })
+  // And the Explain button beside it.
+  const explain = api as unknown as { setChartExplainHandler?: (fn: (() => Promise<AIChartExplanation | null>) | null) => void }
+  explain.setChartExplainHandler?.(() => aiExplainChart(api))
 }
 
 /**
@@ -1021,8 +1120,9 @@ export function disableAiCharting<
   TFeatures extends TableFeatures,
   TData extends RowData,
 >(api: SvGridApi<TFeatures, TData>): void {
-  const hook = api as unknown as { setChartAiHandler?: (fn: null) => void }
+  const hook = api as unknown as { setChartAiHandler?: (fn: null) => void; setChartExplainHandler?: (fn: null) => void }
   hook.setChartAiHandler?.(null)
+  hook.setChartExplainHandler?.(null)
 }
 
 // ---------------------------------------------------------------------------
@@ -1060,6 +1160,17 @@ export const mockAIProvider: AIProvider = async (req) => {
   if (req.task === 'chart') {
     return JSON.stringify(buildMockChart(req.prompt))
   }
+  if (req.task === 'explain-chart') {
+    // Two canned observations round the reading the prompt was grounded on.
+    const reading = /Reading of the chart: ([^\n]+)/.exec(req.prompt)?.[1] ?? ''
+    const rises = /rises/.test(reading)
+    return JSON.stringify({
+      insights: [
+        rises ? 'The growth is front-loaded: the early categories carry most of the change.' : 'The movement is gradual with no single category driving it.',
+        'Compare the peak against the same category a period earlier before reading it as a trend.',
+      ],
+    })
+  }
   return '{}'
 }
 
@@ -1073,7 +1184,18 @@ function buildMockChart(prompt: string): AIChartPlan {
   // can reach the same charts a model can. Ordered most-specific first: "share
   // of the pipeline" is a funnel request, not a pie one.
   const type: AIChartType =
-    /\bfunnel\b|drop.?off|conversion|\bstages?\b|pipeline/.test(q) ? 'funnel'
+    /\bcandle|\bohlc\b|stock price|price chart|\bticker\b/.test(q) ? 'candlestick'
+    : /\bhistogram\b|frequenc|how many fall|bucket(?:ed)? by value/.test(q) ? 'histogram'
+    : /\bpareto\b|80.?20|vital few|biggest contributors/.test(q) ? 'pareto'
+    : /\bsunburst\b|\brings?\b|drill.?down/.test(q) ? 'sunburst'
+    : /\bchord\b/.test(q) ? 'chord'
+    : /\bstream\b|layered over time/.test(q) ? 'stream'
+    : /\bbullet\b|actual vs target|against (?:a |the )?target per/.test(q) ? 'bullet'
+    : /\bnightingale\b|\brose\b|\bpolar\b/.test(q) ? 'nightingale'
+    : /radial (?:bar|progress)|progress rings?|circular progress/.test(q) ? 'radial-bar'
+    : /radial column/.test(q) ? 'radial-column'
+    : /\blollipop\b/.test(q) ? 'lollipop'
+    : /\bfunnel\b|drop.?off|conversion|\bstages?\b|pipeline/.test(q) ? 'funnel'
     : /\bwaterfall\b|running total|contribution|\bbridge\b/.test(q) ? 'waterfall'
     : /\btree ?map\b|nested|hierarch/.test(q) ? 'treemap'
     : /\bradar\b|spider|multi.?measure/.test(q) ? 'radar'
@@ -1100,12 +1222,24 @@ function buildMockChart(prompt: string): AIChartPlan {
   // check downgrades them to a bar, so the mock would answer "heatmap" with a
   // bar chart and look broken rather than offline.
   const series =
-    /\b(split|stack(?:ed)?|by product|by category|per)\b/.test(q) || type === 'heatmap' || type === 'sankey'
+    /\b(split|stack(?:ed)?|by product|by category|per)\b/.test(q) || type === 'heatmap' || type === 'sankey' || type === 'chord' || type === 'stream'
       ? (textFields.find((t) => t !== dimension) ?? null)
       : null
   const measure = numberFields.find((n) => q.includes(n.toLowerCase())) ?? numberFields[0] ?? null
-  const reduce: 'sum' | 'avg' | 'count' =
-    /\b(average|avg|mean)\b/.test(q) ? 'avg' : /\b(count|number of|how many)\b/.test(q) ? 'count' : 'sum'
+  const reduce: AIChartReduce =
+    /\b(average|avg|mean)\b/.test(q) ? 'avg'
+    : /\b(median|typical)\b/.test(q) ? 'median'
+    : /\b(highest|peak|max(?:imum)?)\b/.test(q) ? 'max'
+    : /\b(lowest|min(?:imum)?)\b/.test(q) ? 'min'
+    : /\b(unique|distinct)\b/.test(q) ? 'countDistinct'
+    : /\b(count|number of|how many)\b/.test(q) ? 'count' : 'sum'
+  const bucket: AIChartPlan['bucket'] =
+    /\b(monthly|per month|by month|each month)\b/.test(q) ? 'month'
+    : /\b(weekly|per week|by week|each week)\b/.test(q) ? 'week'
+    : /\b(daily|per day|by day|each day)\b/.test(q) ? 'day'
+    : /\b(quarterly|per quarter|by quarter)\b/.test(q) ? 'quarter'
+    : /\b(yearly|annually|per year|by year)\b/.test(q) ? 'year'
+    : null
   const stacked = /\bstack(ed)?\b/.test(q)
   const logScale = /\b(log|logarithmic)\b/.test(q)
   const timeAxis = /\b(over time|by date|by day|by month|by week|time series|timeline|trend)\b/.test(q)
@@ -1116,12 +1250,22 @@ function buildMockChart(prompt: string): AIChartPlan {
         ? 'percent'
         : 'number'
 
+  // A candlestick runs along a DATE, and the indicators are named in the request.
+  const dateField = typed.find((f) => f.type === 'date')?.name ?? null
+  const indicators: AIChartIndicator[] | undefined = type === 'candlestick'
+    ? ([
+        /\bvolume\b/.test(q) && 'volume', /\brsi\b|relative strength/.test(q) && 'rsi', /\bmacd\b/.test(q) && 'macd',
+        /\bstochastic\b/.test(q) && 'stochastic', /\batr\b|true range/.test(q) && 'atr', /\bobv\b|on.balance/.test(q) && 'obv',
+        /bollinger|\bbands?\b/.test(q) && 'bb', /\bvwap\b/.test(q) && 'vwap', /\bema\b|exponential/.test(q) && 'ema', /\bsma\b|moving average/.test(q) && 'sma',
+      ].filter(Boolean) as AIChartIndicator[])
+    : undefined
   return {
-    type, dimension, series, measure, reduce, stacked, logScale, timeAxis, valueFormat,
+    type, dimension: type === 'candlestick' ? (dateField ?? dimension) : dimension, series, measure, reduce, stacked, logScale, timeAxis, valueFormat, bucket,
+    ...(indicators?.length ? { indicators } : {}),
     rationale:
       `${type} chart of ${reduce}(${measure ?? 'value'}) by ${dimension ?? 'category'}` +
       `${series ? `, split by ${series}` : ''}${stacked ? ', stacked' : ''}` +
-      `${logScale ? ', log scale' : ''}${timeAxis ? ', date axis' : ''} (mock - wire a real model for genuine parsing).`,
+      `${logScale ? ', log scale' : ''}${timeAxis ? ', date axis' : ''}${bucket ? `, by ${bucket}` : ''} (mock - wire a real model for genuine parsing).`,
   }
 }
 

package/src/aria.d.ts

@@ -0,0 +1,11 @@
+// `aria-description` (ARIA 1.3) is what the chart uses to hand a screen
+// reader its plain-language summary. Svelte's element typings predate it,
+// so this adds the attribute to every element's ARIA set rather than casting
+// at the one use site.
+import 'svelte/elements'
+
+declare module 'svelte/elements' {
+  interface AriaAttributes {
+    'aria-description'?: string | null | undefined
+  }
+}

package/src/build-api.coverage.test.ts

@@ -177,6 +177,190 @@ describe("SvGridApi - cell selection", () => {
   });
 });
 
+describe("SvGridApi - Handsontable's selection readers", () => {
+  it("getSelectedLast keeps the orientation the selection was made in", async () => {
+    const { api, destroy } = await mountGrid();
+    try {
+      // Programmatic ranges are normalised on the way in, so the orientation
+      // has to come from a gesture: anchor at (2,1), then extend up-left.
+      api.selectCells([[2, 1, 2, 1]]);
+      await flush();
+      api.getCommandContext().extendSelection(0, 0);
+      await flush();
+      expect(api.getSelected()).toEqual([[0, 0, 2, 1]]);
+      expect(api.getSelectedLast()).toEqual([2, 1, 0, 0]);
+      const last = api.getSelectedRangeLast();
+      expect(last?.from).toEqual({ row: 2, col: 1 });
+      expect(last?.to).toEqual({ row: 0, col: 0 });
+    } finally {
+      destroy();
+    }
+  });
+
+  it("getSelectedRange lists every rectangle oldest first, the active cell as its highlight", async () => {
+    const { api, destroy } = await mountGrid();
+    try {
+      api.selectCells([[0, 0, 1, 1], [3, 2, 4, 2]]);
+      await flush();
+      const ranges = api.getSelectedRange();
+      expect(ranges?.map((r) => [r.from, r.to])).toEqual([
+        [{ row: 0, col: 0 }, { row: 1, col: 1 }],
+        [{ row: 3, col: 2 }, { row: 4, col: 2 }],
+      ]);
+      // The active cell sits in the last range and highlights only that one.
+      expect(ranges?.[1]?.highlight).toEqual({ row: 3, col: 2 });
+      expect(ranges?.[0]?.highlight).toEqual({ row: 0, col: 0 });
+    } finally {
+      destroy();
+    }
+  });
+
+  it("returns undefined, as Handsontable does, when nothing is selected", async () => {
+    const { api, destroy } = await mountGrid();
+    try {
+      expect(api.getSelectedLast()).toBeUndefined();
+      expect(api.getSelectedRange()).toBeUndefined();
+      expect(api.getSelectedRangeLast()).toBeUndefined();
+    } finally {
+      destroy();
+    }
+  });
+
+  it("reports nothing selected when cell selection is off, whatever cell has focus", async () => {
+    // selectable={false} is observable through getSelected() staying [];
+    // the focused cell is getActiveCell()'s business, not a selection.
+    const { api, destroy } = await mountGrid({ enableCellSelection: false });
+    try {
+      api.getCommandContext().setActiveCell(1, 2);
+      await flush();
+      expect(api.getSelected()).toEqual([]);
+      expect(api.getSelectedLast()).toBeUndefined();
+      expect(api.getSelectedRange()).toBeUndefined();
+      expect(api.getSelectedRangeLast()).toBeUndefined();
+    } finally {
+      destroy();
+    }
+  });
+});
+
+describe("SvGridApi - row heights", () => {
+  it("getRowHeight reads the declared height until one is set", async () => {
+    const { api, destroy } = await mountGrid({ rowHeight: 24 });
+    try {
+      expect(api.getRowHeight(2)).toBe(24);
+      api.setRowHeight(2, 52);
+      await flush();
+      expect(api.getRowHeight(2)).toBe(52);
+      expect(api.getRowHeight(1)).toBe(24);
+      api.setRowHeight(2, null);
+      await flush();
+      expect(api.getRowHeight(2)).toBe(24);
+    } finally {
+      destroy();
+    }
+  });
+
+  it("a height belongs to its row: it follows a sort and survives new data", async () => {
+    // Keyed by index, a resized row snapped back on every data change and
+    // the height stayed in the slot when the rows were sorted.
+    const { api, destroy } = await mountGrid({ rowHeight: 24 });
+    try {
+      api.setRowHeight(0, 60); // Ada
+      await flush();
+      api.setSort("name", "asc");
+      await flush();
+      const rows = api.getDisplayedRows() as Row[];
+      const ada = rows.findIndex((r) => r.name === "Ada Lovelace");
+      expect(ada).toBeGreaterThan(-1);
+      expect(api.getRowHeight(ada)).toBe(60);
+      for (let i = 0; i < rows.length; i += 1) if (i !== ada) expect(api.getRowHeight(i)).toBe(24);
+
+      // A data change: a row added on top shifts every index by one.
+      api.addRow({ id: 9, name: "Aaron", team: "QA", salary: 1 } as Row, "top");
+      await flush();
+      const again = (api.getDisplayedRows() as Row[]).findIndex((r) => r.name === "Ada Lovelace");
+      expect(again).toBe(ada + 1);
+      expect(api.getRowHeight(again)).toBe(60);
+      expect(api.getRowHeight(ada)).toBe(24);
+    } finally {
+      destroy();
+    }
+  });
+});
+
+describe("SvGridApi - collapsed columns and rows", () => {
+  it("a collapsed column keeps its index and its width and takes no room", async () => {
+    const { api, target, destroy } = await mountGrid();
+    try {
+      expect(api.isColumnCollapsed("team")).toBe(false);
+      api.setColumnCollapsed("team", true);
+      await flush();
+      expect(api.isColumnCollapsed("team")).toBe(true);
+      // Still the second column: nothing after it shifted.
+      expect(api.getCommandContext().columnIdAt(1)).toBe("team");
+      expect(api.getCommandContext().columnIdAt(2)).toBe("salary");
+      expect(api.getColumnWidths().team).toBe(0);
+      const th = target.querySelector('[data-svgrid-header-col="team"]')!;
+      expect(th.classList.contains("sv-grid-column-collapsed")).toBe(true);
+      expect(target.querySelectorAll("td.sv-grid-cell-collapsed").length).toBe(baseRows.length);
+      api.setColumnCollapsed("team", false);
+      await flush();
+      expect(api.getColumnWidths().team).toBe(160);
+      expect(target.querySelectorAll("td.sv-grid-cell-collapsed").length).toBe(0);
+    } finally {
+      destroy();
+    }
+  });
+
+  it("a collapsed row is 0 high, leaves the flow, and follows its row through a sort", async () => {
+    const { api, target, destroy } = await mountGrid({ rowHeight: 24 });
+    try {
+      api.setRowCollapsed(0, true); // Ada
+      await flush();
+      expect(api.isRowCollapsed(0)).toBe(true);
+      expect(api.getRowHeight(0)).toBe(0);
+      expect(target.querySelectorAll("tr.sv-grid-row-collapsed").length).toBe(1);
+      api.setSort("name", "desc");
+      await flush();
+      const rows = api.getDisplayedRows() as Row[];
+      const ada = rows.findIndex((r) => r.name === "Ada Lovelace");
+      expect(api.isRowCollapsed(ada)).toBe(true);
+      expect(api.isRowCollapsed(0)).toBe(false);
+      api.setRowCollapsed(ada, false);
+      await flush();
+      expect(api.getRowHeight(ada)).toBe(24);
+      expect(target.querySelectorAll("tr.sv-grid-row-collapsed").length).toBe(0);
+    } finally {
+      destroy();
+    }
+  });
+
+  it("the arrow keys step over collapsed rows and columns", async () => {
+    const { api, target, destroy } = await mountGrid();
+    try {
+      api.setColumnCollapsed("team", true);
+      api.setRowCollapsed(1, true);
+      await flush();
+      const cmd = api.getCommandContext();
+      cmd.setActiveCell(0, 0);
+      await flush();
+      const root = target.querySelector<HTMLElement>("table.sv-grid-table")!;
+      root.focus();
+      root.dispatchEvent(new KeyboardEvent("keydown", { key: "ArrowRight", bubbles: true, cancelable: true }));
+      await flush();
+      expect(api.getActiveCell()).toMatchObject({ rowIndex: 0, colIndex: 2 });
+      root.dispatchEvent(new KeyboardEvent("keydown", { key: "ArrowDown", bubbles: true, cancelable: true }));
+      await flush();
+      expect(api.getActiveCell()).toMatchObject({ rowIndex: 2, colIndex: 2 });
+      root.dispatchEvent(new KeyboardEvent("keydown", { key: "ArrowLeft", bubbles: true, cancelable: true }));
+      await flush();
+      expect(api.getActiveCell()).toMatchObject({ rowIndex: 2, colIndex: 0 });
+    } finally {
+      destroy();
+    }
+  });
+});
+
 describe("SvGridApi - row mutations", () => {
   it("addRow appends to the bottom by default", async () => {
     const { api, destroy } = await mountGrid();