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

package/docs/academy/02-MasteryTrack/02-DocumentModelCreation/06-ImplementDocumentModelTests.md

@@ -6,100 +6,214 @@ In the previous chapter, we implemented the core reducer logic for our document
 
 Testing is not an afterthought; it's an integral part of the development lifecycle, especially in systems like Powerhouse where data integrity and predictable state transitions are paramount. Well-crafted tests serve as a safety net, allowing you to refactor and extend your document model with confidence.
 
-This document provides a practical, hands-on tutorial for testing the `To-do List` document model reducers you have just built.
+This document provides a practical, hands-on tutorial for testing the `TodoList` document model reducers you have just built.
 
-## Practical implementation: Writing and running the To-do List tests
+## Practical implementation: Writing and running the TodoList tests
 
-This tutorial assumes you have implemented the `To-do List` reducers as described in the previous chapter and that the code generator has created a test file skeleton at `document-models/to-do-list/src/reducers/tests/to-do-list.test.ts`.
+This tutorial assumes you have implemented the `TodoList` reducers as described in the previous chapter and that the code generator has created a test file skeleton at `document-models/todo-list/src/tests/todos.test.ts`.
 
 <details>
-<summary>Tutorial: Implementing and running the `To-do List` reducer tests</summary>
+<summary>Tutorial: Implementing and running the TodoList reducer tests</summary>
 
 ### 1. Implement the reducer tests
 
-With the reducer logic in place, it's critical to test it. Navigate to the generated test file at `document-models/to-do-list/src/reducers/tests/to-do-list.test.ts` and replace its contents with the following test suite.
+With the reducer logic in place, it's critical to test it. Navigate to the generated test file at `document-models/todo-list/src/tests/todos.test.ts` and replace its contents with comprehensive tests.
 
-This suite tests each operation, verifying not only that the `items` array is correct, but also that our `stats` object is updated as expected and that the operation itself is recorded properly in the document's history.
+This suite tests each operation, verifying not only that the `items` array is correct, but also that the operation itself is recorded properly in the document's history.
 
