@powerhousedao/academy 5.1.0-staging.0 → 5.1.0

package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/01-BuildingDocumentEditors.md

@@ -1,6 +1,6 @@
 # Build document editors
 
-## Build with React on Powerhouse
+## Build with react on powerhouse
 
 At Powerhouse, frontend development for document editors follows a simple and familiar flow, leveraging the power and flexibility of React.
 
@@ -26,13 +26,13 @@ Powerhouse aims to keep your developer experience clean, familiar, and focused:
 To kickstart your editor development, Powerhouse provides a command to generate a basic editor template. This command reads your document model specifications and creates the initial `editor.tsx` file.
 If you want a refresher on how to define your document model specification please read the chapter on [specifying the State Schema](/academy/MasteryTrack/DocumentModelCreation/SpecifyTheStateSchema)
 
-For example, to generate an editor for a TodoList document model with a document type `powerhouse/todo-list`:
+For example, to generate an editor for a To-do List document model with a document type `powerhouse/todolist`:
 
 ```bash
-ph generate --editor todo-list-editor --document-types powerhouse/todo-list
+ph generate --editor ToDoList --document-types powerhouse/todolist
 ```
 
-This will create the template in the `editors/todo-list-editor/editor.tsx` folder.
+This will create the template in the `editors/to-do-list/editor.tsx` folder.
 
 ### Styling your editor
 
@@ -41,11 +41,11 @@ You have several options for styling your editor components:
 1.  **Default HTML Styling**: Standard HTML tags (`<h1>`, `<p>`, `<button>`, etc.) will render with default browser styles or any base styling provided by the Connect environment. This is suitable for basic structure and quick prototyping.
 
 2.  **Tailwind CSS**: Connect Studio comes with Tailwind CSS integrated. You can directly use Tailwind utility classes in your JSX for rapid and consistent styling without writing separate CSS files.
-    _Example (from the TodoList Editor):_
+    _Example (from the ToDoList Editor):_
 
     ```typescript
     <div className="container mx-auto p-4 max-w-md">
-        <h1 className="text-2xl font-bold mb-4">TodoList</h1>
+        <h1 className="text-2xl font-bold mb-4">ToDoList</h1>
         {/* ... more Tailwind styled elements */}
     </div>
     ```
@@ -103,137 +103,46 @@ In any package the styles are being generated through the styles.css file with t
 - When installing a package with `ph install` on any instance, package styles are automatically added to styles.css. This ensures production builds always include the required package styles.
   :::
 
-## State management in editors: Hooks vs Props
+### State management in editors
 
-When you build an editor in Powerhouse, there are **two ways** to access and modify document state. Understanding the difference is important for choosing the right approach for your component.
+When you build an editor in Powerhouse, your main editor component receives `EditorProps`. These props are crucial for interacting with the document:
 
-### Understanding the two approaches
+- **`document`**: This object contains the entire document structure, including its current state. You'll typically access the global document state via `document.state.global`.
+- **`dispatch`**: This function is your gateway to modifying the document's state. You call `dispatch` with an action object (usually created by action creators from your document model's generated code) to signal an intended change.
 
-<details>
-<summary>ℹ️ For Non-Technical Readers</summary>
-
-Think of it like ordering food at a restaurant:
-
-**Hooks Approach** 🪝: Like having a direct line to the kitchen. Any component can call the kitchen directly to get the current menu (state) or place an order (dispatch an action). It's independent and self-sufficient.
-
-**Props Approach** 📦: Like a waiter passing you a menu and taking your order. The main component receives everything and passes it down to child components. Children can only work with what they're given.
-
-**Which is better?** For Powerhouse editors, we recommend the **Hooks approach** because:
-- Components are more independent
-- Easier to move components around
-- Less "prop drilling" (passing data through many layers)
-- Matches modern React best practices
-
-</details>
-
-### Method 1: Using Hooks (Recommended) 🪝
-
-The **hook-based approach** uses `useSelectedTodoListDocument` — a React hook that Powerhouse generates for your document model. Any component can call this hook to get the current document state and a function to dispatch changes.
+**Local vs. Global State:**
 
