plotters-skill 0.1.0

package/node/index.d.ts

@@ -0,0 +1,372 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+/**
+ * A flexible Cartesian axes that supports mixed series (line, scatter, bar,
+ * step, area) — similar to matplotlib's `Axes` object.
+ */
+export declare class Axes {
+  title(t: string): void
+  xlabel(l: string): void
+  ylabel(l: string): void
+  figsize(w: number, h: number): void
+  xlim(lo: number, hi: number): void
+  ylim(lo: number, hi: number): void
+  /** `ChartBuilder::build_cartesian_2d(x_min..x_max, y_min..y_max)` shorthand. */
+  buildCartesian2d(xMin: number, xMax: number, yMin: number, yMax: number): void
+  margin(px: number): void
+  marginTop(px: number): void
+  marginBottom(px: number): void
+  marginLeft(px: number): void
+  marginRight(px: number): void
+  xLabelAreaSize(px: number): void
+  yLabelAreaSize(px: number): void
+  topXLabelAreaSize(px: number): void
+  rightYLabelAreaSize(px: number): void
+  captionFontSize(size: number): void
+  captionFontFamily(family: string): void
+  grid(show: boolean): void
+  legend(show: boolean): void
+  clear(): void
+  /** Configure mesh/grid — maps to plotters' `chart.configure_mesh()`. */
+  configureMesh(options: MeshOptions): void
+  /** Configure legend — maps to plotters' `chart.configure_series_labels()`. */
+  configureSeriesLabels(options: SeriesLabelOptions): void
+  /** Add a line series, similar to `ax.plot(x, y)`. */
+  plot(x: Array<number>, y: Array<number>, options?: PlotOptions | undefined | null): void
+  /** Add a scatter series, similar to `ax.scatter(x, y)`. */
+  scatter(x: Array<number>, y: Array<number>, options?: ScatterOptions | undefined | null): void
+  /** Add a vertical bar series, similar to `ax.bar(x, height)`. */
+  bar(x: Array<number>, heights: Array<number>, options?: BarOptions | undefined | null): void
+  /** Add a step-function series, similar to `ax.step(x, y)`. */
+  step(x: Array<number>, y: Array<number>, options?: StepOptions | undefined | null): void
+  /** Add a filled-area series, similar to `ax.fill_between(x, y1)`. */
+  fillBetween(x: Array<number>, y1: Array<number>, options?: FillBetweenOptions | undefined | null): void
+  /** Save to a PNG file. */
+  savefig(path: string): void
+}
+
+/** A figure/canvas for creating plots, mirroring matplotlib's pyplot interface. */
+export declare class Figure {
+  /** Add an area chart, similar to `plt.fill_between(x, y1, y2=0, color=..., alpha=...)`. */
+  fillBetween(x: Array<number>, y1: Array<number>, options?: AreaOptions | undefined | null): void
+  /**
+   * Add a box plot, similar to `plt.boxplot(datasets, tick_labels=..., showmeans=...)`.
+   *
+   * `datasets` is a list of data arrays — each inner array produces one box.
+   */
+  boxplot(datasets: Array<Array<number>>, options?: BoxPlotOptions | undefined | null): void
+  /**
+   * Add a candlestick chart, similar to `mplfinance.plot(df, type='candle')`.
+   *
+   * `data` is a list of `[open, high, low, close]` arrays.
+   */
+  candlestick(data: Array<Array<number>>, options?: CandlestickOptions | undefined | null): void
+  /** Add a histogram, similar to `plt.hist(data, bins=10, color=..., alpha=...)`. */
+  hist(data: Array<number>, options?: HistOptions | undefined | null): void
+  /** Add a line series, similar to `plt.plot(x, y, color=..., label=...)`. */
+  plot(x: Array<number>, y: Array<number>, options?: LineOptions | undefined | null): void
+  /** Remove all plot elements, keeping title / labels / dimensions. */
+  clear(): void
+  /**
+   * Save an animated GIF where each frame is a line chart snapshot.
+   *
+   * ```js
+   * fig.savegif('animation.gif', {
+   *   frames: [
+   *     [{ x: [0,1,2], y: [10,20,15] }],
+   *     [{ x: [0,1,2,3], y: [10,20,15,25] }],
+   *   ],
+   *   delayMs: 200,
+   * });
+   * ```
+   */
+  savegif(path: string, options: GifOptions): void
+  /** Add a pie or donut chart, similar to `plt.pie(values, labels=..., colors=...)`. */
+  pie(values: Array<number>, options?: PieOptions | undefined | null): void
+  /** Set the figure title. */
+  title(title: string): void
+  /** Set the x-axis label. */
+  xlabel(label: string): void
+  /** Set the y-axis label. */
+  ylabel(label: string): void
+  /** Set figure dimensions in pixels. */
+  figsize(width: number, height: number): void
+  /** Set explicit x-axis limits, similar to `ax.set_xlim(min, max)`. */
+  xlim(min: number, max: number): void
+  /** Set explicit y-axis limits, similar to `ax.set_ylim(min, max)`. */
+  ylim(min: number, max: number): void
+  /** Set chart margin in pixels. */
+  margin(pixels: number): void
+  /** Show or hide grid lines. */
+  grid(show: boolean): void
+  /** Save the figure to a PNG file. */
+  savefig(path: string): void
+}
+
+/**
+ * A flexible multi-row figure layout where each row can have a different
+ * number of columns.
+ */
+export declare class GridFigure {
+  /** Set the overall figure size in pixels. */
+  figsize(width: number, height: number): void
+  /** Set the overall super-title for the grid. */
+  suptitle(title: string): void
+  /** Add a new row with `ncols` columns. */
+  addRow(ncols: number): void
+  /** Number of rows in the grid. */
+  get nrows(): number
+  /** Number of columns in a specific row. */
+  ncols(row: number): number
+  /**
+   * Get the figure at `(row, col)` as a standalone `Figure`.
+   *
+   * Configure it, then put it back with `setAx(row, col, fig)`.
+   */
+  ax(row: number, col: number): Figure
+  /** Put a configured figure back into the grid at `(row, col)`. */
+  setAx(row: number, col: number, fig: Figure): void
+  /** Save the grid figure to a PNG file. */
+  savefig(path: string): void
+}
+
+/** A grid of sub-figures, similar to matplotlib's `fig, axes = plt.subplots(nrows, ncols)`. */
+export declare class SubPlots {
+  /** Set the overall figure size in pixels. */
+  figsize(width: number, height: number): void
+  /** Set the overall super-title for the grid. */
+  suptitle(title: string): void
+  /** Number of rows in the grid. */
+  get nrows(): number
+  /** Number of columns in the grid. */
+  get ncols(): number
+  /**
+   * Get the figure at `(row, col)` as a standalone `Figure`.
+   *
+   * **Note:** this extracts the figure from the grid. Configure it via
+   * the returned `Figure`, then put it back with `setAx(row, col, fig)`.
+   */
+  ax(row: number, col: number): Figure
+  /** Put a configured figure back into the grid at `(row, col)`. */
+  setAx(row: number, col: number, fig: Figure): void
+  /** Save the subplot grid to a PNG file. */
+  savefig(path: string): void
+}
+
+/** Area chart options matching matplotlib's `plt.fill_between()` keyword arguments. */
+export interface AreaOptions {
+  /** Baseline y-value, similar to `y2=0` (default: 0.0). */
+  y2?: number
+  /** Fill colour name or hex code. */
+  color?: string
+  /** Opacity from 0.0 (transparent) to 1.0 (opaque), default 0.3. */
+  alpha?: number
+  /** Legend label. */
+  label?: string
+}
+
+/** Create a new flexible Axes, similar to `fig, ax = plt.subplots()`. */
+export declare function axes(): Axes
+
+export interface BarOptions {
+  color?: string
+  barWidth?: number
+  label?: string
+}
+
+/** Box plot options matching matplotlib's `plt.boxplot()` keyword arguments. */
+export interface BoxPlotOptions {
+  /** Category labels for the x-axis, similar to `tick_labels=[...]`. */
+  tickLabels?: Array<string>
+  /** Box colour name or hex code. */
+  color?: string
+  /** Legend label. */
+  label?: string
+  /** Whether to show mean markers, similar to `showmeans=True`. */
+  showMeans?: boolean
+  /** Whether to show outlier points beyond whiskers, similar to `showfliers=True`. */
+  showFliers?: boolean
+}
+
+/** Candlestick chart options matching mplfinance-style keyword arguments. */
+export interface CandlestickOptions {
+  /** X-axis tick labels (e.g. date strings). */
+  labels?: Array<string>
+  /** Colour for bullish (close >= open) candles. */
+  upColor?: string
+  /** Colour for bearish (close < open) candles. */
+  downColor?: string
+  /** Candle body width in pixels (default: 15). */
+  width?: number
+  /** Legend label. */
+  label?: string
+}
+
+/** Create a new figure, equivalent to `plt.figure()`. */
+export declare function figure(): Figure
+
+export interface FillBetweenOptions {
+  color?: string
+  y2?: number
+  alpha?: number
+  label?: string
+}
+
+/** Options for `savegif()`. */
+export interface GifOptions {
+  /** Each element is a frame; each frame is a list of `{ x, y }` line series. */
+  frames: Array<Array<GifSeries>>
+  /** Delay between frames in milliseconds (default: 100). */
+  delayMs?: number
+}
+
+/** A single `(x, y)` series used as one frame in an animated GIF. */
+export interface GifSeries {
+  x: Array<number>
+  y: Array<number>
+}
+
+/**
+ * Create an empty grid figure. Add rows with `addRow(ncols)`.
+ *
+ * Unlike `subplots(nrows, ncols)` which creates a uniform grid, `gridFigure()`
+ * lets each row have a different number of columns.
+ *
+ * ```ts
+ * const grid = gridFigure();
+ * grid.addRow(2);  // row 0: two columns
+ * grid.addRow(1);  // row 1: one full-width column
+ * grid.figsize(1200, 800);
+ * grid.suptitle("Mixed Layout");
+ *
+ * const ax = grid.ax(0, 0);
+ * ax.hist(data, { bins: 10 });
+ * grid.setAx(0, 0, ax);
+ * grid.savefig("grid.png");
+ * ```
+ */
+export declare function gridFigure(): GridFigure
+
+/** Histogram options matching matplotlib's `plt.hist()` keyword arguments. */
+export interface HistOptions {
+  /** Number of bins (default: 10). */
+  bins?: number
+  /** Bar colour name or hex code, e.g. `"steelblue"` or `"#4682B4"`. */
+  color?: string
+  /** Transparency from 0.0 (transparent) to 1.0 (opaque). */
+  alpha?: number
+  /** Legend label. */
+  label?: string
+  /** Minimum value of the data range. */
+  rangeMin?: number
+  /** Maximum value of the data range. */
+  rangeMax?: number
+}
+
+/** Line chart options matching matplotlib's `plt.plot()` keyword arguments. */
+export interface LineOptions {
+  /** Colour name or hex code, e.g. `"steelblue"` or `"#1f77b4"`. */
+  color?: string
+  /** Line width in pixels (default: 2). */
+  lineWidth?: number
+  /** Legend label. */
+  label?: string
+  /** Fix the y-axis lower bound (useful for animation). */
+  yRangeMin?: number
+  /** Fix the y-axis upper bound (useful for animation). */
+  yRangeMax?: number
+}
+
+/** Options for `configureMesh()` — maps to plotters' `MeshStyle`. */
+export interface MeshOptions {
+  xLabels?: number
+  yLabels?: number
+  xLabelOffset?: number
+  yLabelOffset?: number
+  disableXMesh?: boolean
+  disableYMesh?: boolean
+  disableAxes?: boolean
+  disableXAxis?: boolean
+  disableYAxis?: boolean
+  xMaxLightLines?: number
+  yMaxLightLines?: number
+  boldLineColor?: string
+  boldLineAlpha?: number
+  lightLineColor?: string
+  lightLineAlpha?: number
+  axisColor?: string
+  labelFontSize?: number
+  axisDescFontSize?: number
+  xLabelFontSize?: number
+  yLabelFontSize?: number
+  tickMarkSize?: number
+}
+
+/** Pie chart options matching pyplot-style `pie()` keyword arguments. */
+export interface PieOptions {
+  /** Labels for each slice. */
+  labels?: Array<string>
+  /** Slice colours by CSS-style name or hex code. */
+  colors?: Array<string>
+  /** Starting angle in degrees. */
+  startAngle?: number
+  /** Inner radius for drawing a donut chart. */
+  donutHole?: number
+  /** Label offset relative to the pie radius. */
+  labelOffset?: number
+  /** Whether to draw percentage labels inside slices. */
+  showPercentages?: boolean
+}
+
+export interface PlotOptions {
+  color?: string
+  lineWidth?: number
+  label?: string
+}
+
+export interface ScatterOptions {
+  color?: string
+  markerSize?: number
+  label?: string
+}
+
+/** Options for `configureSeriesLabels()`. */
+export interface SeriesLabelOptions {
+  position?: string
+  margin?: number
+  legendAreaSize?: number
+  backgroundColor?: string
+  backgroundAlpha?: number
+  borderColor?: string
+  fontSize?: number
+}
+
+export interface StepOptions {
+  color?: string
+  lineWidth?: number
+  label?: string
+}
+
+/**
+ * Create a subplot grid, equivalent to `plt.subplots(nrows, ncols)`.
+ *
+ * Returns a grid of figures that can each hold their own chart.
+ *
+ * ```ts
+ * const grid = subplots(2, 2);
+ * grid.figsize(1200, 800);
+ * grid.suptitle("2×2 Grid");
+ *
+ * let ax = grid.ax(0, 0);
+ * ax.hist(data, { bins: 10 });
+ * ax.title("Distribution");
+ * grid.setAx(0, 0, ax);
+ *
+ * ax = grid.ax(1, 0);
+ * ax.pie(values);
+ * grid.setAx(1, 0, ax);
+ *
+ * grid.savefig("grid.png");
+ * ```
+ */
+export declare function subplots(nrows: number, ncols: number): SubPlots