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

package/dist/extensions.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const d=require("react/jsx-runtime"),u=require("react"),g=require("react-dom"),i=require("./tooltip-body-B4Mj-oru.cjs"),v=require("@graphysdk/viz-engine");function m(e,t){return{type:e.type,zOrder:t.zOrder,draw:t.draw}}const w=2147483646;function p(){const e=u.useRef(null),[t,o]=u.useState(null),n=u.useCallback(()=>{const r=e.current;if(!r)return;const l=r.getBoundingClientRect(),c={left:l.left,top:l.top,width:l.width,height:l.height};o(a=>a&&b(a,c)?a:c)},[]),s=u.useCallback(r=>{e.current=r},[]);return u.useLayoutEffect(()=>{if(!e.current)return;n();const r=new ResizeObserver(n);return r.observe(e.current),window.addEventListener("resize",n),window.addEventListener("scroll",n,!0),()=>{r.disconnect(),window.removeEventListener("resize",n),window.removeEventListener("scroll",n,!0)}},[n]),{ref:s,rect:t}}function R({rect:e,children:t}){return g.createPortal(d.jsx("div",{style:{position:"fixed",left:e.left,top:e.top,width:e.width,height:e.height,pointerEvents:"none",zIndex:w,overflow:"visible"},children:t}),document.body)}function b(e,t){return e.left===t.left&&e.top===t.top&&e.width===t.width&&e.height===t.height}function*P(e,t){for(const o of e)yield{kind:o[t],observation:o}}function x(e,t,o,n){return e>=o&&t>=n}const S=({children:e,style:t,...o})=>d.jsx("svg",{width:"100%",height:"100%",viewBox:"0 0 1 1",preserveAspectRatio:"none",...o,style:{overflow:"visible",...t},children:e});function y(){return u.useMemo(()=>{const e=v.DEFAULT_COLOR_PALETTE;return t=>e[t%e.length]??e[0]??"#000000"},[])}function E(e,t){const{hitTesterRegistry:o}=i.useHoverContext(),n=u.useRef(t);n.current=t,u.useLayoutEffect(()=>{const s=r=>n.current(r);return o.set(e,s),()=>{o.delete(e)}},[o,e])}function C(e){const{engine:t,store:o,setCursor:n}=i.useHoverContext();return u.useCallback((s,r)=>{if(s===null){o.getState().setHoverState(v.RESTING_HOVER_STATE),n(null);return}o.getState().setHoverState(t.hoverByKey(e,s)),r&&n(r)},[t,o,n,e])}function h(e,t,o){const n=f(e),s=f(t),r=(l,c)=>Math.round(l+(c-l)*o);return`rgb(${r(n.red,s.red)}, ${r(n.green,s.green)}, ${r(n.blue,s.blue)})`}function T(e,t){return h(e,"#ffffff",t)}function f(e){const t=e.replace("#","");return{red:Number.parseInt(t.slice(0,2),16),green:Number.parseInt(t.slice(2,4),16),blue:Number.parseInt(t.slice(4,6),16)}}exports.CompanionDot=i.CompanionDot;exports.PrimaryDot=i.PrimaryDot;exports.Swatch=i.Swatch;exports.TooltipBody=i.TooltipBody;exports.TooltipRowView=i.TooltipRowView;exports.defineGeomPlugin=i.defineGeomPlugin;exports.defineGeomRenderer=i.defineGeomRenderer;exports.emToPx=i.emToPx;exports.toPercent=i.toPercent;exports.toViewBoxX=i.toViewBoxX;exports.toViewBoxY=i.toViewBoxY;exports.useSvgPathMorph=i.useSvgPathMorph;exports.vars=i.vars;exports.PanelOverlayPortal=R;exports.UnitSpaceSvg=S;exports.defineAnnotationRenderer=m;exports.fitsLabel=x;exports.lighten=T;exports.mixColor=h;exports.partitionByKind=P;exports.useCategoricalColor=y;exports.useGeomHitTest=E;exports.useGeomHover=C;exports.usePanelScreenRect=p;

package/dist/extensions.d.ts

