@graphysdk/viz-engine 0.0.1-plugins.3 → 0.0.1-plugins.5

package/dist/index.d.ts

@@ -96,7 +96,7 @@ export declare interface AngleExtent {
  * render-half `draw` lives in the renderer and binds to this definition by import (`defineAnnotationRenderer`).
  */
 /** Optional coordinate-count guardrail enforced by the builder; unbounded when omitted. */
-declare interface AnnotationArity {
+export declare interface AnnotationArity {
     min?: number;
     max?: number;
 }
@@ -142,7 +142,7 @@ declare interface AnnotationDataPoint {
     rowValue?: DataValue;
 }
 
-declare interface AnnotationDef<TParams extends object = object, TType extends string = string> {
+export declare interface AnnotationDef<TParams extends object = object, TType extends string = string> {
     type: TType;
     /** Carrier that lets the builder recover `TParams` and merge defaults before a param reaches `draw`. */
     defaultParams: TParams;
@@ -1114,7 +1114,7 @@ export declare interface CompiledFreeformArrow {
     hasStickerStyle: boolean;
 }
 
-declare interface CompiledGeom {
+export declare interface CompiledGeom {
     /** The reparameterized dataset (may have new computed variables) */
     data: Dataset;
     /** Any mapping overrides produced by the geom */
@@ -1864,7 +1864,7 @@ declare interface CoordTransformInput {
  * - `'polar'` — Polar coordinates for pie, radar, and radial charts
  * - `'flip'` — Cartesian with x and y axes swapped
  */
-declare type CoordType = 'cartesian' | 'polar' | 'flip';
+export declare type CoordType = 'cartesian' | 'polar' | 'flip';
 
 declare function count(): CountStatSpec;
 
@@ -1916,6 +1916,9 @@ export declare const createGroupValueReader: (data: Dataset, mapping: AesMapping
 
 export declare const createLabelValueReader: (data: Dataset, mapping: AesMapping) => (observation: Observation) => DataValue;
 
+/** Opens a {@link MarkTable} builder for a heterogeneous, kind-tagged geom-layout dataset. */
+export declare function createMarkTable(): MarkTable;
+
 /**
  * Builds a per-observation reader for an `AestheticValue`:
  * - `{ value: X }` → returns `X` for every observation.
@@ -2468,6 +2471,18 @@ declare type DefaultPaletteConfig = {
     type: 'default';
 };
 
+/**
+ * `TType` is a `const` type parameter so the literal kind name (`'calloutBox'`) survives to the type
+ * level — the registration-typed builder keys `annotation.<kind>(...)` off it, the same way
+ * `createGraphyBuilder` captures a geom's name. `TParams` is recovered from `defaultParams`; annotate or
+ * cast it (`defaultParams: {...} as CalloutBoxParams`) when a param's literal union would otherwise widen.
+ */
+export declare function defineAnnotation<const TType extends string, TParams extends object = object>(def: {
+    type: TType;
+    defaultParams?: TParams;
+    coordinates?: AnnotationArity;
+}): AnnotationDef<TParams, TType>;
+
 declare interface DifferenceArrowDimensions {
     /** Gap between the arrow start point and its anchored observation. */
     arrowStartGap: number;
@@ -2584,9 +2599,21 @@ export declare interface ExternalMeasurements {
     footerSize: BoxSize;
 }
 
+/**
+ * Extracts the constant value from a `{ value }` mapping. Returns undefined for variable mappings.
+ */
+export declare function extractConstantValue(aestheticValue: AestheticValue | undefined): DataValue | undefined;
+
 /** Flattens a title, subtitle, or caption to plain text for measurement and static renderers. */
 export declare const extractPlainText: (content: TextContent) => string;
 
+/**
+ * Extracts the variable name from an AestheticValue.
+ * Returns the variable name for string shorthands and { variable } mappings.
+ * Returns null for constant { value } mappings or undefined values.
+ */
+export declare function extractVariableName(aestheticValue: AestheticValue | undefined): VariableName | null;
+
 declare function filter(options: FilterOptions): FilterTransformInput;
 
 /***************************************************************
@@ -2623,6 +2650,24 @@ export declare function findAxisGuide(guides: CompiledGuides, scaleAestheticKey:
  */
 export declare function findLegendForAesthetic(guides: CompiledGuides, aesthetic: AestheticKey): CompiledLegendGuide | null;
 
+/**
+ * A gate fixture: a chart authored as plain data — its spec, the custom geom(s) it uses, and the rows —
+ * with no React. The codegen harness's compile and semantic gates load one (authored beside the geom as
+ * `src/<name>.fixture.ts`, exporting a `fixture`) to check that the geom compiles to finite, serialisable
+ * positions and that a synthetic cursor placed on each probed observation resolves hover and a localised
+ * tooltip. It is the rendered chart minus the renderer, so the gates run headlessly.
+ */
+export declare interface Fixture {
+    /** The custom geom instance(s) to register with the compiler — the same instances the spec uses. */
+    geoms: readonly Geom[];
+    /** The spec rendered in `App.tsx`, built with `createGraphyBuilder` + `pipe`. */
+    spec: SpecInput;
+    /** Rows matching the spec's channels (OHLC for a candlestick, a node/link graph for a sankey, …). */
+    data: Data;
+    /** Observation indices the semantic gate fires a cursor at. Defaults to `[0]` when omitted. */
+    probes?: number[];
+}
+
 declare interface FlipCoordInput {
     type: 'coord';
     coordType: 'flip';
@@ -2792,7 +2837,7 @@ declare type GenerateTicksOptions = {
  * empty default and keep their typed params through the spec builder's static surface; a custom geom
  * names its params type and declares matching {@link defaultParams}.
  */
-declare abstract class Geom<TParams extends object = object> {
+export declare abstract class Geom<TParams extends object = object> {
     /**
      * The aesthetics an author must map for this geom. Built-ins list closed aesthetic keys
      * (`['x','y']`); a custom geom may also list open channel names (a box plot's `min`/`q1`/…) that it
@@ -2884,6 +2929,13 @@ declare abstract class Geom<TParams extends object = object> {
      * renderer how to place the annotation.
      */
     resolveAnchorPosition(_observation: Observation, _coordSystem: CoordSystem): AnchorPosition | null;
+    /**
+     * Reparameterizes the stat-transformed data into the shape this geom's geometry needs, the central
+     * hook a custom geom implements. Receives the transformed dataset, effective mapping and geom params;
+     * returns the dataset with any computed position variables added (e.g. a bar's `xMin`/`xMax`/`yMin`
+     * interval), the mapping overrides the geom injects, and any extra tooltip rows it contributes. The
+     * compile pipeline runs this per layer before the position and visual mappers read the result.
+     */
     abstract compile(input: GeomCompilerInput): CompiledGeom;
     /**
      * Validates the layer's mapping against invariants specific to this geom (e.g. a rule needs exactly
@@ -2952,7 +3004,7 @@ declare class GeomCompiler {
     resolveAnchorPosition(geomName: GeomIdentity, observation: Observation, coordSystem: CoordSystem): AnchorPosition | null;
 }
 
-declare interface GeomCompilerInput {
+export declare interface GeomCompilerInput {
     /** The dataset after stat transformation */
     data: Dataset;
     /** The effective mapping for the layer */
@@ -3020,7 +3072,7 @@ declare class GeomRegistry extends Registry<string, Geom> {
  * data: the `label` is static text and the `variable` names a column, so the rows ride in the
  * serialisable compiled spec.
  */
-declare interface GeomTooltipRow {
+export declare interface GeomTooltipRow {
     /** The row's label (e.g. "Open"). Static text the geom supplies. */
     label: string;
     /** The data column whose per-observation value the row displays. */
@@ -3244,7 +3296,7 @@ declare type GraphyPaletteVariant = 'default' | 'waterfall';
  * for instance. A geom declares these so the axis guide resolves grid policy from the definition
  * instead of a geom-keyed lookup. Every field absent means the geom imposes no policy.
  */
-declare interface GridPolicy {
+export declare interface GridPolicy {
     hideGridX?: boolean;
     hideGridY?: boolean;
     hideBorder?: boolean;
@@ -3648,10 +3700,10 @@ export declare class HoverEngine {
      */
     private nonInteractiveLayerIds;
     /**
-     * Render-side hit-testers registered per layer for `render-hit-test` (Tier-C) layers, keyed by
+     * Render-side hit-testers registered per layer for `render-hit-test` (geom-layout) layers, keyed by
      * `CompiledLayer.id`. The renderer owns this map and injects it via {@link setHitTesters}; the
      * engine holds the live reference so a plugin mounting or updating its tester is visible at the
-     * next `query()` without a re-index. Empty for charts with no Tier-C geom.
+     * next `query()` without a re-index. Empty for charts with no geom-layout geom.
      */
     private hitTesters;
     constructor({ layers, coordSystem }: HoverEngineInput);
@@ -3792,6 +3844,17 @@ declare interface InferredScaleInput {
 
 declare type InferredScaleOptions = ContinuousScaleOptions | DiscreteScaleOptions | DatetimeScaleOptions;
 
+/**
+ * Recovers where a raw sub-value sits inside an already-scaled interval. Given a raw `[rawLo, rawHi]`
+ * pair that the compiler mapped to the scaled `[scaledLo, scaledHi]` endpoints, returns the scaled
+ * position of `raw` by affine interpolation. The geom-scaled trick a candlestick uses to place its open/close
+ * inside the scaled `[low, high]` wick without re-running the y-scale.
+ *
+ * Exact only when the scale between raw and scaled space is **linear** — both endpoints pin a straight
+ * line every interior value reads off. A degenerate interval (`rawLo === rawHi`) returns `scaledLo`.
+ */
+export declare function interpolateInScaledInterval(raw: number, rawLo: number, rawHi: number, scaledLo: number, scaledHi: number): number;
+
 /**
  * Curve interpolation method for lines and areas.
  *
@@ -4283,6 +4346,30 @@ declare interface MappingItem {
     mapping: AesMapping;
 }
 
+/** Declares one mark kind's own columns and the data type of each. */
+export declare type MarkColumnSchema = Record<string, DataType>;
+
+/**
+ * Builds one columnar {@link Dataset} from heterogeneous marks discriminated by a `kind` column — *the*
+ * geom-layout dataset shape (node+link, group+leaf, node+edge). Each kind declares its own columns; the union
+ * across kinds forms the dataset's columns, and a row's off-kind columns are filled with `null` **by
+ * construction**, so the null-padding invariant a hand-built builder maintains by hand (and breaks when a
+ * column is omitted from one kind's push) can no longer drift.
+ */
+declare class MarkTable {
+    /** Column name → declared type, accumulated as the union across every declared kind. */
+    private readonly columnTypes;
+    /** Kind name → the column names that kind owns. */
+    private readonly kindColumns;
+    private readonly rows;
+    /** Declares a mark kind and the columns it carries. Throws if the kind repeats or a column's type conflicts. */
+    kind(name: string, columns: MarkColumnSchema): this;
+    /** Appends one row for a declared kind. Throws if the kind is unknown, or a value misses/overshoots the kind's columns. */
+    push(kind: string, values: Record<string, DataValue>): this;
+    /** Materialises the rows into a {@link Dataset}, null-padding every off-kind column. */
+    toDataset(options: ToDatasetOptions): Dataset;
+}
+
 declare function mean(): MeanStatSpec;
 
 /**
@@ -4476,7 +4563,7 @@ declare interface PanelConfig {
 }
 
 /**
- * A render-side hit-test a Tier-C geom registers for a `render-hit-test` layer. The engine calls it
+ * A render-side hit-test a geom-layout geom registers for a `render-hit-test` layer. The engine calls it
  * with the cursor in panel `[0, 1]` space using a **top-left origin (y-down)** — the same frame the
  * geom paints in (unit-space SVG / `toPercent`), so the geom can test against its own rendered
  * geometry without re-flipping. It returns the declared identity `key` of the observation under the
@@ -4745,7 +4832,7 @@ declare interface PositionalScaleMethods {
  * derives from. A geom's channels are the manifest the position mapper and coord projection iterate
  * instead of hardcoding the column set.
  */
-declare type PositionChannel = RolePositionChannel | ScalarPositionChannel;
+export declare type PositionChannel = RolePositionChannel | ScalarPositionChannel;
 
 declare interface PositionChannelBase {
     axis: ChannelAxis;
@@ -4820,6 +4907,32 @@ export declare interface RadiusExtent {
     outerRadius: NumericDataValue;
 }
 
+/**
+ * Reads an aesthetic value by an open channel name — built-in (`x`, `color`, …) or custom. A custom
+ * geom maps extra channels (a box plot's `q1`/`median`/`q3`, an error bar's bounds) under names outside
+ * the closed {@link AestheticKey} set; those keys ride in the mapping at runtime and are read here
+ * through the one sanctioned widening, so a channel's value is sourced from `aes` rather than `params`.
+ */
+export declare function readAesthetic(aesMapping: AesMapping, name: string): AestheticValue | undefined;
+
+/**
+ * Reads an author-named numeric column from an observation with the same null-discipline as the
+ * built-in position/visual readers (`getX`, `getColor`, …): a missing or wrong-typed value is
+ * `null`, never silently coerced to `0`. A custom geom writes its own columns and has no typed
+ * accessor for them; these readers fill that gap without re-deriving the coercion per geom.
+ *
+ * Pass `fallback` to opt into a default for genuinely-missing values; the overload then narrows the
+ * return to `number`, so a geom that wants `0`-on-missing says so explicitly.
+ */
+export declare function readNumber(observation: Observation, key: string): number | null;
+
+export declare function readNumber(observation: Observation, key: string, fallback: number): number;
+
+/** Reads an author-named string column from an observation; missing or wrong-typed is `null` unless a `fallback` is given. */
+export declare function readString(observation: Observation, key: string): string | null;
+
+export declare function readString(observation: Observation, key: string, fallback: string): string;
+
 /** A rectangle in pixel coordinates, origin at top-left. */
 export declare interface Rect {
     x: number;
@@ -5181,7 +5294,7 @@ export declare type ScaledAestheticKey = ScaledPositionAestheticKey | ScaledVisu
 
 declare type ScaledPositionAestheticKey = 'x' | 'y' | 'ySecondary';
 
-declare type ScaledVisualAestheticKey = 'color' | 'size' | 'alpha' | 'strokeWidth' | 'lineType';
+export declare type ScaledVisualAestheticKey = 'color' | 'size' | 'alpha' | 'strokeWidth' | 'lineType';
 
 /**
  * Union type for all possible scale specifications (including inferred, pre-resolution).
@@ -5491,6 +5604,11 @@ declare interface SmoothStatSpec {
 
 declare function sort(options: SortOptions): SortTransformInput;
 
+/**
+ * Sorts the data by the x variable if it is numeric or temporal.
+ */
+export declare const sortByXIfContinuous: (data: Dataset, mapping: AesMapping) => Dataset;
+
 /***************************************************************
  * Sort Transform
  ***************************************************************/
@@ -5518,7 +5636,7 @@ export declare interface SourceContent {
  * runtime's index builders, so the descriptor lets the engine dispatch on declared data instead
  * of branching on the geom name.
  *
- * `render-hit-test` is the Tier-C escape hatch: the geom's geometry comes from a layout algorithm,
+ * `render-hit-test` is the geom-layout escape hatch: the geom's geometry comes from a layout algorithm,
  * not from scales, so the compiler cannot build a spatial index from position columns. The geom
  * instead provides a render-side hit-test function (injected per-instance through the renderer),
  * and the engine resolves the observation it returns against the declared identity key. Only the
@@ -5530,7 +5648,7 @@ export declare interface SourceContent {
  * time (no stored cartesian, no Delaunay), staying correct across resizes. Geoms never declare it; a
  * polar coord refines a `points`-natural mark to it during the coord transform.
  */
-declare type SpatialIndexKind = 'buckets' | 'rects' | 'points' | 'arcs' | 'noop' | 'render-hit-test' | 'polar-points';
+export declare type SpatialIndexKind = 'buckets' | 'rects' | 'points' | 'arcs' | 'noop' | 'render-hit-test' | 'polar-points';
 
 /**
  * A layer's geometry-agnostic hit-test declaration. Pure serialisable data riding in the compiled
@@ -5820,6 +5938,11 @@ export declare interface TextMeasurer {
     measureText: (text: string, font: FontSpec) => MeasuredText;
 }
 
+declare interface ToDatasetOptions {
+    /** Name of the categorical column that discriminates each row's kind. Must not collide with a declared column. */
+    kindColumn: string;
+}
+
 /** A chart's semantic content for the hovered observations, in reading order. */
 export declare interface TooltipContent {
     /** Localized main-axis value of the primary's observation. `null` for polar. */
@@ -5957,6 +6080,14 @@ declare type Variable = {
     valueFormat?: ValueFormat;
 };
 
+/**
+ * The internal dataset variable a channel reads and writes, derived from its axis and open name. The
+ * built-in names (`point`/`lower`/`upper`) resolve to the canonical position columns (`x`, `xMin`, …),
+ * so value readers and renderer recipes stay untouched; any other name resolves to a namespaced column,
+ * so a custom scaled channel never collides with a built-in or another geom's channel.
+ */
+export declare function variableFor(axis: ChannelAxis, name: string): string;
+
 /** A map of variable names to their type and values. */
 declare type VariableMap = Record<VariableName, Variable>;