Add help text (#115)

Signed-off-by: Teo Koon Peng <[email protected]>
Signed-off-by: Michael X. Grey <[email protected]>
Co-authored-by: Grey <[email protected]>

Author: koonpeng

diagram-editor/frontend/api.preprocessed.schema.json

@@ -114,6 +114,22 @@
         }
       ]
     },
+    "ConfigExample": {
+      "properties": {
+        "config": {
+          "description": "The value of the config"
+        },
+        "description": {
+          "description": "A description of what this config is for",
+          "type": "string"
+        }
+      },
+      "required": [
+        "description",
+        "config"
+      ],
+      "type": "object"
+    },
     "DebugSessionMessage": {
       "oneOf": [
         {
@@ -780,6 +796,18 @@
           "description": "If the user does not specify a default display text, the node ID will\n be used here.",
           "type": "string"
         },
+        "description": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "example_configs": {
+          "items": {
+            "$ref": "#/$defs/ConfigExample"
+          },
+          "type": "array"
+        },
         "request": {
           "type": "string"
         },
@@ -798,7 +826,8 @@
         "request",
         "response",
         "streams",
-        "config_schema"
+        "config_schema",
+        "example_configs"
       ],
       "type": "object"
     },
@@ -1027,14 +1056,27 @@
         "default_display_text": {
           "type": "string"
         },
+        "description": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "example_configs": {
+          "items": {
+            "$ref": "#/$defs/ConfigExample"
+          },
+          "type": "array"
+        },
         "metadata": {
           "$ref": "#/$defs/SectionMetadata"
         }
       },
       "required": [
         "default_display_text",
         "metadata",
-        "config_schema"
+        "config_schema",
+        "example_configs"
       ],
       "type": "object"
     },

diagram-editor/frontend/forms/node-form.tsx

@@ -1,5 +1,13 @@
-import { Autocomplete, TextField } from '@mui/material';
+import {
+  Autocomplete,
+  Box,
+  ListItem,
+  Stack,
+  TextField,
+  Tooltip,
+} from '@mui/material';
 import { useMemo, useState } from 'react';
+import { MaterialSymbol } from '../nodes';
 import { useRegistry } from '../registry-provider';
 import BaseEditOperationForm, {
   type BaseEditOperationFormProps,
@@ -60,6 +68,25 @@ function NodeForm(props: NodeFormProps) {
         renderInput={(params) => (
           <TextField {...params} required label="Builder" />
         )}
+        renderOption={({ key, ...otherProps }, value) => {
+          const nodeMetadata = registry.nodes[value];
+          return (
+            <ListItem key={key} {...otherProps}>
+              <Stack
+                direction="row"
+                justifyContent="space-between"
+                width="100%"
+              >
+                <span>{value}</span>
+                {nodeMetadata?.description && (
+                  <Tooltip title={nodeMetadata.description}>
+                    <MaterialSymbol symbol="info" />
+                  </Tooltip>
+                )}
+              </Stack>
+            </ListItem>
+          );
+        }}
       />
       <TextField
         multiline

diagram-editor/frontend/nodes/icons.tsx

@@ -9,10 +9,15 @@ export interface MaterialSymbolProps extends BoxProps {
 
 export function MaterialSymbol({
   symbol,
+  className,
   ...otherProps
 }: MaterialSymbolProps): React.JSX.Element {
   return (
-    <Box component="span" className="material-symbols-outlined" {...otherProps}>
+    <Box
+      component="span"
+      className={`material-symbols-outlined ${className}`}
+      {...otherProps}
+    >
       {symbol}
     </Box>
   );

diagram-editor/frontend/types/api.d.ts

@@ -352,6 +352,23 @@ export interface BufferSettings {
   retention: RetentionPolicy;
   [k: string]: unknown;
 }
+/**
+ * This interface was referenced by `DiagramEditorApi`'s JSON-Schema
+ * via the `definition` "ConfigExample".
+ */
+export interface ConfigExample {
+  /**
+   * The value of the config
+   */
+  config: {
+    [k: string]: unknown;
+  };
+  /**
+   * A description of what this config is for
+   */
+  description: string;
+  [k: string]: unknown;
+}
 /**
  * This interface was referenced by `DiagramEditorApi`'s JSON-Schema
  * via the `definition` "Diagram".
@@ -1111,6 +1128,8 @@ export interface NodeRegistration {
    *  be used here.
    */
   default_display_text: string;
+  description?: string | null;
+  example_configs: ConfigExample[];
   request: string;
   response: string;
   streams: {
@@ -1125,6 +1144,8 @@ export interface NodeRegistration {
 export interface SectionRegistration {
   config_schema: Schema;
   default_display_text: string;
+  description?: string | null;
+  example_configs: ConfigExample[];
   metadata: SectionMetadata;
   [k: string]: unknown;
 }

examples/diagram/calculator/diagrams/split_and_join.json

@@ -8,14 +8,16 @@
       "type": "node",
       "builder": "mul",
       "next": "a00aa305-9763-4602-b638-6cb190e6c452",
-      "config": 10
+      "config": 100,
+      "display_text": "x100"
     },
     "fee7f385-2a74-4a87-b8a7-87b8bd03fdf8": {
       "type": "node",
       "builder": "add",
       "next": {
         "builtin": "terminate"
-      }
+      },
+      "display_text": "sum"
     },
     "31fb7423-5300-447a-b259-49c5c79654e7": {
       "type": "join",
@@ -29,7 +31,8 @@
       "type": "node",
       "builder": "mul",
       "next": "305f46be-cf0d-42ac-bd28-26d63746abc3",
-      "config": 100
+      "config": 10,
+      "display_text": "x10"
     },
     "74764679-1f94-49f3-8080-259e57f78be9": {
       "type": "split",