@powerhousedao/academy 0.1.0-dev.0

package/docs/academy/02-AdvancedTutorial/01-Create/02-MoreTutorials/Chatroom/04-ImplementOperationReducers.md

@@ -0,0 +1,364 @@
+
+# Implement Operation Reducers
+
+In this section, we will implement and test the operation reducers for the `ChatRoom` document model. In order to do this, you have to export the document model from the Connect application and import it into your powerhouse project directory. 
+
+To export the document model, follow the steps in the `Define Chatroom Document Model` section.
+
+## Import Document Model and Generate Code
+
+To import the document model into your powerhouse project, you can either:
+ 
+- Copy&Paste the file directly into the root of your powerhouse project.
+- Or drag&drop the file into the powerhouse project directory in the VSCode editor as seen in the image below:
+
+Either step will import the document model into your powerhouse project.
+
+![vscode image](image-4.png)
+
+The next steps will take place in the VSCode editor. Make sure to have it open and the terminal window inside vscode open as well. 
+
+
+To write the opearation reducers of the `ChatRoom` document model, you need to generate the document model code from the document model file you have exported into the powerhouse project directory.
+
+To do this, run the following command in the terminal:
+
+```bash
+ph generate ChatRoom.phdm.zip
+```
+You will see that this action created a range of files for you. Before diving in we'll look at this simple schema to make you familiar with the structure you've defined in the document model once more. It shows how each type is connected to the next one.
+ 
+![Chatroom-demo Schema](image.png)
+
+Now you can navigate to `/document-models/chat-room/src/reducers/general-operations.ts` and start writing the operation reducers.
+
+Open the `general-operations.ts` file and you should see the code that needs to be filled for the five operations you have defined earlier. Image below shows the code that needs to be filled:
+
+![chatroom ts file](image-5.png)
+
+## Write the Operation Reducers
+
+1. Copy&paste the code below into the `general-operations.ts` file in the `reducers` folder.
+2. Save the `general-operations.ts` file.
+
+
+```typescript
+/**
+ * This is a scaffold file meant for customization:
+ * - modify it by implementing the reducer functions
+ * - delete the file and run the code generator again to have it reset
+ */
+
+import { ChatRoomAddMessageOperations } from "../../gen/add-message/operations";
+import { MessageContentCannotBeEmpty } from "../../gen/add-message/error";
+
+export const reducer: ChatRoomAddMessageOperations = {
+  addMessageOperation(state, action, dispatch) {
+    if (action.input.content === "") {
+      throw new MessageContentCannotBeEmpty();      // Your reducer exception is used here as a custom error.
+    }
+
+    state.messages.push({
+      id: action.input.messageId,
+      content: action.input.content,
+      sender: action.input.sender,
+      sentAt: action.input.sentAt,
+      reactions: [],
+    });
+  },
+  addEmojiReactionOperation(state, action, dispatch) {
+    const message = state.messages.find(
+      (message) => message.id === action.input.messageId,    // the reducer checks the existence of the message you want to react to.
+    );
+
+    if (!message) {
+      throw new Error("Message not found");        
+    }
+
+    const reactions = message.reactions || [];
+
+    const existingReaction = reactions.find(
+      (reaction) => reaction.type === action.input.type,
+    );
+
+    if (existingReaction) {                                  // if the message reaction exists a new reactedBy gets added.
+      message.reactions = reactions.map((reaction) => {
+        if (reaction.type === action.input.type) {
+          return {
+            ...reaction,
+            reactedBy: [...reaction.reactedBy, action.input.reactedBy],
+          };
+        }
+
+        return reaction;
+      });
+    } else {
+      message.reactions = [
+        ...reactions,
+        {
+          reactedBy: [action.input.reactedBy],      // if the message reaction doesn't exist yet a new reaction gets created
+          type: action.input.type,
+        },
+      ];
+    }
+
+    state.messages = state.messages.map((_message) => {      // the state of the chatroom documents messages gets updated
+      if (_message.id === message.id) {
+        return message;
+      }
+
+      return _message;
+    });
+  },
+  removeEmojiReactionOperation(state, action, dispatch) {   // To remove a reaction the address is removed from the reactedBy object in the reactions type. 
+    state.messages = state.messages.map((message) => {
+      if (message.id === action.input.messageId) {
+        message.reactions = (message.reactions || []).map((reaction) => {
+          if (reaction.type === action.input.type) {
+            return {
+              ...reaction,
+              reactedBy: reaction.reactedBy.filter(
+                (reactedBy) => reactedBy !== action.input.senderId,     // We're removing the sender of the reaction from the the reactedBy object
+              ),
+            };
+          }
+
+          return reaction;
+        });
+      }
+
+      return message;       // We're updating the document state with our changes 
+    });
+  },
+  editChatNameOperation(state, action, dispatch) {
+    state.name = action.input.name || "";
+  },
+  editChatDescriptionOperation(state, action, dispatch) {
+    state.description = action.input.description || "";
+  },
+};
+```
+
+## Write the Operation Reducers Tests
+
+In order to make sure the operation reducers are working as expected before implementing an editor interface, you need to write tests for them.
+
+The auto generated test will only validate if an action or message in our case is included but will not verify if the reducer mutation is succesfull. This is the type of test you'll have to write as a developer. 
+
+Navigate to `/document-models/chat-room/src/tests/general-operations.test.ts` and copy&paste the code below into the file. Save the file.
+
+Here are the tests for the five operations written in the reducers file. 
+
+```typescript
+/**
+ * This is a scaffold file meant for customization:
+ * - change it by adding new tests or modifying the existing ones
+ */
+
+import { generateMock } from "@powerhousedao/codegen";
+import { utils as documentModelUtils } from "document-model/document";
+
+import utils from "../../gen/utils";
+import {
+  z,
+  AddMessageInput,
+  AddEmojiReactionInput,
+  RemoveEmojiReactionInput,
+  EditChatNameInput,
+  EditChatDescriptionInput,
+} from "../../gen/schema";
+import { reducer } from "../../gen/reducer";
+import * as creators from "../../gen/add-message/creators";
+import { ChatRoomDocument } from "../../gen/types";
+
+describe("AddMessage Operations", () => {
+  let document: ChatRoomDocument;
+
+  beforeEach(() => {
+    document = utils.createDocument();
+  });
+
+  const addMessage = (): [ChatRoomDocument, AddMessageInput] => {           // This is a helper function for our upcoming test
+    const input: AddMessageInput = {
+      content: "Hello, World!",
+      messageId: documentModelUtils.hashKey(),
+      sender: {
+        id: "anon-user",
+        name: null,
+        avatarUrl: null,
+      },
+      sentAt: new Date().toISOString(),
+    };
+
+    const updatedDocument = reducer(document, creators.addMessage(input));
+
+    return [updatedDocument, input];
+  };
+
+  it("should handle addMessage operation", () => {                          
+    const [updatedDocument, input] = addMessage();
+
+    expect(updatedDocument.operations.global).toHaveLength(1);              // We're validating that the message is being added to the operations history 
+    expect(updatedDocument.operations.global[0].type).toBe("ADD_MESSAGE");
+    expect(updatedDocument.operations.global[0].input).toStrictEqual(input);
+    expect(updatedDocument.operations.global[0].index).toEqual(0);
+    
+    expect(updatedDocument.state.global.messages).toHaveLength(1);          // We're validating that the message is present in the message state of the document
+    expect(updatedDocument.state.global.messages[0]).toMatchObject({
+      id: input.messageId,
+      content: input.content,
+      sender: input.sender,
+      sentAt: input.sentAt,
+      reactions: [],                                                         // We also want to make sure that reaction object is an empty array 
+    });
+  });
+
+  it("should handle addEmojiReaction operation", () => {                     // We're validating that we can react using an emoji with a helper function
+    const [doc, addMessageInput] = addMessage();                            
+
+    let updatedDocument = doc;
+
+    const addEmojiReactionInput: AddEmojiReactionInput = {
+      messageId: addMessageInput.messageId,
+      reactedBy: "anon-user",
+      type: "THUMBS_UP",
+    };
+
+    updatedDocument = reducer(
+      updatedDocument,
+      creators.addEmojiReaction(addEmojiReactionInput),
+    );
+
+    expect(updatedDocument.operations.global).toHaveLength(2);          // We're validating that the emoji reaction is added to the operation history of the doc. 
+    expect(updatedDocument.operations.global[1].type).toBe(
+      "ADD_EMOJI_REACTION",
+    );
+    expect(updatedDocument.operations.global[1].input).toStrictEqual(
+      addEmojiReactionInput,
+    );
+    expect(updatedDocument.operations.global[1].index).toEqual(1);
+
+    expect(updatedDocument.state.global.messages[0].reactions).toHaveLength(1);     // We're validating that the message we created has only one reaction
+    expect(
+      updatedDocument.state.global.messages[0].reactions?.[0],
+    ).toMatchObject({
+      reactedBy: [addEmojiReactionInput.reactedBy],                                 // We're validating that reactedBy object only contains the right address
+      type: addEmojiReactionInput.type,                                          
+    });
+  });
+
+  it("should handle addEmojiReaction operation to a non existing message", () => {  // We're testing that an error is thrown when reacting to a non-existing message
+    const input: AddEmojiReactionInput = {
+      messageId: "invalid-message-id",
+      reactedBy: "anon-user",
+      type: "THUMBS_UP",
+    };
+
+    const updatedDocument = reducer(document, creators.addEmojiReaction(input));
+
+    expect(updatedDocument.operations.global).toHaveLength(1);
+    expect(updatedDocument.operations.global[0].type).toBe(
+      "ADD_EMOJI_REACTION",
+    );
+    expect(updatedDocument.operations.global[0].error).toBe(
+      "Message not found",
+    );
+    expect(updatedDocument.state.global.messages).toHaveLength(0);
+  });
+
+  it("should handle removeEmojiReaction operation", () => {             // We're making use of a helper function to check if we can remove an EmojiReaction
+    const [doc, addMessageInput] = addMessage();
+
+    let updatedDocument = doc;
+
+    const addEmojiReactionInput: AddEmojiReactionInput = {
+      messageId: addMessageInput.messageId,
+      reactedBy: "anon-user",
+      type: "THUMBS_UP",
+    };
+
+    updatedDocument = reducer(
+      updatedDocument,
+      creators.addEmojiReaction(addEmojiReactionInput),
+    );
+
+    const input: RemoveEmojiReactionInput = {                        // We're validating the removal of a message by our anon-user with a specific messageId 
+      messageId: addMessageInput.messageId,
+      senderId: "anon-user",
+      type: "THUMBS_UP",
+    };
+
+    updatedDocument = reducer(
+      updatedDocument,
+      creators.removeEmojiReaction(input),
+    );
+
+    expect(updatedDocument.operations.global).toHaveLength(3);      // We're validating that the operation was added to the operation history.
+    expect(updatedDocument.operations.global[2].type).toBe(
+      "REMOVE_EMOJI_REACTION",
+    );
+    expect(updatedDocument.operations.global[2].input).toStrictEqual(input);
+    expect(updatedDocument.operations.global[2].index).toEqual(2);
+
+    expect(updatedDocument.state.global.messages[0].reactions).toHaveLength(1);         // The reaction should still exist but no-one should have reacted to it
+    expect(
+      updatedDocument.state.global.messages[0].reactions?.[0]?.reactedBy,
+    ).toHaveLength(0);
+  });
+
+  it("should handle editChatName operation", () => {            
+    const input: EditChatNameInput = {
+      name: "New Chat Name",
+    };
+
+    const updatedDocument = reducer(document, creators.editChatName(input));
+
+    expect(updatedDocument.operations.global).toHaveLength(1);                      // We're validating that the operation is added to the operations history
+    expect(updatedDocument.operations.global[0].type).toBe("EDIT_CHAT_NAME");
+    expect(updatedDocument.operations.global[0].input).toStrictEqual(input);
+    expect(updatedDocument.operations.global[0].index).toEqual(0);
+
+    expect(updatedDocument.state.global.name).toBe(input.name);
+  });
+
+  it("should handle editChatDescription operation", () => {
+    const input: EditChatDescriptionInput = {
+      description: "New Chat Description",
+    };
+
+    const updatedDocument = reducer(
+      document,
+      creators.editChatDescription(input),
+    );
+
+    expect(updatedDocument.operations.global).toHaveLength(1);          // We're validating that the operation is added to the operations history
+    expect(updatedDocument.operations.global[0].type).toBe(
+      "EDIT_CHAT_DESCRIPTION",
+    );
+    expect(updatedDocument.operations.global[0].input).toStrictEqual(input);
+    expect(updatedDocument.operations.global[0].index).toEqual(0);
+
+    expect(updatedDocument.state.global.description).toBe(input.description);
+  });
+});
+```
+
+
+
+Now you can run the tests to make sure the operation reducers are working as expected.
+
+```bash
+npm run test
+```
+
+Output should be as follows:
+
+```bash
+ Test Files  2 passed (2)
+      Tests  7 passed (7)
+   Start at  15:19:52
+   Duration  3.61s (transform 77ms, setup 0ms, collect 3.50s, tests 14ms, environment 0ms, prepare 474ms)
+```
+
+If you got the same output, you have successfully implemented the operation reducers and tests for the `ChatRoom` document model.
+Continue to the next section to learn how to implement the document model editor so you can see a simple user interface for the `ChatRoom` document model in action. 

