@graphysdk/react-renderer 1.9.0-beta.1792400629887 → 1.9.0-beta.1792407460425

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { AnchorPlacement } from '@graphysdk/viz-engine';
+import { BoxSize } from '@graphysdk/viz-engine';
 import { BrandMarkVariant } from '@graphysdk/viz-engine';
 import { CartesianCoordSystem } from '@graphysdk/viz-engine';
 import { ColorScheme } from '@graphysdk/viz-engine';
@@ -22,6 +23,8 @@ import { FormattedAxis } from '@graphysdk/viz-engine';
 import { FormattedHeadline } from '@graphysdk/viz-engine';
 import { FormattedLegend } from '@graphysdk/viz-engine';
 import { Geom } from '@graphysdk/viz-engine';
+import { GeomCornerRadius } from '@graphysdk/viz-engine';
+import { GeomEffects } from '@graphysdk/viz-engine';
 import { GeomName } from '@graphysdk/viz-engine';
 import { GeomStyleReaders } from '@graphysdk/viz-engine';
 import { GraphLayout } from '@graphysdk/viz-engine';
@@ -62,6 +65,7 @@ import { StylePointSymbol } from '@graphysdk/viz-engine';
 import { StyleReadersForLayer } from '@graphysdk/viz-engine';
 import { StyleReaderTree } from '@graphysdk/viz-engine';
 import { StyleResolver } from '@graphysdk/viz-engine';
+import { StyleState } from '@graphysdk/viz-engine';
 import { SVGProps } from 'react';
 import { TextContent } from '@graphysdk/viz-engine';
 import { TextMeasurer } from '@graphysdk/viz-engine';