+- **Local Component State**: For UI-specific state that doesn't need to be part of the persisted document model (e.g., the current text in an input field before submission, visibility of a dropdown), use React's `useState` hook.
   ```typescript
-import { useSelectedTodoListDocument } from "todo-tutorial/document-models/todo-list";
-import { addTodoItem } from "todo-tutorial/document-models/todo-list";
-
-export function AddTodo() {
-  // The hook returns [document, dispatch]
-  const [todoList, dispatch] = useSelectedTodoListDocument();
-
-  if (!todoList) return null;
-
-  const handleAdd = (text: string) => {
-    dispatch(addTodoItem({ text }));
-  };
-
-  return (
-    <button onClick={() => handleAdd("New task")}>
-      Add Todo
-    </button>
-  );
-}
-```
-
-**Why hooks are recommended:**
-- ✅ **Self-contained components**: Each component gets its own connection to the document
-- ✅ **Less boilerplate**: No need to pass props through multiple levels
-- ✅ **Easier refactoring**: Move components around without rewiring props
-- ✅ **Modern React pattern**: Follows React's recommended approach for state management
-
-### Method 2: Using Props 📦
+  const [inputValue, setInputValue] = useState('');
+  // ...
+  <input value={inputValue} onChange={(e) => setInputValue(e.target.value)} />
+  ```
+- **Global Document State**: For data that is part of the document itself and should be saved (e.g., the items in a to-do list), you modify it by dispatching actions. The `document.state.global` object provides read-only access to this state within your editor.
 
-The **props-based approach** receives the document and dispatch function as properties passed from a parent component.
+**Dispatching Actions:**
+Your document model's generated code (e.g., in `document-models/your-model/index.js` or `document-models/your-model/gen/operations.js`) will provide action creators.
 
 ```typescript
-import { EditorProps } from 'document-model';
-import { TodoListDocument } from '../../document-models/todo-list/index.js';
-
-export type IProps = EditorProps<TodoListDocument>;
-
-export default function Editor(props: IProps) {
-    const { document, dispatch } = props;
-    const state = document.state.global;
-
-    // Now you'd pass state and dispatch to child components as props
-    return (
-        <div>
-            <TodoList items={state.items} dispatch={dispatch} />
-        </div>
-    );
-}
+// Assuming 'actions' are imported from your document model
+// import { actions } from '../../document-models/to-do-list/index.js';
+
+// Inside your editor component:
+// function Editor({ document, dispatch }: IProps) {
+//   ...
+//   const handleAddItem = () => {
+//     if (todoItem.trim()) {
+//       dispatch(actions.addTodoItem({ // Dispatch action to add item.
+//         id: Math.random().toString(), // Generate a simple unique ID
+//         text: todoItem,
+//       }));
+//       setTodoItem(''); // Clear local input state
+//     }
+//   };
+// }
 ```
 
-**When props might be useful:**
-- When you need strict control over which components can access state
-- When building components that should work outside of Powerhouse context
-- For testing purposes where you want to inject mock state
-
-### Which should you use?
-
-| Scenario | Recommended Approach |
-|----------|---------------------|
-| Building a standard Powerhouse editor | **Hooks** 🪝 |
-| Component needs document state | **Hooks** 🪝 |
-| Building reusable UI components (buttons, inputs) | **Props** 📦 |
-| Need to test components in isolation | **Props** 📦 |
-
-**Bottom line**: Use hooks for most Powerhouse editor development. It's simpler, cleaner, and matches the patterns used in the [todo-demo repository](https://github.com/powerhouse-inc/todo-demo).
-
-## Local vs. Global State
-
-When building editors, you'll work with two types of state:
-
-- **Global Document State**: Data that is part of the document itself and should be saved. This is accessed via hooks (`useSelectedTodoListDocument`) or props (`document.state.global`). You modify it by dispatching actions.
-
-- **Local Component State**: UI-specific state that doesn't need to be saved (e.g., "is the dropdown open?", "what's in the input field before submission?"). Use React's `useState` hook for this.
-
-```typescript
-import { useState } from 'react';
-import { useSelectedTodoListDocument, addTodoItem } from "todo-tutorial/document-models/todo-list";
-
-export function AddTodo() {
-  // Local state - just for this component's UI
-  const [inputValue, setInputValue] = useState('');
-  
-  // Global document state - saved in the document
-  const [todoList, dispatch] = useSelectedTodoListDocument();
-
-  const handleSubmit = () => {
-    if (inputValue.trim()) {
-      dispatch(addTodoItem({ text: inputValue })); // Updates global state
-      setInputValue(''); // Clears local state
-    }
-  };
-
-  return (
-    <div>
-      <input 
-        value={inputValue} 
-        onChange={(e) => setInputValue(e.target.value)} 
-      />
-      <button onClick={handleSubmit}>Add</button>
-    </div>
-  );
-}
-```
+The actual state modification logic resides in your document model's reducers, ensuring that all changes are consistent and follow the defined operations.
 
 ## Powerhouse component library
 
@@ -275,24 +184,24 @@ Storybook allows you to:
     ```
 
 <details>
