Update plugin API docs with new FetchSelectedOptions, plus minor fixes (

#297)

help/code/interfaces/grist_plugin_api.CustomSectionAPI.md

@@ -0,0 +1,42 @@
+# Interface: CustomSectionAPI
+
+[grist-plugin-api](../modules/grist_plugin_api.md).CustomSectionAPI
+
+Interface for the mapping of a custom widget.
+
+## Table of contents
+
+### Methods
+
+- [configure](grist_plugin_api.CustomSectionAPI.md#configure)
+- [mappings](grist_plugin_api.CustomSectionAPI.md#mappings)
+
+## Methods
+
+### configure
+
+▸ **configure**(`customOptions`): `Promise`<`void`\>
+
+Initial request from a Custom Widget that wants to declare its requirements.
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `customOptions` | [`InteractionOptionsRequest`](grist_plugin_api.InteractionOptionsRequest.md) |
+
+#### Returns
+
+`Promise`<`void`\>
+
+___
+
+### mappings
+
+▸ **mappings**(): `Promise`<``null`` \| [`WidgetColumnMap`](grist_plugin_api.WidgetColumnMap.md)\>
+
+Returns current widget configuration (if requested through configuration method).
+
+#### Returns
+
+`Promise`<``null`` \| [`WidgetColumnMap`](grist_plugin_api.WidgetColumnMap.md)\>

help/code/interfaces/grist_plugin_api.FetchSelectedOptions.md

@@ -0,0 +1,51 @@
+# Interface: FetchSelectedOptions
+
+[grist-plugin-api](../modules/grist_plugin_api.md).FetchSelectedOptions
+
+Options for functions which fetch data from the selected table or record:
+
+- [onRecords](../modules/grist_plugin_api.md#onrecords)
+- [onRecord](../modules/grist_plugin_api.md#onrecord)
+- [fetchSelectedRecord](../modules/grist_plugin_api.md#fetchselectedrecord)
+- [fetchSelectedTable](../modules/grist_plugin_api.md#fetchselectedtable)
+- [GristView.fetchSelectedRecord](grist_plugin_api.GristView.md#fetchselectedrecord)
+- [GristView.fetchSelectedTable](grist_plugin_api.GristView.md#fetchselectedtable)
+
+The different methods have different default values for `keepEncoded` and `format`.
+
+## Table of contents
+
+### Properties
+
+- [format](grist_plugin_api.FetchSelectedOptions.md#format)
+- [includeColumns](grist_plugin_api.FetchSelectedOptions.md#includecolumns)
+- [keepEncoded](grist_plugin_api.FetchSelectedOptions.md#keepencoded)
+
+## Properties
+
+### format
+
+• `Optional` **format**: ``"columns"`` \| ``"rows"``
+
+- `rows`, the returned data will be an array of objects, one per row, with column names as keys.
+- `columns`, the returned data will be an object with column names as keys, and arrays of values.
+
+___
+
+### includeColumns
+
+• `Optional` **includeColumns**: ``"shown"`` \| ``"normal"`` \| ``"all"``
+
+- `shown` (default): return only columns that are explicitly shown
+  in the right panel configuration of the widget. This is the only value that doesn't require full access.
+- `normal`: return all 'normal' columns, regardless of whether the user has shown them.
+- `all`: also return special invisible columns like `manualSort` and display helper columns.
+
+___
+
+### keepEncoded
+
+• `Optional` **keepEncoded**: `boolean`
+
+- `true`: the returned data will contain raw `CellValue`s.
+- `false`: the values will be decoded, replacing e.g. `['D', timestamp]` with a moment date.

help/code/interfaces/grist_plugin_api.GristDocAPI.md

@@ -39,7 +39,7 @@ ___
 
 ▸ **fetchTable**(`tableId`): `Promise`<`any`\>
 
-Returns a complete table of data as RowRecords, including the
+Returns a complete table of data as [GristData.RowRecords](GristData.RowRecords.md), including the
 'id' column. Do not modify the returned arrays in-place, especially if used
 directly (not over RPC).
 

help/code/interfaces/grist_plugin_api.GristView.md

@@ -31,15 +31,16 @@ ___
 
 ### fetchSelectedRecord
 
-▸ **fetchSelectedRecord**(`rowId`): `Promise`<`any`\>
+▸ **fetchSelectedRecord**(`rowId`, `options?`): `Promise`<`any`\>
 
-Fetches selected record by its `rowId`.
+Fetches selected record by its `rowId`. By default, `options.keepEncoded` is `true`.
 
 #### Parameters
 
 | Name | Type |
 | :------ | :------ |
 | `rowId` | `number` |
+| `options?` | [`FetchSelectedOptions`](grist_plugin_api.FetchSelectedOptions.md) |
 
 #### Returns
 
@@ -49,9 +50,16 @@ ___
 
 ### fetchSelectedTable
 
-▸ **fetchSelectedTable**(): `Promise`<`any`\>
+▸ **fetchSelectedTable**(`options?`): `Promise`<`any`\>
 
 Like [GristDocAPI.fetchTable](grist_plugin_api.GristDocAPI.md#fetchtable), but gets data for the custom section specifically, if there is any.
+By default, `options.keepEncoded` is `true` and `format` is `columns`.
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `options?` | [`FetchSelectedOptions`](grist_plugin_api.FetchSelectedOptions.md) |
 
 #### Returns
 

help/code/interfaces/grist_plugin_api.InteractionOptionsRequest.md

@@ -25,7 +25,7 @@ ___
 
 ### columns
 
-• `Optional` **columns**: `ColumnsToMap`
+• `Optional` **columns**: [`ColumnsToMap`](../modules/grist_plugin_api.md#columnstomap)
 
 Tells Grist what columns Custom Widget expects and allows user to map between existing column names
 and those requested by Custom Widget.

help/code/interfaces/grist_plugin_api.ReadyPayload.md

@@ -35,7 +35,7 @@ ___
 
 ### columns
 
-• `Optional` **columns**: `ColumnsToMap`
+• `Optional` **columns**: [`ColumnsToMap`](../modules/grist_plugin_api.md#columnstomap)
 
 Tells Grist what columns Custom Widget expects and allows user to map between existing column names
 and those requested by Custom Widget.

help/code/modules/grist_plugin_api.md

@@ -8,6 +8,8 @@
 - [AccessTokenResult](../interfaces/grist_plugin_api.AccessTokenResult.md)
 - [ColumnToMap](../interfaces/grist_plugin_api.ColumnToMap.md)
 - [CursorPos](../interfaces/grist_plugin_api.CursorPos.md)
+- [CustomSectionAPI](../interfaces/grist_plugin_api.CustomSectionAPI.md)
+- [FetchSelectedOptions](../interfaces/grist_plugin_api.FetchSelectedOptions.md)
 - [GristColumn](../interfaces/grist_plugin_api.GristColumn.md)
 - [GristDocAPI](../interfaces/grist_plugin_api.GristDocAPI.md)
 - [GristTable](../interfaces/grist_plugin_api.GristTable.md)
@@ -23,6 +25,7 @@
 
 ### Type Aliases
 
+- [ColumnsToMap](grist_plugin_api.md#columnstomap)
 - [UIRowId](grist_plugin_api.md#uirowid)
 
 ### Variables
@@ -59,6 +62,15 @@
 
 ## Type Aliases
 
+### ColumnsToMap
+
+Ƭ **ColumnsToMap**: (`string` \| [`ColumnToMap`](../interfaces/grist_plugin_api.ColumnToMap.md))[]
+
+Tells Grist what columns a Custom Widget expects and allows users to map between existing column names
+and those requested by the Custom Widget.
+
+___
+
 ### UIRowId
 
 Ƭ **UIRowId**: `number` \| ``"new"``
@@ -87,7 +99,7 @@ ___
 
 ### sectionApi
 
-• `Const` **sectionApi**: `CustomSectionAPI`
+• `Const` **sectionApi**: [`CustomSectionAPI`](../interfaces/grist_plugin_api.CustomSectionAPI.md)
 
 Interface for the mapping of a custom widget.
 
@@ -146,17 +158,14 @@ ___
 
 ▸ **fetchSelectedRecord**(`rowId`, `options?`): `Promise`<`any`\>
 
-Fetches current selected record as for [GristView.fetchSelectedRecord](../interfaces/grist_plugin_api.GristView.md#fetchselectedrecord),
-but decoding data by default, replacing e.g. ['D', timestamp] with
-a moment date. Option `keepEncoded` skips the decoding step.
+Same as [GristView.fetchSelectedRecord](../interfaces/grist_plugin_api.GristView.md#fetchselectedrecord), but the option `keepEncoded` is `false` by default.
 
 #### Parameters
 
 | Name | Type |
 | :------ | :------ |
 | `rowId` | `number` |
-| `options` | `Object` |
-| `options.keepEncoded?` | `boolean` |
+| `options` | [`FetchSelectedOptions`](../interfaces/grist_plugin_api.FetchSelectedOptions.md) |
 
 #### Returns
 
@@ -168,16 +177,13 @@ ___
 
 ▸ **fetchSelectedTable**(`options?`): `Promise`<`any`\>
 
-Fetches data backing the widget as for [GristView.fetchSelectedTable](../interfaces/grist_plugin_api.GristView.md#fetchselectedtable),
-but decoding data by default, replacing e.g. ['D', timestamp] with
-a moment date. Option `keepEncoded` skips the decoding step.
+Same as [GristView.fetchSelectedTable](../interfaces/grist_plugin_api.GristView.md#fetchselectedtable), but the option `keepEncoded` is `false` by default.
 
 #### Parameters
 
 | Name | Type |
 | :------ | :------ |
-| `options` | `Object` |
-| `options.keepEncoded?` | `boolean` |
+| `options` | [`FetchSelectedOptions`](../interfaces/grist_plugin_api.FetchSelectedOptions.md) |
 
 #### Returns
 
@@ -283,7 +289,7 @@ custom column mapping.
 | :------ | :------ |
 | `data` | `any` |
 | `options?` | `Object` |
-| `options.columns?` | `ColumnsToMap` |
+| `options.columns?` | [`ColumnsToMap`](grist_plugin_api.md#columnstomap) |
 | `options.mappings?` | ``null`` \| [`WidgetColumnMap`](../interfaces/grist_plugin_api.WidgetColumnMap.md) |
 | `options.reverse?` | `boolean` |
 
@@ -308,7 +314,7 @@ we don't attempt to do these transformations automatically.
 | :------ | :------ |
 | `data` | `any` |
 | `options?` | `Object` |
-| `options.columns?` | `ColumnsToMap` |
+| `options.columns?` | [`ColumnsToMap`](grist_plugin_api.md#columnstomap) |
 | `options.mappings?` | ``null`` \| [`WidgetColumnMap`](../interfaces/grist_plugin_api.WidgetColumnMap.md) |
 
 #### Returns
@@ -407,19 +413,21 @@ ___
 
 ### onRecord
 
-▸ **onRecord**(`callback`): `void`
+▸ **onRecord**(`callback`, `options?`): `void`
 
 For custom widgets, add a handler that will be called whenever the
 row with the cursor changes - either by switching to a different row, or
 by some value within the row potentially changing.  Handler may
 in the future be called with null if the cursor moves away from
 any row.
+By default, `options.keepEncoded` is `false`.
 
 #### Parameters
 
 | Name | Type |
 | :------ | :------ |
 | `callback` | (`data`: ``null`` \| [`RowRecord`](../interfaces/GristData.RowRecord.md), `mappings`: ``null`` \| [`WidgetColumnMap`](../interfaces/grist_plugin_api.WidgetColumnMap.md)) => `unknown` |
+| `options` | [`FetchSelectedOptions`](../interfaces/grist_plugin_api.FetchSelectedOptions.md) |
 
 #### Returns
 
@@ -429,16 +437,18 @@ ___
 
 ### onRecords
 
-▸ **onRecords**(`callback`): `void`
+▸ **onRecords**(`callback`, `options?`): `void`
 
 For custom widgets, add a handler that will be called whenever the
-selected records change.  Handler will be called with a list of records.
+selected records change.
+By default, `options.format` is `'rows'` and `options.keepEncoded` is `false`.
 
 #### Parameters
 
 | Name | Type |
 | :------ | :------ |
 | `callback` | (`data`: [`RowRecord`](../interfaces/GristData.RowRecord.md)[], `mappings`: ``null`` \| [`WidgetColumnMap`](../interfaces/grist_plugin_api.WidgetColumnMap.md)) => `unknown` |
+| `options` | [`FetchSelectedOptions`](../interfaces/grist_plugin_api.FetchSelectedOptions.md) |
 
 #### Returns