renderChart — 6.0.0

type ChartSpec = {
  /** Structured series collection. May be empty; explicit axis domains can define an empty frame. */
  series: readonly ChartSeries<X>[];
  /** Fixed plot width or `auto` for active terminal columns. Defaults to 60. */
  width?: ChartWidth;
  /** Plot height in terminal rows. Defaults to 15 unless derived. */
  height?: number;
  /** Desired physical width-to-height ratio used when height is derived. */
  aspectRatio?: number;
  /** Title rendered above the chart. */
  title?: string;
  /** ANSI color applied to the title. */
  titleColor?: Color;
  /** Line behavior outside explicit domains. Defaults to `discard`. */
  overflow?: Overflow;
  /** Plot-cell backend. Defaults to `ascii`. */
  renderer?: Renderer;
  /** Native X-axis configuration. */
  xAxis?: XAxis<X>;
  /** Primary numeric Y-axis configuration. */
  yAxis?: YAxis;
  /** Independently scaled right-side Y-axis configuration. */
  secondaryYAxis?: YAxis;
  /** Legend placement, entity selection, and ANSI color. */
  legend?: ChartLegend;
  /** Explicit numeric X/Y axis intersection. */
  axisCenter?: MaybePoint;
  /** Named point overlays rendered on the primary Y-axis. */
  points?: readonly ChartOverlayPoint<X>[];
  /** Named reference lines rendered on the primary Y-axis. */
  thresholds?: readonly ChartThreshold<X>[];
  /** Data-coordinate spans, text, arrows, and error bars. */
  annotations?: readonly ChartAnnotation<X>[];
  /** Per-call glyph overrides. */
  symbols?: Symbols;
  /** ANSI color applied to the configured border glyph. */
  borderColor?: Color;
  /** ANSI color applied to background glyphs. */
  backgroundColor?: Color;
  /** Logs out-of-bounds drawing attempts for diagnostics. */
  debugMode?: boolean;
  /** Shared arrangement for multi-series bars. Defaults to `overlap`. */
  barLayout?: BarLayout;
  /** Enables bar endpoint labels or configures their text and color. */
  valueLabels?: ChartValueLabels<X>;
};

type ChartSeries = {
  /** Unique series identifier used by legends and callback context. */
  id: string;
  /** Human-readable series label. Defaults to `id`. */
  name?: string;
  /** Native-X/numeric-Y values; `null` creates a continuity gap. */
  data: readonly ChartDatum<X>[];
  /** Series rendering primitive. Defaults to `line`. */
  mode?: GraphMode;
  /** Line-segment interpolation. Defaults to `step`. */
  interpolation?: Interpolation;
  /** Static ANSI series color. */
  color?: Color;
  /** Dynamic per-cell series-color strategy. */
  coloring?: Coloring;
  /** Fills the region between a line and the X-axis baseline. */
  fillArea?: boolean;
  /** Custom glyph callback for occupied series cells. */
  lineFormatter?: (args: LineFormatterArgs) => CustomSymbol | CustomSymbol[];
  /** Y-axis assignment. Defaults to `primary`. */
  yAxis?: 'primary' | 'secondary';
};

type ChartLegend = {
  /** Placement relative to the plot. */
  position: LegendPosition;
  /** `true` shows all series; an ID array selects and orders entries. */
  series?: boolean | readonly string[];
  /** `true` shows all points; an ID array selects and orders entries. */
  points?: boolean | readonly string[];
  /** `true` shows all thresholds; an ID array selects and orders entries. */
  thresholds?: boolean | readonly string[];
  /** ANSI color applied to legend labels. */
  color?: Color;
};

type ChartOverlayPoint = Omit<GraphPoint, 'x'> & {
  /** Unique point identifier used by legends. */
  id: string;
  /** Human-readable point label. Defaults to `id`. */
  name?: string;
  /** Native X coordinate. */
  x: X;
};

type ChartThreshold = Omit<Threshold, 'x'> & {
  /** Unique threshold identifier used by legends. */
  id: string;
  /** Human-readable threshold label. Defaults to `id`. */
  name?: string;
  /** Optional native X coordinate for a vertical reference line. */
  x?: X;
};

