@graphysdk/viz-engine 0.0.1-alpha.4 → 0.0.1-alpha.5

package/dist/index.d.ts

@@ -9,6 +9,7 @@ export declare interface AesMapping {
     alpha?: AestheticValue;
     group?: AestheticValue;
     strokeWidth?: AestheticValue;
+    lineType?: AestheticValue;
 }
 
 export declare type AestheticKey = keyof AesMapping;
@@ -114,7 +115,6 @@ declare function area(options?: GeomOptions<'area'>): LayerInputOf<'area'>;
  */
 export declare interface AreaGeomParams {
     lineWidth: number | 'auto';
-    lineType: LineStyleType;
     interpolate: InterpolateType;
     missingValues: MissingValuesType;
 }
@@ -323,6 +323,19 @@ export declare interface CartesianCoordSystem {
 
 declare type CategoricalDataValue = string | null;
 
+declare interface CategoricalScaleMethods<RangeValue extends number | string> {
+    /**
+     * Discrete (categorical) scale. Supports explicit `range` values.
+     * @example scale.lineType.discrete({ range: ['solid', 'dashed', 'dotted'] })
+     */
+    discrete: (options?: DiscreteScaleOptions<RangeValue>) => DiscreteScaleInput;
+    /**
+     * Identity scale — data values used directly as visual values without transformation.
+     * @example scale.lineType.identity() // observation['lineType'] passed through
+     */
+    identity: (options?: IdentityScaleOptions) => IdentityScaleInput;
+}
+
 declare interface CategoricalValueFormat {
     type: 'text';
 }
@@ -646,6 +659,8 @@ export declare interface CompiledLegendGuide {
     items: LegendItem[];
     /** Resolved format descriptor shared by all items in this legend */
     valueFormat: ValueFormat;
+    /** Visual signature of the geom this legend describes */
+    swatchShape: SwatchShape;
 }
 
 export declare interface CompiledPanel {
@@ -1376,11 +1391,11 @@ declare interface DiscreteScaleInput {
     padding?: number | null;
 }
 
-declare type DiscreteScaleOptions = {
+declare type DiscreteScaleOptions<RangeValue extends number | string = number | string> = {
     /**
      * Explicit output values mapped to domain categories in order.
      */
-    range?: Array<number | string>;
+    range?: RangeValue[];
     /**
      * Sort order for discrete domain values.
      * @default 'none'
@@ -1567,6 +1582,12 @@ export declare function getCrossAxisCoordinate(mainAxis: MainAxis, point: XYPoin
 
 export declare const getGroup: (observation: Observation) => CategoricalDataValue;
 
+/**
+ * Reads the resolved line type (stroke style) from an observation.
+ * Falls back to `'solid'` when no `lineType` variable was derived.
+ */
+export declare function getLineType(observation: Observation): LineStyleType;
+
 /** Reads the coordinate lying on the main (independent) axis of the coord system. */
 export declare function getMainAxisCoordinate(mainAxis: MainAxis, point: XYPoint): number;
 
@@ -2267,16 +2288,23 @@ declare type LegendDisplay = 'pill' | 'direct' | 'auto';
 export declare interface LegendItem {
     /** Raw data value (e.g., "Apples") */
     value: DataValue;
-    /**
-     * Mapped visual values per aesthetic (e.g., { color: '#ff0000' }).
-     * An array signals multi-swatch rendering — used when a color scale is
-     * collapsed into a single legend item.
-     */
-    visual: Partial<Record<ScaledVisualAestheticKey, string | string[]>>;
+    /** Mapped visual values per aesthetic (e.g., { color: '#ff0000' }). */
+    visual: LegendItemVisual;
     /** Normalized y position in [0,1]. Null when display is not 'direct' or no endpoint found. */
     normalizedY: number | null;
 }
 
+/**
+ * Visual values produced by a legend's scales, keyed by aesthetic.
+ */
+declare interface LegendItemVisual {
+    color?: string | string[];
+    size?: DataValue | DataValue[];
+    alpha?: DataValue | DataValue[];
+    strokeWidth?: DataValue | DataValue[];
+    lineType?: LineStyleType | LineStyleType[];
+}
+
 export declare type LegendPosition = 'auto' | 'right' | 'left' | 'top' | 'bottom' | 'none';
 
 declare function line(options?: GeomOptions<'line'>): LayerInputOf<'line'>;
@@ -2286,7 +2314,6 @@ declare function line(options?: GeomOptions<'line'>): LayerInputOf<'line'>;
  */
 export declare interface LineGeomParams {
     lineWidth: number | 'auto';
-    lineType: LineStyleType;
     /**
      * Interpolation method to use for the line.
      * @default 'linear'
@@ -2861,6 +2888,13 @@ declare interface ScaleAPI {
      * @example scale.strokeWidth.identity() // use data values directly as px
      */
     strokeWidth: QuantitativeScaleMethods;
+    /**
+     * Line type (stroke style) scale. Discrete-only — interpolation between dash
+     * patterns is not meaningful. Mapping `lineType` to a numeric variable errors
+     * at compile time.
+     * @example scale.lineType.discrete({ domain: ['actual', 'forecast'], range: ['solid', 'dashed'] })
+     */
+    lineType: CategoricalScaleMethods<LineStyleType>;
 }
 
 /**
@@ -2910,7 +2944,7 @@ export declare type ScaledAestheticKey = ScaledPositionAestheticKey | ScaledVisu
 
 declare type ScaledPositionAestheticKey = 'x' | 'y' | 'ySecondary';
 
-declare type ScaledVisualAestheticKey = 'color' | 'size' | 'alpha' | 'strokeWidth';
+declare type ScaledVisualAestheticKey = 'color' | 'size' | 'alpha' | 'strokeWidth' | 'lineType';
 
 /**
  * Union type for all possible scale specifications (including inferred, pre-resolution).
@@ -3179,7 +3213,14 @@ declare class StatRegistry extends Registry<StatName, Stat> {
 }
 
 /**
- * Visual signature of the source geom.
+ * Visual signature of a geom, decoupled from `GeomName` because legends and tooltips don't care
+ * about the geom's spec-level identity — only what shape best evokes its on-canvas mark.
+ *
+ * - `bar` + cartesian → `square`
+ * - `bar` + polar → `slice` (pie / donut wedge)
+ * - `line` → `line` (a horizontal stroke)
+ * - `area` → `area` (filled region with a stroke accent)
+ * - `point` → `circle`
  */
 export declare type SwatchShape = 'square' | 'line' | 'circle' | 'area' | 'slice';
 
@@ -3221,6 +3262,8 @@ export declare interface TooltipRow {
     swatchColor: string | null;
     /** Visual signature of the row's source geom. Drives the swatch shape. */
     swatchShape: SwatchShape;
+    /** Resolved stroke style for line/area swatches. Falls back to `'solid'` when not derived. */
+    swatchLineType: LineStyleType;
     /** Row label — color value (multi-series) or layer's Y-axis title (single-series). */
     label: string;
     /** Formatted Y reading for this hit. */
@@ -3335,6 +3378,7 @@ export declare const VISUAL_VARIABLES: {
     readonly size: string;
     readonly alpha: string;
     readonly strokeWidth: string;
+    readonly lineType: string;
 };
 
 /**