grist-plugin-api should allow more control over records and tables

[emanuelegissi]

Describe the problem to be solved

Following this discussion (@berhalak @paulfitz):
https://community.getgrist.com/t/how-to-obtain-the-id-of-referenced-records-inside-a-custom-widget/8213
I open this issue as a placeholder for some suggestions of enhancement of grist-plugin-api.

Disclaimer: I am just learning the power of custom widgets, please, be patient if I do not fully get them...

It seems to me, that grist-plugin-api is currently conceived to read data from records and tables for the main purpose of displaying it.
But the users are using the custom widget functionality for developing more complex tools, that introduce workflow logic and actively act on records and related tables.

Describe the solution you would like

Maybe only very simple enhancements of the grist-plugin-api are enough.

Eg. adding additional options to FetchSelectedOptions that have impact on: onRecords, onRecord, fetchSelectedRecord, fetchSelectedTable. For example, something similar to what is currently available in the RECORD function.

I imagine a "duplicate and edit" scenario where the custom widget gets the selected record with all its references, modifies it and add it back to the same table without errors. It would be very useful to obtain a record in the exact format that can be readily inserted back into the same table as-it-is (eg. with referenced records ids in a list format, datetime format, ...).

Thank you!

PS While we are at it, I suggest adding simple examples to the grist-plugin-api doc. The Inspect API custom plugin was of great help for me as a novice.