@@ -247,23 +251,23 @@ export declare const DefaultFooter: ({ ref, footerRect, mode, caption, isCaption
  * at its position rather than traveling to it from an unset attribute at the panel's origin. An
  * entrance is the layer's to play, through {@link IntroFade} or {@link IntroWipeClip}.
  */
-export declare const DefaultGeomCircle: ({ shouldAnimateTransitions, cx, cy, r, ...paint }: GeomCircleProps) => JSX.Element;
+export declare const DefaultGeomCircle: ({ shouldAnimateTransitions, cx, cy, r, effects, ...paint }: GeomCircleProps) => JSX.Element;
 
 /** A straight line whose endpoints spring to their new positions — {@link GeomCircle} for a segment. */
-export declare const DefaultGeomLine: ({ shouldAnimateTransitions, x1, y1, x2, y2, ...paint }: GeomLineProps) => JSX.Element;
+export declare const DefaultGeomLine: ({ shouldAnimateTransitions, x1, y1, x2, y2, effects, ...paint }: GeomLineProps) => JSX.Element;
 
 /**
  * A path whose shape morphs to its new one — {@link GeomCircle} for a free shape, such as a polygon between two
  * bars. A path is drawn in pixels, so it takes the layer it is drawn from as `source`: a resize redraws it where
  * the percentage marks already are, rather than morphing behind them.
  */
-export declare const DefaultGeomPath: ({ shouldAnimateTransitions, d, source, ...paint }: GeomPathProps) => JSX.Element;
+export declare const DefaultGeomPath: ({ shouldAnimateTransitions, d, source, effects, ...paint }: GeomPathProps) => JSX.Element;
 
 /**
- * A rect whose origin and size spring to their new values — {@link GeomCircle} for a box. Motion reads `x`
+ * A rect whose origin, size and corners spring to their new values — {@link GeomCircle} for a box. Motion reads `x`
  * and `y` on an SVG element as a transform, so the origin springs through `attrX` and `attrY`, the attributes.
  */
-export declare const DefaultGeomRect: ({ shouldAnimateTransitions, x, y, width, height, ...paint }: GeomRectProps) => JSX.Element;
+export declare const DefaultGeomRect: ({ shouldAnimateTransitions, x, y, width, height, rx, ry, effects, ...paint }: GeomRectShapeProps) => JSX.Element;
 
 /**
  * Default paint for the grid region — per-tick grid lines, drawn inside the panel frame rect. Where a press
@@ -432,6 +436,8 @@ export declare interface GeomCircleProps {
     stroke?: string;
     strokeOpacity?: number;
     strokeWidth?: number;
+    /** Shadow, blend mode and filters from `readGeomEffects`. The resting shadow is `'none'` when the layer casts it. */
+    effects?: GeomEffects;
     /** Whether a change of center or radius springs to the new one. Snaps when false. */
     shouldAnimateTransitions: boolean;
     /** A geom's own test hook, since the primitive owns the painted element. */
@@ -452,9 +458,9 @@ export declare interface GeomHoverCursor {
 
 /**
  * Pushes a hovered observation key into the central hover, or clears this layer's hover with `null`.
- * A non-null key requires a `cursor` — the overlay intercepts the pointer events the cursor-follow
+ * A non-null key requires a `cursor` — a live geom takes the pointer events the cursor-follow
  * tooltip would otherwise read, so the anchor can only come from the geom's own handler. Consumed by
- * {@link InteractiveOverlayApi.pushHover} and returned by `useGeomHover`.
+ * {@link LiveGeomApi.pushHover} and returned by `useGeomHover`.
  */
 export declare interface GeomHoverPush {
     (key: string, cursor: GeomHoverCursor): void;
@@ -476,24 +482,54 @@ export declare interface GeomLineProps {
     strokeWidth?: number;
     strokeDasharray?: string;
     strokeLinecap?: 'butt' | 'round' | 'square';
+    /** Shadow, blend mode and filters from `readGeomEffects`. The resting shadow is `'none'` when the layer casts it. */
+    effects?: GeomEffects;
     /** Whether a change of either endpoint springs to the new one. Snaps when false. */
     shouldAnimateTransitions: boolean;
     'data-testid'?: string;
 }
 
+/** A live geom's paint function — receives the guaranteed wiring on `input.live`. */
+export declare type GeomLiveRenderFn<G extends GeomName | string = string, C extends CoordKind = CoordKind> = (input: GeomLiveRenderInput<G, C>) => ReactNode;
+
+/**
+ * The input a live render (`{ fn, options: { live: true } }`) receives: the standard render
+ * input plus a guaranteed {@link LiveGeomApi}.
+ */
+export declare interface GeomLiveRenderInput<G extends GeomName | string = string, C extends CoordKind = CoordKind> extends GeomRenderInput<G, C> {
+    live: LiveGeomApi;
+}
+
 /** A custom geom `getOverlayAnchor` handler's input: the layer, coord system, and the matched observation. */
 export declare type GeomOverlayAnchorRendererInput = OverlayAnchorInput;
 
-/** An overlay-hosted geom's paint function — receives the guaranteed overlay wiring on `input.overlay`. */
-export declare type GeomOverlayRenderFn<G extends GeomName | string = string, C extends CoordKind = CoordKind> = (input: GeomOverlayRenderInput<G, C>) => ReactNode;
-
 /**
- * The input an overlay-hosted render (`{ fn, options: { overlay: true } }`) receives: the standard render
- * input plus a guaranteed {@link InteractiveOverlayApi}. The renderer always supplies it, so the geom's
- * render uses `overlay` unconditionally — it never decides where it is mounted, only what it paints.
- */
-export declare interface GeomOverlayRenderInput<G extends GeomName | string = string, C extends CoordKind = CoordKind> extends GeomRenderInput<G, C> {
-    overlay: InteractiveOverlayApi;
+ * Draws a geom's overpaint over `children` alone, masked by their alpha. It shares their parents, so their
+ * transforms, clips and opacity. Patterns are laid out in panel pixels, so wrap a nested view box, not the shapes
+ * inside it.
+ *
+ * Use it in a geom that sets `overpaintPlacement: 'manual'`. Under the default `'layer'` the renderer already
+ * overpaints the hook, so a wrapper there paints its shapes twice. Do not nest one wrapper inside another, for the
+ * same reason.
+ *
+ * @example
+ *   // In a renderer defined with `overpaintPlacement: 'manual'`:
+ *   <>
+ *     {whiskers}
+ *     <GeomOverpaint styleReaders={styleReaders}>
+ *       {boxes}
+ *     </GeomOverpaint>
+ *     {medians}
+ *   </>
+ */
+export declare const GeomOverpaint: (props: GeomOverpaintProps) => JSX.Element;
+
+export declare interface GeomOverpaintProps {
+    /** The geom's readers; the overpaint is read from them. */
+    styleReaders: Pick<GeomStyleReaders, 'get'>;
+    state?: StyleState;
+    /** The shapes the overpaint covers. */
+    children: ReactNode;
 }
 
 export declare const GeomPath: (props: GeomPathProps) => JSX.Element;
@@ -513,12 +549,14 @@ export declare interface GeomPathProps {
     strokeOpacity?: number;
     strokeWidth?: number;
     strokeDasharray?: string;
+    /** Shadow, blend mode and filters from `readGeomEffects`. The resting shadow is `'none'` when the layer casts it. */
+    effects?: GeomEffects;
     /** Whether a change of shape morphs to the new one. Snaps when false. */
     shouldAnimateTransitions: boolean;
     'data-testid'?: string;
 }
 
-export declare const GeomRect: (props: GeomRectProps) => JSX.Element;
+export declare const GeomRect: ({ cornerRadius, ...props }: GeomRectProps) => JSX.Element;
 
 export declare interface GeomRectProps {
     x: ShapePosition;
@@ -531,20 +569,32 @@ export declare interface GeomRectProps {
     stroke?: string;
     strokeOpacity?: number;
     strokeWidth?: number;
+    /** A token or pixels, as `cornerRadius` reads from the geom's style. `'full'` rounds the shorter side. */
+    cornerRadius?: GeomCornerRadius;
+    /** Shadow, blend mode and filters from `readGeomEffects`. The resting shadow is `'none'` when the layer casts it. */
+    effects?: GeomEffects;
     /** Whether a change of origin or size springs to the new one. Snaps when false. */
     shouldAnimateTransitions: boolean;
     'data-testid'?: string;
 }
 
+/** The rect a theme's `Rect` draws, its corner radius resolved to the user units it is placed in. */
+export declare type GeomRectShapeProps = Omit<GeomRectProps, 'cornerRadius'> & {
+    /**
+     * Corner radii in user units, clamped to half the rect's shorter side on screen when its size is known. They differ
+     * inside a `UnitSpaceSvg`, whose units stretch to the panel, so the corner stays round.
+     */
+    rx?: number;
+    ry?: number;
+};
+
 /**
- * A geom's `render`: either a plain panel-SVG paint function, or an overlay-hosted one paired with
- * `options` — so a geom that must paint into the interactive overlay declares
- * `{ fn, options: { overlay: true } }` without a second render entry point. The
- * renderer decides where each is mounted; the geom only decides what it paints. `render` is the single
- * paint declaration either way.
+ * A geom's `render`: either a plain paint function, or a live one paired with `options`, so a geom
+ * that owns its pointer events declares `{ fn, options: { live: true } }` without a second render
+ * entry point.
  */
 export declare type GeomRender<G extends GeomName | string = string, C extends CoordKind = CoordKind> = GeomRenderFn<G, C> | {
-    fn: GeomOverlayRenderFn<G, C>;
+    fn: GeomLiveRenderFn<G, C>;
     options: GeomRenderOptions;
 };
 
@@ -571,9 +621,16 @@ export declare interface GeomRenderContract<G extends GeomName | string = string
      */
     guideMode?: HoverGuideMode | null;
     /**
-     * The geom's paint. A plain function paints into the panel SVG; the `{ fn, options: { overlay: true } }`
-     * form paints into a screen-aligned portal above the central capture layer for a live/drag-driven geom
-     * that owns its pointer events (force-directed), with the wiring on `input.overlay`.
+     * Where a geom `overpaint` lands. `'layer'`, the default, lays it over everything each hook draws.
+     * `'manual'` leaves it to the geom, which wraps its main shapes in `GeomOverpaint` itself so what it draws
+     * before or after them stays clear (a boxplot's whiskers and medians). A manual geom with no wrapper draws
+     * no overpaint.
+     */
+    overpaintPlacement?: OverpaintPlacement;
+    /**
+     * The geom's paint. A plain function paints with the other geoms; the `{ fn, options: { live: true } }`
+     * form paints above the central capture layer for a live or drag-driven geom that owns its pointer events
+     * (force-directed), with the wiring on `input.live`.
      */
     render: GeomRender<G, C>;
     /**
@@ -651,17 +708,14 @@ export declare interface GeomRenderInputBase {
     styleReaders: GeomStyleReaders;
 }
 
-/**
- * Hosting options for an overlay render. The presence of the object form already declares overlay hosting;
- * `overlay: true` makes the call site read explicitly (and leaves room for further hosting options later).
- */
+/** Options for the object form of `render`. */
 export declare interface GeomRenderOptions {
     /**
-     * Mount this render's output in a screen-aligned portal above the central capture layer, rather than in
-     * the panel SVG — for a live or drag-driven geom that must own its pointer events (force-directed). The
-     * renderer then supplies {@link GeomOverlayRenderInput.overlay}.
+     * Paint this render above the central capture layer rather than with the other geoms, for a live or
+     * drag-driven geom that must own its pointer events (force-directed). It still paints in the panel SVG, in
+     * the same units as every other geom. The renderer then supplies {@link GeomLiveRenderInput.live}.
      */
-    overlay: true;
+    live: true;
 }
 
 /**
@@ -671,7 +725,7 @@ export declare interface GeomRenderOptions {
 export declare interface GeomShapes {
     Circle?: ComponentType<GeomCircleProps>;
     Line?: ComponentType<GeomLineProps>;
-    Rect?: ComponentType<GeomRectProps>;
+    Rect?: ComponentType<GeomRectShapeProps>;
     Path?: ComponentType<GeomPathProps>;
 }
 
@@ -1112,21 +1166,6 @@ declare interface HoverStoreActions {
 /** State of the hover store: the current {@link HoverState} plus its setter. */
 declare type HoverStoreState = HoverSlice & HoverStoreActions;
 
-/**
- * The overlay wiring handed to an overlay-hosted render via {@link GeomOverlayRenderInput.overlay}. The
- * geom writes only its simulation, marks, and drag handlers; the renderer owns the on-screen rect
- * measurement, the portal alignment, and the push wiring.
- */
-export declare interface InteractiveOverlayApi {
-    /** Feeds the hovered observation's identity key into the unified hover store — the push path. */
-    pushHover: GeomHoverPush;
-    /**
-     * The panel's on-screen rect in client pixels, so the overlay can place its marks. Distinct from
-     * {@link GeomRenderInput.panelRect} (layout pixels).
-     */
-    panelRect: ScreenRect;
-}
-
 declare interface IntroAnimationOptions {
     /** Whether the entrance plays at all */
     enabled: boolean;
@@ -1214,6 +1253,20 @@ export declare const lightenCss: (colorString: string, amount: number) => string
 /** vanilla-extract class that binds the light token values; the default theme. */
 export declare const lightTheme: string;
 
+/**
+ * The wiring handed to a live render via {@link GeomLiveRenderInput.live}. The geom
+ * writes only its simulation, marks, and drag handlers; the renderer owns the push wiring.
+ */
+export declare interface LiveGeomApi {
+    /** Feeds the hovered observation's identity key into the unified hover store — the push path. */
+    pushHover: GeomHoverPush;
+    /**
+     * A pointer's client coordinates in the panel's units, whatever the graph's on-screen scale, so a drag
+     * moves a mark to the pointer. `null` before the panel mounts.
+     */
+    readPanelPoint: (cursor: GeomHoverCursor) => PanelPoint | null;
+}
+
 declare interface MorphingEditOutlineShape {
     /** SVG path data in panel pixels. */
     pathData: string;
@@ -1238,6 +1291,9 @@ declare interface OverlayAnchorInput<G extends GeomName | string = string, C ext
     observation: Observation;
 }
 
+/** Where a geom `overpaint` lands: over everything a hook draws, or where the geom wraps it itself. */
+export declare type OverpaintPlacement = 'layer' | 'manual';
+
 export declare interface PaintDefs {
     /** The `fill` attribute for a paint: the color itself, or a `url(#id)` into the defs this SVG renders. */
     fillFor: (paint: ResolvedPaint) => string;
@@ -1259,6 +1315,12 @@ export declare interface PaintGridOrigin {
     y: number;
 }
 
+/** A point in the panel's own units, the space a geom's `render` paints in. */
+export declare interface PanelPoint {
+    x: number;
+    y: number;
+}
+
 /** The stroke a line or an area edge paints, named as SVG props so it spreads onto a `<path>` as is. */
 export declare interface PathStroke {
     strokeWidth: number;
@@ -1286,6 +1348,18 @@ export declare const projectPointCartesian: PointProjection;
  */
 export declare const pruneSelection: (selection: readonly EditTarget[], spec: ResolvedSpec) => readonly EditTarget[];
 
+/**
+ * A shared rect's box in pixels from the top-left of the panel (or `UnitBoxSvg`) it is drawn in, not from the graph
+ * container as a layout rect is. `null` when any side is a unit-space coordinate, as in {@link readShapePixels}.
+ */
+export declare const readShapePixelRect: ({ x, y, width, height }: Pick<GeomRectProps, "x" | "y" | "width" | "height">, panel: BoxSize) => Rect | null;
+
+/**
+ * A position in pixels along a panel `extent` pixels long. `null` for a unit-space coordinate, which the
+ * panel's size does not scale, so a theme shape draws the default there.
+ */
+export declare const readShapePixels: (position: ShapePosition, extent: number) => number | null;
+
 export { RenderHitTester }
 
 /** Fires on each deduped size change — the shape of `GraphRenderer`'s `onResize` callback. */
@@ -1623,6 +1697,7 @@ export declare interface UnitBox {
 /**
  * A nested SVG over a unit-space box, placed in panel percentages, with no viewBox. Children live in the
  * box's own unscaled space (`50%` is the center, a pixel radius is a pixel) and are clipped by the viewport.
+ * A theme shape inside reads the box's pixel size from `useGeomPanelSize`, since its percentages resolve against the box.
  */
 export declare const UnitBoxSvg: ({ box, children }: {
     box: UnitBox;
@@ -1633,7 +1708,8 @@ export declare const UnitBoxSvg: ({ box, children }: {
  * A nested SVG that establishes a `[0, 1]` unit coordinate space (top-left origin) stretched to fill
  * the geom panel. A layout geom paints its geometry in raw unit coords so paint and hit-test never re-project against each
  * other. `preserveAspectRatio="none"` maps the unit square onto the (usually non-square) panel exactly.
- * Circles and glyphs stretch here — put them in {@link UnitBoxSvg}.
+ * Circles and glyphs stretch here — put them in {@link UnitBoxSvg}. A theme shape inside reads no panel size, since a
+ * user unit there is the whole panel; a shared rect still reads it, to keep its corners round.
  */
 export declare const UnitSpaceSvg: ({ children, ...rest }: UnitSpaceSvgProps) => ReactNode;
 
@@ -1676,15 +1752,23 @@ export declare function useGeomHitTest(layerId: string, tester: RenderHitTester)
  * drawn (a live simulation) and so owns its own pointer surface above the central capture layer. The
  * geom's pointer handlers call the returned setter with the hovered observation's `identityKey`; the
  * engine resolves it through the same `byKey` lookup the pull path uses, so the geom inherits the tooltip
- * and `renderHover`. Since the overlay intercepts the pointer events, the tooltip is anchored at the
- * supplied cursor. Pass `null` to clear. Geoms with geometry fixed once drawn use `useGeomHitTest`.
+ * and `renderHover`. Since the geom takes the pointer events, the tooltip is anchored at the supplied
+ * cursor. Pass `null` to clear. Geoms with geometry fixed once drawn use `useGeomHitTest`.
  *
- * Escape hatch: an interactive geom should instead declare an overlay-hosted `render`
- * (`{ fn, options: { overlay: true } }`), which the renderer portals into a screen-aligned overlay and
- * hands a ready `pushHover` via `input.overlay`. Reach for this hook only when that form is not enough.
+ * Escape hatch: a live geom should instead declare a live `render`
+ * (`{ fn, options: { live: true } }`), which the renderer paints above the capture layer and
+ * hands a ready `pushHover` via `input.live`. Reach for this hook only when that form is not enough.
  */
 export declare function useGeomHover(layerId: string): GeomHoverPush;
 
+/**
+ * The pixel size of the panel the shape is drawn in, for a theme shape whose drawing depends on pixels (chalk
+ * strokes a set distance apart, a grid of typed characters). `null` outside a geom layer and inside a `UnitSpaceSvg`,
+ * whose unit coordinates no pixel size scales. Inside a `UnitBoxSvg` it is the box's size, since a shape's percentages
+ * resolve against the nearest `<svg>`.
+ */
+export declare const useGeomPanelSize: () => BoxSize | null;
+
 /** The resolver's `geom` subtree, one object per resolver, so the selector never re-renders on a chrome change. */
 export declare const useGeomReaderTree: () => StyleReaderTree["geom"];