@graphysdk/react-renderer 0.0.1-experimental.7 → 0.0.1-plugins.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -1,50 +1,58 @@
1
+ import { AnnotationZOrder } from '@graphysdk/viz-engine';
1
2
  import { AppearanceConfig } from '@graphysdk/viz-engine';
3
+ import { CartesianCoordSystem } from '@graphysdk/viz-engine';
2
4
  import { Command } from '@graphysdk/viz-engine';
3
- import { CompiledPanel } from '@graphysdk/viz-engine';
5
+ import { CompiledLayerFor } from '@graphysdk/viz-engine';
4
6
  import { CompiledSpec } from '@graphysdk/viz-engine';
5
7
  import { CompilerInput } from '@graphysdk/viz-engine';
6
- import { ComponentType } from 'react';
8
+ import { CoordSystem } from '@graphysdk/viz-engine';
7
9
  import { CSSProperties } from 'react';
8
10
  import { CustomPalettesInput } from '@graphysdk/viz-engine';
9
11
  import { Data } from '@graphysdk/viz-engine';
10
12
  import { FontSpec } from '@graphysdk/viz-engine';
11
- import { FormattedAxis } from '@graphysdk/viz-engine';
12
- import { FormattedHeadline } from '@graphysdk/viz-engine';
13
- import { FormattedLegend } from '@graphysdk/viz-engine';
13
+ import { Geom } from '@graphysdk/viz-engine/extensions';
14
+ import { GeomIdentity } from '@graphysdk/viz-engine';
15
+ import { GeomName } from '@graphysdk/viz-engine';
14
16
  import { GraphLayout } from '@graphysdk/viz-engine';
15
17
  import { GraphTheme } from '@graphysdk/viz-engine';
16
- import { HeadlineMeasurer } from '@graphysdk/viz-engine';
18
+ import { HighlightStrategy } from '@graphysdk/viz-engine';
19
+ import { HoverHit } from '@graphysdk/viz-engine';
17
20
  import { HoverState } from '@graphysdk/viz-engine';
18
21
  import { JSX } from 'react/jsx-runtime';
19
- import { LayoutEdge } from '@graphysdk/viz-engine';
20
22
  import { Locale } from '@graphysdk/viz-engine';
21
23
  import { MeasuredText } from '@graphysdk/viz-engine';
24
+ import { Observation } from '@graphysdk/viz-engine';
25
+ import { PolarCoordSystem } from '@graphysdk/viz-engine';
22
26
  import { ReactNode } from 'react';
23
- import { Rect } from '@graphysdk/viz-engine';
24
- import { ResolvedHeadlineSize } from '@graphysdk/viz-engine';
25
- import { SourceContent } from '@graphysdk/viz-engine';
26
- import { TextContent } from '@graphysdk/viz-engine';
27
+ import { ResolvedTarget } from '@graphysdk/viz-engine';
27
28
  import { TextMeasurer } from '@graphysdk/viz-engine';
28
29
  import { TooltipContent } from '@graphysdk/viz-engine';
29
30
 
30
31
  /**
31
- * Props for the AxisLabel slot the axis title of every axis (e.g. "Revenue"). Override via
32
- * `slots.AxisLabel` on `GraphRenderer`. `labelRects` are SVG-local, keyed by edge; each title string
33
- * is `formattedAxes[i].label`. The tick band is a separate region see `AxisTicks`.
32
+ * The drawing surface a custom annotation paints into (ADR-035): a panel-positioned [0,1] frame.
33
+ * `targets` are the resolved coordinates in **top-left [0,1]**; `area` carries the panel's pixel size
34
+ * for the cases [0,1] cannot express (text extents, fixed-length leaders); `params` is the kind's typed
35
+ * params. The draw function returns static nodes — annotations have no hover or tooltip.
34
36
  */