-```typescript
-import utils from "../../gen/utils.js";
-import { reducer } from "../../gen/reducer.js";
-import * as creators from "../../gen/creators.js";
-import { ToDoListDocument } from "../../gen/types.js";
-
-describe("Todolist Operations", () => {
-  let document: ToDoListDocument;
-
-  beforeEach(() => {
-    // REMARKS: We start with a fresh, empty document for each test.
-    // The `createDocument` utility initializes the state with an empty 'items' array
-    // and a 'stats' object with all counts set to 0.
-    document = utils.createDocument();
-  });
+**Basic tests (matching Get Started):**
 
+```typescript
+import { describe, it, expect } from "vitest";
+import { generateMock } from "@powerhousedao/codegen";
+import type {
+  AddTodoItemInput,
+  DeleteTodoItemInput,
+  UpdateTodoItemInput,
+} from "todo-tutorial/document-models/todo-list";
+import {
+  reducer,
+  utils,
+  isTodoListDocument,
+  addTodoItem,
+  AddTodoItemInputSchema,
+  updateTodoItem,
+  UpdateTodoItemInputSchema,
+  deleteTodoItem,
+  DeleteTodoItemInputSchema,
+  TodoItemSchema,
+} from "todo-tutorial/document-models/todo-list";
+
+describe("Todos Operations", () => {
   it("should handle addTodoItem operation", () => {
-    const input = { id: "1", text: "Buy milk" };
+    const document = utils.createDocument();
+    const input: AddTodoItemInput = generateMock(AddTodoItemInputSchema());
 
-    // REMARKS: We apply the 'addTodoItem' operation.
-    const updatedDocument = reducer(document, creators.addTodoItem(input));
+    const updatedDocument = reducer(document, addTodoItem(input));
+    expect(isTodoListDocument(updatedDocument)).toBe(true);
 
-    // REMARKS: We verify the operation was recorded in the document's history.
-    // Powerhouse records every operation in an array.
+    // Verify the operation was recorded
     expect(updatedDocument.operations.global).toHaveLength(1);
-    expect(updatedDocument.operations.global[0].type).toBe("ADD_TODO_ITEM");
-    // REMARKS: We also check that the input data and index are recorded correctly.
-    expect(updatedDocument.operations.global[0].input).toStrictEqual(input);
+    expect(updatedDocument.operations.global[0].action.type).toBe("ADD_TODO_ITEM");
+    expect(updatedDocument.operations.global[0].action.input).toStrictEqual(input);
     expect(updatedDocument.operations.global[0].index).toEqual(0);
+  });
+
+  it("should handle updateTodoItem operation to update text", () => {
+    const mockItem = generateMock(TodoItemSchema());
+    const input: UpdateTodoItemInput = generateMock(UpdateTodoItemInputSchema());
+    input.id = mockItem.id;
+    const newText = "new text";
+    input.text = newText;
+    input.checked = undefined;
+    
+    const document = utils.createDocument({
+      global: {
+        items: [mockItem],
+      },
+    });
+
+    const updatedDocument = reducer(document, updateTodoItem(input));
+    expect(isTodoListDocument(updatedDocument)).toBe(true);
+
+    // Verify the operation was recorded
+    expect(updatedDocument.operations.global).toHaveLength(1);
+    expect(updatedDocument.operations.global[0].action.type).toBe("UPDATE_TODO_ITEM");
+    
+    // Verify the state was updated correctly
+    const updatedItem = updatedDocument.state.global.items.find(
+      (item) => item.id === input.id,
+    );
+    expect(updatedItem?.text).toBe(newText);
+    expect(updatedItem?.checked).toBe(mockItem.checked);
+  });
+
+  it("should handle updateTodoItem operation to update checked", () => {
+    const mockItem = generateMock(TodoItemSchema());
+    const input: UpdateTodoItemInput = generateMock(UpdateTodoItemInputSchema());
+    input.id = mockItem.id;
+    const newChecked = !mockItem.checked;
+    input.checked = newChecked;
+    input.text = undefined;
+    
+    const document = utils.createDocument({
+      global: {
+        items: [mockItem],
+      },
+    });
+
+    const updatedDocument = reducer(document, updateTodoItem(input));
+    expect(isTodoListDocument(updatedDocument)).toBe(true);
+
+    const updatedItem = updatedDocument.state.global.items.find(
+      (item) => item.id === input.id,
+    );
+    expect(updatedItem?.text).toBe(mockItem.text);
+    expect(updatedItem?.checked).toBe(newChecked);
+  });
+
+  it("should handle deleteTodoItem operation", () => {
+    const mockItem = generateMock(TodoItemSchema());
+    const document = utils.createDocument({
+      global: {
+        items: [mockItem],
+      },
+    });
+    
+    const input: DeleteTodoItemInput = generateMock(DeleteTodoItemInputSchema());
+    input.id = mockItem.id;
+    
+    const updatedDocument = reducer(document, deleteTodoItem(input));
+    expect(isTodoListDocument(updatedDocument)).toBe(true);
+
+    // Verify the operation was recorded
+    expect(updatedDocument.operations.global).toHaveLength(1);
+    expect(updatedDocument.operations.global[0].action.type).toBe("DELETE_TODO_ITEM");
+    
+    // Verify the item was removed from state
+    const updatedItems = updatedDocument.state.global.items;
+    expect(updatedItems).toHaveLength(0);
+  });
+});
+```
+
+**Advanced tests (with stats verification):**
+
+:::info Advanced Feature
+If you implemented the advanced version with statistics tracking, add these additional tests to verify the stats are updated correctly.
+:::
+
+```typescript
+describe("Todos Operations with Stats", () => {
+  it("should update stats when adding a todo item", () => {
+    const document = utils.createDocument();
+    const input = { text: "Buy milk" };
+
+    const updatedDocument = reducer(document, addTodoItem(input));
 
-    // REMARKS: Finally, we verify the state was updated according to our reducer logic.
     expect(updatedDocument.state.global.items).toHaveLength(1);
     expect(updatedDocument.state.global.stats.total).toBe(1);
     expect(updatedDocument.state.global.stats.unchecked).toBe(1);
+    expect(updatedDocument.state.global.stats.checked).toBe(0);
   });
 
-  it("should handle updateTodoItem operation", () => {
-    // REMARKS: For an update, we first need to add an item.
-    const addInput = { id: "1", text: "Buy milk" };
-    const updateInput = { id: "1", checked: true }; // We'll test checking the item.
-
-    // REMARKS: Operations are applied sequentially to build up document state.
-    const createdDocument = reducer(document, creators.addTodoItem(addInput));
+  it("should update stats when checking a todo item", () => {
+    const document = utils.createDocument();
+    
+    // Add an item first
+    const addedDocument = reducer(document, addTodoItem({ text: "Buy milk" }));
+    const itemId = addedDocument.state.global.items[0].id;
+    
+    // Now check it
     const updatedDocument = reducer(
-      createdDocument,
-      creators.updateTodoItem(updateInput),
+      addedDocument,
+      updateTodoItem({ id: itemId, checked: true })
     );
 
-    // REMARKS: Now we should have 2 operations in the history.
-    expect(updatedDocument.operations.global).toHaveLength(2);
-    expect(updatedDocument.operations.global[1].type).toBe("UPDATE_TODO_ITEM");
-    expect(updatedDocument.operations.global[1].input).toStrictEqual(
-      updateInput,
-    );
-
-    // REMARKS: We check that the state reflects the update, including our stats.
-    expect(updatedDocument.state.global.items[0].checked).toBe(true);
     expect(updatedDocument.state.global.stats.total).toBe(1);
     expect(updatedDocument.state.global.stats.unchecked).toBe(0);
     expect(updatedDocument.state.global.stats.checked).toBe(1);
   });
 
-  it("should handle deleteTodoItem operation", () => {
-    const addInput = { id: "1", text: "Buy milk" };
-    const deleteInput = { id: "1" };
-
-    const createdDocument = reducer(document, creators.addTodoItem(addInput));
+  it("should update stats when deleting an unchecked todo item", () => {
+    const document = utils.createDocument();
+    
+    // Add an item
+    const addedDocument = reducer(document, addTodoItem({ text: "Buy milk" }));
+    const itemId = addedDocument.state.global.items[0].id;
+    
+    // Delete it
     const updatedDocument = reducer(
-      createdDocument,
-      creators.deleteTodoItem(deleteInput),
+      addedDocument,
+      deleteTodoItem({ id: itemId })
     );
 
-    // REMARKS: After deletion, we still have 2 operations in history,
-    // but the items array is now empty and the stats are back to zero.
-    expect(updatedDocument.operations.global).toHaveLength(2);
-    expect(updatedDocument.operations.global[1].type).toBe("DELETE_TODO_ITEM");
     expect(updatedDocument.state.global.items).toHaveLength(0);
     expect(updatedDocument.state.global.stats.total).toBe(0);
     expect(updatedDocument.state.global.stats.unchecked).toBe(0);
+    expect(updatedDocument.state.global.stats.checked).toBe(0);
+  });
+
+  it("should update stats when deleting a checked todo item", () => {
+    const document = utils.createDocument();
+    
+    // Add and check an item
+    const addedDocument = reducer(document, addTodoItem({ text: "Buy milk" }));
+    const itemId = addedDocument.state.global.items[0].id;
+    const checkedDocument = reducer(
+      addedDocument,
+      updateTodoItem({ id: itemId, checked: true })
+    );
+    
+    // Delete it
+    const updatedDocument = reducer(
+      checkedDocument,
+      deleteTodoItem({ id: itemId })
+    );
+
+    expect(updatedDocument.state.global.items).toHaveLength(0);
+    expect(updatedDocument.state.global.stats.total).toBe(0);
+    expect(updatedDocument.state.global.stats.checked).toBe(0);
   });
 });
 ```
@@ -118,7 +232,7 @@ Or with npm:
 npm test
 ```
 
-If all tests pass, you have successfully verified the core logic of your `To-do List` document model. This ensures that the reducers you wrote behave exactly as expected.
+If all tests pass, you have successfully verified the core logic of your `TodoList` document model. This ensures that the reducers you wrote behave exactly as expected.
 
 </details>
 
@@ -149,6 +263,6 @@ By following the tutorial and applying these best practices, you can build a str
 
 ## Up next
 
-In the next chapter of the Mastery Track - Building User Experiences you will learn how to implement an [editor](/academy/MasteryTrack/BuildingUserExperiences/BuildingDocumentEditors) for your document model so you can see a simple user interface for the **To-do List** document model in action.
+In the next chapter of the Mastery Track - Building User Experiences you will learn how to implement an [editor](/academy/MasteryTrack/BuildingUserExperiences/BuildingDocumentEditors) for your document model so you can see a simple user interface for the **TodoList** document model in action.
 
-For a complete, working example, you can always have a look at the [Example To-do List Repository](/academy/MasteryTrack/DocumentModelCreation/ExampleToDoListRepository) which contains the full implementation of the concepts discussed in this Mastery Track.
+For a complete, working example, you can always have a look at the [Example TodoList Repository](/academy/MasteryTrack/DocumentModelCreation/ExampleToDoListRepository) which contains the full implementation of the concepts discussed in this Mastery Track.

package/docs/academy/02-MasteryTrack/02-DocumentModelCreation/07-ExampleToDoListRepository.md

@@ -14,6 +14,13 @@ There are several ways to explore this package:
 The Todo-demo and repository are your main reference points during the Mastery Track.  
 Follow the steps in the "Mastery Track – Document Model Creation" chapters to build along with the examples.
 
+Key patterns used in the repository:
+- **Naming convention**: `TodoList`, `TodoItem`, `TodoListState` (one word, PascalCase)
+- **Document type**: `powerhouse/todo-list`
+- **Module name**: `todos`
+- **ID generation**: Uses `generateId()` from `document-model/core` in the reducer
+- **Hooks**: Uses `useSelectedTodoListDocument` for state management in the editor
+
 ### Option 2: Clone and run the code locally
 
 The package includes:
@@ -27,6 +34,9 @@ The package includes:
 You can clone the repository and run Connect Studio to see all the code in action:
 
 ```bash
+git clone https://github.com/powerhouse-inc/todo-demo
+cd todo-demo
+pnpm install
 ph connect
 ```
 
@@ -37,3 +47,14 @@ Alternatively, you can install this package in a Powerhouse project or in your d
 ```bash
 ph install @powerhousedao/todo-demo
 ```
+
+## Comparing Get Started vs Mastery Track
+
+| Aspect | Get Started | Mastery Track (Advanced) |
+|--------|-------------|--------------------------|
+| Schema | Basic `items` array only | Includes `stats` object for tracking |
+| Reducer complexity | Simple CRUD operations | Includes statistics updates |
+| Editor | Component-based with hooks | Same approach + stats display |
+| Tests | Basic operation tests | Includes stats verification tests |
+
+Both approaches use the same naming conventions and patterns — the Mastery Track simply extends the foundation with additional features to demonstrate more advanced concepts.