-<summary>Tutorial: Implementing the TodoList Editor</summary>
+<summary>Tutorial: Implementing the `To-do List` Editor</summary>
 
-## Build a TodoList editor
+## Build a To-do List editor
 
-In this final part of our tutorial we will continue with the interface or editor implementation of the **TodoList** document model. This means you will create a simple user interface for the **TodoList** document model which will be used inside the Connect app to create, update and delete your TodoList items, and also display the statistics we've implemented in our reducers (if you followed the advanced version).
+In this final part of our tutorial 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 To-do List items, but also dispaly the statistics we've implemented in our reducers.
 
 ## Generate the editor template
 
-Run the command below to generate the editor template for the **TodoList** document model.  
-This command reads the **TodoList** document model definition from the `document-models` folder and generates the editor template in the `editors/todo-list-editor` folder as `editor.tsx`.
+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/to-do-list` folder as `editor.tsx`.
 
-Notice the `--editor` flag which specifies the editor name, and the `--document-types` flag defines the document type `powerhouse/todo-list`.
+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 todo-list-editor --document-types powerhouse/todo-list
+ph generate --editor ToDoList --document-types powerhouse/todolist
 ```
 
-Once complete, navigate to the `editors/todo-list-editor/editor.tsx` file and open it in your editor.
+Once complete, navigate to the `editors/to-do-list/editor.tsx` file and open it in your editor.
 
 ### Editor implementation options
 
@@ -306,222 +215,323 @@ Connect Studio provides a dynamic local environment (`ph connect`) to visualize
 
 ---
 
-## TodoList editor using hooks (Recommended)
-
-This approach uses the `useSelectedTodoListDocument` hook, which is the same pattern used in the Get Started tutorial and the [todo-demo repository](https://github.com/powerhouse-inc/todo-demo).
-
-### Main editor file
+## To-do List editor
 
-```typescript
-// editors/todo-list-editor/editor.tsx
-import { TodoList } from "./components/TodoList.js";
+:::tip Implementing components
+The editor we are about to implement makes use of some components from **Powerhouse Document Engineering**.
+When you add the editor code, you'll see it makes use of two components, the `Checkbox` and `InputField`.
+These are imported from the Powerhouse Document Engineering design system (`@powerhousedao/document-engineering/scalars`) which you should find under 'devdependencies' in your package.json file.
 
-export function Editor() {
-  return (
-    <div className="py-4 px-8">
-      <TodoList />
-    </div>
-  );
-}
-```
+This system provides a library of reusable components to ensure consistency and speed up development.  
+You can explore available components, see usage examples, and understand their properties (props) using our Storybook instance. For a detailed guide on how to leverage the Document Engineering design system and Storybook, see [Using the Powerhouse Document Engineering](/academy/ComponentLibrary/DocumentEngineering) page.
 
-### TodoList container component
+For this tutorial, create a `components` folder inside `editors/to-do-list`. Then, within this new `components` folder, create the files for the `Checkbox` and `InputField` components (e.g., `checkbox.tsx` and `inputfield.tsx`) with the following code:
+:::
 
+<details>
+<summary>Checkbox</summary>
 ```typescript
-// editors/todo-list-editor/components/TodoList.tsx
-import { useSelectedTodoListDocument } from "todo-tutorial/document-models/todo-list";
-import { Todos } from "./Todos.js";
-import { AddTodo } from "./AddTodo.js";
-
-export function TodoList() {
-  const [selectedTodoList] = useSelectedTodoListDocument();
+import { Form, BooleanField } from "@powerhousedao/document-engineering/scalars";
 
-  if (!selectedTodoList) return null;
-
-  const todos = selectedTodoList.state.global.items;
+interface CheckboxProps {
+value: boolean;
+onChange: (value: boolean) => void;
+}
 
+export const Checkbox = ({ value, onChange }: CheckboxProps) => {
 return (
-    <div>
-      <h1 className="text-2xl font-bold mb-4">TodoList</h1>
-      <section className="mb-4">
-        <Todos todos={todos} />
-      </section>
-      <section>
-        <AddTodo />
-      </section>
-    </div>
-  );
-}
-```
+<Form onSubmit={() => {}}>
+<BooleanField 
+        name="checked"
+        description="Check this box to mark the todo as completed"
+        value={value}
+        onChange={onChange}
+      />
+</Form>
+);
+};
 
