@powerhousedao/academy 5.1.0-staging.0 → 5.1.0

package/docs/academy/03-ExampleUsecases/Chatroom/05-ImplementChatroomEditor.md

@@ -1,257 +1,40 @@
-# Build the ChatRoom editor
+# Implement Chatroom Editor
 
-:::tip Tutorial Repository
-📦 **Reference Code**: [chatroom-demo](https://github.com/powerhouse-inc/chatroom-demo)
-
-This tutorial covers building the ChatRoom editor:
-1. **Editor Scaffolding**: Generating the editor template with `ph generate --editor`
-2. **Component Implementation**: Building a complete, interactive chat UI with components
-
-Explore the complete implementation in the `editors/chat-room-editor/` directory.
-:::
-
-<details>
-<summary>📖 How to use this tutorial</summary>
-
-This tutorial shows building from **generated scaffolding** to a **complete chat UI**.
-
-### Compare your generated editor
-
-After running `pnpm generate --editor`:
-
-```bash
-# Compare generated scaffolding with the reference
-git diff tutorial/main -- editors/chat-room-editor/
-
-# View the generated editor template
-git show tutorial/main:editors/chat-room-editor/editor.tsx
-```
-
-### Browse the complete implementation
-
-Explore the production-ready component structure:
-
-```bash
-# List all components in the reference
-git ls-tree -r --name-only tutorial/main editors/chat-room-editor/components/
-
-# View a specific component
-git show tutorial/main:editors/chat-room-editor/components/ChatRoom/ChatRoom.tsx
-```
-
-### Visual comparison with GitHub Desktop
-
-After committing your editor code:
-1. **Branch** menu → **"Compare to Branch..."**
-2. Select `tutorial/main`
-3. See all your custom components vs. the reference implementation
-
-See step 1 for detailed GitHub Desktop instructions.
-
-</details>
-
-In this chapter we will continue with the interface or editor implementation of the **ChatRoom** document model. This means you will create a user interface for the **ChatRoom** document model which will be used inside the Connect app to visualize your chatroom, send messages, and react with emojis.
+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 the command below 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` folder.
-
-```bash
-pnpm generate --editor chat-room-editor --document-types powerhouse/chat-room
-```
+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 specifies the editor name, and the `--document-types` flag defines the document type `powerhouse/chat-room`.
+Notice the `--editor` flag which defines the `chatroom` document model editor. And the `--document-types` flag which defines the document type `powerhouse/chatroom`.
 
-Once complete, you'll have a new directory structure:
-
-```
-editors/chat-room-editor/
-├── components/
-│   └── EditName.tsx          # Auto-generated component for editing document name
-├── editor.tsx                # Main editor component (to be customized)
-└── module.ts                 # Editor module configuration
-```
-
-Navigate to the `editors/chat-room-editor/editor.tsx` file and open it in your editor. You'll see a basic template ready for customization.
-
-### Editor implementation options
-
-When building your editor component within the Powerhouse ecosystem, you have several options for styling:
-
-1. **Default HTML Styling:** Standard HTML tags will render with default styles offered through the boilerplate.
-2. **Tailwind CSS:** Connect Studio comes with Tailwind CSS integrated. You can directly use Tailwind utility classes.
-3. **Custom CSS Files:** You can import traditional CSS files to apply custom styles.
-
-Connect Studio provides a dynamic local environment. By running `ph connect`, you can visualize your components instantly as you build them.
-
-## Build the editor with components
-
-We'll build the editor using a component-based approach for better organization and reusability.
-
-### Component-based architecture
-
-The ChatRoom editor uses a modular component structure. Each component has its own folder with an `index.ts` file for clean exports:
-
-```
-editors/chat-room-editor/
-├── components/
-│   ├── Avatar/              # User avatar display
-│   │   ├── Avatar.tsx
-│   │   └── index.ts
-│   ├── ChatRoom/            # Main chat container
-│   │   ├── ChatRoom.tsx
-│   │   └── index.ts
-│   ├── Header/              # Chat header with editable title/description
-│   │   ├── EditableLabel.tsx
-│   │   ├── Header.tsx
-│   │   └── index.ts
-│   ├── Message/             # Individual message bubble
-│   │   ├── Message.tsx
-│   │   └── index.ts
-│   ├── MessageItem/         # Message with avatar and reaction dropdown
-│   │   ├── MessageItem.tsx
-│   │   └── index.ts
-│   ├── Reaction/            # Emoji reaction display
-│   │   ├── Reaction.tsx
-│   │   └── index.ts
-│   ├── TextInput/           # Message input field
-│   │   ├── SendIcon.tsx
-│   │   ├── TextInput.tsx
-│   │   └── index.ts
-│   └── index.ts             # Central exports
-├── editor.tsx               # Main editor component
-├── utils.ts                 # Utility functions for data mapping
-└── module.ts                # Editor module configuration
+```bash
+ph generate --editor ChatRoomEditor --document-types powerhouse/chat-room
 ```
 
-### Copy components from the reference repository
+Once complete, navigate to the `editors/chat-room/editor.tsx` file and open it in your editor.
 
-Download the repository of the chatroom-demo as a zip file from https://github.com/powerhouse-inc/chatroom-demo and navigate to `editors/chat-room-editor/` to copy the following:
+As you'll see you will need to add more complex logic to make the chatroom functional and interact with our document model.
 
-1. **The entire `components/` folder** - Contains all UI components
-2. **The `utils.ts` file** - Contains utility functions for emoji mapping
+## Add the necessary components for your editor first
 
-Here's what each component does:
+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.
 
-| Component | Purpose |
-|-----------|---------|
-| `Avatar` | Displays a user avatar image or a deterministic emoji based on the username |
-| `ChatRoom` | Main container that orchestrates the header, messages list, and input field |
-| `Header` | Shows the chat title and description with inline editing capability |
-| `EditableLabel` | Reusable component for inline text editing with edit/cancel icons |
-| `Message` | Renders a single message bubble with styling based on the sender |
-| `MessageItem` | Wraps `Message` with `Avatar` and adds a reaction dropdown menu |
-| `Reaction` | Displays an emoji reaction with a count of users who reacted |
-| `TextInput` | Input field for composing and sending new messages |
+Drag the folder with react components & utils functions into your VSCode of your chat-room-editor.
 
-### The utils.ts file
+In this folder you'll find:
 
-The `utils.ts` file contains helper functions for mapping between document model types and component props:
-
-```typescript
-import type {
-  MessageProps,
-  ReactionMap,
-} from "./components/Message/Message.js";
-import type {
-  Message,
-  ReactionType,
-} from "../../document-models/chat-room/gen/schema/types.js";
-
-const emojis = [
-  "😀", "😂", "🤣", "😍", "😎", "😊", "🙃", "😇", "🤔", "🥳",
-  "🤯", "🤗", "😱", "👻", "🎃", "🐱", "🐶", "🐹", "🦊", "🐻",
-  "🐼", "🐨", "🐯", "🦁", "🐸", "🐵", "🐔", "🐧", "🐦", "🐤",
-  "🐝", "🐞", "🐟", "🐬", "🐳", "🦋", "🌺", "🌸", "🌼", "🍀",
-];
-
-export function getEmojiFromString(input: string): string {
-  function hashString(str: string): number {
-    let hash = 0;
-    for (let i = 0; i < str.length; i++) {
-      const char = str.charCodeAt(i);
-      hash = (hash << 5) - hash + char;
-      hash |= 0;
-    }
-    return Math.abs(hash);
-  }
-
-  const hash = hashString(input);
-  return emojis[hash % emojis.length];
-}
-
-export const reactionTypeToEmoji = (reactionType: ReactionType): string => {
-  switch (reactionType) {
-    case "HEART":
-      return "❤️";
-    case "THUMBS_UP":
-      return "👍";
-    case "THUMBS_DOWN":
-      return "👎";
-    case "LAUGH":
-      return "😂";
-    case "CRY":
-      return "😢";
-    default:
-      return "❤️";
-  }
-};
-
-export const reactionTypeToReactionKey = (
-  reactionType: ReactionType,
-): keyof ReactionMap => {
-  switch (reactionType) {
-    case "HEART":
-      return "heart";
-    case "THUMBS_UP":
-      return "thumbsUp";
-    case "THUMBS_DOWN":
-      return "thumbsDown";
-    case "LAUGH":
-      return "laughing";
-    case "CRY":
-      return "cry";
-    default:
-      return "heart";
-  }
-};
-
-export const reactionKeyToReactionType = (
-  reactionKey: string,
-): ReactionType => {
-  switch (reactionKey) {
-    case "heart":
-      return "HEART";
-    case "thumbsUp":
-      return "THUMBS_UP";
-    case "thumbsDown":
-      return "THUMBS_DOWN";
-    case "laughing":
-      return "LAUGH";
-    case "cry":
-      return "CRY";
-    default:
-      return "HEART";
-  }
-};
-
-export const mapReactions = (
-  reactions: Message["reactions"],
-): MessageProps["reactions"] => {
-  return (reactions || [])
-    .map((reaction) => ({
-      emoji: reactionTypeToEmoji(reaction.type),
-      reactedBy: reaction.reactedBy,
-      type: reactionTypeToReactionKey(reaction.type),
-    }))
-    .filter((reaction) => reaction.reactedBy.length > 0);
-};
-```
+- 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 main editor.tsx file
+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.
 
-The main `editor.tsx` file connects your document model to the UI components. Replace the generated scaffolding with:
+Now, let's copy & paste the code below into the `editor.tsx` file located at `editors/chat-room-editor`and save the file.
 
 ```typescript
 import { generateId } from "document-model/core";
@@ -400,162 +183,18 @@ export default function Editor() {
 }
 ```
 
-**What's happening here:**
-
-- We use `useSelectedChatRoomDocument` hook to get the document state and dispatch function
-- We use `useUser` to get the current user information (for authentication)
-- We map the document's messages to props that our ChatRoom component expects
-- We create handlers for sending messages, adding/removing reactions, and editing metadata
-- We dispatch operations (`addMessage`, `addEmojiReaction`, etc.) from our generated creators
-
-:::info Key Concept: useSelectedChatRoomDocument hook
-The `useSelectedChatRoomDocument` hook is generated by the Powerhouse CLI. It provides:
-1. The current document state (`document`)
-2. A dispatch function to send actions to the reducer
-
-This hook connects your React components to the document model's state and operations.
-:::
-
-## Key components explained
-
-### MessageItem component
-
-The `MessageItem` component wraps the `Message` component with an avatar and a reaction dropdown menu. It uses the `@powerhousedao/design-system` package for the dropdown:
-
-```typescript
-import { Message, type MessageProps } from "../Message/Message.js";
-import { Avatar, type AvatarProps } from "../Avatar/Avatar.js";
-import { useState } from "react";
-import {
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuTrigger,
-  DropdownMenuItem,
-} from "@powerhousedao/design-system";
-
-export type MessageItemProps = MessageProps & AvatarProps;
-
-export const reactionMap = {
-  cry: "😢",
-  laughing: "😂",
-  heart: "❤️",
-  thumbsDown: "👎",
-  thumbsUp: "👍",
-};
-
-export const MessageItem: React.FC<MessageItemProps> = (props) => {
-  const { imgUrl, userName, isCurrentUser, ...messageProps } = props;
-  const { disabled = false } = messageProps;
-
-  const [isHovered, setIsHovered] = useState(false);
-  const [open, setOpen] = useState(false);
-
-  // ... hover and dropdown logic
-
-  return (
-    <div style={{ display: "flex", gap: "2px", alignItems: "flex-end" }}>
-      <Avatar imgUrl={imgUrl} userName={userName} />
-      <DropdownMenu>
-        <Message isCurrentUser={isCurrentUser} userName={userName} {...messageProps} />
-        <DropdownMenuTrigger>🫥</DropdownMenuTrigger>
-        <DropdownMenuContent>
-          {Object.entries(reactionMap).map(([key, emoji]) => (
-            <DropdownMenuItem key={key} onClick={() => /* handle reaction */}>
-              {emoji}
-            </DropdownMenuItem>
-          ))}
-        </DropdownMenuContent>
-      </DropdownMenu>
-    </div>
-  );
-};
-```
-
-### EditableLabel component
-
-The `EditableLabel` component enables inline editing of text fields (like the chat title and description):
-
-```typescript
-export const EditableLabel: React.FC<EditableLabelProps> = ({
-  label: initialLabel,
-  onSubmit,
-  style,
-}) => {
-  const [hover, setHover] = useState(false);
-  const [isEditing, setIsEditing] = useState(false);
-  const [label, setLabel] = useState(initialLabel);
-
-  // Toggle between read mode (displaying text) and write mode (input field)
-  // Press Enter to submit, Escape to cancel
-  
-  return (
-    <div onMouseEnter={() => setHover(true)} onMouseLeave={() => setHover(false)}>
-      {isEditing ? (
-        <input value={label} onChange={(e) => setLabel(e.target.value)} />
-      ) : (
-        <h1>{label}</h1>
-      )}
-      {(hover || isEditing) && <EditIcon onClick={() => setIsEditing(true)} />}
-    </div>
-  );
-};
-```
-
-## Test your editor
-
-Now you can run the Connect app and see the **ChatRoom** editor in action:
+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 ChatRoom document.
-
-:::warning Authentication Required
-A warning will prompt you to login before you can send messages. Login with an Ethereum address via Renown to start sending messages.
-:::
-
-![Chatroom Editor](./images/ChatRoomTest.gif)
-
-**Try it out:**
-1. Create a new ChatRoom document
-2. Login with your Ethereum wallet
-3. Send messages using the input field
-4. React to messages with emoji reactions
-5. Click the chat name or description to edit them
+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.
 
-Congratulations! 🎉  
-If you managed to follow this tutorial until this point, you have successfully implemented the **ChatRoom** document model with its reducer operations and editor.
+Login with an ethereum address via Renown to start sending messages.
 
-## Compare with the reference implementation
+Below GIF shows the `Chatroom` editor in action.
 
-The tutorial repository includes the complete ChatRoom editor with all components:
-
-```bash
-# See the ChatRoom component implementation
-git show tutorial/main:editors/chat-room-editor/components/ChatRoom/ChatRoom.tsx
-
-# Explore the MessageItem component
-git show tutorial/main:editors/chat-room-editor/components/MessageItem/MessageItem.tsx
-
-# View the EditableLabel component
-git show tutorial/main:editors/chat-room-editor/components/Header/EditableLabel.tsx
-
-# Compare your implementation with the reference
-git diff tutorial/main -- editors/chat-room-editor/
-```
-
-## Key concepts learned
-
-In this tutorial you've learned:
-
-✅ **Component-based architecture** - Breaking down complex UIs into reusable components  
-✅ **Document model hooks** - Using `useSelectedChatRoomDocument` to connect React to your document state  
-✅ **User authentication** - Using `useUser` hook for wallet-based authentication  
-✅ **Action dispatching** - How to dispatch operations from your UI  
-✅ **Type-safe development** - Leveraging TypeScript with generated types from your SDL  
-✅ **Real-time collaboration** - Building features that work across multiple users
-
-## Up next: Local Reactor
+![Chatroom Editor](./images/ChatRoomTest.gif)
 
-In the next section, you'll learn how to run a local Reactor to test real-time synchronization between multiple users.
+If you managed to follow this tutorial until this point, you have successfully implemented the `ChatRoom` document model with its reducer operations and editor.

package/docs/academy/03-ExampleUsecases/Chatroom/06-LaunchALocalReactor.md

@@ -1,103 +1,15 @@
 # Launch a local Reactor
 
-:::tip Tutorial Repository
-📦 **Reference Code**: [chatroom-demo](https://github.com/powerhouse-inc/chatroom-demo)
+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.
 
-This final step demonstrates real-time collaboration by running a local Reactor instance.
-:::
+Wind down connect and run the following command in your terminal.
 
-In this final section, we'll create a local Reactor instance to test the real-time synchronization capabilities of your ChatRoom. This simulates how messages would sync between multiple users in a production environment.
+`ph reactor`
 
-## What is a 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.
 
-A Reactor is a node in the Powerhouse network that:
-- Hosts and synchronizes documents across multiple clients
-- Manages document state and operations
-- Enables real-time collaboration between users
+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.
 
-In production, Reactors are typically hosted as remote servers. For development and testing, we can run a local Reactor.
+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.
 
-## Start the local Reactor
-
-First, stop the Connect application if it's running. Then start the Reactor:
-
-```bash
-ph reactor
-```
-
-This spins up a Reactor that:
-- Runs locally on your machine
-- Creates a public drive accessible from your Connect sidebar
-- Enables synchronization between multiple browser sessions
-
-## Test real-time collaboration
-
-To validate the real-time functionality of your ChatRoom:
-
-1. **Open two browser windows** with the Connect application
-2. **Navigate to the Reactor drive** in the left sidebar (it will appear as a public drive)
-3. **Login with different Ethereum addresses** in each window
-4. **Create a ChatRoom document** in one window
-5. **Open the same document** in the other window
-
-Now you can:
-- Send messages from one window and see them appear in the other
-- React to messages with emojis and watch the reactions sync
-- Edit the chat name or description and see updates propagate
-
-:::info Real-time Sync
-The Reactor ensures that all operations are synchronized across connected clients. Each message and reaction is recorded as an operation, maintaining a complete history that can be replayed to reconstruct the document state.
-:::
-
-## Additional features to explore
-
-While testing your ChatRoom, try these features:
-
-1. **Operation History**: Click on the revision history in the top right corner to see all operations performed on the document
-
-2. **ENS Integration**: If you login with an Ethereum address that has an ENS name, your name and avatar will appear in your messages
-
-3. **Reaction Toggling**: Click on an existing reaction to toggle it on/off for your user
-
-## Running Connect alongside Reactor
-
-You can also run Connect and Reactor together. In separate terminal windows:
-
-```bash
-# Terminal 1: Start the Reactor
-ph reactor
-
-# Terminal 2: Start Connect (in a separate terminal)
-ph connect
-```
-
-This allows you to:
-- Use Connect's local drive for development
-- Access the Reactor's public drive for collaboration testing
-- Switch between local and synchronized documents
-
-## What you've accomplished
-
-Congratulations! 🎉 You've now completed the ChatRoom tutorial and learned how to:
-
-✅ **Create a Powerhouse project** - Initialize and configure a new project  
-✅ **Define a document model** - Design schemas using GraphQL SDL  
-✅ **Implement reducers** - Write the business logic for state transitions  
-✅ **Build an editor** - Create a React-based UI for your document  
-✅ **Test with a Reactor** - Validate real-time collaboration features
-
-## Next steps
-
-Now that you've completed this tutorial, you can:
-
-1. **Explore the Mastery Track** - Dive deeper into [Document Model Creation](/academy/MasteryTrack/DocumentModelCreation/WhatIsADocumentModel) for advanced concepts
-
-2. **Try Vetra Studio** - Use AI-assisted development with [Vetra Studio](/academy/GetStarted/VetraStudio) for faster iteration
-
-3. **Build your own project** - Apply what you've learned to create your own document models and editors
-
-4. **Join the community** - Connect with other Powerhouse builders and share your creations
-
----
-
-*This tutorial demonstrated one of the many ways to use document models within the Powerhouse ecosystem. The patterns you've learned here apply to any collaborative application you want to build.*
+Congratulations! You've now explored one of the many ways to use document models within the powerhouse ecosystem.

package/docs/academy/03-ExampleUsecases/Chatroom/_category_.json

@@ -3,6 +3,6 @@
   "position": 2,
   "link": {
     "type": "generated-index",
-    "description": "Build a real-time ChatRoom application with Powerhouse. This tutorial guides you through creating a document model for a chat application where users can post messages and react with emojis. You'll learn to define schemas, implement reducers, build a React editor, and test real-time synchronization using a local Reactor."
+    "description": "Get started with the Chatroom tutoria: 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/04-APIReferences/00-PowerhouseCLI.md

@@ -8,7 +8,7 @@ The **Powerhouse CLI tool** is the only essential tool to install on this page.
 You can find all of the commands on this page, similar to what would displayed when using ph --help or ph _command_ --help.
 Use the table of content or the search function to find what you are looking for.
 
-The Powerhouse CLI (`ph-cmd`) is a command-line interface tool that provides essential commands for managing Powerhouse Vetra projects. You can get access to the Powerhouse ecosystem tools by installing them globally.
+The Powerhouse CLI (`ph-cmd`) is a command-line interface tool that provides essential commands for managing Powerhouse projects. You can get access to the Powerhouse ecosystem tools by installing them globally.
 
 ```bash
 pnpm install -g ph-cmd
@@ -16,11 +16,7 @@ pnpm install -g ph-cmd
 
 :::
 
-<!-- AUTO-GENERATED-CLI-COMMANDS-START -->\n<!-- This content is automatically generated. Do not edit directly. -->\n
-
-### ph-cmd Commands
-
-- [Checkout](#checkout)
+<!-- AUTO-GENERATED-CLI-COMMANDS-START -->\n<!-- This content is automatically generated. Do not edit directly. -->\n### ph-cmd Commands\n\n- [Checkout](#checkout)
 - [Init](#init)
 - [Setup Globals](#setup-globals)
 - [Update](#update)