refactor(webview): improve ergonomics (#2644)

Author: JadenSimon

.prettierignore

@@ -5,4 +5,3 @@ CHANGELOG.md
 src/shared/telemetry/service-2.json
 .changes
 src/testFixtures/**
-resources/markdown/samReadme.md

docs/ARCHITECTURE.md

@@ -17,9 +17,9 @@ Be very mindful about state managment; violating these principles will lead to b
 
 ### Bundling
 
-Each webview is bundled into a single file to speed up load times as well as isolate the 'web' modules from the 'node' modules. Webview bundles are automatically generated on compilation by targeting `entry.ts` files when located under a `vue` directory. All bundles are placed directly under `dist`.
+Each webview is bundled into a single file to speed up load times as well as isolate the 'web' modules from the 'node' modules. Webview bundles are automatically generated on compilation by targeting `index.ts` files when located under a `vue` directory. All bundles are placed under `dist` in the same relative location.
 
-Generated bundle names map based off their path relative to `src`: `src/foo/vue/bar/entry.ts` -> `fooBarVue.js`
+Generated bundle names map based off their path relative to `src`: `src/foo/vue/bar/index.ts` -> `dist/src/foo/vue/bar/index.js`
 
 Running the extension in development mode (e.g. via the `Extension` launch task) starts a local server to automatically rebuild and serve webviews in real-time via hot-module reloading. It's assumed that the server runs on port `8080`, so make sure that nothing is already using that port. Otherwise webviews will not be displayed during development.
 
@@ -29,37 +29,41 @@ The VS Code API restricts our Webviews to a single `postMessage` function. To si
 
 Webview (frontend) clients can be created via `WebviewClientFactory`. This generates a simple Proxy to send messages to the extension, mapping the function name to the command name. Unique IDs are also generated to stop requests from receiving extraneous responses. It is **highly** recommended to use the [Volar](https://marketplace.visualstudio.com/items?itemName=johnsoncodehk.volar) extension for syntax highlighting and type-checking when working with SFCs. Keep in mind that this is purely a development tool: users of the toolkits do not require Volar to view webviews.
 
-Commands and events are defined on the backend via `compileVueWebview` or `compileVueWebviewView` for the special 'view' case. This takes a configuration object that contains information about the webview, such as the name of the main script, the panel id, and the commands/events that the backend provides. This returns a class that can be instantiated into the webview. Webviews can then be executed by calling `start` with any initial data (if applicable). Webviews can be cleared of their internal state without reloading the HTML by calling `clear` with any re-initialization data (if applicable).
+Commands and events are defined on the backend via sub-classes of `VueWebview`. Classes define all the functions and events that will be available to the frontend. These sub-classes can be turned into a fully-resolved class by using either `VueWeview.compilePanel` or `VueWebview.compileView`. The resulting classes can finally be used to instantiate webview panels or view. Panels are shown by calling `show`, while views must be registered before they can be seen.
 
 ### Examples
 
 -   Creating and executing a webview:
 
     ```ts
-    const VueWebview = compileVueWebview({
-        id: 'my.view',
-        title: 'A title',
-        webviewJs: 'myView.js',
-        start: (param?: string) => param ?? 'foo',
-        events: {
-            onBar: new vscode.EventEmitter<number>(),
-        },
-        commands: {
-            foo: () => 'hello!',
-            bar() {
-                // All commands have access to `WebviewServer` via `this`
-                this.emiters.onBar.fire(0)
-            },
-        },
-    })
+    // Export the class so the frontend code can use it for types
+    export class MyVueWebview extends VueWebview {
+        public readonly id = 'my.view'
+        public readonly source = 'myView.js'
+        public readonly onBar = new vscode.EventEmitter<number>()
 
-    // `context` is `ExtContext` provided on activation
-    const view = new VueWebview(context)
-    view.start('some data')
-    view.emitters.onFoo.fire(1)
+        public constructor(private readonly myData: string) {}
+
+        public init() {
+            return this.myData
+        }
 
-    // Export a class so the frontend code can use it for types
-    export class MyView extends VueWebview {}
+        public foo() {
+            return 'foo'
+        }
+
+        public bar() {
+            this.onBar.fire(0)
+        }
+    }
+
+    // Create panel bindings using our class
+    const Panel = VueWebview.compilePanel(MyVueWebview)
+
+    // `context` is `ExtContext` provided on activation
+    const view = new Panel(context, 'hello')
+    view.show({ title: 'My title' })
+    view.server.onFoo.fire(1)
     ```
 
 -   Creating the client on the frontend:
@@ -86,22 +90,12 @@ Commands and events are defined on the backend via `compileVueWebview` or `compi
     client.onBar(num => console.log(num))
     ```
 
--   Retrieving initialization data by calling the `init` method:
+-   Methods called `init` will only return data on the initial webview load:
 
     ```ts
-    client.init(data => console.log(data))
+    client.init(data => (this.data = data ?? this.data))
     ```
 
-    Note that data is retrieved only **once**. Subsequent calls made by the same webview resolve `undefined` unless the state is cleared either by `clear` or refreshing the view.
-
--   Submitting a result (this destroys the view on success):
-
-    ```ts
-    client.submit(result).catch(err => console.error('Something went wrong!'))
-    ```
-
-    `submit` does nothing on views registered as a `WebviewView` as they cannot be disposed of by the extension.
-
 ### Testing
 
 Currently only manual testing is done. Future work will include setting up some basic unit testing capacity via `JSDOM` and `Vue Testing Library`. Strict type-checking may also be enforced on SFCs; currently the type-checking only exists locally due to gaps in the type definitions for the DOM provided by Vue/TypeScript.

resources/markdown/samReadme.md

@@ -19,7 +19,7 @@ ${COMPANYNAME} Lambda functions not defined in the [`template.yaml`](./template.
 
 ## Deploying Serverless Applications
 
-You can deploy a serverless application by invoking the `AWS: Deploy SAM application` command through the Command Palette or by right-clicking the Lambda node in the ${COMPANYNAME} Explorer and entering the deployment region, a valid S3 bucket from the region, and the name of a CloudFormation stack to deploy to. You can monitor your deployment's progress through the **${COMPANYNAME} Toolkit** Output Channel.
+You can deploy a serverless application by invoking the `AWS: Deploy SAM application` command through the Command Palette or by right-clicking the Lambda node in the ${COMPANYNAME} Explorer and entering the deployment region, a valid S3 bucket from the region, and the name of a CloudFormation stack to deploy to. You can monitor your deployment's progress through the `${COMPANYNAME} Toolkit` Output Channel.
 
 ## Interacting With Deployed Serverless Applications
 

src/apigateway/activation.ts

@@ -5,7 +5,7 @@
 
 import * as vscode from 'vscode'
 import { RestApiNode } from './explorer/apiNodes'
-import { invokeRemoteRestApi } from './commands/invokeRemoteRestApi'
+import { invokeRemoteRestApi } from './vue/invokeRemoteRestApi'
 import { copyUrlCommand } from './commands/copyUrl'
 import { ExtContext } from '../shared/extensions'
 

src/apigateway/vue/entry.ts renamed to src/apigateway/vue/index.ts

@@ -34,7 +34,7 @@
         <br />
         <textarea rows="20" cols="90" v-model="jsonInput"></textarea>
         <br />
-        <input type="submit" v-on:click="sendInput" value="Invoke" :disabled="isLoading" />
+        <button class="mt-16 mb-16" @click="sendInput" :disabled="isLoading">{{ invokeText }}</button>
         <br />
         <div v-if="errors.length">
             <b>Please correct the following error(s):</b>
@@ -49,7 +49,7 @@
 import { defineComponent } from 'vue'
 import { WebviewClientFactory } from '../../webviews/client'
 import saveData from '../../webviews/mixins/saveData'
-import { InvokeRemoteRestApiInitialData, RemoteRestInvokeWebview } from '../commands/invokeRemoteRestApi'
+import { InvokeRemoteRestApiInitialData, RemoteRestInvokeWebview } from './invokeRemoteRestApi'
 
 const client = WebviewClientFactory.create<RemoteRestInvokeWebview>()
 
@@ -71,7 +71,7 @@ export default defineComponent({
         initialData: defaultInitialData,
         selectedApiResource: '',
         selectedMethod: '',
-        methods: [],
+        methods: [] as string[],
         jsonInput: '',
         queryString: '',
         errors: [] as string[],
@@ -80,35 +80,11 @@ export default defineComponent({
     async created() {
         this.initialData = (await client.init()) ?? this.initialData
     },
-    mounted() {
-        this.$nextTick(function () {
-            window.addEventListener('message', this.handleMessageReceived)
-        })
-    },
     methods: {
-        handleMessageReceived: function (event: any) {
-            const message = event.data
-            switch (message.command) {
-                case 'setMethods':
-                    this.methods = message.methods
-                    if (this.methods) {
-                        this.selectedMethod = this.methods[0]
-                    }
-                    break
-                case 'invokeApiStarted':
-                    this.isLoading = true
-                    break
-                case 'invokeApiFinished':
-                    this.isLoading = false
-                    break
-            }
-        },
-        setApiResource: function () {
-            client.handler({
-                command: 'apiResourceSelected',
-                resource: this.initialData.Resources[this.selectedApiResource],
-                region: this.initialData.Region,
-            })
+        setApiResource: async function () {
+            const methods = await client.listValidMethods(this.initialData.Resources[this.selectedApiResource])
+            this.methods = methods
+            this.selectedMethod = methods[0]
         },
         sendInput: function () {
             this.errors = []
@@ -122,15 +98,22 @@ export default defineComponent({
                 return
             }
 
-            client.handler({
-                command: 'invokeApi',
-                body: this.jsonInput,
-                api: this.initialData.ApiId,
-                selectedApiResource: this.initialData.Resources[this.selectedApiResource],
-                selectedMethod: this.selectedMethod,
-                queryString: this.queryString,
-                region: this.initialData.Region,
-            })
+            this.isLoading = true
+            client
+                .invokeApi({
+                    body: this.jsonInput,
+                    api: this.initialData.ApiId,
+                    selectedApiResource: this.initialData.Resources[this.selectedApiResource],
+                    selectedMethod: this.selectedMethod,
+                    queryString: this.queryString,
+                    region: this.initialData.Region,
+                })
+                .finally(() => (this.isLoading = false))
+        },
+    },
+    computed: {
+        invokeText() {
+            return this.isLoading ? 'Invoking...' : 'Invoke'
         },
     },
 })