-### AddTodo component
+````
+</details>
 
+<details>
+<summary>Inputfield</summary>
 ```typescript
-// editors/todo-list-editor/components/AddTodo.tsx
-import type { FormEventHandler } from "react";
-import { addTodoItem, useSelectedTodoListDocument } from "todo-tutorial/document-models/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;
+import { Form, StringField } from "@powerhousedao/document-engineering/scalars";
+
+interface InputFieldProps {
+  input: string;
+  value: string;
+  label?: string;
+  onKeyDown: (e: React.KeyboardEvent<HTMLTextAreaElement>) => void;
+  handleInputChange: (e: React.ChangeEvent<HTMLTextAreaElement>) => void;
+}
 
-    dispatch(addTodoItem({ text }));
-    form.reset();
-  };
+export const InputField = (props: InputFieldProps) => {
+  const { input, value, label, onKeyDown, handleInputChange } = props;
 
   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
+    <Form
+      defaultValues={{
+        input: input,
+      }}
+      onSubmit={() => {}}
+      resetOnSuccessfulSubmit
+    >
+      <StringField
+        style={{
+          color: "black",
+        }}
+        label={label}
+        name="input"
+        value={value}
+        onKeyDown={onKeyDown}
+        onChange={(e: React.ChangeEvent<HTMLTextAreaElement>) => {
+          handleInputChange(e);
+        }}
       />
-      <button
-        type="submit"
-        className="text-gray-600 rounded border border-gray-600 px-3 py-1"
-      >
-        Add
-      </button>
-    </form>
+    </Form>
   );
-}
-```
-
-### Todo item component
-
-```typescript
-// editors/todo-list-editor/components/Todo.tsx
-import { useState, type ChangeEventHandler, type FormEventHandler, type MouseEventHandler } from "react";
-import { deleteTodoItem, updateTodoItem, useSelectedTodoListDocument } from "todo-tutorial/document-models/todo-list";
-import type { TodoItem } from "todo-tutorial/document-models/todo-list";
-
-type Props = {
-  todo: TodoItem;
 };
+````
 
-export function Todo({ todo }: Props) {
-  const [isEditing, setIsEditing] = useState(false);
-  const [todoList, dispatch] = useSelectedTodoListDocument();
-
-  if (!todoList) return null;
-
-  const onChangeTodoChecked: ChangeEventHandler<HTMLInputElement> = (event) => {
-    dispatch(updateTodoItem({ id: todo.id, checked: event.target.checked }));
-  };
-
-  const onClickDeleteTodo: MouseEventHandler<HTMLButtonElement> = () => {
-    dispatch(deleteTodoItem({ id: todo.id }));
-  };
-
-  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);
-  };
-
-  if (isEditing) {
-    return (
-      <form className="flex gap-2 items-center" onSubmit={onSubmitUpdateTodoText}>
-        <input className="p-1 grow" type="text" name="todoText" defaultValue={todo.text} autoFocus />
-        <button type="submit" className="text-sm text-gray-600">Save</button>
-        <button className="text-sm text-red-800" onClick={() => setIsEditing(false)}>Cancel</button>
-      </form>
-    );
-  }
-
-  return (
-    <div className="flex justify-between items-center">
-      <div className="flex items-center gap-2 p-1">
-        <input type="checkbox" checked={todo.checked} onChange={onChangeTodoChecked} />
-        <span className={todo.checked ? "line-through" : ""}>{todo.text}</span>
-      </div>
-      <span className="flex place-items-center gap-2 text-sm">
-        <button className="text-gray-600" onClick={() => setIsEditing(true)}>Edit</button>
-        <button className="text-red-800" onClick={onClickDeleteTodo}>Delete</button>
-      </span>
-    </div>
-  );
-}
-```
-
----
+</details>
 
-## Advanced: Adding stats display
+Below is the complete code for the To-Do List editor. It primarily uses Tailwind CSS for styling and imports the local `Checkbox` and `InputField` components you created in the previous step. These local components, in turn, utilize elements from the Powerhouse Document Engineering design system.
 
