doc: Update tile extension SDK api documentation (#1417)

Also breaks out a couple of functions that are for internal use
only into there own interfaces.

Also deprecates and replaces the addErrors and clearErrors functions.

Finally:
1. changes the tile extension theme to use google coloring.
2. changes the tile extensions to use the new addError and clearError
   functions.

Author: bryans99

packages/extension-sdk-react/src/components/ExtensionConnector/ExtensionConnector.tsx

@@ -27,7 +27,11 @@
 import isEqual from 'lodash/isEqual'
 import React, { useEffect, useState, useCallback, useRef } from 'react'
 import { MemoryRouter } from 'react-router-dom'
-import type { RawVisualizationData, TileHostData } from '@looker/extension-sdk'
+import type {
+  RawVisualizationData,
+  TileHostData,
+  TileSDKInternal,
+} from '@looker/extension-sdk'
 import { connectExtensionHost } from '@looker/extension-sdk'
 import { ErrorMessage } from '../ErrorMessage'
 import { RouteChangeListener } from '../RouteChangeListener'
@@ -101,7 +105,7 @@ export const ExtensionConnector: React.FC<ExtensionConnectorProps> = ({
     (partialHostData: Partial<TileHostData>) => {
       if (contextDataRef.current.tileSDK) {
         const { tileSDK } = contextDataRef.current
-        tileSDK.tileHostDataChanged(partialHostData)
+        ;(tileSDK as TileSDKInternal).tileHostDataChanged(partialHostData)
         updateContextData({
           tileHostData: tileSDK.tileHostData,
         })

packages/extension-sdk/src/connect/extension_host_api.ts

@@ -30,9 +30,14 @@ import { logError } from '../util'
 import type {
   VisualizationDataReceivedCallback,
   VisualizationSDK,
+  VisualizationSDKInternal,
 } from './visualization'
 import { VisualizationSDKImpl } from './visualization/visualization_sdk'
-import type { TileHostDataChangedCallback, TileSDK } from './tile'
+import type {
+  TileHostDataChangedCallback,
+  TileSDK,
+  TileSDKInternal,
+} from './tile'
 import { TileSDKImpl } from './tile/tile_sdk'
 import { FetchProxyImpl } from './fetch_proxy'
 import type {
@@ -62,8 +67,8 @@ export class ExtensionHostApiImpl implements ExtensionHostApi {
   private hostChangedRoute?: (route: string, routeState?: any) => void
   private visualizationDataReceivedCallback?: VisualizationDataReceivedCallback
   private tileHostDataChangedCallback?: TileHostDataChangedCallback
-  private _visualizationSDK?: VisualizationSDK
-  private _tileSDK?: TileSDK
+  private _visualizationSDK?: VisualizationSDKInternal
+  private _tileSDK?: TileSDKInternal
 
   private contextData?: string
 
@@ -127,15 +132,17 @@ export class ExtensionHostApiImpl implements ExtensionHostApi {
       }
       case ExtensionNotificationType.VISUALIZATION_DATA: {
         const { payload } = message
-        this.visualizationSDK.updateVisData(payload)
+        ;(this.visualizationSDK as VisualizationSDKInternal).updateVisData(
+          payload
+        )
         if (this.visualizationDataReceivedCallback) {
           this.visualizationDataReceivedCallback(payload)
         }
         return undefined
       }
       case ExtensionNotificationType.TILE_HOST_DATA: {
         const { payload } = message
-        this.tileSDK.tileHostDataChanged(payload)
+        ;(this.tileSDK as TileSDKInternal).tileHostDataChanged(payload)
         if (this.tileHostDataChangedCallback) {
           this.tileHostDataChangedCallback(payload)
         }

packages/extension-sdk/src/connect/tile/tile_sdk.spec.ts

@@ -131,6 +131,21 @@ describe('TileSDK', () => {
     expect(dashboardFilters).toEqual({})
   })
 
+  it('sends add error message ', () => {
+    const message1 = { title: 'Title1', message: 'Message1', group: 'abc' }
+    const tileSdk = makeTileSdk()
+    tileSdk.addError(message1)
+    expect(api.send).toBeCalledWith('TILE_ADD_ERRORS', {
+      errors: [message1],
+    })
+  })
+
+  it('sends clear error message ', () => {
+    const tileSdk = makeTileSdk()
+    tileSdk.clearError()
+    expect(api.send).toBeCalledWith('TILE_CLEAR_ERRORS', { group: undefined })
+  })
+
   it('sends add errors message ', () => {
     const message1 = { title: 'Title1', message: 'Message1', group: 'abc' }
     const message2 = { title: 'Title2', message: 'Message2', group: 'abc' }

packages/extension-sdk/src/connect/tile/tile_sdk.ts

@@ -29,12 +29,12 @@ import { NOT_DASHBOARD_MOUNT_NOT_SUPPORTED_ERROR } from '../../util/errors'
 import { ExtensionRequestType } from '../types'
 import type { ExtensionHostApiImpl } from '../extension_host_api'
 import type {
-  TileSDK,
   TileError,
   DrillMenuOptions,
   CrossFilterOptions,
   Filters,
   TileHostData,
+  TileSDKInternal,
 } from './types'
 import { DashboardRunState } from './types'
 
@@ -43,7 +43,7 @@ const defaultHostData: TileHostData = {
   dashboardRunState: DashboardRunState.UNKNOWN,
   dashboardFilters: {},
 }
-export class TileSDKImpl implements TileSDK {
+export class TileSDKImpl implements TileSDKInternal {
   hostApi: ExtensionHostApiImpl
   tileHostData: TileHostData
 
@@ -60,6 +60,26 @@ export class TileSDKImpl implements TileSDK {
     }
   }
 
+  addError(error: TileError) {
+    if (this.hostApi.isDashboardMountSupported) {
+      this.hostApi.send(ExtensionRequestType.TILE_ADD_ERRORS, {
+        errors: [error],
+      })
+    } else {
+      throw NOT_DASHBOARD_MOUNT_NOT_SUPPORTED_ERROR
+    }
+  }
+
+  clearError() {
+    if (this.hostApi.isDashboardMountSupported) {
+      this.hostApi.send(ExtensionRequestType.TILE_CLEAR_ERRORS, {
+        group: undefined,
+      })
+    } else {
+      throw NOT_DASHBOARD_MOUNT_NOT_SUPPORTED_ERROR
+    }
+  }
+
   addErrors(...errors: TileError[]) {
     if (this.hostApi.isDashboardMountSupported) {
       this.hostApi.send(ExtensionRequestType.TILE_ADD_ERRORS, { errors })

packages/extension-sdk/src/connect/tile/types.ts

@@ -204,18 +204,63 @@ export interface Filters {
   [key: string]: string
 }
 
+/**
+ * For internal use only
+ */
+export interface TileSDKInternal extends TileSDK {
+  tileHostDataChanged: (hostData: Partial<TileHostData>) => void
+}
+
 /**
  * Extension tile SDK
  */
 export interface TileSDK {
+  /**
+   * Tile host data.
+   */
   tileHostData: TileHostData
-  tileHostDataChanged: (hostData: Partial<TileHostData>) => void
+  /**
+   * Display an error beneath the tile extension.
+   */
+  addError: (error: TileError) => void
+  /**
+   * Clear an error beneath the tile extension.
+   */
+  clearError: () => void
+  /**
+   * Display an error beneath the tile extension.
+   * @deprecated
+   */
   addErrors: (...errors: TileError[]) => void
+  /**
+   * Clear an error beneath the tile extension.
+   * @deprecated
+   */
   clearErrors: (group?: string) => void
+  /**
+   * Open a drill menu. The event controls positioning of the drill menu.
+   * Set the pageX and pageY properties on the event to control the
+   * positioning (all other properties are ignored).
+   */
   openDrillMenu: (options: DrillMenuOptions, event?: MouseEvent) => void
+  /**
+   * Toggle cross filters. This is ignored when running in an explore.
+   */
   toggleCrossFilter: (options: CrossFilterOptions, event?: MouseEvent) => void
+  /**
+   * Run the current dashboard. This is ignored when running in an explore.
+   */
   runDashboard: () => void
+  /**
+   * Stop the current dashboard. This is ignored when running in an explore.
+   */
   stopDashboard: () => void
-  updateFilters: (filters: Filters, runDashboard?: boolean) => void
+  /**
+   * Update the current filters.
+   */
+  updateFilters: (filters: Filters, run?: boolean) => void
+  /**
+   * Open the schedule dialog. This is ignored when running in an explore.
+   */
   openScheduleDialog: () => Promise<void>
 }

packages/extension-sdk/src/connect/visualization/types.ts

@@ -93,34 +93,115 @@ export interface PivotConfig extends RawPivotConfig {
   [key: string]: any
 }
 
+/**
+ * Visualization configuration data.
+ */
 export interface VisualizationConfig {
+  /**
+   * Measure information
+   */
   queryFieldMeasures: Measure[]
+  /**
+   * Dimension information
+   */
   queryFieldDimensions: Dimension[]
+  /**
+   * Table calculation information
+   */
   queryFieldTableCalculations: TableCalculation[]
+  /**
+   * Pivot information
+   */
   queryFieldPivots: PivotConfig[]
+  /**
+   * Visual configuration data. This should be merged with the default
+   * configuration and applied to the visualization rendered by the
+   * extension.
+   */
   visConfig: RawVisConfig
 }
 
 export interface QueryResponse {
+  /**
+   * Row data.
+   */
   data: Row[]
+  /**
+   * Field measure information
+   */
   fieldMeasures: Measure[]
+  /**
+   * Field dimension information
+   */
   fieldDimensions: Dimension[]
+  /**
+   * Field table calculation information
+   */
   fieldTableCalculations: TableCalculation[]
+  /**
+   * Field pivot information
+   */
   fieldPivots: PivotConfig[]
+  /*
+   * A concatenated array of field measure information and table calculations
+   * that behave like measures.
+   */
   fieldMeasureLike: Measure[]
+  /*
+   * A concatenated array of field dimension information and table calculations
+   * that behave like dimensions.
+   */
   fieldDimensionLike: Dimension[]
 }
 
+/**
+ * For internal use only.
+ */
+export interface VisualizationSDKInternal extends VisualizationSDK {
+  updateVisData: (rawVisData: RawVisualizationData) => void
+}
+
 /**
  * Extension visualization SDK
  */
 export interface VisualizationSDK {
+  /**
+   * Visualization (combination of visConfig and queryResponse data)
+   */
   visualizationData?: RawVisualizationData
+  /**
+   * Visualization configuration data.
+   * - measure configurations
+   * - dimension configurations
+   * - table calculations
+   * - pivot configurations
+   * - visualization configurations. These would be used to customize
+   *   the look and feel of a visualization in an explore.
+   */
   visConfig: VisualizationConfig
+  /**
+   * Response data from query.
+   * - row data
+   * - field measures
+   * - field table calculations
+   * - field pivots
+   * - field measure like
+   * - field dimension like
+   */
   queryResponse: QueryResponse
-  updateVisData: (rawVisData: RawVisualizationData) => void
+  /**
+   * Set the default configurations for an extension visualization.
+   * The configurations will be rendered inside of the explore
+   * visualization editor. This should only be called once.
+   */
   configureVisualization: (options: VisOptions) => void
+  /**
+   * Update the visualization configuration.
+   */
   setVisConfig: (config: RawVisConfig) => void
+  /**
+   * Update the query row limit.
+   */
   updateRowLimit: (rowLimit: number) => void
 }
 

packages/extension-sdk/src/connect/visualization/visualization_sdk.ts

@@ -29,7 +29,7 @@ import type { ExtensionHostApiImpl } from '../extension_host_api'
 import { ExtensionRequestType } from '../types'
 import type { Row } from '../tile'
 import type {
-  VisualizationSDK,
+  VisualizationSDKInternal,
   RawVisualizationData,
   RawVisConfig,
   VisualizationConfig,
@@ -114,7 +114,7 @@ class VisualizationConfigImpl implements VisualizationConfig {
   }
 }
 
-export class VisualizationSDKImpl implements VisualizationSDK {
+export class VisualizationSDKImpl implements VisualizationSDKInternal {
   hostApi: ExtensionHostApiImpl
   visualizationData?: RawVisualizationData
   _visConfig?: VisualizationConfigImpl

packages/extension-tile-playground/src/TileExtension.tsx

@@ -51,7 +51,11 @@ export const TileExtension: React.FC = () => {
   const { lookerHostData } = useContext(ExtensionContext40)
 
   return (
-    <ComponentsProvider>
+    <ComponentsProvider
+      themeCustomizations={{
+        colors: { key: '#1A73E8' },
+      }}
+    >
       <Switch>
         <Route path="/inspect">
           <Inspector />

packages/extension-tile-playground/src/components/Inspector/components/EventTester/EventTester.tsx

@@ -45,27 +45,16 @@ export const EventTester: React.FC = () => {
   } = useContext(ExtensionContext40)
   const [runDashboard, setRunDashboard] = useState(false)
 
-  const addErrorsClick = useCallback(() => {
-    tileSDK.addErrors(
-      {
-        title: 'Oh no',
-        message: "I've fallen and I can't get up!",
-        group: 'error_group_1',
-      },
-      {
-        title: 'Oh no',
-        message: 'I pressed the wrong button!',
-        group: 'error_group_2',
-      }
-    )
-  }, [tileSDK])
-
-  const partiallyClearErrorsClick = useCallback(() => {
-    tileSDK.clearErrors('error_group_1')
+  const addErrorClick = useCallback(() => {
+    tileSDK.addError({
+      title: 'Oh no',
+      message: "I've fallen and I can't get up!",
+      group: 'error_group_1',
+    })
   }, [tileSDK])
 
-  const clearAllErrorsClick = useCallback(() => {
-    tileSDK.clearErrors()
+  const clearErrorClick = useCallback(() => {
+    tileSDK.clearError()
   }, [tileSDK])
 
   const toggleCrossFilterClick = useCallback(
@@ -123,24 +112,18 @@ export const EventTester: React.FC = () => {
       <CardContent>
         <Accordion2 label="Event Tester" defaultOpen>
           <Grid columns={2} mt="medium">
-            <ButtonOutline onClick={addErrorsClick} width="100%">
-              Test add errors
-            </ButtonOutline>
-            <ButtonOutline onClick={partiallyClearErrorsClick} width="100%">
-              Test partially clear errors
+            <ButtonOutline onClick={addErrorClick} width="100%">
+              Test add error
             </ButtonOutline>
-            <ButtonOutline onClick={clearAllErrorsClick} width="100%">
-              Test clear all errors
+            <ButtonOutline onClick={clearErrorClick} width="100%">
+              Test clear error
             </ButtonOutline>
             <ButtonOutline onClick={updateRowLimit} width="100%">
               Test Update Row Limit
             </ButtonOutline>
             <ButtonOutline onClick={openDrillMenuClick} width="100%">
               Test open drill menu
             </ButtonOutline>
-            <ButtonOutline onClick={toggleCrossFilterClick} width="100%">
-              Test toggle cross filter
-            </ButtonOutline>
             <ButtonOutline onClick={runDashboardClick} width="100%">
               Test run dashboard
             </ButtonOutline>
@@ -159,6 +142,9 @@ export const EventTester: React.FC = () => {
                 on={runDashboard}
               ></FieldToggleSwitch>
             </Space>
+            <ButtonOutline onClick={toggleCrossFilterClick} width="100%">
+              Test toggle cross filter
+            </ButtonOutline>
             <ButtonOutline onClick={openScheduleDialogClick} width="100%">
               Test open schedule dialog
             </ButtonOutline>