Example asset and transform for async content streaming

core/player/src/view/builder/index.test.ts

@@ -32,6 +32,44 @@ describe("multiNode", () => {
     expect(v1.parent).toBe(result);
     expect(v2.parent).toBe(result);
   });
+
+  test("multinode with async node", () => {
+    const v1 = Builder.asyncNode("1");
+    const v2 = Builder.asyncNode("2");
+    const result = Builder.multiNode(v1, v2);
+
+    expect(result.type).toBe(NodeType.MultiNode);
+    expect(result.values[0]?.type).toBe("async");
+    expect(result.values[1]?.type).toBe("async");
+    expect(v1.parent).toBe(result);
+    expect(v2.parent).toBe(result);
+  });
+});
+
+test("async node", () => {
+  const result = Builder.asyncNode("1", false);
+  expect(result.type).toBe(NodeType.Async);
+  expect(result.id).toBe("1");
+  expect(result.flatten).toBe(false);
+
+  const result2 = Builder.asyncNode("2");
+  expect(result2.type).toBe(NodeType.Async);
+  expect(result2.id).toBe("2");
+  expect(result2.flatten).toBe(true);
+});
+
+test("asset wrapper", () => {
+  const result = Builder.assetWrapper({
+    type: NodeType.Asset,
+    value: {
+      id: "1",
+      type: "text",
+      value: "chat message",
+    },
+  });
+
+  expect(result.type).toBe(NodeType.Value);
+  expect(result.children?.[0]?.value.type).toBe("asset");
 });
 
 describe("addChild", () => {

core/player/src/view/builder/index.ts

@@ -17,6 +17,12 @@ export class Builder {
     };
   }
 
+  static assetWrapper<T extends Node.Node>(value: T): Node.Value {
+    const valueNode = Builder.value();
+    Builder.addChild(valueNode, "asset", value);
+    return valueNode;
+  }
+
   /**
    * Creates a value node
    *
@@ -33,10 +39,10 @@ export class Builder {
    * Creates a multiNode and associates the multiNode as the parent
    * of all the value nodes
    *
-   * @param values - the value or applicability nodes to put in the multinode
+   * @param values - the value, applicability or async nodes to put in the multinode
    */
   static multiNode(
-    ...values: (Node.Value | Node.Applicability)[]
+    ...values: (Node.Value | Node.Applicability | Node.Async)[]
   ): Node.MultiNode {
     const m: Node.MultiNode = {
       type: NodeType.MultiNode,
@@ -52,6 +58,25 @@ export class Builder {
     return m;
   }
 
+  /**
+   * Creates an async node
+   *
+   * @param id - the id of async node. It should be identical for each async node
+   */
+  static asyncNode(id: string, flatten = true): Node.Async {
+    return {
+      id,
+      type: NodeType.Async,
+      flatten: flatten,
+      value: {
+        type: NodeType.Value,
+        value: {
+          id,
+        },
+      },
+    };
+  }
+
   /**
    * Adds a child node to a node
    *

core/player/src/view/parser/types.ts

@@ -116,6 +116,10 @@ export declare namespace Node {
     id: string;
     /** The value representing the node */
     value: Node;
+    /**
+     * Should the content streamed in be flattened during resolving
+     */
+    flatten?: boolean;
   }
 
   export interface PluginOptions {

core/player/src/view/resolver/index.ts

@@ -12,7 +12,11 @@ import { DependencyModel, withParser } from "../../data";
 import type { Logger } from "../../logger";
 import type { Node } from "../parser";
 import { NodeType } from "../parser";
-import { caresAboutDataChanges, toNodeResolveOptions } from "./utils";
+import {
+  caresAboutDataChanges,
+  toNodeResolveOptions,
+  unpackAndPush,
+} from "./utils";
 import type { Resolve } from "./types";
 import { getNodeID } from "../parser/utils";
 
@@ -163,7 +167,6 @@ export class Resolver {
     );
     this.resolveCache = resolveCache;
     this.hooks.afterUpdate.call(updated.value);
-
     return updated.value;
   }
 
@@ -408,7 +411,24 @@ export class Resolver {
         );
 
         if (mTree.value !== undefined && mTree.value !== null) {
-          childValue.push(mTree.value);
+          /**
+           * async nodes' parent is a multi-node
+           * When the node to resolve is an async node and the flatten flag is true
+           * Add the content streamed in to the childValue of parent multi-node
+           * Array.isArray(mTree.value.asset.values) is the case when the content is an async asset
+           */
+          if (
+            mValue.type === NodeType.Async &&
+            mValue.flatten &&
+            mTree.value.asset &&
+            Array.isArray(mTree.value.asset.values)
+          ) {
+            mTree.value.asset.values.forEach((v: any) => {
+              unpackAndPush(v, childValue);
+            });
+          } else {
+            childValue.push(mTree.value);
+          }
         }
 
         mTree.dependencies.forEach((bindingDep) =>

docs/site/src/content/docs/plugins/multiplatform/async-node.mdx

@@ -7,28 +7,59 @@ import PlatformTabs from "../../../../components/PlatformTabs.astro";
 The AsyncNode Plugin is used to enable streaming additional content into a flow that has already been loaded and rendered.  
 A common use case for this plugin is conversational UI, as the users input more dialogue, new content must be streamed into Player in order to keep the UI up to date.
 
-The pillar that makes this possible is the concept of an `AsyncNode`. An `AsyncNode` is any tree node with the property `async: true`, it represents a placeholder node that will be replaced by a concrete node in the future.
+The pillar that makes this possible is the concept of an `AsyncNode`. An `AsyncNode` is any tree node with the property `async: true`, it represents a placeholder node that will be replaced by a concrete node in the future. `AsyncNode` is added to the AST tree during asset transform process(You can read more about what transform is [here](/assets/transforms)). In the example below, it shows the content and resolved result. 
 
-In the example below, node with the id "some-async-node" will not be rendered on first render, but will be replaced with a UI asset node at a later time:
+#### Content authoring:
 
+Value of `chat-message` is the asset to render
+- JSON content
 ```json
-{
-  "id": "flow-1",
-    "views": [
       {
-        "id": 'action',
-        "actions": [
-          {
-            "id": "some-async-node",
-            "async": true,
+        "id": "chat-1",
+        "type": "chat-message",
+        "value": {
+          "id": "text-1",
+          "type": "text",
+          "value": "chat message",
+        },
+      },
+```
+- DSL
+```typescript
+  <ChatMessage id="chat">
+    <ChatMessage.Value>
+      <Text>Hello World!</Text>
+    </ChatMessage.Value>
+  </ChatMessage>
+```
+
+#### Resolved
+
+`chat-message` asset is wrapped into a wrapper container with children including the `Text` asset in value and an `AsyncNode` in the associated asset transform before resolving. 
+```json
+    {
+      "id": "collection-async-chat-1",
+      "type": "collection",
+      "values": [
+        {
+          "asset": {
+            "id": "1",
+            "type": "text",
+            "value": "chat message",
           },
-        ],
+        },
+      ],
+    }
+```
+If there is no asset to display, there will be only one `AsyncNode` in resolved result and no content will be rendered.
+```json
+      {
+        "id": "chat-1",
+        "type": "chat-message",
       },
-    ],
-  ...
-}
 ```
 
+
 The `AsyncNodePlugin` exposes an `onAsyncNode` hook on all platforms. The `onAsyncNode` hook will be invoked with the current node when the plugin is available and an `AsyncNode` is detected during the resolve process. The node used to call the hook with could contain metadata according to content spec.
 
 User should tap into the `onAsyncNode` hook to examine the node's metadata before making a decision on what to replace the async node with. The return could be a single asset node or an array of asset nodes, or the return could be even a null|undefined if the async node is no longer relevant.
@@ -218,3 +249,26 @@ AndroidPlayer(asyncNodePlugin)
 
   </Fragment>
 </PlatformTabs>
+
+
+### AsyncTransform function
+`AsyncTransform` is a helper function to create the transform for async asset. With the example below, 
+- id - `chat-message` asset id
+- asset - value asset to pass in
+- wrapperType - container asset type eg. `Collection`
+- flatte - default value is true. Determine if the content streamed in should be flattened. 
+
+```json
+      {
+        "id": "chat",
+        "type": "chat-message",
+        "value": {
+          "id": "text",
+          "type": "text",
+          "value": "chat message",
+        },
+      },
+```
+
+### Flatten
+Flatten is introduced to avoid nested structure caused by continuous streamning. eg. When a new `chat-message` asset is streamed in, in AST tree, instead of `[chat1, [chat2, asyncNode]]`, it's flattened into `[chat1, chat2, asyncNode]`

docs/storybook/src/reference-assets/ChatMessage.mdx

@@ -0,0 +1,9 @@
+import * as ChatMessageStories from "./ChatMessage.stories";
+
+# ChatMessage Asset
+
+The `ChatMessage` asset is used as an example to demostrate the async streaming feature.
+
+## Basic Use Case
+
+The example below shows the basic usage of async node. Transform the `ChatMessage` asset and render the `text` asset with given value

docs/storybook/src/reference-assets/ChatMessage.stories.tsx

@@ -0,0 +1,15 @@
+import { createDSLStory } from "@player-ui/storybook";
+import { Meta } from "@storybook/react";
+
+const meta: Meta = {
+  title: "Reference Assets/ChatMessage",
+};
+
+export default meta;
+
+export const Basic = createDSLStory(
+  () =>
+    import(
+      "!!raw-loader!@player-ui/mocks/chat-message/chat-message-basic.tsx"
+    ),
+);

ios/demo/Sources/MockFlows.swift

@@ -1398,6 +1398,43 @@ static let inputAssetPendingTransaction: String = """
   }
 }
 """
+
+static let chatMessageBasic: String = """
+    {
+      "id": "chat",
+      "views": [
+          {
+          "id": "1",
+          "type": "chat-message",
+          "value": {
+            "asset":{
+                "id": "text",
+                "type": "text",
+                "value": "chat message",
+              },
+            },
+          },
+      ],
+      "navigation": {
+          "BEGIN": "FLOW_1",
+          "FLOW_1": {
+          "startState": "VIEW_1",
+          "VIEW_1": {
+              "state_type": "VIEW",
+              "ref": "1",
+              "transitions": {
+              "*": "END_Done"
+              }
+          },
+          "END_Done": {
+              "state_type": "END",
+              "outcome": "DONE"
+          }
+        }
+      }
+    }
+
+    """
 
     public static let assetSections: [FlowLoader.FlowSection] = [
         (title: "action", flows: [
@@ -1429,6 +1466,9 @@ static let inputAssetPendingTransaction: String = """
         (title: "text", flows: [
             (name: "basic", flow: MockFlows.textBasic),
             (name: "with link", flow: MockFlows.textWithLink)
+        ]),
+        (title: "chat message", flows: [
+            (name: "basic", flow: MockFlows.chatMessageBasic),
         ])
     ]
 

plugins/async-node/core/BUILD

@@ -20,4 +20,8 @@ js_pipeline(
         "//:node_modules/tapable-ts",
         "//:node_modules/timm",
     ],
+    test_deps = [
+        ":node_modules/@player-ui/reference-assets-plugin",
+        "//:vitest_config",
+    ]
 )

plugins/async-node/core/package.json

@@ -4,6 +4,9 @@
     "main": "src/index.ts",
     "peerDependencies": {
       "@player-ui/player": "workspace:*"
+    },
+    "devDependencies": {
+      "@player-ui/reference-assets-plugin": "workspace:*"
     }
   }