@opendata-ai/openchart-core 7.2.4 → 7.4.0

package/dist/index.d.ts

@@ -2411,6 +2411,8 @@ interface ResolvedChrome {
     byline?: ResolvedChromeElement;
     footer?: ResolvedChromeElement;
     brand?: ResolvedChromeElement;
+    /** Absolute y at which bottom-chrome relative offsets are anchored: area.y + area.height + x-axis extent. */
+    bottomAnchorY?: number;
 }
 /** A single axis tick with computed position and formatted label. */
 interface AxisTick {
@@ -2471,6 +2473,14 @@ interface AxisLayout {
      * classic outside-the-area placement.
      */
     tickPosition?: 'inline' | 'gutter';
+    /** Extent in px beyond the chart-area edge occupied by tick labels + title. Engine-resolved from the final (post-thinning) tick set. */
+    extent?: number;
+    /** Absolute anchor for the axis title. Replaces renderer-side offset math. */
+    titlePosition?: {
+        x: number;
+        y: number;
+        angle?: number;
+    };
 }
 /** Accessibility attributes for a mark. */
 interface MarkAria {
@@ -2819,6 +2829,10 @@ interface ResolvedLabel {
     background?: string;
     /** Whether to show the paint-order stroke halo. Default true. */
     halo?: boolean;
+    /** Engine-measured text-block bounds. Renderers should use this for background rects instead of re-estimating. */
+    bounds?: Rect;
+    /** Source index carried through from the LabelCandidate, if the caller set one. */
+    index?: number;
 }
 /** A resolved annotation with computed pixel positions. */
 interface ResolvedAnnotation {
@@ -2869,6 +2883,8 @@ interface ResolvedAnnotation {
         y: number;
         style: TextStyle;
     };
+    /** Full placed extent: label bounds unioned with subtitle bounds. Collision and placement source of truth. */
+    bounds?: Rect;
 }
 /** A single entry in a categorical legend. */
 interface LegendEntry {
@@ -2892,6 +2908,15 @@ interface BaseLegendLayout {
     /** Entry label style. */
     labelStyle: TextStyle;
 }
+/** Engine-resolved absolute position for a single legend entry. */
+interface LegendEntryPosition {
+    x: number;
+    y: number;
+    labelX: number;
+    labelY: number;
+    width: number;
+    row: number;
+}
 /** Categorical legend with discrete swatch entries. */
 interface CategoricalLegendLayout extends BaseLegendLayout {
     /** Discriminant for legend type. Omitted means categorical (backwards compat). */
@@ -2906,6 +2931,10 @@ interface CategoricalLegendLayout extends BaseLegendLayout {
     entryGap: number;
     /** Fill color for the rounded chip background behind the colored bar. */
     swatchChipFill: string;
+    /** Engine-resolved absolute positions, parallel to `entries`. */
+    entryPositions?: LegendEntryPosition[];
+    /** Row advance used to build entryPositions (single source of truth). */
+    rowHeight?: number;
 }
 /** A color stop in a gradient legend. */
 interface GradientColorStop {
@@ -3829,21 +3858,27 @@ declare function resolveTheme(userTheme?: ThemeConfig, base?: Theme): ResolvedTh
 declare function computeChrome(chrome: Chrome | undefined, theme: ResolvedTheme, width: number, measureText?: MeasureTextFn, chromeMode?: ChromeMode, padding?: number, watermark?: boolean, bottomLegendHeight?: number): ResolvedChrome;
 
 /**
- * Estimate the rendered width of a text string.
+ * Text measurement for environments without a DOM.
  *
- * Uses a per-character average width based on font size, adjusted
- * for font weight. Accurate to within ~20% for Latin text in Inter.
+ * Uses per-character advance-width tables measured from Inter (the default
+ * chart font) for ~2-3% accuracy on Latin text at weights 400/700.
+ * Other fonts set via theme.fonts.family still get a better-than-flat-ratio
+ * approximation but no accuracy guarantee.
  *
- * @param text - The text string to measure.
- * @param fontSize - Font size in pixels.
- * @param fontWeight - Font weight (100-900). Defaults to 400.
+ * Tables generated by scripts/generate-char-widths.mjs — regenerate, don't
+ * hand-edit.
+ */
+
+/**
+ * Estimate the rendered width of a text string.
+ *
+ * Uses per-character advance widths measured from Inter (the default chart
+ * font). Accurate to ~2-3% for Latin text at weights 400/700; other weights
+ * are interpolated from the nearest table.
  */
 declare function estimateTextWidth(text: string, fontSize: number, fontWeight?: number): number;
 /**
  * Width reserved for the "tryOpenData.ai" brand watermark in the bottom-right corner.
- * Accounts for ~14 chars at font size 12 with mixed weights, plus a gap
- * so adjacent text doesn't crowd it. Used by chrome and legend layout to avoid
- * overlapping the brand.
  */
 declare const BRAND_RESERVE_WIDTH = 130;
 /** Font size of the brand watermark (px). Shared between layout and renderer. */
@@ -3855,6 +3890,21 @@ declare const BRAND_MIN_WIDTH = 120;
  * padding, label gaps) to maximize data area on small screens.
  */
 declare const COMPACT_WIDTH = 420;
+/**
+ * Distance from the top of a text box to its alphabetic baseline.
+ *
+ * Layout stores text positions as top-edge coordinates; renderers convert to
+ * baseline coordinates with this ratio instead of `dominant-baseline: hanging`.
+ * WebKit computes the hanging baseline from different font metrics than Blink
+ * and never inherits dominant-baseline into tspans (WebKit bugs 139258 /
+ * 297455), which shifted whole titles above the container on iOS Safari.
+ * The 0.8 ratio matches Blink's rendered hanging position for typical UI
+ * fonts (hanging sits at ~0.8 x ascent, Inter ascent ~= 0.97em) and the
+ * Highcharts fontMetrics convention.
+ */
+declare function textAscent(fontSize: number): number;
+declare const heuristicMeasure: MeasureTextFn;
+declare function resolveMeasurer(measureText?: MeasureTextFn): MeasureTextFn;
 
 /**
  * Word-wrap a text string into lines that fit within a max width.
@@ -3971,13 +4021,25 @@ declare const MAX_LEFT_LABEL_FRACTION_COMPACT = 0.45;
 declare const MAX_LEFT_LABEL_FRACTION_MEDIUM = 0.55;
 /** Max fraction of container width reservable for left category labels (standard). */
 declare const MAX_LEFT_LABEL_FRACTION_DEFAULT = 1;
+declare const X_AXIS_BAND_HEIGHT = 26;
+declare const X_AXIS_TITLE_BAND = 22;
+declare const X_AXIS_TITLE_BAND_ROTATED = 20;
+interface XAxisExtentInput {
+    labels: string[];
+    tickAngle?: number;
+    hasTitle: boolean;
+    tickFontSize: number;
+    tickFontWeight: number;
+    xAxisHeight?: number;
+    measure?: (text: string, fontSize: number, fontWeight: number) => number;
+}
+declare function computeXAxisExtentFromLabels(input: XAxisExtentInput): number;
 
 /**
  * Label collision detection and resolution.
  *
  * Greedy algorithm: sort by priority, place in order, try offset
  * positions for conflicts, demote to tooltip-only if no position works.
- * Targeting ~60% of Infrographic quality for Phase 0.
  */
 
 /** Priority levels for label placement. Data labels win over annotations which win over axes. */
@@ -4001,11 +4063,20 @@ interface LabelCandidate {
     priority: LabelPriority;
     /** Text style to apply. */
     style: TextStyle;
+    /**
+     * Optional caller-assigned source index. resolveCollisions may reorder its
+     * output (it sorts by priority), so callers that zip the result back against
+     * a parallel array should carry an index here and read it off ResolvedLabel
+     * rather than relying on positional order.
+     */
+    index?: number;
 }
 /**
  * Detect AABB (axis-aligned bounding box) overlap between two rectangles.
  */
 declare function detectCollision(a: Rect, b: Rect): boolean;
+/** Compute the area of intersection between two axis-aligned rectangles. Returns 0 if disjoint. */
+declare function overlapArea(a: Rect, b: Rect): number;
 /** An offset position to try when resolving a label collision. */
 interface OffsetStrategy {
     dx: number;
@@ -4034,6 +4105,15 @@ declare function resolveCollisions(labels: LabelCandidate[], strategies?: readon
 /**
  * Compute the bounding rect of a resolved label from its position and text.
  * Uses heuristic text measurement so it works without DOM access.
+ *
+ * label.y is the SVG text anchor point, whose meaning depends on the label's
+ * dominant-baseline. The rect's top edge is derived accordingly so the box
+ * covers the actual glyphs (obstacles were sitting ~0.8*fontSize below the
+ * text for alphabetic-baseline labels, e.g. column value labels):
+ *   - 'central': y is the vertical center, so top = y - height/2.
+ *   - 'hanging'/'text-after-edge': y is the top edge already.
+ *   - default (alphabetic): y is the baseline, so top = y - fontSize*0.8
+ *     (matches textAscent, the top-to-baseline distance renderers apply).
  */
 declare function computeLabelBounds(label: ResolvedLabel): Rect;
 
@@ -4329,4 +4409,4 @@ interface TileMapBuilderOptions {
  */
 declare function tileMap(data: Record<string, number | null> | DataRow[], options?: TileMapBuilderOptions): TileMapSpec;
 
-export { type A11yMetadata, AXIS_TITLE_GAP, AXIS_TITLE_OFFSET_COMPACT, AXIS_TITLE_OFFSET_DEFAULT, AXIS_TITLE_TRAILING_PAD, type AggregateOp, type AggregateTransform, type AnimationConfig, type AnimationEase, type AnimationPhaseConfig, type AnimationSpec, type AnimationStagger, type Annotation, type AnnotationAnchor, type AnnotationOffset, type AnnotationPosition, type ArcEncoding, type ArcMark, type AreaEncoding, type AreaMark, type AxisConfig, type AxisLabelDensity, type AxisLayout, type AxisTick, BRAND_FONT_SIZE, BRAND_MIN_WIDTH, BRAND_RESERVE_WIDTH, BREAKPOINT_COMPACT_MAX, BREAKPOINT_MEDIUM_MAX, type BarColumnConfig, type BarEncoding, type BarListEncoding, type BarListLayout, type BarListRowMark, type BarListSpec, type BarListSpecWithoutData, type BarTableCell, type BaseLegendLayout, type BinParams, type BinTransform, type Breakpoint, CATEGORICAL_PALETTE, CHART_ENCODING_RULES, CHART_TYPES, COMPACT_WIDTH, type CalculateExpression, type CalculateTransform, type CategoricalLegendLayout, 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 CircleEncoding, type ColorBlindnessType, type ColumnConfig, type CompileOptions, type CompileTableOptions, type Condition, type ConditionalValueDef, DEFAULT_THEME, DIVERGING_PALETTES, type DarkMode, type DataRow, type DateGranularity, type Display, type DivergingPalette, EXTENDED_OFFSET_STRATEGIES, type ElementEdit, type ElementRef, type Encoding, type EncodingChannel, type EncodingRule, type EndpointLabelEntry, type EndpointLabelsConfig, type EndpointLabelsLayout, type FieldPredicate, type FieldRef, type FieldType, type FilterPredicate, type FilterTransform, type FlagTableCell, type FoldTransform, GRAPH_ENCODING_RULES, type GradientColorStop, type GradientDef, type GradientLegendLayout, type GradientStop, type GraphChannelRule, type GraphEdge, type GraphEdgeLayout, type GraphEncoding, type GraphEncodingChannel, type GraphLayout, type GraphLayoutConfig, type GraphNode, type GraphNodeLayout, type GraphSpec, type GraphSpecWithoutData, type Gridline, HEIGHT_CRAMPED_MAX, HEIGHT_SHORT_MAX, HPAD_COMPACT_FRACTION, HPAD_COMPACT_MIN, type HeatmapColumnConfig, type HeatmapTableCell, type HeightClass, type ImageColumnConfig, type ImageTableCell, LABEL_GAP_COMPACT, LABEL_GAP_DEFAULT, LABEL_GAP_NARROW_MAX, type LabelCandidate, type LabelConfig, type LabelDensity, type LabelMode, type LabelPriority, type LabelSpec, type LayerSpec, type LayoutStrategy, type LegendConfig, type LegendEntry, type LegendLayout, type LegendPosition, type LineEncoding, type LineMark, type LinearGradient, type LogicalAnd, type LogicalNot, type LogicalOr, type LollipopEncoding, MARK_DISPLAY_NAMES, MARK_ENCODING_RULES, MARK_TYPES, MAX_LEFT_LABEL_FRACTION_COMPACT, MAX_LEFT_LABEL_FRACTION_DEFAULT, MAX_LEFT_LABEL_FRACTION_MEDIUM, MAX_LEFT_LABEL_FRACTION_MEDIUM_MAX, type Margins, type Mark, type MarkAria, type MarkDef, type MarkEvent, type MarkType, type MeasureTextFn, type Metric, NARROW_VIEWPORT_MAX, type NodeOverride, OFFSET_STRATEGIES, type OffsetStrategy, type PaginationState, type Point, type PointEncoding, type PointMark, type RadialGradient, type RangeAnnotation, type Rect, type RectEncoding, type RectMark, type RefLineAnnotation, type RelativeTimeRef, type ResolveConfig, type ResolveMode, type ResolvedAnimation, type ResolvedAnnotation, type ResolvedChrome, type ResolvedChromeElement, type ResolvedColumn, type ResolvedLabel, type ResolvedMetricBar, type ResolvedMetricCell, 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, TICK_LABEL_OFFSET, TOP_PAD_EXTRA_NARROW, TOP_PAD_NARROW_MAX, type TableBuilderOptions, type TableCell, type TableCellBase, type TableLayout, type TableRow, type TableSpec, type TableSpecWithoutData, type TextAnnotation, type TextEncoding, type TextMarkLayout, type TextStyle, type TextTableCell, type Theme, type ThemeChromeDefaults, type ThemeColors, type ThemeConfig, type ThemeFontSizes, type ThemeFontWeights, type ThemeFonts, type ThemeSpacing, type TickEncoding, type TickMarkLayout, type TileMapBuilderOptions, type TileMapEncoding, type TileMapLayout, type TileMapPalette, type TileMapSpec, type TileMapSpecWithoutData, type TileMapTileMark, type TimeUnit, type TimeUnitTransform, type TooltipContent, type TooltipField, type Transform, type VizSpec, type WindowFieldDef, type WindowOp, type WindowSortField, type WindowTransform, abbreviateNumber, adaptColorForDarkMode, adaptTheme, areaChart, axisTitleOffset, barChart, buildD3Formatter, buildTemporalFormatter, checkPaletteDistinguishability, columnChart, computeChrome, computeLabelBounds, contrastRatio, dataTable, detectCollision, donutChart, dotChart, elementRef, estimateTextWidth, findAccessibleColor, formatDate, formatNumber, generateAltText, generateAriaLabels, generateDataTable, getAxisTitleOffset, getBreakpoint, getHeightClass, getLayoutStrategy, getRepresentativeColor, inferFieldType, isBarListSpec, isChartSpec, isConditionalDef, isEncodingChannel, isGradientDef, isGraphSpec, isLayerSpec, isRangeAnnotation, isRefLineAnnotation, isSankeySpec, isTableSpec, isTextAnnotation, isTileMapSpec, lineChart, meetsAA, pickLabelColor, pieChart, resolveCollisions, resolveMarkDef, resolveMarkType, resolveTheme, scatterChart, simulateColorBlindness, tileMap, wrapText };
+export { type A11yMetadata, AXIS_TITLE_GAP, AXIS_TITLE_OFFSET_COMPACT, AXIS_TITLE_OFFSET_DEFAULT, AXIS_TITLE_TRAILING_PAD, type AggregateOp, type AggregateTransform, type AnimationConfig, type AnimationEase, type AnimationPhaseConfig, type AnimationSpec, type AnimationStagger, type Annotation, type AnnotationAnchor, type AnnotationOffset, type AnnotationPosition, type ArcEncoding, type ArcMark, type AreaEncoding, type AreaMark, type AxisConfig, type AxisLabelDensity, type AxisLayout, type AxisTick, BRAND_FONT_SIZE, BRAND_MIN_WIDTH, BRAND_RESERVE_WIDTH, BREAKPOINT_COMPACT_MAX, BREAKPOINT_MEDIUM_MAX, type BarColumnConfig, type BarEncoding, type BarListEncoding, type BarListLayout, type BarListRowMark, type BarListSpec, type BarListSpecWithoutData, type BarTableCell, type BaseLegendLayout, type BinParams, type BinTransform, type Breakpoint, CATEGORICAL_PALETTE, CHART_ENCODING_RULES, CHART_TYPES, COMPACT_WIDTH, type CalculateExpression, type CalculateTransform, type CategoricalLegendLayout, 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 CircleEncoding, type ColorBlindnessType, type ColumnConfig, type CompileOptions, type CompileTableOptions, type Condition, type ConditionalValueDef, DEFAULT_THEME, DIVERGING_PALETTES, type DarkMode, type DataRow, type DateGranularity, type Display, type DivergingPalette, EXTENDED_OFFSET_STRATEGIES, type ElementEdit, type ElementRef, type Encoding, type EncodingChannel, type EncodingRule, type EndpointLabelEntry, type EndpointLabelsConfig, type EndpointLabelsLayout, type FieldPredicate, type FieldRef, type FieldType, type FilterPredicate, type FilterTransform, type FlagTableCell, type FoldTransform, GRAPH_ENCODING_RULES, type GradientColorStop, type GradientDef, type GradientLegendLayout, type GradientStop, type GraphChannelRule, type GraphEdge, type GraphEdgeLayout, type GraphEncoding, type GraphEncodingChannel, type GraphLayout, type GraphLayoutConfig, type GraphNode, type GraphNodeLayout, type GraphSpec, type GraphSpecWithoutData, type Gridline, HEIGHT_CRAMPED_MAX, HEIGHT_SHORT_MAX, HPAD_COMPACT_FRACTION, HPAD_COMPACT_MIN, type HeatmapColumnConfig, type HeatmapTableCell, type HeightClass, type ImageColumnConfig, type ImageTableCell, LABEL_GAP_COMPACT, LABEL_GAP_DEFAULT, LABEL_GAP_NARROW_MAX, type LabelCandidate, type LabelConfig, type LabelDensity, type LabelMode, type LabelPriority, type LabelSpec, type LayerSpec, type LayoutStrategy, type LegendConfig, type LegendEntry, type LegendEntryPosition, type LegendLayout, type LegendPosition, type LineEncoding, type LineMark, type LinearGradient, type LogicalAnd, type LogicalNot, type LogicalOr, type LollipopEncoding, MARK_DISPLAY_NAMES, MARK_ENCODING_RULES, MARK_TYPES, MAX_LEFT_LABEL_FRACTION_COMPACT, MAX_LEFT_LABEL_FRACTION_DEFAULT, MAX_LEFT_LABEL_FRACTION_MEDIUM, MAX_LEFT_LABEL_FRACTION_MEDIUM_MAX, type Margins, type Mark, type MarkAria, type MarkDef, type MarkEvent, type MarkType, type MeasureTextFn, type Metric, NARROW_VIEWPORT_MAX, type NodeOverride, OFFSET_STRATEGIES, type OffsetStrategy, type PaginationState, type Point, type PointEncoding, type PointMark, type RadialGradient, type RangeAnnotation, type Rect, type RectEncoding, type RectMark, type RefLineAnnotation, type RelativeTimeRef, type ResolveConfig, type ResolveMode, type ResolvedAnimation, type ResolvedAnnotation, type ResolvedChrome, type ResolvedChromeElement, type ResolvedColumn, type ResolvedLabel, type ResolvedMetricBar, type ResolvedMetricCell, 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, TICK_LABEL_OFFSET, TOP_PAD_EXTRA_NARROW, TOP_PAD_NARROW_MAX, type TableBuilderOptions, type TableCell, type TableCellBase, type TableLayout, type TableRow, type TableSpec, type TableSpecWithoutData, type TextAnnotation, type TextEncoding, type TextMarkLayout, type TextStyle, type TextTableCell, type Theme, type ThemeChromeDefaults, type ThemeColors, type ThemeConfig, type ThemeFontSizes, type ThemeFontWeights, type ThemeFonts, type ThemeSpacing, type TickEncoding, type TickMarkLayout, type TileMapBuilderOptions, type TileMapEncoding, type TileMapLayout, type TileMapPalette, type TileMapSpec, type TileMapSpecWithoutData, type TileMapTileMark, type TimeUnit, type TimeUnitTransform, type TooltipContent, type TooltipField, type Transform, type VizSpec, type WindowFieldDef, type WindowOp, type WindowSortField, type WindowTransform, type XAxisExtentInput, X_AXIS_BAND_HEIGHT, X_AXIS_TITLE_BAND, X_AXIS_TITLE_BAND_ROTATED, abbreviateNumber, adaptColorForDarkMode, adaptTheme, areaChart, axisTitleOffset, barChart, buildD3Formatter, buildTemporalFormatter, checkPaletteDistinguishability, columnChart, computeChrome, computeLabelBounds, computeXAxisExtentFromLabels, contrastRatio, dataTable, detectCollision, donutChart, dotChart, elementRef, estimateTextWidth, findAccessibleColor, formatDate, formatNumber, generateAltText, generateAriaLabels, generateDataTable, getAxisTitleOffset, getBreakpoint, getHeightClass, getLayoutStrategy, getRepresentativeColor, heuristicMeasure, inferFieldType, isBarListSpec, isChartSpec, isConditionalDef, isEncodingChannel, isGradientDef, isGraphSpec, isLayerSpec, isRangeAnnotation, isRefLineAnnotation, isSankeySpec, isTableSpec, isTextAnnotation, isTileMapSpec, lineChart, meetsAA, overlapArea, pickLabelColor, pieChart, resolveCollisions, resolveMarkDef, resolveMarkType, resolveMeasurer, resolveTheme, scatterChart, simulateColorBlindness, textAscent, tileMap, wrapText };