Adjust snaps insights documentation (MetaMask#616)

* fix: adjust snaps insights documentation Transaction insights is now using Custom UI for its output * fix: kick ci * fix: autofix lint errors * feat: add documentation on Snaps Custom UI * fix: remove "soon" tag on Custom UI * fix: link Custom UI text to relevant concept * Update docs/guide/snaps-concepts.md Co-authored-by: legobeat <[email protected]> * improve insights and Custom UI docs * Update docs/guide/snaps-exports.md Co-authored-by: Maarten Zuidhoorn <[email protected]> * Update docs/guide/snaps-exports.md Co-authored-by: Maarten Zuidhoorn <[email protected]> * Update docs/guide/snaps-exports.md Co-authored-by: Maarten Zuidhoorn <[email protected]> * Update docs/guide/snaps-exports.md Co-authored-by: Maarten Zuidhoorn <[email protected]> * Update docs/guide/snaps-exports.md Co-authored-by: Frederik Bolding <[email protected]> --------- Co-authored-by: legobeat <[email protected]> Co-authored-by: Maarten Zuidhoorn <[email protected]> Co-authored-by: Frederik Bolding <[email protected]>
readyalid · Feb 16, 2023 · 111ccaa · 111ccaa
1 parent e4a619e
commit 111ccaa
Show file tree

Hide file tree

Showing 4 changed files with 172 additions and 7 deletions.
diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
@@ -176,6 +176,7 @@ const guideSidebar = [
       'snaps-permissions',
       'snaps-exports',
       'snaps-patching-dependencies',
+      'snaps-concepts',
     ],
   },
   {

diff --git a/docs/guide/snaps-concepts.md b/docs/guide/snaps-concepts.md
@@ -0,0 +1,147 @@
+# Concepts
+
+[[toc]]
+
+## Custom UI
+
+### Introduction
+
+Custom UI is a UI definition system used by various Snaps features. It enables Snaps to describe a rich UI to be displayed in some contexts.
+
+Custom UI is used to describe custom user interfaces in [`snap_dialog`](./snaps-rpc-api.html#snap-dialog), and in the [`onTransaction` export](./snaps-exports.html#ontransaction).
+
+### How to use it
+
+To use Custom UI, you must first install the `@metamask/snaps-ui` NPM package:
+
+```sh
+yarn add @metamask/snaps-ui
+```
+
+Then, whenever you're required to return a Custom UI, import the components you need from the package, and build your UI with them. For example:
+
+```javascript
+import { panel, heading, text } from '@metamask/snaps-ui';
+
+// ...
+
+const content = panel([
+  heading('Alert heading'),
+  text('Something happened in the system.'),
+]);
+
+return content;
+```
+
+### Components
+
+The `NodeType` enum exported by `@metamask/snaps-ui` details the available components.
+
+#### `Copyable`
+
+##### Description
+
+Outputs a read-only text field with a copy-to-clipboard shortcut.
+
+##### Usage
+
+```javascript
+import { copyable } from '@metamask/snaps-ui';
+
+// ...
+
+const content = copyable('Text to be copied');
+```
+
+#### `Divider`
+
+##### Description
+
+Outputs a horizontal divider.
+
+##### Usage
+
+```javascript
+import { panel, divider, text } from '@metamask/snaps-ui';
+
+// ...
+
+const content = panel([
+  text('Text before the divider'),
+  divider(),
+  text('Text after the divider'),
+]);
+```
+
+#### `Heading`
+
+##### Description
+
+Outputs a heading. Useful for panel titles.
+
+##### Usage
+
+```javascript
+import { panel, heading, text } from '@metamask/snaps-ui';
+
+// ...
+
+const content = panel([
+  heading('Title of the panel'),
+  text('Text of the panel'),
+]);
+```
+
+#### `Panel`
+
+##### Description
+
+Outputs a panel, which can be used as a container for other components.
+
+##### Usage
+
+```javascript
+import { panel, heading, text } from '@metamask/snaps-ui';
+
+// ...
+
+const insights = [
+  /*...*/
+];
+const content = panel([
+  heading('Here are the transaction insights'),
+  ...insights.map((insight) => text(insight.description)),
+]);
+```
+
+#### `Spinner`
+
+##### Description
+
+Outputs a loading indicator.
+
+##### Usage
+
+```javascript
+import { panel, heading, spinner } from '@metamask/snaps-ui';
+
+// ...
+
+const content = panel([heading('Please wait...'), spinner()]);
+```
+
+#### `Text`
+
+##### Description
+
+Outputs text.
+
+##### Usage
+
+```javascript
+import { text } from '@metamask/snaps-ui';
+
+// ...
+
+const content = text('This is a simple text UI');
+```
diff --git a/docs/guide/snaps-exports.md b/docs/guide/snaps-exports.md
@@ -107,42 +107,59 @@ The `transactionOrigin` property is only passed to `onTransaction` if `allowTran
 ### Returns
 
 ```typescript
+import { Component } from '@metamask/snaps-ui';
+
 type OnTransactionHandlerReturn = Promise<OnTransactionResponse>;
 
 interface OnTransactionResponse {
-  insights: { [key: string]: unknown };
+  content: Component;
 }
 ```
 
-- `onTransactionResponse` - The `insights` object returned by the snap will be displayed alongside the confirmation for the transaction that `onTransaction` was called with. Keys and values will be displayed in the order received, with each key rendered as a title and each value rendered as a string.
+- `onTransactionResponse` - The `content` object returned by the snap will be displayed using [Custom UI](./snaps-concepts.html#custom-ui) alongside the confirmation for the transaction that `onTransaction` was called with.
 
 ### Examples
 
 #### Typescript
 
 ```typescript
-import { OnTransactionHandler } from "@metamask/snap-types";
+import { OnTransactionHandler } from '@metamask/snap-types';
+import { panel, heading, text } from '@metamask/snaps-ui';
 
 export const onTransaction: OnTransactionHandler = async ({
   transactionOrigin
   transaction,
   chainId,
 }) => {
   const insights = /* Get insights */;
-  return { insights };
+  return {
+    content: panel([
+      heading('My Transaction Insights'),
+      text('Here are the insights:'),
+      ...(insights.map((insight) => text(insight.value)))
+    ])
+  };
 };
 ```
 
 #### Javascript
 
 ```js
+import { panel, heading, text } from '@metamask/snaps-ui';
+
 module.exports.onTransaction = async ({
   transactionOrigin
   transaction,
   chainId,
 }) => {
   const insights = /* Get insights */;
-  return { insights };
+  return {
+    content: panel([
+      heading('My Transaction Insights'),
+      text('Here are the insights:'),
+      ...(insights.map((insight) => text(insight.value)))
+    ])
+  };
 };
 ```
 

diff --git a/docs/guide/snaps.md b/docs/guide/snaps.md
@@ -65,11 +65,11 @@ Bring your insights, anti-phishing, and security solutions to the MetaMask UI wi
 
 Perform actions that run periodically at fixed times, dates, or intervals.
 
-<img src="../assets/soon.png" alt="Coming soon" style="width: 106px; position: relative; top: 20px;" />
+<img src="../assets/flask.png" alt="Live in MetaMask Flask" style="width: 171px; position: relative;top: 20px;" />
 
 #### Custom UI in MetaMask using a defined set of components
 
-Display custom UI within MetaMask using a set of pre-defined components, including Markdown, form controls, and images. This custom UI can include actionable controls for dynamic interfaces that respond to user input.
+Display [Custom UI](./snaps-concepts.html#custom-ui) within MetaMask using a set of pre-defined components, including inline Markdown.
 
 ### Propose a feature