-:::info Advanced Feature
-If you implemented the advanced version with statistics tracking, you can add a stats component to display the todo counts.
-:::
+<details>
+<summary>Complete To-do list editor example (using Tailwind CSS)</summary>
 
 ```typescript
-// Add to TodoList.tsx
-export function TodoList() {
-  const [selectedTodoList] = useSelectedTodoListDocument();
-
-  if (!selectedTodoList) return null;
-
-  const { items, stats } = selectedTodoList.state.global;
-
-  return (
-    <div>
-      <h1 className="text-2xl font-bold mb-4">TodoList</h1>
-      
-      {/* Stats section (only show if there are items) */}
-      {items.length >= 2 && (
+import { EditorProps } from 'document-model'; // Core type for editor components.
+import {
+    ToDoListState,       // Type for the global state of the ToDoList.
+    ToDoListAction,      // Type for actions that can modify the ToDoList state.
+    ToDoListLocalState,  // Type for local (non-shared) editor state (if needed).
+    ToDoItem,            // Type for a single item in the list.
+    actions,             // Object containing action creators for dispatching changes.
+    ToDoListDocument     // The complete document structure including state and metadata.
+} from '../../document-models/to-do-list/index.js'; // Path to your document model definition.
+import { useState } from 'react'; // React hook for managing component-local state.
+import { Checkbox } from './components/checkbox.js'; // Custom Checkbox component.
+import { InputField } from './components/inputfield.js'; // Custom InputField component.
+
+// Define the props expected by this Editor component. It extends EditorProps with our specific document type.
+export type IProps = EditorProps<ToDoListDocument>;
+
+// Define the main Editor component function.
+export default function Editor(props: IProps) {
+    // Destructure props for easier access.
+    const { document, dispatch } = props;
+    // Access the global state from the document object.
+    const { state: { global: state } } = document;
+
+    // --- Component State ---
+    // State for the text input field where new tasks are typed.
+    const [todoItem, setTodoItem] = useState('');
+    // State to track which item is currently being edited (null if none). Stores the item's ID.
+    const [editingItemId, setEditingItemId] = useState<string | null>(null);
+    // State to hold the text of the item currently being edited.
+    const [editedText, setEditedText] = useState('');
+
+    // Sort items to show unchecked items first
+    const sortedItems: ToDoItem[] = [...state.items].sort((a, b) => {
+        return (a.checked ? 1 : 0) - (b.checked ? 1 : 0);
+    });
+
+    // --- JSX Structure (What gets rendered) ---
+    return (
+        // Main container div.
+        // `container`: Sets max-width based on viewport breakpoints.
+        // `mx-auto`: Centers the container horizontally.
+        // `p-4`: Adds padding on all sides (4 units, typically 1rem).
+        // `max-w-sm`: Sets a maximum width (small size).
+        <div className="container mx-auto p-4 max-w-xs">
+            {/* Heading for the editor */}
+            {/* `text-2xl`: Sets font size to extra-large. */}
+            {/* `font-bold`: Makes the text bold. */}
+            {/* `mb-4`: Adds margin to the bottom. */}
+            <h1 className="text-2xl font-bold mb-4">To-do List</h1>
+
+            {/* Stats Section */}
+            {state.items.length >= 2 && (
                 <div className="mb-4 bg-white rounded-lg px-3 py-2 shadow-md">
                     <div className="grid grid-cols-3 gap-3">
                         <div>
-              <div className="text-xs text-slate-500">Total</div>
-              <div className="text-lg font-semibold">{stats.total}</div>
+                            <div className="text-xs text-slate-500 mb-0.5">Total</div>
+                            <div className="text-lg font-semibold text-slate-800">{state.stats.total}</div>
                         </div>
                         <div>
-              <div className="text-xs text-slate-500">Completed</div>
-              <div className="text-lg font-semibold text-green-600">{stats.checked}</div>
+                            <div className="text-xs text-slate-500 mb-0.5">Completed</div>
+                            <div className="text-lg font-semibold text-green-600">{state.stats.checked}</div>
                         </div>
                         <div>
-              <div className="text-xs text-slate-500">Remaining</div>
-              <div className="text-lg font-semibold text-orange-600">{stats.unchecked}</div>
+                            <div className="text-xs text-slate-500 mb-0.5">Remaining</div>
+                            <div className="text-lg font-semibold text-orange-600">{state.stats.unchecked}</div>
                         </div>
                     </div>
                 </div>
             )}
 
-      <section className="mb-4">
-        <Todos todos={items} />
-      </section>
-      <section>
-        <AddTodo />
-      </section>
+            {/* Container for the input field and "Add" button */}
+            {/* `flex items-end`: Enables flexbox layout for children with bottom alignment. */}
+            {/* `gap-2`: Adds a small gap between flex items. */}
+            {/* `mb-4`: Adds margin to the bottom. */}
+            <div className="flex items-end gap-2 mb-4">
+                {/* Custom InputField component */}
+                <div className="flex-grow">
+                    <InputField
+                        label="New Task" // Prop for accessibility/placeholder.
+                        input={todoItem} // Current value from state.
+                        value={todoItem} // Controlled component value.
+                        handleInputChange={(e) => setTodoItem(e.target.value)} // Update state on change.
+                        onKeyDown={(e) => { // Handle "Enter" key press to add item.
+                            if (e.key === 'Enter' && todoItem.trim()) { // Check if key is Enter and input is not empty
+                                dispatch(actions.addTodoItem({ // Dispatch action to add item.
+                                    id: Math.random().toString(), // Generate a simple unique ID (use a better method in production!).
+                                    text: todoItem,
+                                }));
+                                setTodoItem(''); // Clear the input field.
+                            }
+                        }}
+                    />
+                </div>
+                {/* "Add" button */}
+                {/* `bg-blue-500`: Sets background color to blue. */}
+                {/* `hover:bg-blue-600`: Changes background color on hover. */}
+                {/* `text-white`: Sets text color to white. */}
+                {/* `px-4`: Adds horizontal padding (4 units). */}
+                {/* `py-1.5`: Adds vertical padding (1.5 units). */}
+                {/* `rounded`: Applies rounded corners. */}
+                {/* `transition-colors`: Smoothly animates color changes. */}
+                <button
+                    className="bg-blue-500 hover:bg-blue-600 text-white px-4 py-1.5 rounded transition-colors"
+                    onClick={() => { // Handle button click to add item.
+                        if (todoItem.trim()) { // Check if input is not empty
+                            dispatch(actions.addTodoItem({ // Dispatch action to add item.
+                                id: Math.random().toString(), // Simple unique ID.
+                                text: todoItem,
+                            }));
+                            setTodoItem(''); // Clear the input field.
+                        }
+                    }}
+                >
+                    Add
+                </button>
+            </div>
+
+            {/* Unordered list to display the to-do items */}
+            {/* `list-none`: Removes default list bullet points. */}
+            {/* `p-0`: Removes default padding. */}
+            <ul className="list-none p-0">
+                {/* Map over the items array in the global state to render each item */}
+                {sortedItems.map((item: ToDoItem) => (
+                    // List item element for each to-do.
+                    // `key={item.id}`: React requires a unique key for list items for efficient updates.
+                    // `flex`: Enables flexbox layout (checkbox, text, delete icon in a row).
+                    // `items-center`: Aligns items vertically in the center.
+                    // `p-2`: Adds padding.
+                    // `relative`: Needed for positioning the delete icon absolutely (if we were doing that).
+                    // `border-b`: Adds a bottom border.
+                    // `border-gray-100`: Sets border color to light gray.
+                    <li
+                        key={item.id}
+                        className="flex items-center p-2 relative border-b border-gray-100"
+                    >
+                        {/* Custom Checkbox component */}
+                        <Checkbox
+                            value={item.checked} // Bind checked state to item's checked property.
+                            onChange={() => { // Handle checkbox click.
+                                dispatch(actions.updateTodoItem({ // Dispatch action to update item.
+                                    id: item.id,
+                                    checked: !item.checked, // Toggle the checked state.
+                                }));
+                            }}
+                        />
+
+                        {/* Conditional Rendering: Show input field or text based on editing state */}
+                        {editingItemId === item.id ? (
+                            // --- Editing State ---
+                            // Input field shown when this item is being edited.
+                            // `ml-2`: Adds left margin.
+                            // `flex-grow`: Allows input to take available horizontal space.
+                            // `p-1`: Adds small padding.
+                            // `border`: Adds a default border.
+                            // `rounded`: Applies rounded corners.
+                            // `focus:outline-none`: Removes the default browser focus outline.
+                            // `focus:ring-1 focus:ring-blue-500`: Adds a custom blue ring when focused.
+                            <input
+                                className="ml-2 flex-grow p-1 border rounded focus:outline-none focus:ring-1 focus:ring-blue-500"
+                                value={editedText} // Controlled input value from editedText state.
+                                onChange={(e) => setEditedText(e.target.value)} // Update editedText state.
+                                onKeyDown={(e) => { // Handle "Enter" key to save changes.
+                                    if (e.key === 'Enter') {
+                                        dispatch(actions.updateTodoItem({ // Dispatch update action.
+                                            id: item.id,
+                                            text: editedText, // Save the edited text.
+                                        }));
+                                        setEditingItemId(null); // Exit editing mode.
+                                    }
+                                }}
+                                autoFocus // Automatically focus the input when it appears.
+                            />
+                        ) : (
+                            // --- Display State ---
+                            // Container for the item text and delete icon when not editing.
+                            // `ml-2`: Adds left margin.
+                            // `flex items-center`: Aligns text and icon vertically.
+                            // `flex-grow`: Allows this container to take available space.
+                            // `gap-1`: Adds a small gap between text and icon.
+                            <div className="ml-2 flex items-center flex-grow gap-1">
+                                {/* The actual to-do item text */}
+                                {/* `cursor-pointer`: Shows a pointer cursor on hover, indicating clickability. */}
+                                {/* Conditional class: Apply line-through and gray text if item is checked. */}
+                                {/* `line-through`: Strikes through the text. */}
+                                {/* `text-gray-500`: Sets text color to gray. */}
+                                <span
+                                    className={`cursor-pointer ${item.checked ? 'line-through text-gray-500' : ''}`}
+                                    onClick={() => { // Handle click to enter editing mode.
+                                        setEditingItemId(item.id); // Set the ID of the item being edited.
+                                        setEditedText(item.text); // Initialize the input with current text.
+                                    }}
+                                >
+                                    {item.text} {/* Display the item's text */}
+                                </span>
+                                {/* Delete "button" (using a span styled as a button) */}
+                                {/* `text-gray-400`: Sets default text color to light gray. */}
+                                {/* `cursor-pointer`: Shows pointer cursor. */}
+                                {/* `opacity-40`: Makes it semi-transparent by default. */}
+                                {/* `transition-all duration-200`: Smoothly animates all changes (opacity, color). */}
+                                {/* `text-base font-bold`: Sets text size and weight. */}
+                                {/* `inline-flex items-center`: Needed for proper alignment if using an icon font/SVG. */}
+                                {/* `pl-1`: Adds small left padding. */}
+                                {/* `hover:opacity-100`: Makes it fully opaque on hover. */}
+                                {/* `hover:text-red-500`: Changes text color to red on hover. */}
+                                <span
+                                    className="text-gray-400 cursor-pointer opacity-40 transition-all duration-200 text-base font-bold inline-flex items-center pl-1 hover:opacity-100 hover:text-red-500"
+                                    onClick={() => dispatch(actions.deleteTodoItem({ id: item.id }))} // Dispatch delete action on click.
+                                >
+                                    × {/* Simple multiplication sign used as delete icon */}
+                                </span>
+                            </div>
+                        )}
+                    </li>
+                ))}
+            </ul>
         </div>
     );
 }
 ```
 
----
-
-## Test your editor
+</details>
 
-Now you can run the Connect app and see the **TodoList** editor in action:
+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: **TodoList**. Click on it to create a new TodoList document.
+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.
 
 :::tip Connect as your dynamic development environment
 The editor will update dynamically, so you can play around with your editor styling while seeing your results appear in Connect Studio.
@@ -530,9 +540,9 @@ The editor will update dynamically, so you can play around with your editor styl
 </details>
 
 Congratulations!
-If you managed to follow this tutorial until this point, you have successfully implemented the **TodoList** document model with its reducer operations and editor.
+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.
 
 ## Up Next
 
-Now you can move on to creating a [custom drive explorer](/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer) for your TodoList document.  
-Imagine you have many TodoLists sitting in a drive. A custom drive explorer will allow you to organize and track them at a glance, opening up a new world of possibilities to increase the functionality of your documents!
+Now you can move on to creating a [custom drive explorer](/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer) for your To-do List document.  
+Imagine you have many To-do Lists sitting in a drive. A custom drive explorer will allow you to organize and track them at a glance, opening up a new world of possibilities to increase the functionality of your documents!