@graphysdk/viz-engine 0.0.1-plugins.2 → 0.0.1-plugins.4

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 Tier-C 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;
 
 /***************************************************************
@@ -2792,7 +2819,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
@@ -2952,7 +2979,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 +3047,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 +3271,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;
@@ -3792,6 +3819,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 Tier-B 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.
  *
@@ -4010,14 +4048,16 @@ export declare const LAYOUT_PADDING = 24;
  * settled after the first resolve.
  *
  * Here's the pipeline:
- *   1. **Seed**: stamp each axis with a placeholder label so the grid has something to measure.
- *   2. **Resolve v1**: first grid pass; `panel.height` is now final.
- *   3. **Finalize vertical**: pick the densest candidate that fits `panel.height` for left/right
+ *   1. **Polar prep**: split cartesian from polar axes, format the polar axes whole, and derive the
+ *      symmetric `polarMargin` their rim labels reserve (both empty/zero for a cartesian chart).
+ *   2. **Seed**: stamp each cartesian axis with a placeholder label so the grid has something to measure.
+ *   3. **Resolve v1**: first grid pass; `panel.height` is now final.
+ *   4. **Finalize vertical**: pick the densest candidate that fits `panel.height` for left/right
  *      axes; horizontal axes keep their seed.
- *   4. **Resolve v2**: vertical edge widths now reflect final labels, so `panel.width` is final.
- *   5. **Finalize horizontal**: pick the densest candidate that fits `panel.width` for top/bottom
- *      axes. Vertical axes carry over from step 3.
- *   6. **Resolve v3**: final grid pass with all axes finalized.
+ *   5. **Resolve v2**: vertical edge widths now reflect final labels, so `panel.width` is final.
+ *   6. **Finalize horizontal**: pick the densest candidate that fits `panel.width` for top/bottom
+ *      axes. Vertical axes carry over from step 4.
+ *   7. **Resolve v3**: final grid pass with all axes finalized.
  */
 export declare class LayoutCompiler {
     private readonly measurer;
@@ -4281,6 +4321,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*
+ * Tier-C 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;
 
 /**
@@ -4743,7 +4807,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;
@@ -4818,6 +4882,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;
@@ -5179,7 +5269,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).
@@ -5489,6 +5579,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
  ***************************************************************/
@@ -5528,7 +5623,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
@@ -5818,6 +5913,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. */
@@ -5955,6 +6055,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>;