@svgrid/grid 3.0.2 → 3.0.4

package/dist/ai.d.ts

@@ -25,6 +25,8 @@
  * so they add nothing to the base bundle unless you actually use them.
  */
 import type { RowData, SvGridApi, TableFeatures } from './index.js';
+import { type ChartDiagnostic } from './chart-validate.js';
+import type { ChartSpec } from './chart-types.js';
 type ExportFormat = 'xlsx' | 'xls' | 'pdf' | 'csv' | 'tsv' | 'html' | 'json' | 'xml' | 'md';
 /**
  * Shape every consumer-provided model adapter must implement. Keeping this
@@ -53,7 +55,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';
+export type AITask = 'filter' | 'smart-fill' | 'summarize' | 'classify' | 'export' | 'anomaly' | 'chart' | 'explain-chart';
 /**
  * Register the model adapter every AI call will route through. Call once
  * at app boot. Passing `null` clears the provider and AI calls revert to
@@ -270,13 +272,14 @@ export declare function aiFindAnomalies<TFeatures extends TableFeatures, TData e
  * 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';
+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';
 /** A chart the model proposed: its type, and the fields to plot. */
 export type AIChartPlan = {
     type: AIChartType;
@@ -286,13 +289,22 @@ 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';
 /** 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. */
@@ -305,6 +317,26 @@ export type AIChartOptions = {
  * `apply: true`) pushes it into the panel through `api.configureChart`.
  */
 export declare function aiChart<TFeatures extends TableFeatures, TData extends RowData>(api: SvGridApi<TFeatures, TData>, query: string, opts?: AIChartOptions): Promise<AIChartPlan>;
+/** 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 declare function aiExplainChart<TFeatures extends TableFeatures, TData extends RowData>(api: SvGridApi<TFeatures, TData>, opts?: AIExplainChartOptions): Promise<AIChartExplanation>;
 /**
  * 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

package/dist/ai.js

@@ -25,6 +25,8 @@
  * so they add nothing to the base bundle unless you actually use them.
  */
 import { getExportProvider } from './export-provider.js';
+import { validateChartSpec } from './chart-validate.js';
+import { chartSummary } from './chart-summary.js';
 let provider = null;
 /**
  * Register the model adapter every AI call will route through. Call once
@@ -500,6 +502,8 @@ export async function aiFindAnomalies(api, opts = {}) {
         summary: result.summary ?? '',
     };
 }
+const AI_INDICATORS = ['volume', 'rsi', 'macd', 'stochastic', 'atr', 'obv', 'sma', 'ema', 'bb', 'vwap'];
+const AI_REDUCERS = ['sum', 'avg', 'count', 'min', 'max', 'median', 'p90', 'first', 'last', 'countDistinct'];
 /**
  * Translate a natural-language request into a chart plan for the grid's built-in
  * `charting` panel. Validates every field against the real schema, then (with
@@ -511,15 +515,17 @@ export async function aiChart(api, query, opts = {}) {
         `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; ` +
@@ -532,9 +538,17 @@ export async function aiChart(api, query, opts = {}) {
         `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` +
@@ -551,6 +565,8 @@ export async function aiChart(api, query, opts = {}) {
         '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;
@@ -564,17 +580,33 @@ export async function aiChart(api, query, opts = {}) {
     // 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) => 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')
+    // 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.dimension)
+    if (plan.type !== 'gauge' && plan.type !== 'histogram' && !plan.dimension)
         plan.type = 'bar';
-    plan.reduce = ['sum', 'avg', 'count'].includes(plan.reduce) ? plan.reduce : 'sum';
+    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'];
+    plan.bucket =
+        plan.bucket && BUCKETS.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;
@@ -593,10 +625,41 @@ export async function aiChart(api, query, opts = {}) {
             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.getChartSpec?.();
+        if (spec)
+            plan.diagnostics = validateChartSpec(spec).filter((d) => d.severity === 'error');
     }
     return plan;
 }
+/**
+ * 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(api, opts = {}) {
+    const spec = opts.spec ?? api.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({ prompt, task: 'explain-chart', signal: opts.signal, maxOutputTokens: 300 });
+    const insights = Array.isArray(out.insights) ? out.insights.filter((x) => 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
@@ -617,9 +680,13 @@ export function enableAiCharting(api) {
             logScale: plan.logScale,
             timeAxis: plan.timeAxis,
             valueFormat: plan.valueFormat,
+            bucket: plan.bucket,
             rationale: plan.rationale,
         };
     });
+    // And the Explain button beside it.
+    const explain = api;
+    explain.setChartExplainHandler?.(() => aiExplainChart(api));
 }
 /**
  * Remove the natural-language chart handler, hiding the AI button in the chart
@@ -628,6 +695,7 @@ export function enableAiCharting(api) {
 export function disableAiCharting(api) {
     const hook = api;
     hook.setChartAiHandler?.(null);
+    hook.setChartExplainHandler?.(null);
 }
 // ---------------------------------------------------------------------------
 // 8. Mock provider for examples + tests
@@ -662,6 +730,17 @@ export const mockAIProvider = 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 '{}';
 };
 function buildMockChart(prompt) {
@@ -672,19 +751,30 @@ function buildMockChart(prompt) {
     // Mirrors the type hints in the real prompt, so the bundled offline provider
     // 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 = /\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'
-                    : /\bheat ?map\b/.test(q) ? 'heatmap'
-                        : /\bbox ?plot\b|spread|distribution|variance|outlier|percentile|quartile/.test(q) ? 'boxplot'
-                            : /\bgauge\b|\bdial\b|vs target|against target/.test(q) ? 'gauge'
-                                : /\bcalendar\b|daily activity|year of/.test(q) ? 'calendar'
-                                    : /\bsankey\b|\bflow\b/.test(q) ? 'sankey'
-                                        : /\bline\b|\btrend\b|over time/.test(q) ? 'line'
-                                            : /\barea\b/.test(q) ? 'area'
-                                                : /\bpie\b|share|proportion|breakdown/.test(q) ? 'pie'
-                                                    : 'bar';
+    const type = /\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'
+                                                                : /\bheat ?map\b/.test(q) ? 'heatmap'
+                                                                    : /\bbox ?plot\b|spread|distribution|variance|outlier|percentile|quartile/.test(q) ? 'boxplot'
+                                                                        : /\bgauge\b|\bdial\b|vs target|against target/.test(q) ? 'gauge'
+                                                                            : /\bcalendar\b|daily activity|year of/.test(q) ? 'calendar'
+                                                                                : /\bsankey\b|\bflow\b/.test(q) ? 'sankey'
+                                                                                    : /\bline\b|\btrend\b|over time/.test(q) ? 'line'
+                                                                                        : /\barea\b/.test(q) ? 'area'
+                                                                                            : /\bpie\b|share|proportion|breakdown/.test(q) ? 'pie'
+                                                                                                : 'bar';
     const byMatch = q.match(/\bby\s+([a-z0-9_ ]+?)(?:\s+(?:split|stacked|grouped|by|as|,|$))/);
     const pickText = (hint) => {
         if (hint) {
@@ -698,11 +788,22 @@ function buildMockChart(prompt) {
     // Heatmap and sankey are two-dimension charts: without a split the shape
     // 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'
+    const series = /\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 = /\b(average|avg|mean)\b/.test(q) ? 'avg' : /\b(count|number of|how many)\b/.test(q) ? 'count' : 'sum';
+    const reduce = /\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 = /\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);
@@ -711,11 +812,21 @@ function buildMockChart(prompt) {
         : /\b(percent|percentage|%|rate|share)\b/.test(q)
             ? '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 = 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)
+        : 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).`,
     };
 }
 function extractUserRequest(prompt) {

package/dist/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/dist/build-api.js

@@ -2,6 +2,40 @@ import "./sv-grid-scrollbar.js";
 import { untrack } from "svelte";
 import { isGroupRow, getColumnAlign, columnDefMatchesId, } from "./cell-values.js";
 import { hasAdvancedFilterEngine } from "./advanced-filter.svelte.js";
+import { undoHistory, redoHistory } from "./history.js";
+import { buildCommandContext } from "./command-context.js";
+/**
+ * The selection as the user made it: committed ranges first, the active one
+ * last, each keeping its anchor as `from` and its focus as `to`. The active
+ * cell is the highlight of the range it sits in and of no other, which is
+ * how Handsontable reports it and what a range-aware paste needs to know.
+ */
+function selectedRanges(ctx) {
+    const committed = ctx.selectionRanges ?? [];
+    const active = ctx.selectionRange ?? { anchor: null, focus: null };
+    const cursor = ctx.grid.getState().activeCell;
+    const toRange = (r) => {
+        if (!r.anchor || !r.focus)
+            return null;
+        const from = { row: r.anchor.rowIndex, col: r.anchor.colIndex };
+        const to = { row: r.focus.rowIndex, col: r.focus.colIndex };
+        const inside = cursor &&
+            cursor.rowIndex >= Math.min(from.row, to.row) && cursor.rowIndex <= Math.max(from.row, to.row) &&
+            cursor.colIndex >= Math.min(from.col, to.col) && cursor.colIndex <= Math.max(from.col, to.col);
+        const highlight = inside ? { row: cursor.rowIndex, col: cursor.colIndex } : from;
+        return { from, to, highlight };
+    };
+    const out = [];
+    for (const r of committed) {
+        const o = toRange(r);
+        if (o)
+            out.push(o);
+    }
+    const last = toRange(active);
+    if (last)
+        out.push(last);
+    return out;
+}
 export function createGridApi(ctx) {
     function buildApi() {
         const findColumn = (columnId) => ctx.grid.getAllColumns().find((column) => column.id === columnId);
@@ -94,10 +128,26 @@ export function createGridApi(ctx) {
                 ctx.setActiveCell(active.anchor.rowIndex, active.anchor.colIndex);
             },
             getSelected() {
+                // Rectangles only. With cell selection off none is ever recorded and
+                // this stays [], which is how `selectable={false}` is observable from
+                // the API; the focused cell is `getActiveCell()`, not a selection.
                 return ctx
                     .getSelectionRects()
                     .map((r) => [r.minRow, r.minCol, r.maxRow, r.maxCol]);
             },
+            getSelectedLast() {
+                const all = selectedRanges(ctx);
+                const last = all[all.length - 1];
+                return last ? [last.from.row, last.from.col, last.to.row, last.to.col] : undefined;
+            },
+            getSelectedRange() {
+                const all = selectedRanges(ctx);
+                return all.length ? all : undefined;
+            },
+            getSelectedRangeLast() {
+                const all = selectedRanges(ctx);
+                return all[all.length - 1];
+            },
             openChart() {
                 ctx.chartPanelOpen = true;
             },
@@ -116,6 +166,23 @@ export function createGridApi(ctx) {
                 if (ctx.chartingEnabled)
                     ctx.applyChartConfig(config);
             },
+            saveChart(name) {
+                if (ctx.chartingEnabled)
+                    ctx.saveChart(name);
+            },
+            applySavedChart(name) {
+                return ctx.chartingEnabled ? ctx.applySavedChart(name) : false;
+            },
+            removeSavedChart(name) {
+                if (ctx.chartingEnabled)
+                    ctx.removeSavedChart(name);
+            },
+            getSavedCharts() {
+                return ctx.chartingEnabled ? ctx.getSavedCharts() : [];
+            },
+            setChartExplainHandler(handler) {
+                ctx.chartExplainHandler = handler ?? null;
+            },
             setChartAiHandler(handler) {
                 ctx.chartAiHandler = handler ?? null;
             },
@@ -316,6 +383,12 @@ export function createGridApi(ctx) {
             clearFilter(columnId) {
                 ctx.clearColumnFilter(columnId);
             },
+            openContextMenu(event, rowIndex, colIndex) {
+                const columnId = ctx.allColumns[colIndex]?.id;
+                if (columnId == null)
+                    return;
+                ctx.openContextMenu(event, rowIndex, colIndex, columnId);
+            },
             refreshEditorOptions(columnId) {
                 // Async `editorOptions` are cached per column (or per column+row for a
                 // per-row source) so opening an editor twice does not refetch. This
@@ -506,6 +579,31 @@ export function createGridApi(ctx) {
             autosizeColumn(columnId) {
                 ctx.autosizeColumn(columnId);
             },
+            getRowHeight(rowIndex) {
+                const own = ctx.rowResizeHeightPx(rowIndex);
+                if (own != null)
+                    return own;
+                const declared = ctx.props.rowHeight;
+                return typeof declared === "function" ? declared(rowIndex) : (declared ?? 30);
+            },
+            setRowHeight(rowIndex, height) {
+                ctx.setRowResizeHeight(rowIndex, height);
+            },
+            setColumnCollapsed(columnId, collapsed) {
+                ctx.setColumnCollapsed(columnId, collapsed);
+            },
+            isColumnCollapsed(columnId) {
+                return !!ctx.collapsedColumns[columnId];
+            },
+            setRowCollapsed(rowIndex, collapsed) {
+                ctx.setRowCollapsed(rowIndex, collapsed);
+            },
+            getMergedCells() {
+                return (ctx.props.mergedCells ?? []).map((m) => ({ ...m }));
+            },
+            isRowCollapsed(rowIndex) {
+                return ctx.isRowCollapsed(rowIndex);
+            },
             autosizeAllColumns() {
                 ctx.autosizeAllColumns();
             },
@@ -550,28 +648,12 @@ export function createGridApi(ctx) {
                 ctx.grid.setExpanded(() => ({}));
             },
             // ---- Undo / redo (history + pointer)
-            undo() {
-                if (ctx.historyPtr < 0)
-                    return false;
-                const step = ctx.history[ctx.historyPtr];
-                if (!step)
-                    return false;
-                ctx.applyHistoryStep(step, 'undo');
-                ctx.historyPtr -= 1;
-                ctx.historyVersion += 1;
-                return true;
-            },
-            redo() {
-                if (ctx.historyPtr >= ctx.history.length - 1)
-                    return false;
-                const step = ctx.history[ctx.historyPtr + 1];
-                if (!step)
-                    return false;
-                ctx.applyHistoryStep(step, 'redo');
-                ctx.historyPtr += 1;
-                ctx.historyVersion += 1;
-                return true;
-            },
+            undo() { return undoHistory(ctx); },
+            redo() { return redoHistory(ctx); },
+            // Built fresh per call rather than memoized: it is a handful of getters
+            // over `ctx`, and a caller that holds one keeps reading live state
+            // anyway, so caching would only add a slot to keep in sync.
+            getCommandContext() { return buildCommandContext(ctx, false); },
             canUndo() { void ctx.historyVersion; return ctx.historyPtr >= 0; },
             canRedo() { void ctx.historyVersion; return ctx.historyPtr < ctx.history.length - 1; },
             clearHistory() { ctx.history = []; ctx.historyPtr = -1; ctx.historyVersion += 1; },
@@ -715,6 +797,8 @@ export function createGridApi(ctx) {
                             },
                             charts: ctx.getChartsState(),
                             chartActive: ctx.activeChartIndex,
+                            // Only when there is one, for the same snapshot-churn reason.
+                            ...(ctx.savedCharts.length ? { savedCharts: ctx.getSavedCharts() } : {}),
                         }
                         : {}),
                 };
@@ -768,6 +852,8 @@ export function createGridApi(ctx) {
                 if ("advancedFilter" in state) {
                     ctx.advancedFilter = state.advancedFilter ?? null;
                 }
+                if (Array.isArray(state.savedCharts) && ctx.chartingEnabled)
+                    ctx.applySavedCharts(state.savedCharts);
                 if ((state.chart || state.charts) && ctx.chartingEnabled) {
                     if (Array.isArray(state.charts) && state.charts.length) {
                         ctx.applyChartsState(state.charts, state.chartActive);