@graphysdk/react-renderer 0.0.1-plugins.3 → 0.0.1-plugins.5

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { AnimationPlaybackOptions } from 'motion/react';
+import { AnnotationDef } from '@graphysdk/viz-engine';
 import { AnnotationZOrder } from '@graphysdk/viz-engine';
 import { AppearanceConfig } from '@graphysdk/viz-engine';
 import { CartesianCoordSystem } from '@graphysdk/viz-engine';
@@ -10,7 +12,7 @@ import { CSSProperties } from 'react';
 import { CustomPalettesInput } from '@graphysdk/viz-engine';
 import { Data } from '@graphysdk/viz-engine';
 import { FontSpec } from '@graphysdk/viz-engine';
-import { Geom } from '@graphysdk/viz-engine/extensions';
+import { Geom } from '@graphysdk/viz-engine';
 import { GeomIdentity } from '@graphysdk/viz-engine';
 import { GeomName } from '@graphysdk/viz-engine';
 import { GraphLayout } from '@graphysdk/viz-engine';
@@ -19,14 +21,21 @@ import { HighlightStrategy } from '@graphysdk/viz-engine';
 import { HoverHit } from '@graphysdk/viz-engine';
 import { HoverState } from '@graphysdk/viz-engine';
 import { JSX } from 'react/jsx-runtime';
+import { LineStyleType } from '@graphysdk/viz-engine';
 import { Locale } from '@graphysdk/viz-engine';
 import { MeasuredText } 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 { TextMeasurer } 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.
@@ -34,7 +43,7 @@ import { TooltipContent } from '@graphysdk/viz-engine';
  * 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.
  */
-declare interface AnnotationDrawInput<TParams extends object = object> {
+export declare interface AnnotationDrawInput<TParams extends object = object> {
     targets: readonly ResolvedTarget[];
     area: {
         width: number;
@@ -49,12 +58,20 @@ declare interface AnnotationDrawInput<TParams extends object = object> {
  * `draw` is a React render function that may reuse the render kit (theme tokens, `toPercent`, value
  * readers) but never participates in hover.
  */
-declare interface AnnotationPlugin {
+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 }
+
 /**
  * Browser text measurer backed by OffscreenCanvas.
  *
@@ -109,13 +126,60 @@ export declare class CanvasTextMeasurer implements TextMeasurer {
     private getEmojiCorrection;
 }
 
-declare type CoordKind = CoordSystem['type'];
+/**
+ * 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;
 
 export declare const darkTheme: string;
 
+/**
+ * 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 DevToolsPanel: ({ width, style, className }?: DevToolsPanelProps) => JSX.Element;
 
 /**
@@ -132,6 +196,16 @@ export declare interface DevToolsPanelProps {
     className?: string;
 }
 
+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;
 
@@ -152,7 +226,7 @@ declare type GeomHighlightStrategy = HighlightStrategy | null;
  * {@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.
  */
-declare type GeomPlugin<G extends string = GeomIdentity, C extends CoordKind = CoordKind> = NoOverlayAnchorGeomPlugin<G, C, GeomHighlightStrategy, PluginParams<G>> | OverlayAnchorGeomPlugin<G, C, GeomHighlightStrategy, PluginParams<G>>;
+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;
@@ -176,7 +250,26 @@ declare interface GeomPluginBase<G extends string, C extends CoordKind, S extend
     renderTooltip?: (input: TooltipRenderInput<G, C, TParams>) => ReactNode;
 }
 
-declare interface GeomRenderInput<G extends string = GeomName, C extends CoordKind = CoordKind, TParams = PluginParams<G>> {
+/**
+ * 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;
@@ -229,13 +322,13 @@ export declare interface GraphRendererProps {
     mode?: GraphMode;
 }
 
-declare interface HoverCompanionsRenderInput<G extends string = GeomName, TParams = PluginParams<G>> {
+export declare interface HoverCompanionsRenderInput<G extends string = GeomName, TParams = PluginParams<G>> {
     layer: CompiledLayerFor<G, TParams>;
     primary: HoverHit;
     related: HoverHit[];
 }
 
-declare type HoverGuideMode = 'continuous' | 'bar';
+export declare type HoverGuideMode = 'continuous' | 'bar';
 
 /**
  * Hosts the hover store + engine for the surrounding `<GraphProvider>`. Subscribes only to the
@@ -248,7 +341,7 @@ declare interface HoverProviderProps {
     children: ReactNode;
 }
 
-declare interface HoverRenderInput<G extends string = GeomName, C extends CoordKind = CoordKind, TParams = PluginParams<G>> {
+export declare interface HoverRenderInput<G extends string = GeomName, C extends CoordKind = CoordKind, TParams = PluginParams<G>> {
     layer: CompiledLayerFor<G, TParams>;
     coordSystem: CoordSystemFor<C>;
     primary: HoverHit;
@@ -275,8 +368,18 @@ declare interface HoverStoreActions {
 
 declare type HoverStoreState = HoverSlice & HoverStoreActions;
 
+/** 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;
+
 export declare const lightTheme: 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
@@ -290,7 +393,7 @@ declare interface NoOverlayAnchorGeomPlugin<G extends string, C extends CoordKin
  * 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.
  */
-declare interface OverlayAnchor {
+export declare interface OverlayAnchor {
     x: number;
     y: number;
 }
@@ -300,15 +403,74 @@ declare interface OverlayAnchorGeomPlugin<G extends string, C extends CoordKind,
     getOverlayAnchor: (input: OverlayAnchorInput<G, C, TParams>) => OverlayAnchor | null;
 }
 
-declare interface OverlayAnchorInput<G extends string = GeomName, C extends CoordKind = CoordKind, TParams = PluginParams<G>> {
+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 geom-layout 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;
+}
+
 /**
  * Creates a font-ready, cached text measurer and shares it with descendants via context.
  * Renders nothing until the measurer resolves, so consumers reading the context always
@@ -348,13 +510,31 @@ declare interface ThemeProviderProps {
 
 export declare type ThemeValues = Record<keyof typeof vars, string>;
 
+/**
+ * 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.
  */
-declare interface TooltipRenderInput<G extends string = GeomName, C extends CoordKind = CoordKind, TParams = PluginParams<G>> {
+export declare interface TooltipRenderInput<G extends string = GeomName, C extends CoordKind = CoordKind, TParams = PluginParams<G>> {
     content: TooltipContent;
     layer: CompiledLayerFor<G, TParams>;
     coordSystem: CoordSystemFor<C>;
@@ -363,6 +543,57 @@ declare interface TooltipRenderInput<G extends string = GeomName, C extends Coor
     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 geom-layout 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 geom-layout 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;
+
 /**
  * Subscribes to a derived slice of the compiled spec. The subscription only fires when the
  * selector's result changes by reference, so combined with the compiler's per-stage memoization
@@ -376,6 +607,31 @@ declare interface TooltipRenderInput<G extends string = GeomName, C extends Coor
  */
 export declare const useCompiledSelector: <Selected>(selector: (compiled: CompiledSpec) => Selected) => Selected;
 
+/**
+ * Registers a geom-layout 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 geom-layout 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;
+
 export declare const useGraphCommandDispatcher: () => ((command: Command) => void);
 
 /**
@@ -383,6 +639,25 @@ export declare const useGraphCommandDispatcher: () => ((command: Command) => voi
  */
 export declare function useHoverState<T>(selector: (state: HoverStoreState) => T): T;
 
+/**
+ * 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
+ * geom-layout 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 useTextMeasurer: () => TextMeasurer;
 
 export declare const vars: {