@graphysdk/viz-engine 0.0.1-experimental.0 → 0.0.1-experimental.1

package/dist/index.d.ts

@@ -16,7 +16,11 @@
  * @packageDocumentation
  */
 
+import { Area } from 'd3-shape';
+import { CurveFactory } from 'd3-shape';
 import { internal } from 'arquero';
+import { Line } from 'd3-shape';
+import { Translator } from '@graphysdk/i18n';
 
 /** Maps each visual channel (x, y, color, size, ...) to a data column or constant value. */
 export declare interface AesMapping {
@@ -259,6 +263,11 @@ export declare interface AreaGeomParams {
     missingValues: MissingValuesType;
 }
 
+export declare interface AreaPathGenerators {
+    lineGenerator: Line<Observation>;
+    areaGenerator: Area<Observation>;
+}
+
 /** One end of a freeform arrow, positioned as a fraction of the plot rect (0..1) so it re-flows on resize. */
 export declare interface ArrowEndpoint {
     /** 0..1 of plot width. */
@@ -627,6 +636,13 @@ declare interface BuildLayerYValueFormatterInput {
     locale: Locale;
 }
 
+/**
+ * Builds the SVG arc path for a polar bar (pie / donut slice).
+ *
+ * Returns `null` for an empty slice (no angular span or no radius) that d3 cannot render.
+ */
+export declare const buildPolarBarArcPath: (input: PolarBarArcInput) => string | null;
+
 /**
  * Pure projection of `(compiled, hover)` into the tooltip's `{ header, rows }`. Pure (no I/O, no
  * mutation) — safe to memoize on its input.
@@ -2014,6 +2030,18 @@ declare interface CountStatSpec {
 /** Reader for the raw value behind a layer's `alpha` mapping. */
 export declare const createAlphaValueReader: (data: Dataset, mapping: AesMapping) => RawValueReader;
 
+/**
+ * Builds the d3 area + top-line generators for an area layer.
+ *
+ * The `mainAxis === 'y'` branch is structural: d3-area exposes two separate APIs —
+ * `.x(main).y0(crossMin).y1(crossMax)` for vertical fills and `.y(main).x0(crossMin).x1(crossMax)`
+ * for horizontal fills — there is no orientation-agnostic setter. After `coord.flip()` has run,
+ * `POSITION_VARIABLES.x` holds the measure (fill bound) and `POSITION_VARIABLES.y` the band
+ * center, so the flipped branch reads `xMin`/`xMax` as the fill bounds and `y` as the main-axis
+ * position.
+ */
+export declare const createAreaPathGenerators: (coordSystem: CartesianCoordSystem, params: AreaGeomParams) => AreaPathGenerators;
+
 /** Reader for the raw value behind a layer's `color` mapping. */
 export declare const createColorValueReader: (data: Dataset, mapping: AesMapping) => RawValueReader;
 
@@ -2038,9 +2066,19 @@ export declare function createEmptyHighlight(geom: GeomName): CompiledLayerHighl
 /** Reader for the raw value behind a layer's `group` mapping. */
 export declare const createGroupValueReader: (data: Dataset, mapping: AesMapping) => RawValueReader;
 
+/**
+ * The single structural model of a headline item's rows and segments. Both the measurer (which sizes
+ * each segment without a DOM) and the JSX (which paints them) read this, so a layout change — a new
+ * row, a reordered segment — lands in one place and the two can't drift. Styling and font pixels are
+ * resolved by each consumer from the roles; this model carries only structure, text, and gaps.
+ */
+export declare const createHeadlineItemRows: (item: FormattedHeadlineItem) => HeadlineRow[];
+
 /** Reader for the raw value behind a layer's `label` mapping. */
 export declare const createLabelValueReader: (data: Dataset, mapping: AesMapping) => RawValueReader;
 
+export declare const createLinePathGenerator: (params: LineGeomParams) => Line<Observation>;
+
 /**
  * Builds a per-observation reader for an `AestheticValue`:
  * - `{ value: X }` → returns `X` for every observation.
@@ -2082,6 +2120,8 @@ export declare const createSizeValueReader: (data: Dataset, mapping: AesMapping)
  */
 export declare function createSpec(...items: Array<AesMapping | SpecItem>): SpecInput;
 
+export declare const createStableKeyGenerator: (data: Dataset, mapping: AesMapping, layerId: string) => ((observation: Observation) => string);
+
 /** Reader for the raw value behind a layer's `strokeWidth` mapping. */
 export declare const createStrokeWidthValueReader: (data: Dataset, mapping: AesMapping) => RawValueReader;
 
@@ -2543,6 +2583,9 @@ export declare const DEFAULT_FONT_STYLE = "normal";
  */
 export declare const DEFAULT_FONT_WEIGHT = 500;
 
+/** Stroke width used when a line/area layer leaves `lineWidth` on `'auto'` and the observation carries none. */
+export declare const DEFAULT_LINE_WIDTH = 2;
+
 /** Locale used when a consumer does not specify one. */
 export declare const DEFAULT_LOCALE: Locale;
 
@@ -2771,7 +2814,7 @@ export declare interface FontSpec {
  * Every field on the result is render-verbatim (see {@link FormattedHeadlineItem}); the renderer adds
  * only the arrow/colour implied by the trend `direction`. Returns null when there is no headline.
  */
-export declare const formatHeadline: ({ headline, show, numberFormat, parsingLocale, formattingLocale, }: FormatHeadlineInput) => FormattedHeadline | null;
+export declare const formatHeadline: ({ headline, show, numberFormat, parsingLocale, formattingLocale, t, }: FormatHeadlineInput) => FormattedHeadline | null;
 
 /** Inputs to {@link formatHeadline}. `formattingLocale` overrides `parsingLocale` for display when the two differ. */
 export declare interface FormatHeadlineInput {
@@ -2785,6 +2828,7 @@ export declare interface FormatHeadlineInput {
      * ('en-GB', 'en-US', 'ar', 'pt-PT'); a `duration` figure always formats in English regardless.
      */
     formattingLocale?: Locale;
+    t: Translator;
 }
 
 /**
@@ -3035,6 +3079,17 @@ export declare function getAlpha(observation: Observation): NumericDataValue;
  */
 export declare function getAngleExtent(observation: Observation): AngleExtent;
 
+/**
+ * Normalized data-space bounds for a bar observation in [0, 1]² with origin at the top-left
+ * (matches SVG conventions used by overlay renderers). Negative values flip the rect upside-down
+ * so callers don't need to know whether the bar grows up or down from its baseline.
+ *
+ * `mainAxis` selects which data axis separates bars (bar length runs along the cross axis). For
+ * `'x'` bars grow vertically; for `'y'` (flipped) they grow horizontally and the cross-axis
+ * extent can be negative for negative values.
+ */
+export declare const getBarRectBounds: (mainAxis: MainAxis, observation: Observation) => Rect | null;
+
 /**
  * Reads the resolved color string from an observation.
  *
@@ -3046,6 +3101,10 @@ export declare function getColor(observation: Observation): string | undefined;
 /** Reads the coordinate lying on the cross axis of the coord system. */
 export declare function getCrossAxisCoordinate(mainAxis: MainAxis, point: XYPoint): number;
 
+export declare const getCurve: (interpolate: InterpolateType) => CurveFactory;
+
+export declare const getDashArray: (lineType: LineStyleType) => string | undefined;
+
 /**
  * Returns pixel dimensions for a difference arrow at the requested size.
  *
@@ -3064,6 +3123,10 @@ export declare const getDifferenceArrowDimensions: (size: DifferenceArrowSize, t
  */
 export declare const getGroup: (observation: Observation) => CategoricalDataValue;
 
+export declare function getHoverGuideLineProps(coordSystem: CartesianCoordSystem, primary: XYPoint): HoverGuideLineProps;
+
+export declare function getHoverGuideRectProps(coordSystem: CartesianCoordSystem, scales: CompiledSpec['scales'], primary: HoverHit): HoverGuideRectProps | null;
+
 /**
  * Reads the resolved line type (stroke style) from an observation.
  * Falls back to `'solid'` when no `lineType` variable was derived.
@@ -3101,6 +3164,8 @@ export declare function getRadiusExtent(observation: Observation): RadiusExtent;
  */
 export declare function getSize(observation: Observation): NumericDataValue;
 
+export declare const getStablePolarBarKeyGenerator: () => ((observation: Observation, index: number) => string);
+
 /**
  * Reads the resolved stroke width value from an observation, in pixels.
  *
@@ -3431,6 +3496,21 @@ declare type GuideConfig = Pick<ConfigSpec, 'axes' | 'legend' | 'headline' | 'pa
 /** Geometric shape an axis traces: a straight line, a full circle, or a spoke from the centre. */
 declare type GuideGeometry = 'linear' | 'circular' | 'radial';
 
+/** Gap between the swatch and its group label, in pixels. */
+export declare const HEADLINE_SWATCH_GAP = 4;
+
+/** Side length of the colour swatch in a headline group row, in pixels. */
+export declare const HEADLINE_SWATCH_SIZE = 12;
+
+/** Gap between trend segments (arrow, percentage, reference), in pixels. */
+export declare const HEADLINE_TREND_GAP = 4;
+
+/** Side length of the trend arrow icon, in pixels. */
+export declare const HEADLINE_TREND_ICON_SIZE = 12;
+
+/** Gap between the value figure and its observation label, in pixels. */
+export declare const HEADLINE_VALUE_LABEL_GAP = 4;
+
 /**
  * Comparison reference for trend indicator
  * - 'previous': Compare to preceding data point
@@ -3475,6 +3555,9 @@ declare interface HeadlineConfig {
     position: HeadlinePosition;
 }
 
+/** Which font token a text segment renders at: the large figure or the smaller chrome. */
+export declare type HeadlineFontRole = 'value' | 'label';
+
 declare interface HeadlineGroupSwatch {
     color: string;
     shape: SwatchShape;
@@ -3570,6 +3653,32 @@ export declare interface HeadlinePlacement {
  */
 export declare type HeadlinePosition = 'above' | 'center';
 
+export declare interface HeadlineRow {
+    role: HeadlineRowRole;
+    gap: number;
+    segments: HeadlineSegment[];
+    ariaLabel?: string;
+}
+
+/** Which row a segment stacks into, aligned with the renderer's CSS class names. */
+export declare type HeadlineRowRole = 'valueRow' | 'trendRow' | 'groupRow';
+
+export declare type HeadlineSegment = {
+    kind: 'text';
+    textRole: HeadlineTextRole;
+    fontRole: HeadlineFontRole;
+    text: string;
+    trendDirection?: HeadlineTrendDirection;
+} | {
+    kind: 'swatch';
+    swatch: HeadlineSwatch;
+    size: number;
+} | {
+    kind: 'trendArrow';
+    direction: HeadlineTrendDirection;
+    size: number;
+};
+
 /**
  * Display mode for headline numbers
  * - 'total': Sum of all values
@@ -3589,6 +3698,11 @@ export declare type HeadlineShow = 'total' | 'average' | 'current' | 'conversion
  */
 export declare type HeadlineSize = 'auto' | 'small' | 'medium' | 'large';
 
+declare type HeadlineSwatch = NonNullable<FormattedHeadlineItem['swatch']>;
+
+/** Which styled span a text segment maps to (drives its CSS class and colour). */
+export declare type HeadlineTextRole = 'value' | 'observation' | 'label' | 'trendPercentage' | 'trendReference';
+
 /**
  * Direction of a headline's trend, and the SOLE source of the comparison's sign — drive both the
  * arrow and the colour off it, since `percentage` is unsigned. `flat` is neutral, so render it
@@ -3827,6 +3941,22 @@ export declare interface HoverEngineInput {
     coordSystem: CoordSystem;
 }
 
+/** SVG `<line>` endpoints for the continuous-composition rule. */
+declare interface HoverGuideLineProps {
+    x1: string | number;
+    x2: string | number;
+    y1: string | number;
+    y2: string | number;
+}
+
+/** SVG `<rect>` attributes for the bar-composition band rect. */
+declare interface HoverGuideRectProps {
+    x: string | number;
+    y: string | number;
+    width: string | number;
+    height: string | number;
+}
+
 /**
  * A single hit returned by the hover engine.
  *
@@ -3979,6 +4109,17 @@ export declare const isLookupValueFormat: (valueFormat: ValueFormat) => valueFor
 
 export declare const isNumericValueFormat: (valueFormat: ValueFormat) => valueFormat is NumericValueFormat | CurrencyValueFormat;
 
+/**
+ * Whether a string is safe to assign to an `href`. Allows http, https, and
+ * mailto; rejects javascript:, data:, vbscript:, and any other scheme that
+ * could execute code or load arbitrary content.
+ *
+ * Leading control characters (NUL, tab, newline, etc.) are stripped before
+ * the scheme check because the browser ignores them when parsing href, so
+ * `\tjavascript:alert(1)` would otherwise sneak past a naive prefix test.
+ */
+export declare const isSafeUrl: (input: unknown) => input is string;
+
 /**
  * True for positions that accumulate values along an axis (`'stack'` and `'fill'`).
  *
@@ -4822,6 +4963,13 @@ declare interface PointPosition {
     y: number;
 }
 
+export declare interface PolarBarArcInput {
+    startAngle: number;
+    endAngle: number;
+    innerRadius: number;
+    outerRadius: number;
+}
+
 declare interface PolarCoordInput {
     type: 'coord';
     coordType: 'polar';
@@ -5006,6 +5154,10 @@ export declare type Predicate = VariablePredicate | LogicalPredicate;
  */
 export declare const prefixInternalVariable: (name: string) => string;
 
+export declare const prepareAreaObservations: (observations: Observation[], missingValues: AreaGeomParams["missingValues"]) => Observation[];
+
+export declare const prepareLineObservations: (observations: Observation[], missingValues: LineGeomParams["missingValues"]) => Observation[];
+
 declare interface QuantitativeScaleMethods {
     /**
      * Continuous (numeric) scale. Supports `transform`, `reverse`, `nice`, `zero`, `domainMin`, `domainMax`.
@@ -5033,6 +5185,10 @@ export declare interface RadiusExtent {
 /** Resolves one observation's raw, type-filtered value for an aesthetic. */
 declare type RawValueReader = (observation: Observation) => DataValue;
 
+export declare function readXExtent(primary: HoverHit): number | null;
+
+export declare function readYExtent(primary: HoverHit): number | null;
+
 /**
  * A rectangle in pixel coordinates, origin at top-left. Every rect on a {@link GraphLayout} is measured
  * from the chart CONTAINER top-left (with {@link LAYOUT_PADDING} already included), never panel- or
@@ -5195,6 +5351,8 @@ export declare interface ResolveHeadlinePlacementInput {
 /** Source of a layer's segment y value: `yRaw` when stacked, user's y mapping otherwise. */
 export declare function resolveSegmentYSource(position: PositionType, mapping: AesMapping): AestheticValue;
 
+export declare const resolveStrokeWidth: (observation: Observation, params: AreaGeomParams | LineGeomParams) => number;
+
 /**
  * Resolves the Y scale aesthetic based on the layer's `yScaleType` axis assignment.
  *
@@ -6034,6 +6192,22 @@ export declare interface TooltipRow {
     key: string;
 }
 
+/** Formats a normalized [0,1] value as a CSS percentage string for SVG positioning. */
+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;
+
 /** Factories for data transforms applied before charting (reshape, filter, sort, aggregate, constant). */
 export declare const transform: {
     reshape: typeof reshape;