@opendata-ai/openchart-core 6.5.1 → 6.6.0

package/dist/index.d.ts

@@ -895,6 +895,51 @@ interface LayerSpec {
     /** Animation configuration. */
     animation?: AnimationSpec;
 }
+/** Node alignment strategy for sankey layout. */
+type SankeyNodeAlign = 'left' | 'right' | 'center' | 'justify';
+/** Link coloring strategy for sankey diagrams. */
+type SankeyLinkColor = 'gradient' | 'source' | 'target' | 'neutral';
+/** Encoding channels specific to sankey diagrams. */
+interface SankeyEncoding {
+    /** Source node field (required, nominal). */
+    source: EncodingChannel;
+    /** Target node field (required, nominal). */
+    target: EncodingChannel;
+    /** Flow value field (required, quantitative). */
+    value: EncodingChannel;
+    /** Color encoding for nodes/links (optional, nominal). */
+    color?: EncodingChannel;
+    /** Tooltip encoding (optional). */
+    tooltip?: EncodingChannel | EncodingChannel[];
+}
+interface SankeySpec {
+    /** Discriminant: always "sankey". */
+    type: 'sankey';
+    /** Tabular flow data. Each row is a source-target-value link. */
+    data: DataRow[];
+    /** Encoding channels mapping data fields to visual properties. */
+    encoding: SankeyEncoding;
+    /** Width of node rectangles in pixels. Defaults to 12. */
+    nodeWidth?: number;
+    /** Vertical padding between nodes in pixels. Defaults to 16. */
+    nodePadding?: number;
+    /** Node alignment algorithm. Defaults to 'justify'. */
+    nodeAlign?: SankeyNodeAlign;
+    /** Number of layout relaxation iterations. Defaults to 6. */
+    iterations?: number;
+    /** Link coloring strategy. Defaults to 'gradient'. */
+    linkStyle?: SankeyLinkColor;
+    /** Editorial chrome (title, subtitle, source, byline, footer). */
+    chrome?: Chrome;
+    /** Legend display configuration. */
+    legend?: LegendConfig;
+    /** Theme configuration overrides. */
+    theme?: ThemeConfig;
+    /** Dark mode behavior. Defaults to "off". */
+    darkMode?: DarkMode;
+    /** Animation configuration for entrance animations. */
+    animation?: AnimationSpec;
+}
 /**
  * Top-level visualization spec: union discriminated by structural shape.
  *
@@ -902,16 +947,19 @@ interface LayerSpec {
  * - LayerSpec: has `layer` field
  * - TableSpec: has `type: 'table'`
  * - GraphSpec: has `type: 'graph'`
+ * - SankeySpec: has `type: 'sankey'`
  */
-type VizSpec = ChartSpec | LayerSpec | TableSpec | GraphSpec;
+type VizSpec = ChartSpec | LayerSpec | TableSpec | GraphSpec | SankeySpec;
 /** Chart spec without runtime data, for persistence/storage. */
 type ChartSpecWithoutData = Omit<ChartSpec, 'data'>;
 /** Table spec without runtime data and columns, for persistence/storage. Columns can be auto-generated via dataTable(). */
 type TableSpecWithoutData = Omit<TableSpec, 'data' | 'columns'>;
 /** Graph spec without runtime data, for persistence/storage. */
 type GraphSpecWithoutData = Omit<GraphSpec, 'nodes' | 'edges'>;
+/** Sankey spec without runtime data, for persistence/storage. */
+type SankeySpecWithoutData = Omit<SankeySpec, 'data'>;
 /** Union of data-stripped spec types for persistence/storage. */