35
- export declare interface AxisLabelSlotProps {
36
- formattedAxes: FormattedAxis[];
37
- labelRects: Partial<Record<LayoutEdge, Rect>>;
37
+ declare interface AnnotationDrawInput<TParams extends object = object> {
38
+ targets: readonly ResolvedTarget[];
39
+ area: {
40
+ width: number;
41
+ height: number;
42
+ };
43
+ params: TParams;
38
44
  }
39
45
 
40
46
  /**
41
- * Props for the AxisTicks slot the tick marks and tick labels of every axis. Override via
42
- * `slots.AxisTicks` on `GraphRenderer`. `tickRects` are SVG-local, keyed by edge; `formattedAxes` is
43
- * the render-ready viz-engine runtime shape. The axis title is a separate region see `AxisLabel`.
47
+ * A custom annotation's render half. `type` resolves it for a compiled annotation; `zOrder` is the
48
+ * kind's default slot (background paints before geoms, foreground after) overridable per instance;
49
+ * `draw` is a React render function that may reuse the render kit (theme tokens, `toPercent`, value
50
+ * readers) but never participates in hover.
44
51
  */
45
- export declare interface AxisTicksSlotProps {
46
- formattedAxes: FormattedAxis[];
47
- tickRects: Partial<Record<LayoutEdge, Rect>>;
52
+ declare interface AnnotationPlugin {
53
+ type: string;
54
+ zOrder: AnnotationZOrder;
55
+ draw: (input: AnnotationDrawInput) => ReactNode;
48
56
  }
49
57
 
50
58
  /**
@@ -101,25 +109,13 @@ export declare class CanvasTextMeasurer implements TextMeasurer {
101
109
  private getEmojiCorrection;
102
110
  }
103
111
 
104
- /** vanilla-extract class that binds the dark token values; set it on any ancestor to flip to dark. */
105
- export declare const darkTheme: string;
106
-
107
- /** Default paint for the footer region — caption and source line. */
108
- export declare const DefaultFooter: ({ ref, footerRect, mode, caption, isCaptionVisible, source, isSourceVisible, }: FooterSlotProps) => JSX.Element | null;
112
+ declare type CoordKind = CoordSystem['type'];
109
113
 
110
- /** Default paint for the grid region — panel border and per-tick gridlines, drawn inside the panel rect. */
111
- export declare const DefaultGrid: ({ axes, panel, panelRect }: GridSlotProps) => JSX.Element;
114
+ /** Maps a coord-kind discriminator to the corresponding `CoordSystem` member. */
115
+ declare type CoordSystemFor<C extends CoordKind> = C extends 'cartesian' ? CartesianCoordSystem : C extends 'polar' ? PolarCoordSystem : never;
112
116
 
113
- /** Default paint for the header region — title and subtitle. */
114
- export declare const DefaultHeader: ({ ref, headerRect, mode, title, isTitleVisible, subtitle, isSubtitleVisible, }: HeaderSlotProps) => JSX.Element | null;
115
-
116
- /**
117
- * Presentational tooltip body. Pure function of props — paints the box, header, and rows.
118
- * Positioning and data wiring live in the {@link Tooltip} wrapper, never here.
119
- */
120
- export declare const DefaultTooltip: ({ content, isVisible }: TooltipSlotProps) => JSX.Element | null;
117
+ export declare const darkTheme: string;
121
118
 
122
- /** Dev-only compile-cache inspector; render inside a `<GraphProvider>`. See {@link DevToolsPanelProps}. */
123
119
  export declare const DevToolsPanel: ({ width, style, className }?: DevToolsPanelProps) => JSX.Element;
124
120
 
125
121
  /**
@@ -136,20 +132,55 @@ export declare interface DevToolsPanelProps {
136
132
  className?: string;
137
133
  }
138
134
 
135
+ /** A geom's declared highlight composition strategy, or `null` when it opts out of highlighting. */
136
+ declare type GeomHighlightStrategy = HighlightStrategy | null;
137
+
139
138
  /**
140
- * Props for the Footer slot. Override via `slots.Footer` on `GraphRenderer`. The content
141
- * (caption/source + visibility) arrives as props; in-place caption editing in `editable` mode is
142
- * internal to this default an override replacing the region opts out of that editing.
139
+ * Self-contained module owning everything a single `(geom, coord)` composition needs to paint
140
+ * and respond to hover. Plugins are dispatched via the registry keyed on `(geom, coord)`
141
+ * the registry guarantees the input shapes match the plugin's identity.
142
+ *
143
+ * Generic by default: a plugin parameterised as `GeomPlugin<'bar', 'cartesian'>` declares
144
+ * narrow input types so its handlers receive `CompiledLayerFor<'bar'>` /
145
+ * `CartesianCoordSystem` directly, no runtime checks. Use {@link defineGeomPlugin} to build
146
+ * one — the helper centralizes the variance cast so individual plugin files stay free of
147
+ * `as` assertions.
148
+ *
149
+ * The public shape is a flat `NoOverlayAnchor | OverlayAnchor` union so call sites can
150
+ * invoke `plugin.render(...)` against `CompiledLayerFor<GeomIdentity>` without each call site
151
+ * having to discriminate. Per-plugin enforcement of `getOverlayAnchor` happens at the
152
+ * {@link defineGeomPlugin} boundary via {@link GeomPluginForStrategy}, keyed on the plugin's own
153
+ * declared `highlightStrategy` — so a custom geom is gated by what it declares, not a name lookup.
143
154
  */
144
- export declare interface FooterSlotProps {
145
- /** Forward this to the region's outer element — the layout measures the rendered DOM to reserve its space. */
146
- ref?: React.Ref<HTMLDivElement>;
147
- footerRect: Rect;
148
- mode?: GraphMode;
149
- caption: TextContent | null;
150
- isCaptionVisible: boolean;
151
- source: SourceContent | null;
152
- isSourceVisible: boolean;
155
+ declare type GeomPlugin<G extends string = GeomIdentity, C extends CoordKind = CoordKind> = NoOverlayAnchorGeomPlugin<G, C, GeomHighlightStrategy, PluginParams<G>> | OverlayAnchorGeomPlugin<G, C, GeomHighlightStrategy, PluginParams<G>>;
156
+
157
+ declare interface GeomPluginBase<G extends string, C extends CoordKind, S extends GeomHighlightStrategy, TParams> {
158
+ geom: G;
159
+ coord: C;
160
+ /**
161
+ * The geom's highlight composition strategy — the same value its compile-half declares. Drives the
162
+ * `getOverlayAnchor` requirement at the {@link defineGeomPlugin} boundary, so the render contract is
163
+ * derived from a declared strategy rather than a closed geom-name lookup.
164
+ */
165
+ highlightStrategy: S;
166
+ guideMode: HoverGuideMode | null;
167
+ render: (input: GeomRenderInput<G, C, TParams>) => ReactNode;
168
+ renderHover: (input: HoverRenderInput<G, C, TParams>) => ReactNode;
169
+ renderHoverCompanions: (input: HoverCompanionsRenderInput<G, TParams>) => ReactNode;
170
+ /**
171
+ * Optional: paints the tooltip body when one of this geom's observations is the primary hit. The
172
+ * renderer keeps the positioned, themed card and calls this for its contents only; returning `null`
173
+ * falls through to the default body. The input carries the engine-built {@link TooltipContent} (feed
174
+ * it to `TooltipBody` to reproduce the default) and the raw `primary.observation`.
175
+ */
176
+ renderTooltip?: (input: TooltipRenderInput<G, C, TParams>) => ReactNode;
177
+ }
178
+
179
+ declare interface GeomRenderInput<G extends string = GeomName, C extends CoordKind = CoordKind, TParams = PluginParams<G>> {
180
+ layer: CompiledLayerFor<G, TParams>;
181
+ coordSystem: CoordSystemFor<C>;
182
+ isAnimated: boolean;
183
+ formattingLocale: Locale;
153
184
  }
154
185
 
155
186
  /**
@@ -163,7 +194,7 @@ export declare type GraphMode = 'readonly' | 'editable';
163
194
  * Owns the compiled spec for a graph and exposes it via {@link useCompiledSpec}, plus a
164
195
  * `dispatch` for applying {@link Command}s.
165
196
  */
166
- export declare const GraphProvider: ({ data, input, formattingLocale, onChange, customPalettes, theme, themeOverrides: themeOverridesInput, children, }: GraphProviderProps) => JSX.Element;
197
+ export declare const GraphProvider: ({ data, input, formattingLocale, onChange, customPalettes, theme, themeOverrides: themeOverridesInput, geoms, plugins, annotationPlugins, children, }: GraphProviderProps) => JSX.Element;
167
198
 
168
199
  declare interface GraphProviderProps {
169
200
  data: Data;
@@ -173,6 +204,12 @@ declare interface GraphProviderProps {
173
204
  theme?: GraphTheme;
174
205
  themeOverrides?: ThemeOverrides;
175
206
  customPalettes?: CustomPalettesInput;
207
+ /** Custom geom definitions, injected per-instance into the compiler (override built-ins by name). */
208
+ geoms?: readonly Geom[];
209
+ /** Custom geom render plugins, injected per-instance (override built-ins by `(geom, coord)`). */
210
+ plugins?: readonly GeomPlugin[];
211
+ /** Custom annotation render plugins, injected per-instance and resolved by annotation `type` (ADR-035). */
212
+ annotationPlugins?: readonly AnnotationPlugin[];
176
213
  children: ReactNode;
177
214
  }
178
215
 
@@ -182,106 +219,23 @@ declare interface GraphProviderProps {
182
219
  * no `config` prop: every consumer must wrap with `<GraphProvider>` so commands can operate
183
220
  * on the live spec.
184
221
  */
185
- export declare const GraphRenderer: ({ slots, sizing, onResize, ...props }: GraphRendererProps) => JSX.Element;
222
+ export declare const GraphRenderer: (props: GraphRendererProps) => JSX.Element;
186
223
 
187
- /** Props for {@link GraphRenderer}: container sizing, interaction toggles, and per-region slot overrides. */
188
224
  export declare interface GraphRendererProps {
189
- /** Controls how the graph responds to its container size. Defaults to filling the parent container. */
190
- sizing?: GraphSizing;
191
- /** Callback invoked when the graph's container is resized. Fires in every sizing mode. */
192
- onResize?: ResizeObserverOnResize;
225
+ width: number;
226
+ height: number;
193
227
  isAnimated?: boolean;
194
228
  showTooltips?: boolean;
195
229
  mode?: GraphMode;
196
- /** Per-region component overrides. Unspecified regions render their default. */
197
- slots?: GraphSlots;
198
- }
199
-
200
- /** Controls how the graph claims space in its container. */
201
- export declare type GraphSizing = {
202
- mode: 'responsive';
203
- } | {
204
- mode: 'fixed';
205
- width: number;
206
- height: number;
207
- } | {
208
- mode: 'keepAspectRatio';
209
- intrinsicWidth: number;
210
- intrinsicHeight: number;
211
- } | {
212
- mode: 'keepAspectRatio';
213
- intrinsicWidth: number;
214
- aspectRatio: number;
215
- } | {
216
- mode: 'keepAspectRatio';
217
- intrinsicHeight: number;
218
- aspectRatio: number;
219
- };
220
-
221
- /**
222
- * Region overrides for `GraphRenderer`. Each slot replaces how one region paints; the viz-engine
223
- * `Spec` stays the source of truth for whether a region exists and what data it receives. An
224
- * override is handed the same render-ready props as its default.
225
- *
226
- * Layout-safe regions (`Header`, `Footer`, `Tooltip`, `Grid`) are bare components — their size is
227
- * measured from the rendered DOM, or they reserve no edge space, so the layout never reads them
228
- * ahead of paint. Layout-coupled regions (`AxisTicks`, `AxisLabel`, `Legend`, `Headline`) are
229
- * {@link SlotOverride}s: a custom renderer must also declare its reserved size via `measure`,
230
- * otherwise paint and the reserved band would desync.
231
- *
232
- * Each slot owns exactly one region the layout reserves — the axis tick band (`AxisTicks`) and the
233
- * axis-title band (`AxisLabel`) are separate, mirroring the engine's own split (`GraphLayout.axes`
234
- * vs `GraphLayout.axisLabels`). Override one and the other keeps its default paint + reservation, so
235
- * a custom tick band never leaves the title band an unpainted gap.
236
- */
237
- export declare interface GraphSlots {
238
- Header?: ComponentType<HeaderSlotProps>;
239
- Footer?: ComponentType<FooterSlotProps>;
240
- Tooltip?: ComponentType<TooltipSlotProps>;
241
- Grid?: ComponentType<GridSlotProps>;
242
- Legend?: SlotOverride<LegendSlotProps, (legend: FormattedLegend, ctx: SlotMeasureContext) => number>;
243
- Headline?: SlotOverride<HeadlineSlotProps, HeadlineMeasurer>;
244
- AxisTicks?: SlotOverride<AxisTicksSlotProps, (axis: FormattedAxis, ctx: SlotMeasureContext) => number>;
245
- AxisLabel?: SlotOverride<AxisLabelSlotProps, (axis: FormattedAxis, ctx: SlotMeasureContext) => number>;
246
- }
247
-
248
- /**
249
- * Props for the Grid slot. Override via `slots.Grid` on `GraphRenderer`. `panelRect` is in
250
- * SVG-local coordinates; `axes` and `panel` are render-ready viz-engine runtime shapes.
251
- */
252
- export declare interface GridSlotProps {
253
- axes: FormattedAxis[];
254
- panel: CompiledPanel;
255
- panelRect: GraphLayout['panel'];
256
230
  }
257
231
 
258
- /**
259
- * Props for the Header slot. Override via `slots.Header` on `GraphRenderer`. The content
260
- * (title/subtitle + visibility) arrives as props; in-place title editing in `editable` mode is
261
- * internal to this default — an override replacing the region opts out of that editing.
262
- */
263
- export declare interface HeaderSlotProps {
264
- /** Forward this to the region's outer element — the layout measures the rendered DOM to reserve its space. */
265
- ref?: React.Ref<HTMLDivElement>;
266
- headerRect: Rect;
267
- mode?: GraphMode;
268
- title: TextContent | null;
269
- isTitleVisible: boolean;
270
- subtitle: TextContent | null;
271
- isSubtitleVisible: boolean;
232
+ declare interface HoverCompanionsRenderInput<G extends string = GeomName, TParams = PluginParams<G>> {
233
+ layer: CompiledLayerFor<G, TParams>;
234
+ primary: HoverHit;
235
+ related: HoverHit[];
272
236
  }
273
237
 
274
- /**
275
- * Props for the Headline slot. Override via `slots.Headline` on `GraphRenderer`; the data is
276
- * render-ready, formatted by the viz-engine runtime.
277
- */
278
- export declare interface HeadlineSlotProps {
279
- headline: FormattedHeadline;
280
- rect: Rect;
281
- resolvedSize: ResolvedHeadlineSize;
282
- /** Leading strip items to paint; the rest are hidden because they would overflow the band. */
283
- visibleItemCount: number;
284
- }
238
+ declare type HoverGuideMode = 'continuous' | 'bar';
285
239
 
286
240
  /**
287
241
  * Hosts the hover store + engine for the surrounding `<GraphProvider>`. Subscribes only to the
@@ -294,72 +248,67 @@ declare interface HoverProviderProps {
294
248
  children: ReactNode;
295
249
  }
296
250
 
251
+ declare interface HoverRenderInput<G extends string = GeomName, C extends CoordKind = CoordKind, TParams = PluginParams<G>> {
252
+ layer: CompiledLayerFor<G, TParams>;
253
+ coordSystem: CoordSystemFor<C>;
254
+ primary: HoverHit;
255
+ group: HoverHit[];
256
+ related: HoverHit[];
257
+ panelRect: GraphLayout['panel'];
258
+ }
259
+
297
260
  declare interface HoverSlice {
298
261
  hover: HoverState;
262
+ /**
263
+ * Whether the pointer is over the chart's interactive surface. Drives the tooltip's open/close at
264
+ * the enter/leave boundary. Held as state (not a ref) because that transition must re-render the
265
+ * tooltip; the cursor *position* stays a ref (see `HoverContextValue.cursorRef`) so pointer-rate
266
+ * moves reposition through floating-ui without re-rendering.
267
+ */
268
+ isPointerInside: boolean;
299
269
  }
300
270
 
301
271
  declare interface HoverStoreActions {
302
272
  setHoverState: (next: HoverState) => void;
273
+ setPointerInside: (value: boolean) => void;
303
274
  }
304
275
 
305
- /** State of the hover store: the current {@link HoverState} plus its setter. */
306
276
  declare type HoverStoreState = HoverSlice & HoverStoreActions;
307
277
 
308
- /**
309
- * Props for the Legend slot. Override via `slots.Legend` on `GraphRenderer`; the data is
310
- * render-ready, formatted by the viz-engine runtime.
311
- */
312
- export declare interface LegendSlotProps {
313
- formattedLegends: FormattedLegend[];
314
- rects: Partial<Record<LayoutEdge, Rect>>;
315
- textScale: number;
316
- }
317
-
318
- /** vanilla-extract class that binds the light token values; the default theme. */
319
278
  export declare const lightTheme: string;
320
279
 
321
- export declare type ResizeObserverOnResize = (state: ResizeObserverState) => void;
322
-
323
- export declare interface ResizeObserverState {
324
- width: number;
325
- height: number;
326
- /** True until the first ResizeObserver measurement lands. */
327
- isDefault: boolean;
328
- }
329
-
330
280
  /**
331
- * Passed as the second argument to a layout-coupled slot's `measure`. Exposes the renderer's own
332
- * text measurer the same Canvas-backed instance the built-in measurers use and the active
333
- * text-scale, so a `measure` can size its band from real text metrics without constructing its own
334
- * measurer or guessing the font size. A `measure` whose size is unrelated to text can ignore it.
281
+ * Plugin shape for geoms that don't compute an overlay anchor either `'observation-rerender'`
282
+ * geoms (matched rows re-render in place) or geoms that opt out of highlighting entirely
283
+ * (`null` strategy). The renderer never asks these plugins for an anchor, so the property is forbidden.
335
284
  */
336
- export declare interface SlotMeasureContext {
337
- /** Measures a string at a given font; returns `{ width, height, ascent, descent }` in CSS pixels. */
338
- measureText: TextMeasurer['measureText'];
339
- /** Active text-scale multiplier; multiply an em size by this to get the pixel size to measure at. */
340
- textScale: number;
285
+ declare interface NoOverlayAnchorGeomPlugin<G extends string, C extends CoordKind, S extends GeomHighlightStrategy, TParams> extends GeomPluginBase<G, C, S, TParams> {
286
+ getOverlayAnchor?: never;
341
287
  }
342
288
 
343
289
  /**
344
- * A layout-coupled slot: pairs the region's renderer with the measurer the layout uses to reserve
345
- * its space. `measure` mirrors the matching `LayoutMeasurer` method, so an override supplies exactly
346
- * the function the engine would have used — paint and reserved space derive from one source and
347
- * cannot disagree.
348
- *
349
- * Give `measure` a stable reference (module scope, or `useCallback`'d). The measurer it feeds is
350
- * built once per chart for layout stability, so a `measure` whose identity changes every render is
351
- * still read on the next paint but does not by itself retrigger a layout pass.
290
+ * Anchor point in normalized [0,1] coord-space where a highlight overlay marker
291
+ * should be painted for one observation. Renderer turns [0,1] into pixels.
352
292
  */
353
- export declare interface SlotOverride<Props, Measure> {
354
- /** The component that paints the region. */
355
- render: ComponentType<Props>;
356
- /**
357
- * Returns the region's reserved size. Receives the region's formatted data plus a
358
- * {@link SlotMeasureContext} (`measureText`, `textScale`) for sizing from real text metrics.
359
- */
360
- measure: Measure;
293
+ declare interface OverlayAnchor {
294
+ x: number;
295
+ y: number;
296
+ }
297
+
298
+ declare interface OverlayAnchorGeomPlugin<G extends string, C extends CoordKind, S extends GeomHighlightStrategy, TParams> extends GeomPluginBase<G, C, S, TParams> {
299
+ /** Returns the panel-space anchor for a matched observation. */
300
+ getOverlayAnchor: (input: OverlayAnchorInput<G, C, TParams>) => OverlayAnchor | null;
301
+ }
302
+
303
+ declare interface OverlayAnchorInput<G extends string = GeomName, C extends CoordKind = CoordKind, TParams = PluginParams<G>> {
304
+ layer: CompiledLayerFor<G, TParams>;
305
+ coordSystem: CoordSystemFor<C>;
306
+ observation: Observation;
361
307
  }
362
308
 
309
+ /** The compiled-layer params a plugin's handlers see — built-ins default from the geom name; a custom geom supplies its own. */
310
+ declare type PluginParams<G extends string> = CompiledLayerFor<G>['params'];
311
+
363
312
  /**
364
313
  * Creates a font-ready, cached text measurer and shares it with descendants via context.
365
314
  * Renders nothing until the measurer resolves, so consumers reading the context always
@@ -384,13 +333,10 @@ declare interface TextMeasurerProviderProps {
384
333
  measurer?: TextMeasurer;
385
334
  }
386
335
 
387
- /** The name of a single theme token. */
388
336
  export declare type ThemeKey = keyof ThemeValues;
389
337
 
390
- /** A partial set of token values layered over a base theme — the shape of the `themeOverrides` prop. */
391
338
  export declare type ThemeOverrides = Partial<ThemeValues>;
392
339
 
393
- /** Resolves the base theme plus per-chart `themeOverrides` into token values and publishes them to the subtree. */
394
340
  export declare const ThemeProvider: ({ theme, themeOverrides, appearance, children }: ThemeProviderProps) => JSX.Element;
395
341
 
396
342
  declare interface ThemeProviderProps {
@@ -400,14 +346,21 @@ declare interface ThemeProviderProps {
400
346
  children: ReactNode;
401
347
  }
402
348
 
403
- /** Every theme token mapped to its resolved CSS string value. */
404
349
  export declare type ThemeValues = Record<keyof typeof vars, string>;
405
350
 
406
- export declare interface TooltipSlotProps {
407
- /** Render-ready tooltip body, already formatted by the viz-engine runtime. */
351
+ /**
352
+ * Input a plugin's {@link GeomPluginBase.renderTooltip} receives when one of its observations is the
353
+ * primary hit. `content` is the body the built-in tooltip would render — feed it to `TooltipBody` to
354
+ * reproduce the default — while `primary.observation` carries the geom's own columns for a bespoke
355
+ * layout. The card around the body (positioning, theme) stays the renderer's.
356
+ */
357
+ declare interface TooltipRenderInput<G extends string = GeomName, C extends CoordKind = CoordKind, TParams = PluginParams<G>> {
408
358
  content: TooltipContent;
409
- /** Whether the tooltip is currently shown. The wrapper only mounts the slot while open. */
410
- isVisible: boolean;
359
+ layer: CompiledLayerFor<G, TParams>;
360
+ coordSystem: CoordSystemFor<C>;
361
+ primary: HoverHit;
362
+ group: HoverHit[];
363
+ related: ReadonlyMap<string, HoverHit[]>;
411
364
  }
412
365
 
413
366
  /**
@@ -423,7 +376,6 @@ export declare interface TooltipSlotProps {
423
376
  */
424
377
  export declare const useCompiledSelector: <Selected>(selector: (compiled: CompiledSpec) => Selected) => Selected;
425
378
 
426
- /** Returns the dispatcher for applying {@link Command}s to the provider's live spec. */
427
379
  export declare const useGraphCommandDispatcher: () => ((command: Command) => void);
428
380
 
429
381
  /**
@@ -431,10 +383,8 @@ export declare const useGraphCommandDispatcher: () => ((command: Command) => voi
431
383
  */
432
384
  export declare function useHoverState<T>(selector: (state: HoverStoreState) => T): T;
433
385
 
434
- /** Returns the {@link TextMeasurer} from context; throws outside a `<TextMeasurerProvider>`. */
435
386
  export declare const useTextMeasurer: () => TextMeasurer;
436
387
 
437
- /** CSS custom-property references for every theme token; read at paint sites as `vars.tooltipBackground`, etc. */
438
388
  export declare const vars: {
439
389
  white: `var(--${string})`;
440
390
  black: `var(--${string})`;
@@ -504,25 +454,6 @@ export declare const vars: {
504
454
  annotationMenuTriggerIconColor: `var(--${string})`;
505
455
  heatmapEmptyTileBackground: `var(--${string})`;
506
456
  dataLabelOutsideBackground: `var(--${string})`;
507
- graphPadding: `var(--${string})`;
508
- gridLineWidth: `var(--${string})`;
509
- gridLineDash: `var(--${string})`;
510
- tooltipBorderRadius: `var(--${string})`;
511
- tooltipBorderWidth: `var(--${string})`;
512
- tooltipPaddingBlock: `var(--${string})`;
513
- tooltipPaddingInline: `var(--${string})`;
514
- tooltipRowGap: `var(--${string})`;
515
- tooltipShadow: `var(--${string})`;
516
- tickLabelOffset: `var(--${string})`;
517
- legendItemGap: `var(--${string})`;
518
- legendSwatchGap: `var(--${string})`;
519
- legendSwatchWidth: `var(--${string})`;
520
- legendSwatchHeight: `var(--${string})`;
521
- legendPillPaddingInline: `var(--${string})`;
522
- legendPillPaddingBlock: `var(--${string})`;
523
- legendPillBorderWidth: `var(--${string})`;
524
- headlineRowGap: `var(--${string})`;
525
- headlineItemGap: `var(--${string})`;
526
457
  canvasDefault: `var(--${string})`;
527
458
  canvasBlue: `var(--${string})`;
528
459
  canvasCyan: `var(--${string})`;