(core) add grist.getTable(tableId) and a getTableId() method in plugin api

Summary:
Makes the new TableOperations API available for all tables
in the document. Adds methods for discovering the tableId of the
selected table. I was very tempted to implement the select() TODO
in the TableOperations API, but it requires a significant refactor
of the backend.

Test Plan: added test

Reviewers: alexmojaki

Reviewed By: alexmojaki

Differential Revision: https://phab.getgrist.com/D3325

app/plugin/TableOperations.ts

@@ -19,6 +19,9 @@ export interface TableOperations {
   upsert(records: Types.AddOrUpdateRecord|Types.AddOrUpdateRecord[],
          options?: UpsertOptions): Promise<void>;
 
+  // Determine the tableId of the table.
+  getTableId(): Promise<string>;
+
   // TODO: offer a way to query the table.
   // select(): Records;
 }

app/plugin/TableOperationsImpl.ts

@@ -16,6 +16,10 @@ export class TableOperationsImpl implements TableOperations {
                      private _defaultOptions: OpOptions) {
   }
 
+  public getTableId() {
+    return this._platform.getTableId();
+  }
+
   public create(records: Types.NewRecord, options?: OpOptions): Promise<Types.MinimalRecord>;
   public create(records: Types.NewRecord[], options?: OpOptions): Promise<Types.MinimalRecord[]>;
   public async create(recordsOrRecord: Types.NewRecord[]|Types.NewRecord,

app/plugin/grist-plugin-api.ts

@@ -82,18 +82,40 @@ export const setOptions = widgetApi.setOptions.bind(widgetApi);
 export const getOptions = widgetApi.getOptions.bind(widgetApi);
 export const clearOptions = widgetApi.clearOptions.bind(widgetApi);
 
-export const selectedTable: TableOperations = new TableOperationsImpl({
-  async getTableId() {
-    await _initialization;
-    return _tableId!;
-  },
-  throwError(verb, text, status) {
-    throw new Error(text);
-  },
-  applyUserActions(actions, opts) {
-    return docApi.applyUserActions(actions, opts);
-  },
-}, {});
+// Get access to a table in the document. If no tableId specified, this
+// will use the current selected table (for custom widgets).
+// If a table does not exist, there will be no error until an operation
+// on the table is attempted.
+export function getTable(tableId?: string): TableOperations {
+  return new TableOperationsImpl({
+    async getTableId() {
+      return tableId || await getSelectedTableId();
+    },
+    throwError(verb, text, status) {
+      throw new Error(text);
+    },
+    applyUserActions(actions, opts) {
+      return docApi.applyUserActions(actions, opts);
+    },
+  }, {});
+}
+
+// Get the current selected table (for custom widgets).
+export const selectedTable: TableOperations = getTable();
+
+// Get the ID of the current selected table (for custom widgets).
+// Will wait for the table ID to be set.
+export async function getSelectedTableId(): Promise<string> {
+  await _initialization;
+  return _tableId!;
+}
+
+// Get the ID of the current selected table if set (for custom widgets).
+// The ID may take some time to be set, or may never be set if the widget
+// is not linked to anything.
+export function getSelectedTableIdSync(): string|undefined {
+  return _tableId;
+}
 
 // For custom widgets that support custom columns mappings store current configuration
 // in a memory.