package/docs/academy/02-AdvancedTutorial/01-Create/02-MoreTutorials/Chatroom/05-ImplementChatroomEditor.md

@@ -0,0 +1,194 @@
+
+# Implement Chatroom Editor
+
+In this section you will implement the `Chatroom` document model editor. This means you will create a simple user interface for the `Chatroom` document model which will be used inside the Connect app to visualise our chatroom, send messages and emoji reactions. 
+
+## Generate the editor template
+
+Run below command to generate the editor template for the `Chatroom` document model. This command reads the `Chatroom` document model definition from the `document-models` folder and generates the editor template in the `editors/chat-room/editor.tsx` folder.
+
+Notice the `--editor` flag which defines the `chatroom` document model editor. And the `--document-types` flag which defines the document type `powerhouse/chatroom`.
+
+```bash
+ph generate -- --editor ChatRoomEditor --document-types powerhouse/chat-room
+```
+
+Once complete, navigate to the `editors/chat-room/editor.tsx` file and open it in your editor.
+
+As you'll see you will need to add more complex logic to make the chatroom functional and interact with our document model. 
+
+## Add the necessary components for your editor first
+
+Download the repository of the chatroom-demo as a zip file https://github.com/powerhouse-inc/chatroom-demo
+and navigate to .../chatroom-demo-main/editors/chat-room-editor to copy both the components folder & utils function. In this repository you will also find all of the other code snippets we've been using in this tutorial. 
+
+Drag the folder with react components & utils functions into your VSCode of your chat-room-editor.
+
+In this folder you'll find:
+- An avatar to be set for each chat room participant
+- The chatroom environment itself
+- A header for the chatroom
+- The UI for rendering the message, username and reaction popup. 
+- The emoji reaction interface 
+- A UI for a text input field 
+
+The utils function will help you with mapping information from the document model to your chatroom components. Such as your emoji values to the relevant emoji to be displayed.   
+
+Now, let's copy & paste the code below into the `editor.tsx` file located at `editors/chat-room-editor`and save the file.
+
+```typescript
+/* eslint-disable react/jsx-no-bind */
+import { EditorProps } from "document-model/document";
+import {
+  ChatRoomState,
+  ChatRoomAction,
+  ChatRoomLocalState,
+  ReactionType,
+  actions,
+} from "../../document-models/chat-room";
+import { utils as documentModelUtils } from "document-model/document";
+import { ChatRoom, ChatRoomProps, MessageProps } from "./components";
+import { reactionKeyToReactionType, mapReactions } from "./utils";
+
+export type IProps = EditorProps<
+  ChatRoomState,
+  ChatRoomAction,
+  ChatRoomLocalState
+>;
+
+export default function Editor(props: IProps) {
+  const disableChatRoom = !props.context.user;          // we're disabling the chatroom when a user is not logged in.
+
+  const messages: ChatRoomProps["messages"] =
+    props.document.state.global.messages.map((message) => ({    // this object comes from the document state with a mapping that validates which message which user has send. 
+      id: message.id,
+      message: message.content || "",
+      timestamp: message.sentAt,
+      userName: message.sender.name || message.sender.id,
+      imgUrl: message.sender.avatarUrl || undefined,        // if the user has an avatar set we'll use it.
+      isCurrentUser: message.sender.id === props.context.user?.address,
+      reactions: mapReactions(message.reactions),
+    }));
+
+  const onSendMessage: ChatRoomProps["onSendMessage"] = (message) => {
+    if (!message) {
+      return;
+    }
+
+    props.dispatch(             
+      actions.addMessage({
+        messageId: documentModelUtils.hashKey(),
+        content: message,
+        sender: {
+          id: props.context.user?.address || "anon-user",           
+          name: props.context.user?.ens?.name || null,  // The context of the editor allows us to get hold of the users profile information. 
+          avatarUrl: props.context.user?.ens?.avatarUrl || null,
+        },
+        sentAt: new Date().toISOString(),
+      }),
+    );
+  };
+
+  const addReaction = (
+    messageId: string,
+    userId: string,
+    reactionType: ReactionType,
+  ) => {
+    props.dispatch(
+      actions.addEmojiReaction({
+        messageId,
+        reactedBy: userId,
+        type: reactionType,
+      }),
+    );
+  };
+
+  const removeReaction = (
+    messageId: string,
+    userId: string,
+    reactionType: ReactionType,
+  ) => {
+    props.dispatch(
+      actions.removeEmojiReaction({
+        messageId,
+        senderId: userId,
+        type: reactionType,
+      }),
+    );
+  };
+
+  const onClickReaction: MessageProps["onClickReaction"] = (reaction) => {      // This allows us to increase the reactions on a emoji that already has been used as a reaction to a message.
+    const message = messages.find(
+      (message) => message.id === reaction.messageId,
+    );
+
+    if (!message) {
+      return;
+    }
+
+    const messageId = reaction.messageId;
+    const reactionType = reactionKeyToReactionType(reaction.type);
+    const currentUserId = props.context.user?.address || "anon-user";
+
+    const existingReaction = message.reactions?.find(
+      (r) => r.type === reaction.type,
+    );
+
+    if (existingReaction) {
+      const dispatchAction = existingReaction.reactedBy.includes(currentUserId)
+        ? removeReaction
+        : addReaction;
+
+      dispatchAction(messageId, currentUserId, reactionType);
+    } else {
+      addReaction(messageId, currentUserId, reactionType);
+    }
+  };
+
+  const onSubmitTitle: ChatRoomProps["onSubmitTitle"] = (title) => {
+    props.dispatch(actions.editChatName({ name: title }));
+  };
+
+  const onSubmitDescription: ChatRoomProps["onSubmitDescription"] = (
+    description,
+  ) => {
+    props.dispatch(actions.editChatDescription({ description }));
+  };
+
+  return (
+    <div
+      style={{
+        height: "calc(100vh - 140px)",
+      }}
+    >
+      <ChatRoom
+        description={
+          props.document.state.global.description || "This is a chat room demo"
+        }
+        disabled={disableChatRoom}      // we're disabling the chatroom when a user is not logged in.
+        messages={messages}             // the list of messages users are submitting
+        onClickReaction={onClickReaction}
+        onSendMessage={onSendMessage}
+        onSubmitDescription={onSubmitDescription}
+        onSubmitTitle={onSubmitTitle}
+        title={props.document.state.global.name || "Chat Room Demo"}
+      />
+    </div>
+  );
+```
+
+Now you can run the Connect app and see the `Chatroom` editor in action.
+
+```bash
+ph connect
+```
+
+In connect, in the bottom right corner you'll find a new Document Model that you can create: `ChatRoom`. Click on it to create a new Chat Room document. A warning will prompt you to login before you are able to send messages. 
+
+Login with an ethereum address via Renown to start sending messages.
+
+Below GIF shows the `Chatroom` editor in action.
+
+![Chatroom Editor](./images/ChatRoomTest.gif)
+
+If you managed to follow this tutorial until this point, you have successfully implemented the `ChatRoom` document model with its reducer operations and editor. In the next chapter we'll be showing you how to simulate a synchronisation between two nodes or users making use of the chatroom by starting up a local reactor.