type XAxis = {
  /** Scale kind. Defaults to the kind inferred from X values. */
  scale?: XScale;
  /** Explicit category order or continuous scale extent. */
  domain?: XAxisDomain<X>;
  /** Exact native tick values or an exact tick count of at least two. */
  ticks?: number | readonly X[];
  /** Axis label rendered outside tick labels. */
  label?: string;
  /** Formatter called with native X values. */
  formatter?: AxisFormatter<X>;
  /** Hides the axis line, ticks, labels, and axis label. */
  hidden?: boolean;
  /** Hides tick markers and labels while retaining the axis line. */
  hideTicks?: boolean;
  /** Handling for labels that do not fit the available width. */
  labelCollision?: LabelCollisionPolicy;
  /** ANSI color applied to the axis line, ticks, tick labels, and label. */
  color?: Color;
};

type YAxis = {
  /** Explicit numeric extent as `[minimum, maximum]`. */
  domain?: readonly [number, number];
  /** Exact numeric tick values or an exact tick count of at least two. */
  ticks?: number | readonly number[];
  /** Axis label rendered outside tick labels. */
  label?: string;
  /** Formatter called for each numeric Y-axis tick. */
  formatter?: Formatter;
  /** Hides the axis line, ticks, labels, and axis label. */
  hidden?: boolean;
  /** Hides tick markers and labels while retaining the axis line. */
  hideTicks?: boolean;
  /** Reserves enough width for complete Y-axis tick labels. */
  showTickLabel?: boolean;
  /** ANSI color applied to the axis line, ticks, tick labels, and label. */
  color?: Color;
};

type Coloring = {
  /** Selects callback-based colors. */
  type: 'conditional';
  /** Returns a color or `undefined` to use the static series fallback. */
  getColor: (context: ColorContext) => Color | undefined;
} | {
  /** Selects equal-band palette coloring. */
  type: 'gradient';
  /** Data-space axis used to select a palette band. */
  by: 'x' | 'y';
  /** Nonempty ordered ANSI color palette. */
  colors: readonly Color[];
  /** Optional finite palette extent. Defaults to the resolved chart domain. */
  domain?: readonly [number, number];
};

type ChartValueLabels = boolean | {
  /** Formats the rendered value; normalized layouts receive a percentage. */
  formatter?: ValueLabelFormatter<X>;
  /** ANSI color applied to every value label. */
  color?: Color;
};

type ChartSpanAnnotation = ChartAnnotationBase & (Readonly<{
  /** Span annotation discriminator. */
  type: 'span';
  /** Fills an X-axis interval across the complete plot height. */
  axis: 'x';
  /** Inclusive native interval start. */
  from: X;
  /** Inclusive native interval end. */
  to: X;
  /** One-column fill glyph. */
  symbol?: string;
}> | Readonly<{
  /** Span annotation discriminator. */
  type: 'span';
  /** Fills a Y-axis interval across the complete plot width. */
  axis: 'y';
  /** Inclusive numeric interval start. */
  from: number;
  /** Inclusive numeric interval end. */
  to: number;
  /** One-column fill glyph. */
  symbol?: string;
}>);

type ChartTextAnnotation = ChartAnnotationBase & Readonly<{
  /** Text annotation discriminator. */
  type: 'text';
  /** Native X anchor. */
  x: X;
  /** Numeric Y anchor. */
  y: number;
  /** Display-safe terminal text. */
  text: string;
  /** Horizontal placement relative to the anchor. Defaults to `right`. */
  align?: 'left' | 'center' | 'right';
}>;

type ChartArrowAnnotation = ChartAnnotationBase & Readonly<{
  /** Arrow annotation discriminator. */
  type: 'arrow';
  /** Native-X/numeric-Y path start. */
  from: readonly [x: X, y: number];
  /** Native-X/numeric-Y path end and arrowhead position. */
  to: readonly [x: X, y: number];
  /** One-column path glyph. */
  lineSymbol?: string;
}>;

type ChartErrorBarAnnotation = ChartAnnotationBase & Readonly<{
  /** Error-bar annotation discriminator. */
  type: 'errorBar';
  /** Native X center. */
  x: X;
  /** Numeric Y center. */
  y: number;
  /** Symmetric or asymmetric Y-axis error magnitude. */
  yError?: ChartErrorMagnitude;
}> & ([X] extends [string] ? Readonly<{
  xError?: never;
}> : Readonly<{
  /** Symmetric or asymmetric X-axis error magnitude. */
  xError?: ChartErrorMagnitude;
}>);