@powerhousedao/academy 5.1.0-dev.1 → 5.1.0-dev.11

package/docs/academy/01-GetStarted/05-BuildToDoListEditor.md

@@ -0,0 +1,560 @@
+# Build a to-do list editor
+
+:::tip Tutorial Repository
+📦 **Reference Code**: 
+- **Editor Scaffolding**: [step-5-generate-todo-list-document-editor](https://github.com/powerhouse-inc/todo-tutorial/tree/step-5-generate-todo-list-document-editor)
+- **Complete Editor UI**: [step-6-add-basic-todo-editor-ui-components](https://github.com/powerhouse-inc/todo-tutorial/tree/step-6-add-basic-todo-editor-ui-components)
+
+This tutorial covers two steps:
+1. **Step 5**: Generating the editor template with `ph generate --editor`
+2. **Step 6**: Building a complete, interactive UI with components for adding, editing, and deleting todos
+
+Compare implementations: `git diff step-5-generate-todo-list-document-editor step-6-add-basic-todo-editor-ui-components`
+:::
+
+<details>
+<summary>📖 How to use this tutorial</summary>
+
+This tutorial shows building from **generated scaffolding** (step-5) to **complete UI** (step-6).
+
+### Compare your generated editor
+
+After running `ph generate --editor`:
+
+```bash
+# Compare generated scaffolding with step-5
+git diff tutorial/step-5-generate-todo-list-document-editor -- editors/
+
+# View the generated editor template
+git show tutorial/step-5-generate-todo-list-document-editor:editors/todo-list-editor/editor.tsx
+```
+
+### Compare your custom components
+
+After building your UI:
+
+```bash
+# Compare your complete editor with step-6
+git diff tutorial/step-6-add-basic-todo-editor-ui-components -- editors/
+
+# See what was added from scaffolding to complete UI
+git diff tutorial/step-5-generate-todo-list-document-editor..tutorial/step-6-add-basic-todo-editor-ui-components
+```
+
+### Browse the complete implementation
+
+Explore the production-ready component structure:
+
+```bash
+# List all components in step-6
+git ls-tree -r --name-only tutorial/step-6-add-basic-todo-editor-ui-components editors/todo-list-editor/components/
+
+# View a specific component
+git show tutorial/step-6-add-basic-todo-editor-ui-components:editors/todo-list-editor/components/TodoList.tsx
+```
+
+### Visual comparison with GitHub Desktop
+
+After committing your editor code:
+1. **Branch** menu → **"Compare to Branch..."**
+2. Select `tutorial/step-5-generate-todo-list-document-editor` or `tutorial/step-6-add-basic-todo-editor-ui-components`
+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 **To-do List** document model. This means you will create a simple user interface for the **To-do List** document model which will be used inside the Connect app to create, update and delete your ToDoList items.
+
+## Generate the editor template
+
+Run the command below to generate the editor template for the **To-do List** document model.  
+This command reads the **To-do List** document model definition from the `document-models` folder and generates the editor template in the `editors/todo-list-editor` folder.
+
+```bash
+pnpm generate --editor todo-list-editor --document-types powerhouse/todo-list
+```
+
+Notice the `--editor` flag which specifies the editor name, and the `--document-types` flag defines the document type `powerhouse/todo-list`.
+
+Once complete, you'll have a new directory structure:
+
+```
+editors/todo-list-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/todo-list-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, allowing you to leverage your preferred methods:
+
+1.  **Default HTML Styling:** Standard HTML tags (`<h1>`, `<p>`, `<button>`, etc.) 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 for rapid, consistent styling without writing separate CSS files.
+3.  **Custom CSS Files:** You can import traditional CSS files (`.css`) to apply custom styles or integrate existing style libraries.
+
+Connect Studio provides a dynamic local environment, by running `ph connect` to visualize your components instantly as you build them, regardless of the styling method you choose.  
+Manual build steps are typically only needed when publishing packages.
+
+## Build the editor with components
+
+We'll build the editor using a component-based approach for better organization and reusability. We'll create separate components for different UI features, making the code more maintainable and easier to understand.
+
+### Component-based architecture
+
+The editor structure we'll build includes:
+- `editor.tsx` - Main editor wrapper (imports TodoList)
+- `TodoList.tsx` - Main container component that orchestrates all other components
+- `AddTodo.tsx` - Form component for adding new todos
+- `Todo.tsx` - Individual todo item component with edit/delete functionality
+- `Todos.tsx` - List wrapper component for rendering all todos
+
+:::tip
+The tutorial repository (step-6) includes additional components like `TodoListName`, `CloseButton`, and `UndoRedoButtons`. We'll focus on the core components here, but you can explore the complete implementation using the git commands shown above.
+:::
+
+### Step 1: Update the main editor file
+
+First, update `editors/todo-list-editor/editor.tsx` to import and render the main `TodoList` component:
+
+```tsx
+// removed-line
+import { EditTodoListName } from "./components/EditName.js";
+// added-line
+import { TodoList } from "./components/TodoList.js";
+
+/** Editor component for the Todo List document type */
+export function Editor() {
+  return (
+    <div className="py-4 px-8">
+      // removed-line
+      <EditTodoListName />
+      // added-line
+      <TodoList />
+    </div>
+  );
+}
+```
+
+### Step 2: Create the TodoList container component
+
+Create `editors/todo-list-editor/components/TodoList.tsx`. This is the main orchestrator that brings together all child components:
+
+```tsx
+import { useSelectedTodoListDocument } from "todo-tutorial/document-models/todo-list";
+import { TodoListName } from "./TodoListName.js";
+import { Todos } from "./Todos.js";
+import { AddTodo } from "./AddTodo.js";
+
+/** Displays the selected todo list */
+export function TodoList() {
+  const [selectedTodoList] = useSelectedTodoListDocument();
+
+  if (!selectedTodoList) return null;
+
+  const todos = selectedTodoList.state.global.items;
+
+  return (
+    <div>
+      <section className="mb-4">
+        <TodoListName />
+      </section>
+      <section className="mb-4">
+        <Todos todos={todos} />
+      </section>
+      <section>
+        <AddTodo />
+      </section>
+    </div>
+  );
+}
+```
+
+:::info Key Concept: useSelectedTodoListDocument hook
+The `useSelectedTodoListDocument` hook is generated by the Powerhouse CLI. It provides:
+1. The current document state (`selectedTodoList`)
+2. A dispatch function to send actions to the reducer
+
+This hook connects your React components to the document model's state and operations.
+:::
+
+### Step 3: Create the AddTodo form component
+
+Create `editors/todo-list-editor/components/AddTodo.tsx` to handle adding new todo items:
+
+```tsx
+import type { FormEventHandler } from "react";
+import { addTodoItem } from "todo-tutorial/document-models/todo-list";
+import { useSelectedTodoListDocument } from "todo-tutorial/document-models/todo-list";
+
+/** Component for adding a new todo item to the selected todo list */
+export function AddTodo() {
+  const [todoList, dispatch] = useSelectedTodoListDocument();
+
+  if (!todoList) return null;
+
+  const onSubmitAddTodo: FormEventHandler<HTMLFormElement> = (event) => {
+    event.preventDefault();
+
+    const form = event.currentTarget;
+    const addTodoInput = form.elements.namedItem("addTodo") as HTMLInputElement;
+    const text = addTodoInput.value;
+    if (!text) return;
+
+    dispatch(addTodoItem({ text }));
+
+    form.reset();
+  };
+
+  return (
+    <form onSubmit={onSubmitAddTodo} className="flex mx-auto min-w-fit gap-2">
+      <input
+        className="py-1 px-2 grow min-w-fit placeholder:text-gray-600 rounded border border-gray-600 text-gray-800"
+        type="text"
+        name="addTodo"
+        placeholder="What needs to be done?"
+        autoFocus
+      />
+      <button
+        type="submit"
+        className="text-gray-600 rounded border border-gray-600 px-3 py-1"
+      >
+        Add
+      </button>
+    </form>
+  );
+}
+```
+
+**What's happening here:**
+- We use a form with `onSubmit` handler for better UX (Enter key support)
+- We extract the text value from the input field
+- We dispatch the `addTodoItem` action (generated from our SDL)
+- We reset the form after submission
+
+### Step 4: Create the Todos list component
+
+Create `editors/todo-list-editor/components/Todos.tsx` to render the list of todos:
+
+```tsx
+import type { TodoItem } from "todo-tutorial/document-models/todo-list";
+import { Todo } from "./Todo.js";
+
+type Props = {
+  todos: TodoItem[];
+};
+
+/** Shows a list of the todo items in the selected todo list */
+export function Todos({ todos }: Props) {
+  const hasTodos = todos.length > 0;
+
+  if (!hasTodos) {
+    return <p>Start adding things to your todo list</p>;
+  }
+
+  return (
+    <ul>
+      {todos.map((todo) => (
+        <li key={todo.id}>
+          <Todo todo={todo} />
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+**What's happening here:**
+- We accept `todos` as a prop (passed from `TodoList` parent)
+- We show a helpful message if the list is empty
+- We map over todos and render a `Todo` component for each item
+
+### Step 5: Create the Todo item component
+
+Create `editors/todo-list-editor/components/Todo.tsx` for individual todo items with edit and delete functionality:
+
+```tsx
+import {
+  useState,
+  type ChangeEventHandler,
+  type FormEventHandler,
+  type MouseEventHandler,
+} from "react";
+import {
+  deleteTodoItem,
+  updateTodoItem,
+} from "todo-tutorial/document-models/todo-list";
+import type { TodoItem } from "todo-tutorial/document-models/todo-list";
+import { useSelectedTodoListDocument } from "todo-tutorial/document-models/todo-list";
+
+type Props = {
+  todo: TodoItem;
+};
+
+/** Displays a single todo item in the selected todo list
+ *
+ * Allows checking/unchecking the todo item.
+ * Allows editing the todo item text.
+ * Allows deleting the todo item.
+ */
+export function Todo({ todo }: Props) {
+  const [isEditing, setIsEditing] = useState(false);
+  const [todoList, dispatch] = useSelectedTodoListDocument();
+
+  if (!todoList) return null;
+
+  const todoId = todo.id;
+  const todoText = todo.text;
+  const todoChecked = todo.checked;
+
+  const onSubmitUpdateTodoText: FormEventHandler<HTMLFormElement> = (event) => {
+    event.preventDefault();
+
+    const form = event.currentTarget;
+    const textInput = form.elements.namedItem("todoText") as HTMLInputElement;
+    const text = textInput.value;
+    if (!text) return;
+    dispatch(updateTodoItem({ id: todo.id, text }));
+    setIsEditing(false);
+  };
+
+  const onChangeTodoChecked: ChangeEventHandler<HTMLInputElement> = (event) => {
+    dispatch(
+      updateTodoItem({
+        id: todo.id,
+        checked: event.target.checked,
+      }),
+    );
+  };
+
+  const onClickDeleteTodo: MouseEventHandler<HTMLButtonElement> = () => {
+    dispatch(deleteTodoItem({ id: todoId }));
+  };
+
+  const onClickEditTodo: MouseEventHandler<HTMLButtonElement> = () => {
+    setIsEditing(true);
+  };
+
+  const onClickCancelEditTodo: MouseEventHandler<HTMLButtonElement> = () => {
+    setIsEditing(false);
+  };
+
+  if (isEditing)
+    return (
+      <form
+        className="flex gap-2 items-center justify-between"
+        onSubmit={onSubmitUpdateTodoText}
+      >
+        <input
+          className="p-1 grow"
+          type="text"
+          name="todoText"
+          defaultValue={todoText}
+          autoFocus
+        />
+        <div className="flex gap-2 grow-0">
+          <button type="submit" className="text-sm text-gray-600">
+            Save
+          </button>
+          <button
+            className="text-sm text-red-800"
+            onClick={onClickCancelEditTodo}
+          >
+            Cancel
+          </button>
+        </div>
+      </form>
+    );
+
+  return (
+    <div className="flex justify-between items-center">
+      <div className="flex items-center gap-2 p-1">
+        <input
+          type="checkbox"
+          checked={todoChecked}
+          onChange={onChangeTodoChecked}
+        />
+        <span className={todoChecked ? "line-through" : ""}>{todoText}</span>
+      </div>
+      <span className="flex place-items-center gap-2 text-sm">
+        <button className="text-gray-600" onClick={onClickEditTodo}>
+          Edit
+        </button>
+        <button className="text-red-800" onClick={onClickDeleteTodo}>
+          Delete
+        </button>
+      </span>
+    </div>
+  );
+}
+```
+
+**What's happening here:**
+- We use local state (`isEditing`) to toggle between view and edit modes
+- We dispatch `updateTodoItem` for both checking and text editing
+- We dispatch `deleteTodoItem` to remove items
+- We use TypeScript event handlers for type safety
+
+### Step 6: Create the TodoListName component
+
+Finally, create `editors/todo-list-editor/components/TodoListName.tsx` for displaying and editing the document name:
+
+```tsx
+import { useState, type FormEventHandler } from "react";
+import { useSelectedTodoListDocument } from "todo-tutorial/document-models/todo-list";
+import { setName } from "document-model/document";
+
+/** Allows editing the name of the selected todo list */
+export function TodoListName() {
+  const [isEditing, setIsEditing] = useState(false);
+  const [selectedTodoList, dispatch] = useSelectedTodoListDocument();
+
+  if (!selectedTodoList) return null;
+
+  const documentName = selectedTodoList.name;
+
+  const onSubmitEditName: FormEventHandler<HTMLFormElement> = (event) => {
+    event.preventDefault();
+
+    const form = event.currentTarget;
+    const nameInput = form.elements.namedItem("name") as HTMLInputElement;
+    const name = nameInput.value;
+
+    if (name) {
+      dispatch(setName(name));
+      setIsEditing(false);
+    }
+  };
+
+  if (isEditing) {
+    return (
+      <form onSubmit={onSubmitEditName}>
+        <input
+          name="name"
+          defaultValue={documentName}
+          className="text-xl font-bold"
+          autoFocus
+        />
+      </form>
+    );
+  }
+
+  return (
+    <h1
+      className="text-xl font-bold cursor-pointer"
+      onClick={() => setIsEditing(true)}
+    >
+      {documentName}
+    </h1>
+  );
+}
+```
+
+**What's happening here:**
+- We use the `setName` action from `document-model/document` (a built-in action)
+- We toggle between viewing and editing the name
+- Click the name to edit it
+
+## Test your editor
+
+Now you can run the Connect app and see the **To-do List** editor in action:
+
+```bash
+ph connect
+```
+
+In Connect, in the bottom right corner you'll find a new Document Model that you can create: **To-do List**.  
+Click on it to create a new To-do List document.
+
+:::info Live Development
+The editor will update dynamically as you make changes, so you can experiment with styling and functionality while seeing your results appear in Connect Studio in real-time.
+:::
+
+**Try it out:**
+1. Add some todo items using the input form
+2. Click on the document name to edit it
+3. Check/uncheck items to mark them as complete
+4. Click "Edit" on any item to modify its text
+5. Click "Delete" to remove items
+
+Congratulations! 🎉  
+If you managed to follow this tutorial until this point, you have successfully implemented the **To-do List** document model with its reducer operations and editor.
+
+## Compare with the reference implementation
+
+The tutorial repository's step-6 branch includes additional enhancements you can explore:
+
+**Additional components in step-6:**
+```
+editors/todo-list-editor/components/
+├── CloseButton.tsx       # Editor close functionality
+├── UndoRedoButtons.tsx   # Operation history navigation
+└── Stats.tsx             # Display metadata (creation/modification times)
+```
+
+**View individual components from the reference:**
+
+```bash
+# See the enhanced TodoList component with all features
+git show tutorial/step-6-add-basic-todo-editor-ui-components:editors/todo-list-editor/components/TodoList.tsx
+
+# Explore the UndoRedoButtons component
+git show tutorial/step-6-add-basic-todo-editor-ui-components:editors/todo-list-editor/components/UndoRedoButtons.tsx
+
+# Compare your implementation with the reference
+git diff tutorial/step-6-add-basic-todo-editor-ui-components -- editors/todo-list-editor/
+```
+
+:::tip Check your work
+
+To make sure everything works as expected:
+
+```bash
+# Check types compile correctly
+pnpm tsc
+
+# Check linting passes
+pnpm lint
+
+# Run tests
+pnpm test
+
+# Test in Connect Studio
+ph connect
+
+# Compare with reference implementation
+git diff tutorial/step-6-add-basic-todo-editor-ui-components -- editors/todo-list-editor/
+```
+
+In Connect, you should be able to:
+- Create a new To-do List document
+- Add, edit, and delete todo items
+- Check/uncheck items to mark them complete
+
+:::
+
+## Key concepts learned
+
+In this tutorial you've learned:
+
+✅ **Component-based architecture** - Breaking down complex UIs into reusable components  
+✅ **Document model hooks** - Using `useSelectedTodoListDocument` to connect React to your document state  
+✅ **Action dispatching** - How to dispatch operations (`addTodoItem`, `updateTodoItem`, `deleteTodoItem`) from your UI  
+✅ **Type-safe development** - Leveraging TypeScript with generated types from your SDL  
+✅ **Form handling** - Using React forms with proper event handlers  
+✅ **Local vs. document state** - When to use React `useState` vs. document model state  
+
+### Up next: Mastery Track
+
+In the [Mastery Track chapter: Document Model Creation](/academy/MasteryTrack/DocumentModelCreation/WhatIsADocumentModel) we guide you through the theoretics of the previous steps while creating a more advanced version of the To-do List.
+
+You will learn:
+
+- The in's & out's of a document model.
+- How to use UI & Scalar components from the Document Engineering system.
+- How to build Custom Drive Apps or Drive Explorers.
+

package/docs/academy/01-GetStarted/_04-BuildToDoListEditor

@@ -10,7 +10,7 @@ This command reads the **To-do List** document model definition from the `docume
 Notice the `--editor` flag which specifies the **To-do List** document model, and the `--document-types` flag defines the document type `powerhouse/todolist`.
 
 ```bash
-ph generate --editor ToDoList --document-types powerhouse/todolist
+pnpm generate --editor Todo-List-editor --document-types powerhouse/todolist
 ```
 
 Once complete, navigate to the `editors/to-do-list/editor.tsx` file and open it in your editor.

package/docs/academy/02-MasteryTrack/01-BuilderEnvironment/03-BuilderTools.md

@@ -1,6 +1,6 @@
-# Powerhouse builder tooling
+# Vetra builder tooling
 
-This page provides an overview of all the builder tooling offered by the Powerhouse ecosystem.  
+This page provides an overview of all the builder tooling offered in the Vetra ecosystem by Powerhouse.  
 This list will be maintained and updated as our toolkit grows.
 
 ## Powerhouse command line interface

package/docs/academy/{01-GetStarted → 02-MasteryTrack/01-BuilderEnvironment}/05-VetraStudio.md

@@ -1,4 +1,4 @@
-# Tool: Vetra Studio 
+# Vetra Studio 
 
 :::tip Important
 
@@ -77,6 +77,28 @@ You could then add the specific remote Vetra drive to your powerhouse configurat
 
 An example of a builder team building on the Powerhouse Vetra Ecosystem and it's complementary Vetra Studio Drive specifications for the different packages be found [here](https://vetra.io/builders/bai)
 
+<details>
+<summary>📦 Vetra Remote Drive Commands</summary>
+
+Remote drives enable collaborative development by syncing specifications across team members.
+
+**Key Commands:**
+- `ph init --remote-drive <url>` - Create a NEW project connected to a remote drive
+- `ph checkout --remote-drive <url>` - Clone an EXISTING project from a remote drive  
+- `ph vetra --watch` - Start development with a preview drive for testing local changes
+
+**Workflows:**
+- **Project Owner**: `ph init --remote-drive` → Create GitHub repo → Push → `ph vetra` to configure
+- **Collaborator**: `ph checkout --remote-drive` → `ph vetra` to start developing
+
+**Preview Drive (`--watch` mode):**
+- Main "Vetra" drive syncs with remote and contains stable package configuration
+- "Vetra Preview" drive is created locally for testing document models before syncing
+
+→ [Full Vetra Remote Drive Reference](/academy/APIReferences/VetraRemoteDrive)
+
+</details>
+
 ## Vetra Studio Workflow
 
 ### 1. Launch Vetra Studio
@@ -146,16 +168,35 @@ Connected to MCP successfully! I can see there's a
   running and ready for document model operations.
 ```
 
--  To learn what is a [Reactor](apps/academy/docs/academy/Architecture/WorkingWithTheReactor) read the reactor article
--  To learn more about the [Reactor MCP](apps/academy/docs/academy/GetStarted/ReactorMCP) read the reactor MCP article
-
 ### Key Reactor MCP Features
 
 - It supports automatic document model creation from natural language descriptions
 - It implements a smart editor based on the underlying document models
 - It automatically triggers code generation when documents reach valid state
-- The MCP server enables the agent to work with both existing and newly created document models.
-- Vetra supports integration with custom remote drives, allowing users to create, share and manage documents within these drives.
+- The MCP server enables the agent to work with both existing and newly created document models
+- Vetra supports integration with custom remote drives, allowing users to create, share and manage documents within these drives
+
+<details>
+<summary>🤖 Reactor MCP Overview</summary>
+
+**Reactor-mcp** is a Model Context Protocol (MCP) server that bridges AI agents with Powerhouse document operations.
+
+**Document Operations:**
+- `createDocument` / `getDocument` / `deleteDocument` - Manage documents
+- `addActions` - Modify document state through operations
+
+**Drive Operations:**
+- `getDrives` / `addDrive` / `getDrive` - Manage document drives
+- `addRemoteDrive` - Connect to remote drives
+
+**Document Model Operations:**
+- `getDocumentModels` - List available document model types
+- `getDocumentModelSchema` - Get schema for specific models
+
+**Document Model Agent:**
+A specialized AI agent that guides users through document model creation with requirements gathering, design confirmation, and implementation including state schema definition, operation creation, and code generation.
+
+</details>
 
 
 ### 3. Vetra Studio Package Creation Workflow
@@ -211,3 +252,4 @@ Support for:
    - Verify implementation details in generated code before continuing. 
    - Always double-check proposed next actions
 
+