[BUG]: imperfect type definitions around graph export features

[fujidana]

Description

I found the following imperfect definitions in type definitions Plotly introduced recently (v4.0.0?), around toImage(), downloadImage() and config.toImageButtonOptions. This will hinder using these functions/option for TypeScript users (like me).

• Lack of full-json export format. A graph can be exported as JSON probably since v1.53.0 (see CHANGELOG.md or add format "full-json" to Plotly.toImage and Plotly.dowloadImage #4593) but this feature was not documented until very recently (docs: Add 'full-json' docs, examples graphing-library-docs#471).
• Lack of imageDataOnly option. This option is also very recently documented here.
• Some properties being set as required. The properties of the second parameter in toImage() and downloadImage() should be all optional. Currently some are required.

Can I send a PR for these? The PR won't include changes on executable code in JS; it will only modify *.d.ts files and maybe docstring parts in JS files.

[camdecoster]

I was just looking at this as a result of your docs PR. Updating the hand written types is a good first step, but I'm wondering if we should update the schema and then generate the types from that. What do you think?

[fujidana]

Hi, @camdecoster.
I was also wondering why these types are hand-written, though other properties of Config are auto-generated. Though I don't understand perfectly how the type generation in this project works, I think in general it makes a bit difficult for developers to keep the type definitions and implementation consistent when some definitions are defined separately.

Do you (or your college) have a plan to do this update?

[camdecoster]

All of the generated types are derived from the schema. If information isn't available in the schema, we have to hand write the types that cover that information. In the case of toImageButtonOptions, no info is provided in the schema. In fact, we direct people toward a script file:

plotly.js/src/plot_api/plot_config.js

Lines 281 to 289 in f618df5

	toImageButtonOptions: {
	valType: 'any',
	dflt: {},
	description: [
	'Statically override options for toImage modebar button',
	'allowed keys are format, filename, width, height, scale',
	'see ../components/modebar/buttons.js'
	].join(' ')
	},

The type generation is set up to be (mostly) automatic, using the schema as the source of truth. You can read more about it in the type docs included in the repo.

Since I already started looking at it, why don't I take care of this issue. But please be on the lookout for other gaps in our type coverage. I'd love to have some help getting things completely covered.