-type StoredVizSpec = ChartSpecWithoutData | TableSpecWithoutData | GraphSpecWithoutData;
+type StoredVizSpec = ChartSpecWithoutData | TableSpecWithoutData | GraphSpecWithoutData | SankeySpecWithoutData;
 /** Logical AND combinator for filter predicates. */
 interface LogicalAnd<T> {
     and: T[];
@@ -1053,6 +1101,8 @@ declare function isLayerSpec(spec: VizSpec | Record<string, unknown>): spec is L
 declare function isTableSpec(spec: VizSpec | Record<string, unknown>): spec is TableSpec;
 /** Check if a spec is a GraphSpec. */
 declare function isGraphSpec(spec: VizSpec | Record<string, unknown>): spec is GraphSpec;
+/** Check if a spec is a SankeySpec. */
+declare function isSankeySpec(spec: VizSpec | Record<string, unknown>): spec is SankeySpec;
 /** Check if an annotation is a TextAnnotation. */
 declare function isTextAnnotation(annotation: Annotation): annotation is TextAnnotation;
 /** Check if an annotation is a RangeAnnotation. */
@@ -1837,8 +1887,8 @@ interface ResolvedLabel {
         to: Point;
         /** Connector line color. */
         stroke: string;
-        /** Connector style: straight line, curved arrow, or directional caret. */
-        style: 'straight' | 'curve' | 'caret';
+        /** Connector style: straight line or curved arrow. */
+        style: 'straight' | 'curve';
     };
     /** Background color behind the label text. */
     background?: string;
@@ -2218,6 +2268,98 @@ interface GraphLayout {
         height: number;
     };
 }
