@pixerate/editor 0.170.0 → 0.172.0

package/dist/chart/index.d.cts

@@ -22,6 +22,7 @@ export * from './recommend.cjs';
 export * from './controller.cjs';
 export * from './commands.cjs';
 export * from './interaction.cjs';
+export * from './tooltip.cjs';
 export * from './mermaid.cjs';
 export * from './ooxml.cjs';
 export * from './tools.cjs';

package/dist/chart/index.d.ts

@@ -22,6 +22,7 @@ export * from './recommend.js';
 export * from './controller.js';
 export * from './commands.js';
 export * from './interaction.js';
+export * from './tooltip.js';
 export * from './mermaid.js';
 export * from './ooxml.js';
 export * from './tools.js';

package/dist/chart/index.js

@@ -47,7 +47,7 @@ import {
   monochromeChartPalette,
   sparklineToSvg,
   summarizeChart
-} from "../chunk-N3ACT6VJ.js";
+} from "../chunk-KPWG3PSW.js";
 import "../chunk-KGRZMHZB.js";
 import {
   CHART_DATE_STEPS,
@@ -55,6 +55,7 @@ import {
   MAX_CHART_LINE_POINTS,
   MAX_CHART_MARKERS,
   chartBoxStats,
+  chartCategoryAtPoint,
   chartDateLabels,
   chartDateToSerial,
   chartHistogram,
@@ -98,7 +99,7 @@ import {
   suggestChartReferences,
   summarizeChartSeries,
   trendNumberText
-} from "../chunk-M52UCHVZ.js";
+} from "../chunk-OJQVKJYD.js";
 import {
   CHART_AXIS_KINDS,
   CHART_AXIS_SCALES,
@@ -1336,6 +1337,71 @@ function chartHitTest(scene, point, measure = (t, s, w = 400) => t.length * s *
   return point.x >= 0 && point.y >= 0 && point.x <= scene.width && point.y <= scene.height ? { kind: "chart" } : null;
 }
 
+// src/chart/tooltip.ts
+var VALUE_FAMILIES = /* @__PURE__ */ new Set(["cartesian", "xy", "pie", "radar", "waterfall", "funnel", "parliament", "slope"]);
+var SLICE_FAMILIES = /* @__PURE__ */ new Set(["pie", "funnel", "parliament"]);
+function valueFormat(spec, series) {
+  return series.format ?? (series.axis === "secondary" ? spec.yAxis2.format : spec.yAxis.format);
+}
+var percentText = (share) => formatChartNumber(share, { style: "percent", decimals: share < 0.1 ? 1 : 0 });
+function item(spec, seriesIndex, index, share) {
+  const family = chartFamily(spec);
+  const series = spec.series[seriesIndex];
+  const value = series.values[index] ?? null;
+  const slice = SLICE_FAMILIES.has(family);
+  let text = formatChartNumber(value, valueFormat(spec, series));
+  if (family === "xy") {
+    const x = series.x?.[index];
+    if (x !== null && x !== void 0) text = `${formatChartNumber(x, spec.xAxis.format)}, ${text}`;
+  }
+  if (share !== void 0) text = `${text} (${percentText(share)})`;
+  return {
+    seriesId: series.id,
+    name: slice ? spec.categories[index] ?? series.name : series.name,
+    color: slice ? series.pointColors?.[index] ?? chartSliceColor(spec, index) : chartPointColor(spec, seriesIndex, index),
+    value,
+    ...share !== void 0 ? { share } : {},
+    text
+  };
+}
+function chartTooltipFor(spec, index, seriesId, anchor = { x: 0, y: 0 }) {
+  const family = chartFamily(spec);
+  if (!VALUE_FAMILIES.has(family)) return null;
+  if (!Number.isInteger(index) || index < 0 || index >= Math.max(spec.categories.length, ...spec.series.map((s) => s.values.length))) return null;
+  const visible = spec.series.map((s, i) => ({ s, i })).filter(({ s }) => !s.hidden && (!seriesId || s.id === seriesId));
+  const present = visible.filter(({ s }) => s.values[index] !== null && s.values[index] !== void 0 && Number.isFinite(s.values[index]));
+  if (!present.length) return null;
+  const shareOf = (s) => {
+    const v = s.values[index];
+    if (spec.stacking === "percent" && family === "cartesian") {
+      const total = spec.series.filter((t) => !t.hidden && t.axis === s.axis).reduce((sum, t) => sum + Math.abs(t.values[index] ?? 0), 0);
+      return total ? Math.abs(v) / total : void 0;
+    }
+    if (family === "pie") {
+      const total = s.values.reduce((sum, t) => sum + (t !== null && t > 0 ? t : 0), 0);
+      return total && v > 0 ? v / total : void 0;
+    }
+    return void 0;
+  };
+  const items = present.map(({ s, i }) => item(spec, i, index, shareOf(s)));
+  const title = family === "xy" ? spec.categories[index] || present[0].s.name : spec.categories[index] ?? "";
+  return { title, index, items, x: anchor.x, y: anchor.y };
+}
+function chartTooltipAt(spec, scene, point, options = {}) {
+  if (options.mode === "category" && scene.categoryScale) {
+    const index = chartCategoryAtPoint(scene, point);
+    if (index !== void 0) return chartTooltipFor(spec, index, void 0, point);
+  }
+  const target = chartHitTest(scene, point, options.measureText ?? estimateChartTextWidth);
+  if (target?.kind === "point") return chartTooltipFor(spec, target.index, target.seriesId, point);
+  if (target?.kind === "category" && scene.categoryScale && options.mode === "category") return chartTooltipFor(spec, target.index, void 0, point);
+  return null;
+}
+function sameChartTooltip(a, b) {
+  if (!a || !b) return a === b;
+  return a.index === b.index && a.items.length === b.items.length && a.items.every((it, i) => it.seriesId === b.items[i].seriesId && it.text === b.items[i].text);
+}
+
 // src/chart/presence.ts
 var ChartPresence = class extends PresenceStore {
 };
@@ -1767,6 +1833,24 @@ function createChartToolProvider(controller, options = {}) {
       return { trendline: line, coefficients: fit.coefficients, r2: fit.r2, equation: fit.equation, points: fit.points };
     }
   };
+  const getTooltip = {
+    name: "get_chart_tooltip",
+    title: "Read a chart tooltip",
+    description: "Returns what a viewer sees when hovering a category (or one series in it): the category label and, for each visible series with a value there, its name, colour, value, share (percent-stacked and pie charts, 0\u20131) and the value as the chart writes it. Returns null for charts without one value per category (histogram, box, treemap, sunburst, sankey, \u2026) or when no visible series has a value there.",
+    inputSchema: {
+      type: "object",
+      properties: { category: CATEGORY_REF, series: { ...SERIES_REF, description: `${SERIES_REF.description} Omit to include every visible series in the category.` } },
+      required: ["category"],
+      additionalProperties: false
+    },
+    annotations: { title: "Read a chart tooltip", ...READ },
+    handler: ({ category, series }) => {
+      const index = categoryIndex(category);
+      const seriesId = series === void 0 ? void 0 : seriesById(series).id;
+      const tooltip = chartTooltipFor(controller.toJSON(), index, seriesId);
+      return tooltip && { title: tooltip.title, index: tooltip.index, items: tooltip.items };
+    }
+  };
   const raceRanking = {
     name: "get_chart_race_ranking",
     title: "Read a bar race ranking",
@@ -2476,7 +2560,7 @@ function createChartToolProvider(controller, options = {}) {
       return { redone, ...redone ? { label } : {} };
     }
   };
-  const reads = [getChart, renderChart, checkColors, recommend, getTrendline, raceRanking, mapRegions, listPresets, exportMermaid, exportOoxml];
+  const reads = [getChart, renderChart, checkColors, recommend, getTrendline, getTooltip, raceRanking, mapRegions, listPresets, exportMermaid, exportOoxml];
   const writes = [
     updateChart,
     setData,
@@ -3246,6 +3330,7 @@ export {
   blendChartScenes,
   canDragChartPoint,
   chartBoxStats,
+  chartCategoryAtPoint,
   chartClientToScene,
   chartColorDistance,
   chartColorInputValue,
@@ -3305,6 +3390,8 @@ export {
   chartToMermaid,
   chartToOoxml,
   chartToSvg,
+  chartTooltipAt,
+  chartTooltipFor,
   chartTreeColumnLabels,
   chartTreeDepth,
   chartTreeFromRows,
@@ -3391,6 +3478,7 @@ export {
   removeChartTreeRow,
   resolveChartSvgPaints,
   sameChartSelection,
+  sameChartTooltip,
   setChartLinkField,
   setChartTreeRowName,
   setChartTreeRowValue,

package/dist/chart/layout-shared.d.cts

@@ -1,5 +1,5 @@
 import { type NiceScale } from './scale.cjs';
-import type { ChartAxis, ChartMark, ChartMarker, ChartRect, ChartScene, ChartSelection, ChartSpec, ChartTheme, ChartValueScale, ChartWarning } from './types.cjs';
+import type { ChartAxis, ChartCategoryScale, ChartMark, ChartMarker, ChartRect, ChartScene, ChartSelection, ChartSpec, ChartTheme, ChartValueScale, ChartWarning } from './types.cjs';
 export type ChartTextMeasure = (text: string, size: number, weight?: number) => number;
 export interface ChartLayoutOptions {
     width: number;
@@ -73,6 +73,7 @@ export interface FamilyResult {
     valueScale?: ChartValueScale;
     valueScale2?: ChartValueScale;
     xScale?: ChartValueScale;
+    categoryScale?: ChartCategoryScale;
     percent?: boolean;
 }
 export type ChartSceneBase = Omit<ChartScene, 'marks' | 'warnings' | 'theme' | 'width' | 'height'>;

package/dist/chart/layout-shared.d.ts

@@ -1,5 +1,5 @@
 import { type NiceScale } from './scale.js';
-import type { ChartAxis, ChartMark, ChartMarker, ChartRect, ChartScene, ChartSelection, ChartSpec, ChartTheme, ChartValueScale, ChartWarning } from './types.js';
+import type { ChartAxis, ChartCategoryScale, ChartMark, ChartMarker, ChartRect, ChartScene, ChartSelection, ChartSpec, ChartTheme, ChartValueScale, ChartWarning } from './types.js';
 export type ChartTextMeasure = (text: string, size: number, weight?: number) => number;
 export interface ChartLayoutOptions {
     width: number;
@@ -73,6 +73,7 @@ export interface FamilyResult {
     valueScale?: ChartValueScale;
     valueScale2?: ChartValueScale;
     xScale?: ChartValueScale;
+    categoryScale?: ChartCategoryScale;
     percent?: boolean;
 }
 export type ChartSceneBase = Omit<ChartScene, 'marks' | 'warnings' | 'theme' | 'width' | 'height'>;

package/dist/chart/layout.d.cts

@@ -18,6 +18,11 @@ export declare function chartValueAtPoint(scene: ChartScene, point: {
     x: number;
     y: number;
 }, secondary?: boolean): number | undefined;
+/** The category index under a scene point inside the plot of a bar, line or area chart, or `undefined`. */
+export declare function chartCategoryAtPoint(scene: ChartScene, point: {
+    x: number;
+    y: number;
+}): number | undefined;
 /** The x value at a scene point on a scatter or bubble chart, or `undefined` without a numeric x axis. */
 export declare function chartXAtPoint(scene: ChartScene, point: {
     x: number;

package/dist/chart/layout.d.ts

@@ -18,6 +18,11 @@ export declare function chartValueAtPoint(scene: ChartScene, point: {
     x: number;
     y: number;
 }, secondary?: boolean): number | undefined;
+/** The category index under a scene point inside the plot of a bar, line or area chart, or `undefined`. */
+export declare function chartCategoryAtPoint(scene: ChartScene, point: {
+    x: number;
+    y: number;
+}): number | undefined;
 /** The x value at a scene point on a scatter or bubble chart, or `undefined` without a numeric x axis. */
 export declare function chartXAtPoint(scene: ChartScene, point: {
     x: number;

package/dist/chart/tooltip.d.cts

@@ -0,0 +1,53 @@
+import { type ChartTextMeasure } from './layout-shared.cjs';
+import type { ChartScene, ChartSpec, ChartValue } from './types.cjs';
+/** `point`: the bar, point or slice under the pointer. `category`: every series in the category under the pointer (bar, line and area charts; other charts fall back to `point`). */
+export type ChartTooltipMode = 'point' | 'category';
+export interface ChartTooltipItem {
+    seriesId: string;
+    /** The series name (the category label on pie, funnel and parliament charts). */
+    name: string;
+    color: string;
+    value: ChartValue;
+    /** Share of the category (percent-stacked charts) or of the series (pie and donut charts), 0–1. */
+    share?: number;
+    /** The value as the chart writes it: the series format, else its value axis format. */
+    text: string;
+}
+export interface ChartTooltip {
+    /** The category label (the series name on scatter and bubble charts with x values). */
+    title: string;
+    /** The category the items belong to. */
+    index: number;
+    items: ChartTooltipItem[];
+    /** Where to anchor the tooltip, in scene pixels (the pointer). */
+    x: number;
+    y: number;
+}
+export interface ChartTooltipOptions {
+    /** Default `point`. */
+    mode?: ChartTooltipMode;
+    /** Text width for hit-testing labels (default: an estimate). */
+    measureText?: ChartTextMeasure;
+}
+/**
+ * What a tooltip shows for one category: the category label and each visible series' value
+ * there, written as the chart writes it. `seriesId` narrows it to one series (one bar, point
+ * or slice). Returns `null` for charts whose marks are not one value per category (histogram,
+ * box, treemap and sunburst with a tree, sankey, …), for an index out of range, or when no
+ * visible series has a value there.
+ */
+export declare function chartTooltipFor(spec: ChartSpec, index: number, seriesId?: string, anchor?: {
+    x: number;
+    y: number;
+}): ChartTooltip | null;
+/**
+ * The tooltip at a scene point (for hover), or `null` when the pointer is over nothing with a
+ * value. In `category` mode, anywhere in a category's band of a bar, line or area chart shows
+ * every series there; elsewhere both modes show the one bar, point or slice under the pointer.
+ */
+export declare function chartTooltipAt(spec: ChartSpec, scene: ChartScene, point: {
+    x: number;
+    y: number;
+}, options?: ChartTooltipOptions): ChartTooltip | null;
+/** Whether two tooltips show the same thing (so a host can skip re-rendering while the pointer moves within a mark). */
+export declare function sameChartTooltip(a: ChartTooltip | null, b: ChartTooltip | null): boolean;

package/dist/chart/tooltip.d.ts

@@ -0,0 +1,53 @@
+import { type ChartTextMeasure } from './layout-shared.js';
+import type { ChartScene, ChartSpec, ChartValue } from './types.js';
+/** `point`: the bar, point or slice under the pointer. `category`: every series in the category under the pointer (bar, line and area charts; other charts fall back to `point`). */
+export type ChartTooltipMode = 'point' | 'category';
+export interface ChartTooltipItem {
+    seriesId: string;
+    /** The series name (the category label on pie, funnel and parliament charts). */
+    name: string;
+    color: string;
+    value: ChartValue;
+    /** Share of the category (percent-stacked charts) or of the series (pie and donut charts), 0–1. */
+    share?: number;
+    /** The value as the chart writes it: the series format, else its value axis format. */
+    text: string;
+}
+export interface ChartTooltip {
+    /** The category label (the series name on scatter and bubble charts with x values). */
+    title: string;
+    /** The category the items belong to. */
+    index: number;
+    items: ChartTooltipItem[];
+    /** Where to anchor the tooltip, in scene pixels (the pointer). */
+    x: number;
+    y: number;
+}
+export interface ChartTooltipOptions {
+    /** Default `point`. */
+    mode?: ChartTooltipMode;
+    /** Text width for hit-testing labels (default: an estimate). */
+    measureText?: ChartTextMeasure;
+}
+/**
+ * What a tooltip shows for one category: the category label and each visible series' value
+ * there, written as the chart writes it. `seriesId` narrows it to one series (one bar, point
+ * or slice). Returns `null` for charts whose marks are not one value per category (histogram,
+ * box, treemap and sunburst with a tree, sankey, …), for an index out of range, or when no
+ * visible series has a value there.
+ */
+export declare function chartTooltipFor(spec: ChartSpec, index: number, seriesId?: string, anchor?: {
+    x: number;
+    y: number;
+}): ChartTooltip | null;
+/**
+ * The tooltip at a scene point (for hover), or `null` when the pointer is over nothing with a
+ * value. In `category` mode, anywhere in a category's band of a bar, line or area chart shows
+ * every series there; elsewhere both modes show the one bar, point or slice under the pointer.
+ */
+export declare function chartTooltipAt(spec: ChartSpec, scene: ChartScene, point: {
+    x: number;
+    y: number;
+}, options?: ChartTooltipOptions): ChartTooltip | null;
+/** Whether two tooltips show the same thing (so a host can skip re-rendering while the pointer moves within a mark). */
+export declare function sameChartTooltip(a: ChartTooltip | null, b: ChartTooltip | null): boolean;

package/dist/chart/types.d.cts

@@ -440,6 +440,18 @@ export interface ChartValueScale {
     /** Set when the axis is logarithmic: values map by their logarithm in this base. */
     logBase?: number;
 }
+/**
+ * The category bands of a bar, line or area chart: `count` equal bands of the category axis,
+ * from `start` for `length` pixels (the last category first when `reverse` is set).
+ */
+export interface ChartCategoryScale {
+    /** `x` for vertical charts, `y` for horizontal bars. */
+    axis: 'x' | 'y';
+    start: number;
+    length: number;
+    count: number;
+    reverse: boolean;
+}
 /** Something the layout had to leave out or shorten, as a sentence (for agents and screen readers). */
 export interface ChartWarning {
     code: 'labels-hidden' | 'labels-truncated' | 'legend-truncated' | 'points-decimated' | 'values-skipped' | 'data-labels-hidden' | 'type-fallback' | 'annotations-skipped' | 'highlight-unmatched';
@@ -459,6 +471,8 @@ export interface ChartScene {
     valueScale2?: ChartValueScale;
     /** The numeric x scale of a scatter or bubble chart with x values. */
     xScale?: ChartValueScale;
+    /** The category bands of a bar, line or area chart. */
+    categoryScale?: ChartCategoryScale;
     /** Percent-stacked: values are shown as shares, so dragging is disabled. */
     percent: boolean;
     theme: ChartTheme;

package/dist/chart/types.d.ts

@@ -440,6 +440,18 @@ export interface ChartValueScale {
     /** Set when the axis is logarithmic: values map by their logarithm in this base. */
     logBase?: number;
 }
+/**
+ * The category bands of a bar, line or area chart: `count` equal bands of the category axis,
+ * from `start` for `length` pixels (the last category first when `reverse` is set).
+ */
+export interface ChartCategoryScale {
+    /** `x` for vertical charts, `y` for horizontal bars. */
+    axis: 'x' | 'y';
+    start: number;
+    length: number;
+    count: number;
+    reverse: boolean;
+}
 /** Something the layout had to leave out or shorten, as a sentence (for agents and screen readers). */
 export interface ChartWarning {
     code: 'labels-hidden' | 'labels-truncated' | 'legend-truncated' | 'points-decimated' | 'values-skipped' | 'data-labels-hidden' | 'type-fallback' | 'annotations-skipped' | 'highlight-unmatched';
@@ -459,6 +471,8 @@ export interface ChartScene {
     valueScale2?: ChartValueScale;
     /** The numeric x scale of a scatter or bubble chart with x values. */
     xScale?: ChartValueScale;
+    /** The category bands of a bar, line or area chart. */
+    categoryScale?: ChartCategoryScale;
     /** Percent-stacked: values are shown as shares, so dragging is disabled. */
     percent: boolean;
     theme: ChartTheme;