From 229ec3a87ea9c6741a38785ecc9b1bad929e1e92 Mon Sep 17 00:00:00 2001
From: hikmetba-bit <hikmetba-bit@users.noreply.github.com>
Date: Sat, 19 Sep 2026 18:45:06 +0300
Subject: [PATCH] Fix ToImgopts/DownloadImgopts type definitions

Both interfaces required format/width/height (and DownloadImgopts also
required filename), but the runtime (src/plot_api/to_image.js,
src/snapshot/download.js) defaults every one of them -- toImage/
downloadImage can be called with no options at all (opts = opts || {}).

Also two gaps against the runtime's attrs object in to_image.js:

- format's value union was missing 'full-json' (documented export
  format, valType enumerated values includes it, dflt: 'png').
- imageDataOnly (valType boolean, dflt: false) had no type at all.

Added setBackground to both interfaces too: to_image.js's shared attrs
object accepts it (valType 'any', same per-call meaning as the existing
top-level Config#setBackground override in this same file), but neither
interface had it typed.

Fixes #8057.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 src/types/core/config.d.ts | 62 +++++++++++++++++++++++++++-----------
 1 file changed, 45 insertions(+), 17 deletions(-)

diff --git a/src/types/core/config.d.ts b/src/types/core/config.d.ts
index 5d8e57e63c0..bc182a891d4 100644
--- a/src/types/core/config.d.ts
+++ b/src/types/core/config.d.ts
@@ -23,29 +23,57 @@ export type { Edits };
  * for use as a data URI or as raw SVG markup.
  */
 export interface ToImgopts {
-    /** Output image format. */
-    format: 'jpeg' | 'png' | 'webp' | 'svg';
-    /** If null, uses current graph width */
-    width: number | null;
-    /** If null, uses current graph height */
-    height: number | null;
-    /** Resolution multiplier for raster formats. */
+    /**
+     * Output image format. `'full-json'` returns the figure as a JSON
+     * string instead of a raster/vector image.
+     */
+    format?: 'jpeg' | 'png' | 'webp' | 'svg' | 'full-json';
+    /** If null (the default), uses current graph width */
+    width?: number | null;
+    /** If null (the default), uses current graph height */
+    height?: number | null;
+    /** Resolution multiplier for raster formats. Defaults to 1. */
     scale?: number | undefined;
+    /**
+     * Overrides the image background, which otherwise follows
+     * `layout.paper_bgcolor`. Set to `'opaque'` when exporting a `'jpeg'`,
+     * since JPEG does not support transparency.
+     */
+    setBackground?: 'opaque' | 'transparent' | ((gd: PlotlyHTMLElement, bgColor: string) => void);
+    /**
+     * If true, returns only the raw base64/SVG data, without the
+     * `data:image/...;base64,` (or `data:image/svg+xml,`) prefix. Defaults
+     * to false.
+     */
+    imageDataOnly?: boolean;
 }
 
 /**
- * Options for `Plotly.downloadImage`. Like `ToImgopts`, but also requires
- * a `filename` because the result is saved to disk by the browser.
+ * Options for `Plotly.downloadImage`. Like `ToImgopts`, but adds a
+ * `filename` for the downloaded file; unlike `ToImgopts`, `imageDataOnly`
+ * is not accepted since `downloadImage` always saves a full file.
  */
 export interface DownloadImgopts {
-    /** Output image format. */
-    format: 'jpeg' | 'png' | 'webp' | 'svg';
-    /** Output width in pixels. */
-    width: number | null;
-    /** Output height in pixels. */
-    height: number | null;
-    /** Filename used for the downloaded file (no extension required). */
-    filename: string;
+    /** Output image format. `'full-json'` downloads the figure as JSON. */
+    format?: 'jpeg' | 'png' | 'webp' | 'svg' | 'full-json';
+    /** Output width in pixels. If null (the default), uses current graph width. */
+    width?: number | null;
+    /** Output height in pixels. If null (the default), uses current graph height. */
+    height?: number | null;
+    /**
+     * Filename used for the downloaded file (no extension required). If
+     * omitted, a name is derived from the graph's title (or subtitle),
+     * falling back to `'plot-image'`.
+     */
+    filename?: string;
+    /** Resolution multiplier for raster formats. Defaults to 1. */
+    scale?: number | undefined;
+    /**
+     * Overrides the image background, which otherwise follows
+     * `layout.paper_bgcolor`. Set to `'opaque'` when exporting a `'jpeg'`,
+     * since JPEG does not support transparency.
+     */
+    setBackground?: 'opaque' | 'transparent' | ((gd: PlotlyHTMLElement, bgColor: string) => void);
 }
 
 /**