package/docs/academy/02-AdvancedTutorial/01-Create/02-MoreTutorials/Chatroom/06-LaunchALocalReactor.md

@@ -0,0 +1,15 @@
+# Launch a local Reactor
+
+Now we'll create a local Reactor instance to simulate the behaviour of the chatroom synchronising messages between two nodes or users in the network. 
+
+Wind down connect and run the following command in your terminal. 
+
+`ph reactor`
+
+This spins up a reactor, which represents a node that is usally hosted as a remote server, but in our case we run it locally on our machine. The reactor you've created will become available as a public drive in your left hand side bar. 
+
+If you would now open up two different browser windows you will be able to login into two version of connect, with two different ethereum addresses to start validating the functionality of your chatroom. 
+
+Please go ahead now and send a message to yourself, give yourself a thumbs up or try to make your ENS name appear as your profile when logging in. Also remind yourself that you are able to see the revision history of your document and all it's operation history in the top right corner. 
+
+Congratulations! You've now explored one of the many ways to use document models within the powerhouse ecosystem. 

package/docs/academy/02-AdvancedTutorial/01-Create/02-MoreTutorials/Chatroom/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Chatroom",
+  "position": 2,
+  "link": {
+    "type": "generated-index",
+    "description": "Get started with the Chatroom tutorial! Jump into creating a new Powerhouse project if you have NodeJs, VSCode, and Git installed. Whe are going to create a new document model that represents a chat.  So you as a user can post messages into that chat room, react to the messages. This chatroom will be synchronized between different connect instances. Let's explore the potential of the tools available in the powerhouse toolkit"
+  }
+}

package/docs/academy/02-AdvancedTutorial/01-Create/02-MoreTutorials/_category_.json

@@ -0,0 +1,8 @@
+{
+    "label": "More Tutorials",
+    "position": 3,
+    "link": {
+      "type": "generated-index",
+      "description": "Explore our tutorials to learn how to use document models in your project."
+    }
+}