@powerhousedao/academy 5.1.0-dev.9 → 5.1.0

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

@@ -6,214 +6,100 @@ 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 `TodoList` document model reducers you have just built.
+This document provides a practical, hands-on tutorial for testing the `To-do List` document model reducers you have just built.
 
-## Practical implementation: Writing and running the TodoList tests
+## Practical implementation: Writing and running the To-do List tests
 
-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`.
+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`.
 
 <details>
-<summary>Tutorial: Implementing and running the TodoList reducer tests</summary>
+<summary>Tutorial: Implementing and running the `To-do List` 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/todo-list/src/tests/todos.test.ts` and replace its contents with comprehensive 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.
 
-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.
-
-**Basic tests (matching Get Started):**
+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.
 
 ```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 document = utils.createDocument();
-    const input: AddTodoItemInput = generateMock(AddTodoItemInputSchema());
-
-    const updatedDocument = reducer(document, addTodoItem(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("ADD_TODO_ITEM");
-    expect(updatedDocument.operations.global[0].action.input).toStrictEqual(input);
-    expect(updatedDocument.operations.global[0].index).toEqual(0);
+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();
   });
 
-  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 addTodoItem operation", () => {
+    const input = { id: "1", text: "Buy milk" };
 
-  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);
-  });
+    // REMARKS: We apply the 'addTodoItem' operation.
+    const updatedDocument = reducer(document, creators.addTodoItem(input));
 
-  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
+    // REMARKS: We verify the operation was recorded in the document's history.
+    // Powerhouse records every operation in an array.
     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));
+    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].index).toEqual(0);
 
+    // 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 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
+  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));
     const updatedDocument = reducer(
-      addedDocument,
-      updateTodoItem({ id: itemId, checked: true })
+      createdDocument,
+      creators.updateTodoItem(updateInput),
     );
 
+    // 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 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(
-      addedDocument,
-      deleteTodoItem({ id: itemId })
-    );
-
-    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 handle deleteTodoItem operation", () => {
+    const addInput = { id: "1", text: "Buy milk" };
+    const deleteInput = { id: "1" };
 
-  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 createdDocument = reducer(document, creators.addTodoItem(addInput));
     const updatedDocument = reducer(
-      checkedDocument,
-      deleteTodoItem({ id: itemId })
+      createdDocument,
+      creators.deleteTodoItem(deleteInput),
     );
 
+    // 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.checked).toBe(0);
+    expect(updatedDocument.state.global.stats.unchecked).toBe(0);
   });
 });
 ```
@@ -232,7 +118,7 @@ Or with npm:
 npm test
 ```
 
-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.
+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.
 
 </details>
 
@@ -263,6 +149,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 **TodoList** 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 **To-do List** document model in action.
 
-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.
+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.

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

@@ -14,13 +14,6 @@ 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:
@@ -34,9 +27,6 @@ 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
 ```
 
@@ -47,14 +37,3 @@ 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.