@opendata-ai/openchart-core 8.0.0-rc.11 → 8.0.0-rc.13

package/dist/index.d.ts

@@ -991,13 +991,40 @@ interface GraphEncodingChannel {
     type?: FieldType;
     /** Scale configuration. Auto-derived from data if omitted. */
     scale?: ScaleConfig;
+    /**
+     * Category ordering for the color domain and legend. Graph channels default
+     * `'ascending'` (VL-aligned, deterministic); `string[]` pins an explicit
+     * order; `null` keeps data order.
+     *
+     * NOTE: chart encoding channels keep data-order — this graph default is a
+     * deliberate divergence this release (see docs/migrating-v8.md).
+     */
+    sort?: 'ascending' | 'descending' | null | string[];
+    /**
+     * Category values to emphasize on load; the rest dim. Mirrors the chart
+     * `encoding.color.highlight` value list. Distinct from the `highlight()`
+     * runtime verb and `interaction.hover.mode`.
+     */
+    highlight?: string | string[];
 }
 /** Graph-specific encoding mapping visual properties to node/edge data fields. */
 interface GraphEncoding {
     /** Color mapping for nodes. */
     nodeColor?: GraphEncodingChannel;
-    /** Size mapping for nodes. */
+    /**
+     * Size mapping for nodes. `scale.type` defaults to `'sqrt'` (area-perceptual,
+     * today's behavior); set `scale.type: 'linear'` for a linear radius ramp.
+     * `scale.range` sets the pixel radius extent (default `[3, 12]`).
+     */
     nodeSize?: GraphEncodingChannel;
+    /**
+     * Opacity mapping for nodes (VL opacity channel). Quantitative fields map
+     * linearly to `[0.25, 1]`; `scale.range` overrides.
+     *
+     * NOTE: there is deliberately no `edgeOpacity` channel — edge alpha is owned
+     * by the interaction alpha-tier machinery (hover dimming, search).
+     */
+    nodeOpacity?: GraphEncodingChannel;
     /** Color mapping for edges. */
     edgeColor?: GraphEncodingChannel;
     /** Width mapping for edges. */
@@ -1026,6 +1053,31 @@ interface GraphLayoutConfig {
     linkStrength?: number;
     /** Whether to apply center force (default true). */
     centerForce?: boolean;
+    /**
+     * Deterministic layout seed. Same spec + seed ⇒ identical settled layout
+     * within a given execution path (worker vs sync parity is not guaranteed).
+     */
+    seed?: number;
+    /**
+     * Repulsion preset (plain-language, no d3 jargon):
+     * `gentle`/`balanced`/`energetic` → chargeStrength −150/−300/−600 and
+     * velocityDecay 0.5/0.4/0.3. A raw `chargeStrength` wins over the preset.
+     */
+    energy?: 'gentle' | 'balanced' | 'energetic';
+    /**
+     * Settle-speed preset: `quick`/`balanced`/`thorough` → alphaDecay
+     * 0.05/0.0228/0.01. Higher = faster cool-down, less final refinement.
+     */
+    settle?: 'quick' | 'balanced' | 'thorough';
+    /**
+     * Headless settle ticks run before the first paint. `true` → 100 ticks under
+     * a 250ms budget; a number sets an explicit tick count; `false` disables.
+     *
+     * Lives in `layout`, NOT `animation`, on purpose: warmup *reduces* motion, so
+     * it must survive `animation: false` (opt-out consumers get less settling
+     * chaos, not more).
+     */
+    warmup?: boolean | number;
 }
 /** Style overrides for a chrome text element. */
 interface ChromeTextStyle {
@@ -1037,6 +1089,14 @@ interface ChromeTextStyle {
     fontFamily?: string;
     /** Text color (CSS color string). */
     color?: string;
+    /**
+     * Maximum number of lines this chrome text may wrap to. Additional lines are
+     * dropped and the last kept line is truncated with an ellipsis. Bounds the
+     * chrome's contribution to layout height at any container width. Applies
+     * whether the font size comes from the theme default or an explicit override.
+     * Caps height only, not horizontal overflow of a single unbreakable word.
+     */
+    maxLines?: number;
 }
 /** A chrome text element with optional style overrides. */
 interface ChromeText {
@@ -1890,6 +1950,20 @@ interface BaseChartSpec<TData extends DataRow = DataRow> {
     transform?: Transform[];
     /** Editorial chrome (title, subtitle, source, etc.). */
     chrome?: Chrome;
+    /**
+     * How chrome height interacts with the container height budget.
+     *
+     * - `'subtract'` (default): the container height is fixed and chrome text
+     *   (title/subtitle/source) is subtracted from it, shrinking the plot. This
+     *   is the historical behavior.
+     * - `'grow'`: the container height is treated as the *plot* budget, and the
+     *   rendered SVG grows taller by the measured chrome height. The plot keeps
+     *   its full budget (minus axis/padding overhead) regardless of how many
+     *   lines the title wraps to.
+     *
+     * `'grow'` is a no-op for faceted specs in this version.
+     */
+    chromeLayout?: 'subtract' | 'grow';
     /**
      * Top-level title sugar (Vega-Lite aligned). Expanded into `chrome.title`
      * (and `chrome.subtitle` for the object form). `chrome.title` wins when
@@ -2214,6 +2288,70 @@ interface NodeOverride {
     /** Force label to always show regardless of zoom/priority. */
     alwaysShowLabel?: boolean;
 }
+/**
+ * Per-phase and per-behavior motion config for a graph.
+ *
+ * DEFAULT-ON semantics (deliberately different from charts, which are opt-in):
+ * omit `animation` → the resolver returns full defaults; `animation: false` →
+ * no choreography (but `layout.warmup` still applies); a per-phase `false`
+ * disables just that phase. Graphs are default-on because physics motion
+ * already exists on load and choreography reduces the chaos.
+ */
+interface GraphAnimationConfig {
+    /** Node/edge reveal on first render. Default `{ duration: 600, ease: 'smooth', stagger: true }`. */
+    enter?: AnimationPhaseConfig | boolean;
+    /** Data-update enter-fade for newly added marks. Default `{ duration: 300, ease: 'smooth' }`. */
+    update?: AnimationPhaseConfig | boolean;
+    /** Ghost fade-out for removed marks. Default `{ duration: 300, ease: 'smooth' }`. */
+    exit?: AnimationPhaseConfig | boolean;
+    /** Camera flight easing. Default duration `'auto'` (derived from the zoom distance). */
+    camera?: {
+        duration?: number;
+        ease?: AnimationEase;
+    } | boolean;
+    /** Hover emphasis crossfade. Default `{ duration: 150, ease: 'smooth' }`. */
+    hover?: {
+        duration?: number;
+        ease?: AnimationEase;
+    } | boolean;
+}
+/**
+ * Graph motion spec.
+ * - omitted → full defaults (default-ON)
+ * - `false` → no choreography (warmup still applies)
+ * - object → per-phase control
+ *
+ * `prefers-reduced-motion` is always respected regardless of this value.
+ */
+type GraphAnimationSpec = boolean | GraphAnimationConfig;
+/** Interaction behavior for a graph (hover mode, select-fly, opt-in physics). */
+interface GraphInteractionConfig {
+    /**
+     * Hover emphasis behavior. `neighbors` (default) lights the hovered node and
+     * its adjacency; `category` lights same-category nodes; `node` lights only the
+     * hovered node; `none` disables. `dimOpacity` (default 0.15) is the node dim
+     * tier. Named `mode` (not `highlight`) to avoid colliding with the three other
+     * meanings of "highlight" (the encoding value list, the `highlight()` verb).
+     */
+    hover?: {
+        mode?: 'neighbors' | 'category' | 'node' | 'none';
+        dimOpacity?: number;
+    };
+    /** Selecting a node flies the camera to it. Default `false`. */
+    select?: {
+        flyTo?: boolean;
+    };
+    /**
+     * Opt-in cursor repulsion (nodes drift away from the pointer). Disabled under
+     * `prefers-reduced-motion` and above the node-count gate.
+     */
+    cursorRepulsion?: boolean | {
+        radius?: number;
+        strength?: number;
+    };
+    /** Opt-in springy node drag (user-initiated; no reduced-motion gate). */
+    springyDrag?: boolean;
+}
 interface GraphSpec {
     /** Discriminant: always "graph". */
     type: 'graph';
@@ -2235,6 +2373,21 @@ interface GraphSpec {
     theme?: ThemeConfig;
     /** Dark mode behavior. */
     darkMode?: DarkMode;
+    /**
+     * Motion configuration. DEFAULT-ON: omit for full defaults, `false` to opt
+     * out of choreography (layout warmup still applies).
+     */
+    animation?: GraphAnimationSpec;
+    /** Interaction behavior (hover mode, select-fly, opt-in physics). */
+    interaction?: GraphInteractionConfig;
+    /**
+     * Built-in legend. Interactive by default. Set `false` if you render your own
+     * legend, so the built-in filter UI doesn't compete with it.
+     */
+    legend?: boolean | {
+        interactive?: boolean;
+        counts?: boolean;
+    };
     /** Whether to show the tryOpenData.ai watermark. Defaults to true. */
     watermark?: boolean;
 }
@@ -3215,6 +3368,12 @@ interface ResolvedChromeElement {
     y: number;
     /** Maximum width for line wrapping. */
     maxWidth: number;
+    /**
+     * Maximum wrapped lines. When set, the renderer caps the wrapped output to
+     * this many lines and truncates the last kept line with an ellipsis. The
+     * layout height reserved for this element already reflects the cap.
+     */
+    maxLines?: number;
     /** Computed text style. */
     style: TextStyle;
 }
@@ -3823,6 +3982,8 @@ interface LegendEntry {
     active?: boolean;
     /** True for overflow indicator entries ("+N more"). Not interactive. */
     overflow?: boolean;
+    /** Node/edge count for this category (graph legends). Additive; undefined elsewhere. */
+    count?: number;
 }
 /** The encoding channel a legend keys. */
 type LegendChannel = 'color' | 'size';
@@ -4969,6 +5130,14 @@ interface CompileOptions {
     width: number;
     /** Total available height in pixels. */
     height: number;
+    /**
+     * How chrome height interacts with the height budget. Mirrors the spec-level
+     * `chromeLayout`; the engine reads whichever is set (spec wins).
+     *
+     * - `'subtract'` (default): `height` is the fixed total; chrome shrinks the plot.
+     * - `'grow'`: `height` is the plot budget; the SVG grows by the chrome height.
+     */
+    chromeLayout?: 'subtract' | 'grow';
     /** Theme overrides. */
     theme?: ThemeConfig;
     /**
@@ -5547,12 +5716,20 @@ declare function computeXAxisExtentFromLabels(input: XAxisExtentInput): number;
  */
 declare function maxRotatedLabelWidth(tickAngle: number, tickFontSize: number): number;
 /**
- * Truncate a rotated tick label with an ellipsis so it fits inside the capped
- * reservation. Returns the label unchanged when it already fits.
+ * Truncate a label with an ellipsis so it fits inside an explicit pixel budget.
+ * Returns the label unchanged when it already fits.
  *
  * Binary-search on character count against the real measure function, so it
  * respects proportional fonts rather than assuming a fixed character width.
  */
+declare function truncateToWidth(label: string, budget: number, fontSize: number, fontWeight: number, measure?: (text: string, fontSize: number, fontWeight?: number) => number): string;
+/**
+ * Truncate a rotated tick label with an ellipsis so it fits inside the capped
+ * reservation. Returns the label unchanged when it already fits.
+ *
+ * Delegates to `truncateToWidth` with the budget derived from the rotation
+ * geometry, so the binary-search stays in one place.
+ */
 declare function truncateRotatedLabel(label: string, tickAngle: number, tickFontSize: number, tickFontWeight: number, measure?: (text: string, fontSize: number, fontWeight?: number) => number): string;
 
 /**
@@ -5987,4 +6164,4 @@ declare const CSS_TOKEN_ROOT_SELECTORS: readonly string[];
 declare const CSS_TOKENS: readonly CssTokenDef[];
 declare function cssTokenDefault(name: string, mode: 'light' | 'dark'): string;
 
-export { type A11yConfig, type A11yMetadata, ACHROMATIC_RAMP, 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 AnnotationFootnote, 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 BeeswarmEncoding, type BinParams, type BinTransform, type Breakpoint, CATEGORICAL_PALETTE, COMPACT_WIDTH, CSS_TOKENS, CSS_TOKEN_ROOT_SELECTORS, type CalculateExpression, type CalculateTransform, type CalendarEncoding, 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 Chrome, type ChromeDefaults, type ChromeKey, type ChromeMode, type ChromeText, type ChromeTextStyle, type ChromeThemeOverride, type CircleEncoding, type ColorBlindnessType, type ColumnConfig, type CompileOptions, type CompileTableOptions, type CompileWarning, type Condition, type ConditionalValueDef, type ConnectorConfig, type ConnectorType, type ContinuousLegendBin, type ContinuousLegendLayout, type ContinuousLegendTick, type CssTokenDef, 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 EndpointLabelContent, type EndpointLabelEntry, type EndpointLabelsConfig, type EndpointLabelsLayout, FOOTNOTE_LINE_HEIGHT, type FacetChannel, type FacetLayout, type FacetPanelLayout, type FieldFormatContext, type FieldPredicate, type FieldRef, type FieldType, type FillPatternType, 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 LegendChannel, 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 MapBorders, type MapEncoding, type MapFeatureMark, type MapFocus, type MapFocusLayout, type MapGeo, type MapLayout, type MapPointMark, type MapPointsLayer, type MapProjection, type MapSpec, type MapSpecWithoutData, type Margins, type Mark, type MarkAria, type MarkDef, type MarkEvent, type MarkType, type MeasureTextFn, type Metric, NARROW_VIEWPORT_MAX, type NodeOverride, type NumberFormatter, OFFSET_STRATEGIES, type OffsetStrategy, type PaginationState, type ParliamentEncoding, type Point, type PointEncoding, type PointMark, type RadialGradient, type RangeAnnotation, type RangeEncoding, type Rect, type RectEncoding, type RectMark, type RefLineAnnotation, type RelativeTimeRef, type ResolveConfig, type ResolveMode, type ResolvedAnimation, type ResolvedAnimationPhase, type ResolvedAnnotation, type ResolvedChrome, type ResolvedChromeElement, type ResolvedColumn, type ResolvedFillPattern, type ResolvedLabel, type ResolvedMetricBar, type ResolvedMetricCell, type ResolvedSeriesSearch, type ResolvedTheme, type ResolvedYouDrawIt, type ResponsiveConfig, type RuleMarkLayout, SEQUENTIAL_PALETTES, SUPPORTED_SCHEME_NAMES, type SankeyEncoding, type SankeyLayout, type SankeyLinkColor, type SankeyLinkMark, type SankeyNodeAlign, type SankeyNodeMark, type SankeySpec, type SankeySpecWithoutData, type ScaleConfig, type ScaleInvert, type ScaleType, type SequentialPalette, type SeriesSearchConfig, type SeriesStrategy, type SeriesStyle, type SizeLegendCircle, type SizeLegendLayout, type SortByField, type SortState, type SparklineColumnConfig, type SparklineData, type SparklineTableCell, type StoredVizSpec, TICK_LABEL_OFFSET, TICK_LINE_HEIGHT_FACTOR, 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 TokenValue, type TooltipContent, type TooltipField, type Transform, type ValueDef, type VizSpec, type WaffleEncoding, type WindowFieldDef, type WindowOp, type WindowSortField, type WindowTransform, type XAxisExtentInput, X_AXIS_BAND_HEIGHT, X_AXIS_ROTATED_EXTENT_CAP, X_AXIS_TITLE_BAND, X_AXIS_TITLE_BAND_ROTATED, type YouDrawItConfig, type YouDrawItSample, type YouDrawItYInvert, abbreviateNumber, adaptColorForDarkMode, adaptForLightLineStroke, adaptTheme, areaChart, axisTitleOffset, barChart, buildCompactStepFormatter, buildD3Formatter, buildTemporalFormatter, checkPaletteDistinguishability, columnChart, computeChrome, computeFieldFormatContext, computeLabelBounds, computeXAxisExtentFromLabels, contrastRatio, cssTokenDefault, dataTable, deepMergeSpec, defaultNumberFormatter, detectCollision, donutChart, dotChart, editorial, elementRef, essay, estimateTextWidth, findAccessibleColor, footnoteBandHeight, formatCurrency, formatDate, formatNumber, formatOrdinal, formatPercent, generateAltText, generateAriaLabels, generateDataTable, getAxisTitleOffset, getBreakpoint, getHeightClass, getLayoutStrategy, getRepresentativeColor, heuristicMeasure, inferFieldType, isAxislessMark, isBarListSpec, isChartSpec, isConditionalDef, isEncodingChannel, isGradientDef, isGraphSpec, isLayerSpec, isMapSpec, isOpaqueColor, isRangeAnnotation, isRefLineAnnotation, isSankeySpec, isTableSpec, isTextAnnotation, isTileMapSpec, isValueDef, isYearContext, lineChart, maxRotatedLabelWidth, meetsAA, overlapArea, pickLabelColor, pieChart, resolveCollisions, resolveMarkDef, resolveMarkType, resolveMeasurer, resolveNumberFormatter, resolveSchemeName, resolveTheme, scatterChart, simulateColorBlindness, textAscent, tileMap, truncateRotatedLabel, wire, wrapText };
+export { type A11yConfig, type A11yMetadata, ACHROMATIC_RAMP, 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 AnnotationFootnote, 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 BeeswarmEncoding, type BinParams, type BinTransform, type Breakpoint, CATEGORICAL_PALETTE, COMPACT_WIDTH, CSS_TOKENS, CSS_TOKEN_ROOT_SELECTORS, type CalculateExpression, type CalculateTransform, type CalendarEncoding, 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 Chrome, type ChromeDefaults, type ChromeKey, type ChromeMode, type ChromeText, type ChromeTextStyle, type ChromeThemeOverride, type CircleEncoding, type ColorBlindnessType, type ColumnConfig, type CompileOptions, type CompileTableOptions, type CompileWarning, type Condition, type ConditionalValueDef, type ConnectorConfig, type ConnectorType, type ContinuousLegendBin, type ContinuousLegendLayout, type ContinuousLegendTick, type CssTokenDef, 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 EndpointLabelContent, type EndpointLabelEntry, type EndpointLabelsConfig, type EndpointLabelsLayout, FOOTNOTE_LINE_HEIGHT, type FacetChannel, type FacetLayout, type FacetPanelLayout, type FieldFormatContext, type FieldPredicate, type FieldRef, type FieldType, type FillPatternType, type FilterPredicate, type FilterTransform, type FlagTableCell, type FoldTransform, GRAPH_ENCODING_RULES, type GradientColorStop, type GradientDef, type GradientLegendLayout, type GradientStop, type GraphAnimationConfig, type GraphAnimationSpec, type GraphChannelRule, type GraphEdge, type GraphEdgeLayout, type GraphEncoding, type GraphEncodingChannel, type GraphInteractionConfig, 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 LegendChannel, 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 MapBorders, type MapEncoding, type MapFeatureMark, type MapFocus, type MapFocusLayout, type MapGeo, type MapLayout, type MapPointMark, type MapPointsLayer, type MapProjection, type MapSpec, type MapSpecWithoutData, type Margins, type Mark, type MarkAria, type MarkDef, type MarkEvent, type MarkType, type MeasureTextFn, type Metric, NARROW_VIEWPORT_MAX, type NodeOverride, type NumberFormatter, OFFSET_STRATEGIES, type OffsetStrategy, type PaginationState, type ParliamentEncoding, type Point, type PointEncoding, type PointMark, type RadialGradient, type RangeAnnotation, type RangeEncoding, type Rect, type RectEncoding, type RectMark, type RefLineAnnotation, type RelativeTimeRef, type ResolveConfig, type ResolveMode, type ResolvedAnimation, type ResolvedAnimationPhase, type ResolvedAnnotation, type ResolvedChrome, type ResolvedChromeElement, type ResolvedColumn, type ResolvedFillPattern, type ResolvedLabel, type ResolvedMetricBar, type ResolvedMetricCell, type ResolvedSeriesSearch, type ResolvedTheme, type ResolvedYouDrawIt, type ResponsiveConfig, type RuleMarkLayout, SEQUENTIAL_PALETTES, SUPPORTED_SCHEME_NAMES, type SankeyEncoding, type SankeyLayout, type SankeyLinkColor, type SankeyLinkMark, type SankeyNodeAlign, type SankeyNodeMark, type SankeySpec, type SankeySpecWithoutData, type ScaleConfig, type ScaleInvert, type ScaleType, type SequentialPalette, type SeriesSearchConfig, type SeriesStrategy, type SeriesStyle, type SizeLegendCircle, type SizeLegendLayout, type SortByField, type SortState, type SparklineColumnConfig, type SparklineData, type SparklineTableCell, type StoredVizSpec, TICK_LABEL_OFFSET, TICK_LINE_HEIGHT_FACTOR, 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 TokenValue, type TooltipContent, type TooltipField, type Transform, type ValueDef, type VizSpec, type WaffleEncoding, type WindowFieldDef, type WindowOp, type WindowSortField, type WindowTransform, type XAxisExtentInput, X_AXIS_BAND_HEIGHT, X_AXIS_ROTATED_EXTENT_CAP, X_AXIS_TITLE_BAND, X_AXIS_TITLE_BAND_ROTATED, type YouDrawItConfig, type YouDrawItSample, type YouDrawItYInvert, abbreviateNumber, adaptColorForDarkMode, adaptForLightLineStroke, adaptTheme, areaChart, axisTitleOffset, barChart, buildCompactStepFormatter, buildD3Formatter, buildTemporalFormatter, checkPaletteDistinguishability, columnChart, computeChrome, computeFieldFormatContext, computeLabelBounds, computeXAxisExtentFromLabels, contrastRatio, cssTokenDefault, dataTable, deepMergeSpec, defaultNumberFormatter, detectCollision, donutChart, dotChart, editorial, elementRef, essay, estimateTextWidth, findAccessibleColor, footnoteBandHeight, formatCurrency, formatDate, formatNumber, formatOrdinal, formatPercent, generateAltText, generateAriaLabels, generateDataTable, getAxisTitleOffset, getBreakpoint, getHeightClass, getLayoutStrategy, getRepresentativeColor, heuristicMeasure, inferFieldType, isAxislessMark, isBarListSpec, isChartSpec, isConditionalDef, isEncodingChannel, isGradientDef, isGraphSpec, isLayerSpec, isMapSpec, isOpaqueColor, isRangeAnnotation, isRefLineAnnotation, isSankeySpec, isTableSpec, isTextAnnotation, isTileMapSpec, isValueDef, isYearContext, lineChart, maxRotatedLabelWidth, meetsAA, overlapArea, pickLabelColor, pieChart, resolveCollisions, resolveMarkDef, resolveMarkType, resolveMeasurer, resolveNumberFormatter, resolveSchemeName, resolveTheme, scatterChart, simulateColorBlindness, textAscent, tileMap, truncateRotatedLabel, truncateToWidth, wire, wrapText };

package/dist/index.js

@@ -1371,17 +1371,16 @@ function maxRotatedLabelWidth(tickAngle, tickFontSize) {
   const usable = X_AXIS_ROTATED_EXTENT_CAP - lineHeight * Math.cos(angleRad) - AXIS_TO_LABEL_GAP;
   return Math.max(0, usable / sin);
 }
-function truncateRotatedLabel(label, tickAngle, tickFontSize, tickFontWeight, measure = estimateTextWidth) {
-  const budget = maxRotatedLabelWidth(tickAngle, tickFontSize);
+function truncateToWidth(label, budget, fontSize, fontWeight, measure = estimateTextWidth) {
   if (!Number.isFinite(budget)) return label;
-  if (measure(label, tickFontSize, tickFontWeight) <= budget) return label;
+  if (measure(label, fontSize, fontWeight) <= budget) return label;
   const ELLIPSIS = "\u2026";
   let lo = 0;
   let hi = label.length;
   while (lo < hi) {
     const mid = Math.ceil((lo + hi) / 2);
     const candidate = label.slice(0, mid) + ELLIPSIS;
-    if (measure(candidate, tickFontSize, tickFontWeight) <= budget) {
+    if (measure(candidate, fontSize, fontWeight) <= budget) {
       lo = mid;
     } else {
       hi = mid - 1;
@@ -1389,6 +1388,10 @@ function truncateRotatedLabel(label, tickAngle, tickFontSize, tickFontWeight, me
   }
   return lo > 0 ? label.slice(0, lo).trimEnd() + ELLIPSIS : ELLIPSIS;
 }
+function truncateRotatedLabel(label, tickAngle, tickFontSize, tickFontWeight, measure = estimateTextWidth) {
+  const budget = maxRotatedLabelWidth(tickAngle, tickFontSize);
+  return truncateToWidth(label, budget, tickFontSize, tickFontWeight, measure);
+}
 
 // src/theme/defaults.ts
 var DEFAULT_THEME = {
@@ -1884,13 +1887,14 @@ function buildTextStyle(defaults, fontFamily, textColor, width, overrides) {
     textAnchor: "start"
   };
 }
-function estimateLineCount(text, style, maxWidth, measureText) {
+function estimateLineCount(text, style, maxWidth, measureText, maxLines) {
   if (maxWidth <= 0) return 1;
   const segments = text.split("\n");
   if (segments.length > 1) {
-    return segments.reduce((total, segment) => {
+    const count = segments.reduce((total, segment) => {
       return total + (segment.length === 0 ? 1 : estimateLineCount(segment, style, maxWidth, measureText));
     }, 0);
+    return maxLines != null ? Math.min(count, maxLines) : count;
   }
   if (measureText) {
     const textWidth = measureText(text, style.fontSize, style.fontWeight).width;
@@ -1908,7 +1912,7 @@ function estimateLineCount(text, style, maxWidth, measureText) {
         current2 = candidate;
       }
     }
-    return lines2;
+    return maxLines != null ? Math.min(lines2, maxLines) : lines2;
   }
   const charWidth = estimateCharWidth(style.fontSize, style.fontWeight);
   const maxChars = Math.floor(maxWidth / charWidth);
@@ -1925,7 +1929,7 @@ function estimateLineCount(text, style, maxWidth, measureText) {
       current = candidate;
     }
   }
-  return lines;
+  return maxLines != null ? Math.min(lines, maxLines) : lines;
 }
 var FOOTNOTE_LINE_HEIGHT = 1.3;
 var FOOTNOTE_BAND_GAP = 4;
@@ -1953,12 +1957,14 @@ function computeChrome(chrome, theme, width, measureText, chromeMode = "full", p
       width,
       eyebrowNorm.style
     );
-    const lineCount = estimateLineCount(eyebrowNorm.text, style, maxWidth, measureText);
+    const maxLines = eyebrowNorm.style?.maxLines;
+    const lineCount = estimateLineCount(eyebrowNorm.text, style, maxWidth, measureText, maxLines);
     const element = {
       text: eyebrowNorm.text,
       x: pad2 + (eyebrowNorm.offset?.dx ?? 0),
       y: topY + (eyebrowNorm.offset?.dy ?? 0),
       maxWidth,
+      ...maxLines != null ? { maxLines } : {},
       style
     };
     topElements.eyebrow = element;
@@ -1973,12 +1979,14 @@ function computeChrome(chrome, theme, width, measureText, chromeMode = "full", p
       width,
       titleNorm.style
     );
-    const lineCount = estimateLineCount(titleNorm.text, style, maxWidth, measureText);
+    const maxLines = titleNorm.style?.maxLines;
+    const lineCount = estimateLineCount(titleNorm.text, style, maxWidth, measureText, maxLines);
     const element = {
       text: titleNorm.text,
       x: pad2 + (titleNorm.offset?.dx ?? 0),
       y: topY + (titleNorm.offset?.dy ?? 0),
       maxWidth,
+      ...maxLines != null ? { maxLines } : {},
       style
     };
     topElements.title = element;
@@ -1993,12 +2001,14 @@ function computeChrome(chrome, theme, width, measureText, chromeMode = "full", p
       width,
       subtitleNorm.style
     );
-    const lineCount = estimateLineCount(subtitleNorm.text, style, maxWidth, measureText);
+    const maxLines = subtitleNorm.style?.maxLines;
+    const lineCount = estimateLineCount(subtitleNorm.text, style, maxWidth, measureText, maxLines);
     const element = {
       text: subtitleNorm.text,
       x: pad2 + (subtitleNorm.offset?.dx ?? 0),
       y: topY + (subtitleNorm.offset?.dy ?? 0),
       maxWidth,
+      ...maxLines != null ? { maxLines } : {},
       style
     };
     topElements.subtitle = element;
@@ -2063,7 +2073,14 @@ function computeChrome(chrome, theme, width, measureText, chromeMode = "full", p
         width,
         item.norm.style
       );
-      const lineCount = estimateLineCount(item.norm.text, style, bottomMaxWidth, measureText);
+      const maxLines = item.norm.style?.maxLines;
+      const lineCount = estimateLineCount(
+        item.norm.text,
+        style,
+        bottomMaxWidth,
+        measureText,
+        maxLines
+      );
       const height = estimateTextHeight(style.fontSize, lineCount, style.lineHeight);
       bottomElements[item.key] = {
         text: item.norm.text,
@@ -2071,6 +2088,7 @@ function computeChrome(chrome, theme, width, measureText, chromeMode = "full", p
         y: bottomHeight + (item.norm.offset?.dy ?? 0),
         // offset from where bottom chrome starts
         maxWidth: bottomMaxWidth,
+        ...maxLines != null ? { maxLines } : {},
         style
       };
       bottomHeight += height + chromeGap;
@@ -4129,6 +4147,7 @@ export {
   textAscent,
   tileMap,
   truncateRotatedLabel,
+  truncateToWidth,
   wire,
   wrapText
 };