@@ -0,0 +1,635 @@
+import { AnimationPlaybackOptions } from 'motion/react';
+import { AnnotationDef } from '@graphysdk/viz-engine/extensions';
+import { AnnotationZOrder } from '@graphysdk/viz-engine';
+import { CartesianCoordSystem } from '@graphysdk/viz-engine';
+import { CompiledLayerFor } from '@graphysdk/viz-engine';
+import { CoordSystem } from '@graphysdk/viz-engine';
+import { Geom } from '@graphysdk/viz-engine/extensions';
+import { GeomIdentity } from '@graphysdk/viz-engine';
+import { GeomName } from '@graphysdk/viz-engine';
+import { GraphLayout } from '@graphysdk/viz-engine';
+import { HighlightStrategy } from '@graphysdk/viz-engine';
+import { HoverHit } from '@graphysdk/viz-engine';
+import { JSX } from 'react/jsx-runtime';
+import { LineStyleType } from '@graphysdk/viz-engine';
+import { Locale } from '@graphysdk/viz-engine';
+import { MotionValue } from 'motion/react';
+import { Observation } from '@graphysdk/viz-engine';
+import { PanelHitTester } from '@graphysdk/viz-engine';
+import { PolarCoordSystem } from '@graphysdk/viz-engine';
+import { ReactNode } from 'react';
+import { RefCallback } from 'react';
+import { ResolvedTarget } from '@graphysdk/viz-engine';
+import { SVGProps } from 'react';
+import { SwatchShape } from '@graphysdk/viz-engine';
+import { TooltipContent } from '@graphysdk/viz-engine';
+import { TooltipRow } from '@graphysdk/viz-engine';
+
+/**
+ * The drawing surface a custom annotation paints into (ADR-035): a panel-positioned [0,1] frame.
+ * `targets` are the resolved coordinates in **top-left [0,1]**; `area` carries the panel's pixel size
+ * for the cases [0,1] cannot express (text extents, fixed-length leaders); `params` is the kind's typed
+ * params. The draw function returns static nodes — annotations have no hover or tooltip.
+ */
+export declare interface AnnotationDrawInput<TParams extends object = object> {
+    targets: readonly ResolvedTarget[];
+    area: {
+        width: number;
+        height: number;
+    };
+    params: TParams;
+}
+
+/**
+ * A custom annotation's render half. `type` resolves it for a compiled annotation; `zOrder` is the
+ * kind's default slot (background paints before geoms, foreground after) — overridable per instance;
+ * `draw` is a React render function that may reuse the render kit (theme tokens, `toPercent`, value
+ * readers) but never participates in hover.
+ */
+export declare interface AnnotationPlugin {
+    type: string;
+    zOrder: AnnotationZOrder;
+    draw: (input: AnnotationDrawInput) => ReactNode;
+}
+
+/** The render half an author supplies to {@link defineAnnotationRenderer} — everything but `type`. */
+declare interface AnnotationRenderHalf<TParams extends object> {
+    zOrder: AnnotationZOrder;
+    draw: (input: AnnotationDrawInput<TParams>) => ReactNode;
+}
+
+export { AnnotationZOrder }
+
+/**
+ * Hover-overlay dot drawn at a non-primary hit's `(x, y)`: a single circle at reduced opacity
+ * so it reads as secondary. Used for any companion hit — same-layer sibling (e.g. another
+ * series at the primary X) or cross-layer related.
+ */
+export declare const CompanionDot: ({ hit }: CompanionDotProps) => JSX.Element;
+
+declare interface CompanionDotProps {
+    hit: HoverHit;
+}
+
+export declare type CoordKind = CoordSystem['type'];
+
+/** Maps a coord-kind discriminator to the corresponding `CoordSystem` member. */
+declare type CoordSystemFor<C extends CoordKind> = C extends 'cartesian' ? CartesianCoordSystem : C extends 'polar' ? PolarCoordSystem : never;
+
+/**
+ * Binds a custom annotation's render half to its imported compile-half {@link AnnotationDef}: the kind
+ * name (`def.type`) and the params type (`def.defaultParams`) are read from `def`, so the half never
+ * re-declares them and cannot disagree with the definition — the construction-level handshake mirroring
+ * `defineGeomRenderer`. `draw` receives the resolved targets with `params` typed from the def.
+ */
+export declare function defineAnnotationRenderer<TParams extends object>(def: AnnotationDef<TParams>, half: AnnotationRenderHalf<TParams>): AnnotationPlugin;
+
+/**
+ * Type-narrowing constructor for a plugin. Each plugin file declares its `(geom, coord)` pair and its
+ * `highlightStrategy` inline; TypeScript infers `G`/`C`/`S` from the object literal — handlers then
+ * receive `CompiledLayerFor<G>` / `CoordSystemFor<C>` with no `as` casts. Whether `getOverlayAnchor` is
+ * required follows from the declared `highlightStrategy` via {@link GeomPluginForStrategy}. A custom geom
+ * supplies its params type `TParams` (e.g. by annotating `render`'s input) to type `layer.params`.
+ *
+ * Returns the broad `GeomPlugin` type (with the type parameters erased) so all plugins fit into one
+ * registry. The cast inside this helper is safe because the registry routes every call to the plugin
+ * keyed by `(geom, coord)`.
+ */
+export declare function defineGeomPlugin<G extends string, C extends CoordKind, S extends GeomHighlightStrategy, TParams = PluginParams<G>>(plugin: GeomPluginForStrategy<G, C, S, TParams>): GeomPlugin;
+
+/**
+ * Binds a geom's render half to its imported compile-half {@link Geom} definition: the geom name
+ * (`def.type`), the highlight strategy (`def.highlightStrategy`), and the params type
+ * (`def.defaultParams`) are all read from `def`, so the half never re-declares them and cannot disagree
+ * with the definition — the construction-level handshake. Whether `getOverlayAnchor` is required follows
+ * from the def's declared `highlightStrategy`, and `render`/`renderHover` receive `layer.params` typed
+ * from the def with no annotation. Built-in plugins keep {@link defineGeomPlugin}; reach for this only to
+ * pair a custom geom's two halves.
+ *
+ * Returns the broad {@link GeomPlugin} (type parameters erased) so every plugin fits one registry; the
+ * cast is the same variance bypass {@link defineGeomPlugin} performs, safe because the registry routes
+ * each call by `(geom, coord)`.
+ */
+export declare function defineGeomRenderer<Def extends Geom, C extends CoordKind>(def: Def, half: GeomRenderHalf<Def, C>): GeomPlugin;
+
+export declare const emToPx: (em: number, textScale: number) => number;
+
+/**
+ * Whether a region is large enough to carry a label: both dimensions must clear their minimum. Works in
+ * any single consistent space — pass unit dimensions with unit thresholds, or pixels with pixel
+ * thresholds. A space-filling geom (treemap) culls labels with it so a tile too small to fit text stays
+ * unlabelled rather than overflowing.
+ */
+export declare function fitsLabel(width: number, height: number, minWidth: number, minHeight: number): boolean;
+
+/** A geom's declared highlight composition strategy, or `null` when it opts out of highlighting. */
+declare type GeomHighlightStrategy = HighlightStrategy | null;
+
+/**
+ * Self-contained module owning everything a single `(geom, coord)` composition needs to paint
+ * and respond to hover. Plugins are dispatched via the registry keyed on `(geom, coord)` —
+ * the registry guarantees the input shapes match the plugin's identity.
+ *
+ * Generic by default: a plugin parameterised as `GeomPlugin<'bar', 'cartesian'>` declares
+ * narrow input types so its handlers receive `CompiledLayerFor<'bar'>` /
+ * `CartesianCoordSystem` directly, no runtime checks. Use {@link defineGeomPlugin} to build
+ * one — the helper centralizes the variance cast so individual plugin files stay free of
+ * `as` assertions.
+ *
+ * The public shape is a flat `NoOverlayAnchor | OverlayAnchor` union so call sites can
+ * invoke `plugin.render(...)` against `CompiledLayerFor<GeomIdentity>` without each call site
+ * having to discriminate. Per-plugin enforcement of `getOverlayAnchor` happens at the
+ * {@link defineGeomPlugin} boundary via {@link GeomPluginForStrategy}, keyed on the plugin's own
+ * declared `highlightStrategy` — so a custom geom is gated by what it declares, not a name lookup.
+ */
+export declare type GeomPlugin<G extends string = GeomIdentity, C extends CoordKind = CoordKind> = NoOverlayAnchorGeomPlugin<G, C, GeomHighlightStrategy, PluginParams<G>> | OverlayAnchorGeomPlugin<G, C, GeomHighlightStrategy, PluginParams<G>>;
+
+declare interface GeomPluginBase<G extends string, C extends CoordKind, S extends GeomHighlightStrategy, TParams> {
+    geom: G;
+    coord: C;
+    /**
+     * The geom's highlight composition strategy — the same value its compile-half declares. Drives the
+     * `getOverlayAnchor` requirement at the {@link defineGeomPlugin} boundary, so the render contract is
+     * derived from a declared strategy rather than a closed geom-name lookup.
+     */
+    highlightStrategy: S;
+    guideMode: HoverGuideMode | null;
+    render: (input: GeomRenderInput<G, C, TParams>) => ReactNode;
+    renderHover: (input: HoverRenderInput<G, C, TParams>) => ReactNode;
+    renderHoverCompanions: (input: HoverCompanionsRenderInput<G, TParams>) => ReactNode;
+    /**
+     * Optional: paints the tooltip body when one of this geom's observations is the primary hit. The
+     * renderer keeps the positioned, themed card and calls this for its contents only; returning `null`
+     * falls through to the default body. The input carries the engine-built {@link TooltipContent} (feed
+     * it to `TooltipBody` to reproduce the default) and the raw `primary.observation`.
+     */
+    renderTooltip?: (input: TooltipRenderInput<G, C, TParams>) => ReactNode;
+}
+
+/**
+ * Picks the plugin shape required for a plugin's own declared `highlightStrategy`. Only the
+ * `'overlay-anchor'` strategy demands the anchor reader; `'observation-rerender'` and `null` (no
+ * highlight) both resolve to {@link NoOverlayAnchorGeomPlugin}.
+ *
+ * Used by {@link defineGeomPlugin} to enforce the strategy→shape coupling at plugin-definition
+ * sites — `observation-rerender` plugins cannot declare `getOverlayAnchor`, `overlay-anchor` ones must
+ * — for any geom name, built-in or custom, with no closed geom-name lookup.
+ */
+declare type GeomPluginForStrategy<G extends string, C extends CoordKind, S extends GeomHighlightStrategy, TParams> = S extends 'overlay-anchor' ? OverlayAnchorGeomPlugin<G, C, S, TParams> : NoOverlayAnchorGeomPlugin<G, C, S, TParams>;
+
+/**
+ * The render half an author supplies to {@link defineGeomRenderer}: every field of a plugin except the
+ * two its imported compile-half definition already declares — `geom` and `highlightStrategy`.
+ * `getOverlayAnchor` is gated on the def's declared strategy via {@link GeomPluginForStrategy}, so the
+ * render contract is bound to the definition rather than re-declared.
+ */
+declare type GeomRenderHalf<Def extends Geom, C extends CoordKind> = Omit<GeomPluginForStrategy<Def['type'] & string, C, Def['highlightStrategy'], Def['defaultParams']>, 'geom' | 'highlightStrategy'>;
+
+export declare interface GeomRenderInput<G extends string = GeomName, C extends CoordKind = CoordKind, TParams = PluginParams<G>> {
+    layer: CompiledLayerFor<G, TParams>;
+    coordSystem: CoordSystemFor<C>;
+    isAnimated: boolean;
+    formattingLocale: Locale;
+}
+
+export declare interface HoverCompanionsRenderInput<G extends string = GeomName, TParams = PluginParams<G>> {
+    layer: CompiledLayerFor<G, TParams>;
+    primary: HoverHit;
+    related: HoverHit[];
+}
+
+export declare type HoverGuideMode = 'continuous' | 'bar';
+
+export declare interface HoverRenderInput<G extends string = GeomName, C extends CoordKind = CoordKind, TParams = PluginParams<G>> {
+    layer: CompiledLayerFor<G, TParams>;
+    coordSystem: CoordSystemFor<C>;
+    primary: HoverHit;
+    group: HoverHit[];
+    related: HoverHit[];
+    panelRect: GraphLayout['panel'];
+}
+
+/** Lightens a hex colour by mixing it toward white by `amount` (`0` keeps the colour, `1` is white). */
+export declare function lighten(hex: string, amount: number): string;
+
+/**
+ * Mixes a hex colour toward another by `amount` in `[0, 1]` (`0` keeps `hex`, `1` returns `towardHex`),
+ * channel-wise in sRGB. Returns an `rgb(...)` string. Used for within-group shading where leaves share a
+ * group hue and vary only in lightness.
+ */
+export declare function mixColor(hex: string, towardHex: string, amount: number): string;
+
+/**
+ * Plugin shape for geoms that don't compute an overlay anchor — either `'observation-rerender'`
+ * geoms (matched rows re-render in place) or geoms that opt out of highlighting entirely
+ * (`null` strategy). The renderer never asks these plugins for an anchor, so the property is forbidden.
+ */
+declare interface NoOverlayAnchorGeomPlugin<G extends string, C extends CoordKind, S extends GeomHighlightStrategy, TParams> extends GeomPluginBase<G, C, S, TParams> {
+    getOverlayAnchor?: never;
+}
+
+/**
+ * Anchor point in normalized [0,1] coord-space where a highlight overlay marker
+ * should be painted for one observation. Renderer turns [0,1] into pixels.
+ */
+export declare interface OverlayAnchor {
+    x: number;
+    y: number;
+}
+
+declare interface OverlayAnchorGeomPlugin<G extends string, C extends CoordKind, S extends GeomHighlightStrategy, TParams> extends GeomPluginBase<G, C, S, TParams> {
+    /** Returns the panel-space anchor for a matched observation. */
+    getOverlayAnchor: (input: OverlayAnchorInput<G, C, TParams>) => OverlayAnchor | null;
+}
+
+export declare interface OverlayAnchorInput<G extends string = GeomName, C extends CoordKind = CoordKind, TParams = PluginParams<G>> {
+    layer: CompiledLayerFor<G, TParams>;
+    coordSystem: CoordSystemFor<C>;
+    observation: Observation;
+}
+
+export { PanelHitTester }
+
+/**
+ * Portals an interactive overlay to `document.body`, fixed over the given panel rect at the documented
+ * top `z-index`. Owns only the placement and chrome; the simulation canvas it wraps paints inside. Sized
+ * to the rect with `pointerEvents: 'none'` so gaps fall through to the chart — the overlay's own marks
+ * re-enable pointer events to capture drags.
+ */
+export declare function PanelOverlayPortal({ rect, children }: {
+    rect: PanelScreenRect;
+    children: ReactNode;
+}): ReactNode;
+
+/** The panel's on-screen rectangle in page-relative pixels — the frame a portalled overlay aligns to. */
+export declare interface PanelScreenRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+
+/**
+ * Walks a kind-tagged Tier-C dataset (the output of `createMarkTable`), yielding each observation paired
+ * with its discriminant `kind`. The render half switches on `kind` to build its per-kind marks, instead
+ * of re-reading the kind column inline in every plugin. `Kind` narrows the discriminant to the geom's own
+ * union (e.g. `'node' | 'link'`) for an exhaustive switch.
+ */
+export declare function partitionByKind<Kind extends string = string>(data: Iterable<Observation>, kindColumn: string): Generator<{
+    kind: Kind;
+    observation: Observation;
+}>;
+
+/** The compiled-layer params a plugin's handlers see — built-ins default from the geom name; a custom geom supplies its own. */
+declare type PluginParams<G extends string> = CompiledLayerFor<G>['params'];
+
+/**
+ * Hover-overlay dot drawn at the primary hit's `(x, y)`: colored disc with a thicker white
+ * border and an outer white ring offset by a 1px gap. Radius is data-driven so bubble charts
+ * whose size channel carries data don't distort under hover.
+ */
+export declare const PrimaryDot: ({ hit, ...rest }: PrimaryDotProps) => JSX.Element;
+
+declare interface PrimaryDotProps {
+    hit: HoverHit;
+    'data-testid'?: string;
+}
+
+export { ResolvedTarget }
+
+/**
+ * Shared shape glyph used by both the tooltip and the legend.
+ */
+export declare const Swatch: ({ shape, color, lineType, width, height, }: SwatchProps) => JSX.Element;
+
+declare interface SwatchProps {
+    shape: SwatchShape;
+    color: string;
+    lineType?: LineStyleType;
+    width?: number;
+    height?: number;
+}
+
+/**
+ * The default tooltip body — the optional header and one row per hovered observation, with the
+ * in-place primary-row highlight. Presentational and engine-decoupled: it renders a
+ * {@link TooltipContent} and nothing else, so the built-in `Tooltip` and a custom geom's
+ * `renderTooltip` paint the same rows. The positioned, themed card around it stays the renderer's.
+ */
+export declare const TooltipBody: ({ content }: TooltipBodyProps) => JSX.Element;
+
+declare interface TooltipBodyProps {
+    content: TooltipContent;
+}
+
+/** Page-relative cursor position the tooltip anchors to. `null` when the pointer is outside the chart. */
+export declare interface TooltipCursor {
+    clientX: number;
+    clientY: number;
+}
+
+/**
+ * Input a plugin's {@link GeomPluginBase.renderTooltip} receives when one of its observations is the
+ * primary hit. `content` is the body the built-in tooltip would render — feed it to `TooltipBody` to
+ * reproduce the default — while `primary.observation` carries the geom's own columns for a bespoke
+ * layout. The card around the body (positioning, theme) stays the renderer's.
+ */
+export declare interface TooltipRenderInput<G extends string = GeomName, C extends CoordKind = CoordKind, TParams = PluginParams<G>> {
+    content: TooltipContent;
+    layer: CompiledLayerFor<G, TParams>;
+    coordSystem: CoordSystemFor<C>;
+    primary: HoverHit;
+    group: HoverHit[];
+    related: ReadonlyMap<string, HoverHit[]>;
+}
+
+/**
+ * One tooltip row — swatch, label, value, with the optional in-place highlight. Exposed so a custom
+ * geom's `renderTooltip` can map `content.rows` itself and interleave its own content between rows,
+ * rather than rendering the whole {@link TooltipBody} as an opaque block.
+ */
+export declare const TooltipRowView: ({ row, shouldHighlight }: TooltipRowViewProps) => JSX.Element;
+
+declare interface TooltipRowViewProps {
+    row: TooltipRow;
+    shouldHighlight: boolean;
+}
+
+export declare const toPercent: (value: number) => string;
+
+/**
+ * Converts a normalized [0,1] x-coordinate to viewBox coordinate (identity transform).
+ * Used inside nested SVGs with viewBox="0 0 1 1".
+ */
+export declare function toViewBoxX(normalized: number): number;
+
+/**
+ * Converts a normalized [0,1] y-coordinate to viewBox coordinate (Y-inverted).
+ * SVG y=0 is at the top, but data y=0 is at the bottom, so we invert.
+ * Used inside nested SVGs with viewBox="0 0 1 1".
+ */
+export declare function toViewBoxY(normalized: number): number;
+
+/**
+ * An `<svg>` preset for painting Tier-C geometry in panel `[0,1]` unit space: `viewBox="0 0 1 1"`,
+ * `preserveAspectRatio="none"` (so unit coordinates stretch to fill the panel exactly, the way a bar
+ * chart's bars do), and `overflow: visible`.
+ *
+ * Chrome gotcha (documented once here, so geoms don't rediscover it): with a sub-unit `viewBox`, native
+ * SVG fill hit-testing is unreliable at this scale — which is why Tier-C geoms answer a numeric
+ * `useGeomHitTest` query instead of relying on pointer events landing on these shapes. Paint here; hit-test
+ * through the engine.
+ */
+export declare const UnitSpaceSvg: ({ children, style, ...rest }: SVGProps<SVGSVGElement>) => ReactNode;
+
+/**
+ * Returns an `index → colour` resolver over the chart's default categorical palette — the same
+ * `DEFAULT_COLOR_PALETTE` the compiler bakes into a colour-encoded layer — so a custom geom that
+ * assigns its own colour indices draws from the chart's palette instead of inventing a private one.
+ * Colours therefore match what a sibling layer's colour scale would produce, and follow the engine's
+ * palette rather than a hardcoded array.
+ *
+ * Out of scope (ADR-034 open question #4): declaring a colour *aesthetic* with its own scale + legend,
+ * or honouring a per-spec custom palette. This primitive only ensures the colours match the default.
+ */
+export declare function useCategoricalColor(): (index: number) => string;
+
+/**
+ * Registers a Tier-C geom's render-side hit-test for its layer, so the central hover engine routes
+ * the cursor to it — the geom inherits the built-in hover, tooltip, and (in time) accessibility
+ * instead of hand-rolling a pointer overlay. The geom declares `spatialKind: 'render-hit-test'`; this
+ * hook supplies the matching closure.
+ *
+ * The `tester` receives the cursor in panel `[0, 1]` with a top-left origin (the frame the geom
+ * paints in) and returns the declared identity key of the observation under it, or `null`. It may
+ * close over freshly computed geometry each render — a stable wrapper reads the latest through a ref,
+ * so the registration effect runs once per layer rather than every render.
+ */
+export declare function useGeomHitTest(layerId: string, tester: PanelHitTester): void;
+
+/**
+ * The push counterpart to `useGeomHitTest`, for a Tier-C geom that owns its own pointer surface — a
+ * live simulation whose interactive overlay intercepts pointer events before the central capture
+ * layer sees them, so the engine cannot pull a hit. The geom already knows which observation is under
+ * the cursor and pushes its declared identity key; the engine resolves it to the same unified
+ * `HoverState` the pull path produces, and the cursor is forwarded so the central tooltip tracks.
+ *
+ * Returns a stable `setHovered(key, cursor?)`: a key with the page-relative cursor opens the tooltip
+ * on that observation; `null` clears it.
+ */
+export declare function useGeomHover(layerId: string): (key: string | null, cursor?: TooltipCursor) => void;
+
+/**
+ * Tracks the on-screen rect of the element the returned `ref` is attached to, across container resize and
+ * page scroll. Only a live-simulation geom needs this (ADR-034 decision 4): it paints and hit-tests
+ * render-side every frame, so its interactive overlay must sit above the chart in pixel space. Every other
+ * Tier-C geom routes hover through the engine (decision 2) and never tracks a screen rect.
+ */
+export declare function usePanelScreenRect(): {
+    ref: RefCallback<Element>;
+    rect: PanelScreenRect | null;
+};
+
+/**
+ * Animates SVG path transitions using `d3-interpolate-path` for smooth morphing
+ * when data points are added or removed (Framer Motion doesn't support this natively).
+ *
+ * Based on: https://github.com/framer/motion/issues/451#issuecomment-761302824
+ */
+export declare const useSvgPathMorph: (pathDefinition: string, config: AnimationPlaybackOptions) => MotionValue<string>;
+
+export declare const vars: {
+    white: `var(--${string})`;
+    black: `var(--${string})`;
+    transparent: `var(--${string})`;
+    grey100: `var(--${string})`;
+    grey95: `var(--${string})`;
+    grey90: `var(--${string})`;
+    grey85: `var(--${string})`;
+    grey80: `var(--${string})`;
+    grey75: `var(--${string})`;
+    grey70: `var(--${string})`;
+    grey60: `var(--${string})`;
+    grey50: `var(--${string})`;
+    grey0: `var(--${string})`;
+    greyGradient80: `var(--${string})`;
+    green60: `var(--${string})`;
+    green50: `var(--${string})`;
+    red60: `var(--${string})`;
+    red50: `var(--${string})`;
+    amber70: `var(--${string})`;
+    amber50: `var(--${string})`;
+    amber40: `var(--${string})`;
+    amber30: `var(--${string})`;
+    blue80: `var(--${string})`;
+    blue60: `var(--${string})`;
+    purple50: `var(--${string})`;
+    purple30: `var(--${string})`;
+    brand: `var(--${string})`;
+    success: `var(--${string})`;
+    warning: `var(--${string})`;
+    alert: `var(--${string})`;
+    textPrimary: `var(--${string})`;
+    textSecondary: `var(--${string})`;
+    textDisabled: `var(--${string})`;
+    iconPrimary: `var(--${string})`;
+    iconSecondary: `var(--${string})`;
+    iconStickerBackground: `var(--${string})`;
+    border100: `var(--${string})`;
+    border50: `var(--${string})`;
+    border10: `var(--${string})`;
+    sunkenBackground: `var(--${string})`;
+    defaultBackground: `var(--${string})`;
+    raisedBackground: `var(--${string})`;
+    overlayBackground: `var(--${string})`;
+    overlayBorderGradient: `var(--${string})`;
+    graphBackground: `var(--${string})`;
+    gridLineColor: `var(--${string})`;
+    originLineColor: `var(--${string})`;
+    targetLineColor: `var(--${string})`;
+    targetLineMarkerColor: `var(--${string})`;
+    targetLineLabelTextColor: `var(--${string})`;
+    legendBackground: `var(--${string})`;
+    legendBorderColor: `var(--${string})`;
+    legendFocusOutlineColor: `var(--${string})`;
+    legendTextColor: `var(--${string})`;
+    dimmedSeriesLabelTextColor: `var(--${string})`;
+    dimmedSeriesLabelLineColor: `var(--${string})`;
+    trendNegativeColor: `var(--${string})`;
+    trendPositiveColor: `var(--${string})`;
+    trendNeutralColor: `var(--${string})`;
+    defaultAnnotationArrowStroke: `var(--${string})`;
+    defaultAnnotationShapeStroke: `var(--${string})`;
+    defaultAnnotationShapeFill: `var(--${string})`;
+    arrowAnnotationStickerOutlineColor: `var(--${string})`;
+    arrowAnnotationStickerOutlineColorInverse: `var(--${string})`;
+    annotationFrameBorderColor: `var(--${string})`;
+    annotationMenuTriggerIconColor: `var(--${string})`;
+    heatmapEmptyTileBackground: `var(--${string})`;
+    dataLabelOutsideBackground: `var(--${string})`;
+    canvasDefault: `var(--${string})`;
+    canvasBlue: `var(--${string})`;
+    canvasCyan: `var(--${string})`;
+    canvasGreen: `var(--${string})`;
+    canvasYellow: `var(--${string})`;
+    canvasOrange: `var(--${string})`;
+    canvasRed: `var(--${string})`;
+    canvasPink: `var(--${string})`;
+    canvasPurple: `var(--${string})`;
+    canvasGray: `var(--${string})`;
+    canvasInverse: `var(--${string})`;
+    elevationXs: `var(--${string})`;
+    elevationSm: `var(--${string})`;
+    elevationMd: `var(--${string})`;
+    elevationLg: `var(--${string})`;
+    radiiXs: `var(--${string})`;
+    radiiSm: `var(--${string})`;
+    radiiMd: `var(--${string})`;
+    radiiLg: `var(--${string})`;
+    spaceXxs: `var(--${string})`;
+    spaceXs: `var(--${string})`;
+    spaceSm: `var(--${string})`;
+    spaceMd: `var(--${string})`;
+    spaceLg: `var(--${string})`;
+    spaceXl: `var(--${string})`;
+    zIndexToolbar: `var(--${string})`;
+    zIndexToolbarTooltip: `var(--${string})`;
+    zIndexToolbarPopover: `var(--${string})`;
+    toolbarBackgroundColor: `var(--${string})`;
+    toolbarButtonBackgroundColor: `var(--${string})`;
+    toolbarButtonBackgroundColorHovered: `var(--${string})`;
+    toolbarButtonBackgroundColorSelected: `var(--${string})`;
+    toolbarSeparatorColor: `var(--${string})`;
+    tooltipBackground: `var(--${string})`;
+    tooltipBorderColor: `var(--${string})`;
+    tooltipHeadingTextColor: `var(--${string})`;
+    tooltipLabelTextColor: `var(--${string})`;
+    tooltipValueTextColor: `var(--${string})`;
+    tooltipPrimaryRowColor: `var(--${string})`;
+    hoverGuideLineColor: `var(--${string})`;
+    hoverGuideFillColor: `var(--${string})`;
+    hoveredBarBorderColor: `var(--${string})`;
+    hoveredPointRingColor: `var(--${string})`;
+    pointStrokeColor: `var(--${string})`;
+    stackedBarHoverBorderColor: `var(--${string})`;
+    fontFamilyDefault: `var(--${string})`;
+    fontFamilyHeading: `var(--${string})`;
+    fontWeightRegular: `var(--${string})`;
+    fontWeightMedium: `var(--${string})`;
+    fontWeightSemibold: `var(--${string})`;
+    fontWeightBold: `var(--${string})`;
+    fontWeightExtraBold: `var(--${string})`;
+    fontWeightBlack: `var(--${string})`;
+    textScale: `var(--${string})`;
+    fontSizeXxs: `var(--${string})`;
+    fontSizeXs: `var(--${string})`;
+    fontSizeSm: `var(--${string})`;
+    fontSizeMd: `var(--${string})`;
+    fontSizeLg: `var(--${string})`;
+    fontSizeXl: `var(--${string})`;
+    fontLineHeightXxs: `var(--${string})`;
+    fontLineHeightXs: `var(--${string})`;
+    fontLineHeightSm: `var(--${string})`;
+    fontLineHeightMd: `var(--${string})`;
+    fontLineHeightLg: `var(--${string})`;
+    fontLineHeightXl: `var(--${string})`;
+    fontSizeEditorBody: `var(--${string})`;
+    fontSizeHeadingSm: `var(--${string})`;
+    fontSizeHeadingMd: `var(--${string})`;
+    fontSizeHeadingLg: `var(--${string})`;
+    fontLineHeightEditorBody: `var(--${string})`;
+    fontLineHeightHeadingSm: `var(--${string})`;
+    fontLineHeightHeadingMd: `var(--${string})`;
+    fontLineHeightHeadingLg: `var(--${string})`;
+    fontTickLabel: `var(--${string})`;
+    fontAxisLabel: `var(--${string})`;
+    fontDataLabel: `var(--${string})`;
+    fontStackTotal: `var(--${string})`;
+    fontLegendLabel: `var(--${string})`;
+    fontSeriesLabel: `var(--${string})`;
+    fontTooltipLabel: `var(--${string})`;
+    fontTooltipHeading: `var(--${string})`;
+    fontTooltipFooter: `var(--${string})`;
+    fontJumboTooltipLabel: `var(--${string})`;
+    fontJumboTooltip: `var(--${string})`;
+    fontMiniTooltipLabel: `var(--${string})`;
+    fontMiniTooltipFooter: `var(--${string})`;
+    fontTooltipCaption: `var(--${string})`;
+    fontTooltipCaptionSmall: `var(--${string})`;
+    fontTrendTag: `var(--${string})`;
+    fontTrendTagSmall: `var(--${string})`;
+    fontGoalLineLabel: `var(--${string})`;
+    fontPieLabel: `var(--${string})`;
+    fontPieChartTotal: `var(--${string})`;
+    fontDifferenceArrowSmall: `var(--${string})`;
+    fontDifferenceArrowMedium: `var(--${string})`;
+    fontDifferenceArrowLarge: `var(--${string})`;
+    fontButton: `var(--${string})`;
+    fontInput: `var(--${string})`;
+    fontInputLabel: `var(--${string})`;
+    fontSelectLabel: `var(--${string})`;
+    fontSelectDescription: `var(--${string})`;
+    fontColorSelectLabel: `var(--${string})`;
+    fontMenuTitle: `var(--${string})`;
+    fontMenuGroupTitle: `var(--${string})`;
+    fontMenuItemLabel: `var(--${string})`;
+    fontMenuItemLabelSecondary: `var(--${string})`;
+    fontUITooltip: `var(--${string})`;
+    fontUITooltipSecondary: `var(--${string})`;
+    fontErrorBoundaryTitle: `var(--${string})`;
+    fontErrorBoundaryMessage: `var(--${string})`;
+    fontTableCell: `var(--${string})`;
+    fontTableHeaderCell: `var(--${string})`;
+    fontSourceLabel: `var(--${string})`;
+    fontSourceLink: `var(--${string})`;
+    fontTextEditorH1: `var(--${string})`;
+    fontTextEditorH2: `var(--${string})`;
+    fontTextEditorH3: `var(--${string})`;
+    fontTextEditorH6: `var(--${string})`;
+    fontTextEditorBody: `var(--${string})`;
+    fontTextEditorLink: `var(--${string})`;
+    fontHighlightModeTitle: `var(--${string})`;
+    fontHighlightModeSubtitle: `var(--${string})`;
+};
+
+export { }