+/** A resolved sankey node with computed position and visual properties. */
+interface SankeyNodeMark {
+    type: 'sankeyNode';
+    /** Left edge x position. */
+    x: number;
+    /** Top edge y position. */
+    y: number;
+    /** Node rectangle width. */
+    width: number;
+    /** Node rectangle height (proportional to throughput). */
+    height: number;
+    /** Fill color. */
+    fill: string;
+    /** Stroke color. */
+    stroke?: string;
+    /** Stroke width. */
+    strokeWidth?: number;
+    /** Corner radius for subtle rounding. */
+    cornerRadius: number;
+    /** Node label positioned outside the node. */
+    label: ResolvedLabel;
+    /** Node identifier (unique across the diagram). */
+    nodeId: string;
+    /** Total value flowing through this node. */
+    value: number;
+    /** Depth column (0 = leftmost). */
+    depth: number;
+    /** Original data associated with this node. */
+    data: Record<string, unknown>;
+    /** Accessibility attributes. */
+    aria: MarkAria;
+    /** Index for stagger animation ordering. */
+    animationIndex?: number;
+}
+/** A resolved sankey link with computed path and visual properties. */
+interface SankeyLinkMark {
+    type: 'sankeyLink';
+    /** SVG path string for the curved ribbon. */
+    path: string;
+    /** Source node color (for gradient start). */
+    sourceColor: string;
+    /** Target node color (for gradient end). */
+    targetColor: string;
+    /** Fill opacity (0.35 default, increases on hover). */
+    fillOpacity: number;
+    /** Source node identifier. */
+    sourceId: string;
+    /** Target node identifier. */
+    targetId: string;
+    /** Link ribbon width at its thinnest point. */
+    width: number;
+    /** Flow value this link represents. */
+    value: number;
+    /** Original data row for this link. */
+    data: Record<string, unknown>;
+    /** Accessibility attributes. */
+    aria: MarkAria;
+    /** Index for stagger animation ordering. */
+    animationIndex?: number;
+}
+/**
+ * SankeyLayout: the complete engine output for sankey diagram visualizations.
+ *
+ * Contains everything an adapter needs to render the sankey: dimensions,
+ * chrome, nodes, links, legend, tooltip descriptors, and accessibility metadata.
+ * No axes (sankey has no traditional axis system).
+ */
+interface SankeyLayout {
+    /** The sankey drawing area (after chrome and legend are subtracted). */
+    area: Rect;
+    /** Resolved chrome text elements with positions and styles. */
+    chrome: ResolvedChrome;
+    /** Resolved sankey node marks with positions and colors. */
+    nodes: SankeyNodeMark[];
+    /** Resolved sankey link marks with paths and gradient colors. */
+    links: SankeyLinkMark[];
+    /** Legend layout (position, entries, bounds). */
+    legend: LegendLayout;
+    /** Tooltip descriptors keyed by node/link identifier. */
+    tooltipDescriptors: Map<string, TooltipContent>;
+    /** Accessibility metadata. */
+    a11y: A11yMetadata;
+    /** The resolved theme used for rendering. */
+    theme: ResolvedTheme;
+    /** Total SVG dimensions. */
+    dimensions: {
+        width: number;
+        height: number;
+    };
+    /** Resolved animation config. Present only when animation is enabled. */
+    animation?: ResolvedAnimation;
+}
 /** Function signature for text measurement provided by adapters. */
 type MeasureTextFn = (text: string, fontSize: number, fontWeight?: number) => {
     width: number;
@@ -2786,4 +2928,4 @@ declare function scatterChart(data: DataRow[], x: FieldRef, y: FieldRef, options
  */
 declare function dataTable(data: DataRow[], options?: TableBuilderOptions): TableSpec;
 
-export { type A11yMetadata, type AggregateOp, type AnimationConfig, type AnimationEase, type AnimationPhaseConfig, type AnimationSpec, type AnimationStagger, type Annotation, type AnnotationAnchor, type AnnotationOffset, type AnnotationPosition, type ArcMark, type AreaMark, type AxisConfig, type AxisLabelDensity, type AxisLayout, type AxisTick, BRAND_FONT_SIZE, BRAND_MIN_WIDTH, BRAND_RESERVE_WIDTH, type BarColumnConfig, type BarTableCell, type BinParams, type BinTransform, type Breakpoint, CATEGORICAL_PALETTE, CHART_ENCODING_RULES, CHART_TYPES, type CalculateExpression, type CalculateTransform, type CategoricalPalette, type CategoryColorsConfig, type CategoryTableCell, type CellStyle, type ChannelRule, type ChartBuilderOptions, type ChartEventHandlers, type ChartLayout, type ChartSpec, type ChartSpecOverride, type ChartSpecWithoutData, type ChartType, type Chrome, type ChromeDefaults, type ChromeKey, type ChromeMode, type ChromeText, type ChromeTextStyle, type ColorBlindnessType, type ColumnConfig, type CompileOptions, type CompileTableOptions, type Condition, type ConditionalValueDef, DEFAULT_THEME, DIVERGING_PALETTES, type DarkMode, type DataRow, type DateGranularity, type DivergingPalette, EXTENDED_OFFSET_STRATEGIES, type ElementEdit, type ElementRef, type Encoding, type EncodingChannel, type EncodingRule, type FieldPredicate, type FieldRef, type FieldType, type FilterPredicate, type FilterTransform, type FlagTableCell, GRAPH_ENCODING_RULES, type GraphChannelRule, type GraphEdge, type GraphEdgeLayout, type GraphEncoding, type GraphEncodingChannel, type GraphLayout, type GraphLayoutConfig, type GraphNode, type GraphNodeLayout, type GraphSpec, type GraphSpecWithoutData, type Gridline, type HeatmapColumnConfig, type HeatmapTableCell, type HeightClass, type ImageColumnConfig, type ImageTableCell, type LabelCandidate, type LabelConfig, type LabelDensity, type LabelMode, type LabelPriority, type LayerSpec, type LayoutStrategy, type LegendConfig, type LegendEntry, type LegendLayout, type LegendPosition, type LineMark, type LogicalAnd, type LogicalNot, type LogicalOr, MARK_DISPLAY_NAMES, MARK_ENCODING_RULES, MARK_TYPES, type Margins, type Mark, type MarkAria, type MarkDef, type MarkEvent, type MarkType, type MeasureTextFn, type NodeOverride, OFFSET_STRATEGIES, type OffsetStrategy, type PaginationState, type Point, type PointMark, type RangeAnnotation, type Rect, type RectMark, type RefLineAnnotation, type ResolveConfig, type ResolveMode, type ResolvedAnimation, type ResolvedAnnotation, type ResolvedChrome, type ResolvedChromeElement, type ResolvedColumn, type ResolvedLabel, type ResolvedTheme, type RuleMarkLayout, SEQUENTIAL_PALETTES, type ScaleConfig, type ScaleType, type SequentialPalette, type SeriesStyle, type SortState, type SparklineColumnConfig, type SparklineData, type SparklineTableCell, type StoredVizSpec, type TableBuilderOptions, type TableCell, type TableCellBase, type TableLayout, type TableRow, type TableSpec, type TableSpecWithoutData, type TextAnnotation, type TextMarkLayout, type TextStyle, type TextTableCell, type Theme, type ThemeChromeDefaults, type ThemeColors, type ThemeConfig, type ThemeFontSizes, type ThemeFontWeights, type ThemeFonts, type ThemeSpacing, type TickMarkLayout, type TimeUnit, type TimeUnitTransform, type TooltipContent, type TooltipField, type Transform, type VizSpec, abbreviateNumber, adaptColorForDarkMode, adaptTheme, areaChart, barChart, buildD3Formatter, buildTemporalFormatter, checkPaletteDistinguishability, columnChart, computeChrome, computeLabelBounds, contrastRatio, dataTable, detectCollision, donutChart, dotChart, elementRef, estimateTextWidth, findAccessibleColor, formatDate, formatNumber, generateAltText, generateAriaLabels, generateDataTable, getBreakpoint, getHeightClass, getLayoutStrategy, inferFieldType, isChartSpec, isConditionalDef, isEncodingChannel, isGraphSpec, isLayerSpec, isRangeAnnotation, isRefLineAnnotation, isTableSpec, isTextAnnotation, lineChart, meetsAA, pieChart, resolveCollisions, resolveMarkDef, resolveMarkType, resolveTheme, scatterChart, simulateColorBlindness };
+export { type A11yMetadata, type AggregateOp, type AnimationConfig, type AnimationEase, type AnimationPhaseConfig, type AnimationSpec, type AnimationStagger, type Annotation, type AnnotationAnchor, type AnnotationOffset, type AnnotationPosition, type ArcMark, type AreaMark, type AxisConfig, type AxisLabelDensity, type AxisLayout, type AxisTick, BRAND_FONT_SIZE, BRAND_MIN_WIDTH, BRAND_RESERVE_WIDTH, type BarColumnConfig, type BarTableCell, type BinParams, type BinTransform, type Breakpoint, CATEGORICAL_PALETTE, CHART_ENCODING_RULES, CHART_TYPES, type CalculateExpression, type CalculateTransform, type CategoricalPalette, type CategoryColorsConfig, type CategoryTableCell, type CellStyle, type ChannelRule, type ChartBuilderOptions, type ChartEventHandlers, type ChartLayout, type ChartSpec, type ChartSpecOverride, type ChartSpecWithoutData, type ChartType, type Chrome, type ChromeDefaults, type ChromeKey, type ChromeMode, type ChromeText, type ChromeTextStyle, type ColorBlindnessType, type ColumnConfig, type CompileOptions, type CompileTableOptions, type Condition, type ConditionalValueDef, DEFAULT_THEME, DIVERGING_PALETTES, type DarkMode, type DataRow, type DateGranularity, type DivergingPalette, EXTENDED_OFFSET_STRATEGIES, type ElementEdit, type ElementRef, type Encoding, type EncodingChannel, type EncodingRule, type FieldPredicate, type FieldRef, type FieldType, type FilterPredicate, type FilterTransform, type FlagTableCell, GRAPH_ENCODING_RULES, type GraphChannelRule, type GraphEdge, type GraphEdgeLayout, type GraphEncoding, type GraphEncodingChannel, type GraphLayout, type GraphLayoutConfig, type GraphNode, type GraphNodeLayout, type GraphSpec, type GraphSpecWithoutData, type Gridline, type HeatmapColumnConfig, type HeatmapTableCell, type HeightClass, type ImageColumnConfig, type ImageTableCell, type LabelCandidate, type LabelConfig, type LabelDensity, type LabelMode, type LabelPriority, type LayerSpec, type LayoutStrategy, type LegendConfig, type LegendEntry, type LegendLayout, type LegendPosition, type LineMark, type LogicalAnd, type LogicalNot, type LogicalOr, MARK_DISPLAY_NAMES, MARK_ENCODING_RULES, MARK_TYPES, type Margins, type Mark, type MarkAria, type MarkDef, type MarkEvent, type MarkType, type MeasureTextFn, type NodeOverride, OFFSET_STRATEGIES, type OffsetStrategy, type PaginationState, type Point, type PointMark, type RangeAnnotation, type Rect, type RectMark, type RefLineAnnotation, type ResolveConfig, type ResolveMode, type ResolvedAnimation, type ResolvedAnnotation, type ResolvedChrome, type ResolvedChromeElement, type ResolvedColumn, type ResolvedLabel, type ResolvedTheme, type RuleMarkLayout, SEQUENTIAL_PALETTES, type SankeyEncoding, type SankeyLayout, type SankeyLinkColor, type SankeyLinkMark, type SankeyNodeAlign, type SankeyNodeMark, type SankeySpec, type SankeySpecWithoutData, type ScaleConfig, type ScaleType, type SequentialPalette, type SeriesStyle, type SortState, type SparklineColumnConfig, type SparklineData, type SparklineTableCell, type StoredVizSpec, type TableBuilderOptions, type TableCell, type TableCellBase, type TableLayout, type TableRow, type TableSpec, type TableSpecWithoutData, type TextAnnotation, type TextMarkLayout, type TextStyle, type TextTableCell, type Theme, type ThemeChromeDefaults, type ThemeColors, type ThemeConfig, type ThemeFontSizes, type ThemeFontWeights, type ThemeFonts, type ThemeSpacing, type TickMarkLayout, type TimeUnit, type TimeUnitTransform, type TooltipContent, type TooltipField, type Transform, type VizSpec, abbreviateNumber, adaptColorForDarkMode, adaptTheme, areaChart, barChart, buildD3Formatter, buildTemporalFormatter, checkPaletteDistinguishability, columnChart, computeChrome, computeLabelBounds, contrastRatio, dataTable, detectCollision, donutChart, dotChart, elementRef, estimateTextWidth, findAccessibleColor, formatDate, formatNumber, generateAltText, generateAriaLabels, generateDataTable, getBreakpoint, getHeightClass, getLayoutStrategy, inferFieldType, isChartSpec, isConditionalDef, isEncodingChannel, isGraphSpec, isLayerSpec, isRangeAnnotation, isRefLineAnnotation, isSankeySpec, isTableSpec, isTextAnnotation, lineChart, meetsAA, pieChart, resolveCollisions, resolveMarkDef, resolveMarkType, resolveTheme, scatterChart, simulateColorBlindness };

package/dist/index.js

@@ -201,6 +201,9 @@ function isTableSpec(spec) {
 function isGraphSpec(spec) {
   return "type" in spec && spec.type === "graph";
 }
+function isSankeySpec(spec) {
+  return "type" in spec && spec.type === "sankey";
+}
 function isTextAnnotation(annotation) {
   return annotation.type === "text";
 }
@@ -2781,6 +2784,7 @@ export {
   isLayerSpec,
   isRangeAnnotation,
   isRefLineAnnotation,
+  isSankeySpec,
   isTableSpec,
   isTextAnnotation,
   lineChart,