@powerhousedao/academy 2.5.0-dev.27 → 2.5.0-dev.28

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 2.5.0-dev.28 (2025-06-16)
+
+### 🚀 Features
+
+- add app skeleton to html at build time ([1882bb820](https://github.com/powerhouse-inc/powerhouse/commit/1882bb820))
+
+### ❤️ Thank You
+
+- acaldas
+
 ## 2.5.0-dev.27 (2025-06-16)
 
 This was a version bump only for @powerhousedao/academy to align it with other projects, there were no code changes.

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

@@ -1,6 +1,6 @@
 # Build a ToDoList Editor
 
-In this chapter 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.
+In this chapter 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, but also dispaly the statistics we've implemented in our reducers. 
 
 ## Generate the editor template
 
@@ -26,167 +26,6 @@ When building your editor component within the Powerhouse ecosystem, you have se
 
 Connect Studio provides a dynamic local environment (`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.
 
-Let's look at a simple example component structure a styling method can be applied.
-
-**Example Component Structure (Base HTML with inline styles)**
-
-<details>
-<summary>Base HTML Example</summary>
-
-Here's a basic editor structure using only standard HTML tags.    
-This demonstrates how elements look with very minimal default styling:
-
-```typescript
-import { EditorProps } from 'document-model';
-// Assuming a simple document model for demonstration
-// import { ExampleDocument, actions } from '../../document-models/example'; 
-
-// Replace with your actual document type props if needed
-export type IProps = EditorProps<any>; 
-
-export default function Editor({ document, dispatch }: IProps) {
-    return (
-        <div>
-            <h1 style={{ fontWeight: 'bold' }}>Document Title</h1>
-            <h2>Document Subtitle</h2>
-            <input 
-                type="text" 
-                placeholder="Small text input"
-                style={{ border: '1px solid gray', marginBottom: '0.5rem' }}
-            />
-            <textarea 
-                placeholder="Large text area" 
-                rows={4}
-                style={{ border: '1px solid gray', display: 'block', marginBottom: '0.5rem' }}
-            />
-            <button style={{ backgroundColor: 'yellow' }}>
-                Submit
-            </button>
-        </div>
-    );
-}
-```
-</details>
-
-*Run `ph connect` to see the default styles applied to components in real-time.*
-
-**Styling with Tailwind CSS**
-
-<details>
-<summary>Tailwind CSS Example</summary>
-
-Now, let's add Tailwind utility classes to the same structure for styling:
-
-```typescript
-import { EditorProps } from 'document-model';
-// import { ExampleDocument, actions } from '../../document-models/example';
-
-export type IProps = EditorProps<any>;
-
-export default function Editor({ document, dispatch }: IProps) {
-    return (
-        <div className="p-4 space-y-4"> {/* Add padding and spacing */}
-            <h1 className="text-2xl font-bold">Document Title</h1> {/* Style heading */}
-            <h2 className="text-lg text-gray-600 mb-4">Document Subtitle</h2> {/* Style subheading */}
-            <input 
-                type="text" 
-                placeholder="Small text input"
-                className="w-full p-2 border rounded focus:outline-none focus:ring-2 focus:ring-blue-500 mb-4" // Style input
-            />
-            <textarea 
-                placeholder="Large text area" 
-                rows={4}
-                className="w-full p-2 border rounded focus:outline-none focus:ring-2 focus:ring-blue-500" // Style textarea
-            />
-            <button className="bg-blue-500 hover:bg-blue-600 text-white px-4 py-2 rounded transition-colors"> {/* Style button */}
-                Submit
-            </button>
-        </div>
-    );
-}
-```
-</details>
-
-*Run `ph connect` to see these Tailwind styles applied in real-time.*
-
-**Styling with a Custom CSS File**
-
-<details>
-<summary>Custom CSS File Example</summary>
-
-You can also import a standard CSS file.
-
-1.  Create a CSS file (e.g., `editor.css`) in the same directory as your `editor.tsx`:
-
-    ```css
-        /* editors/your-editor/editor.css */
-    .editor-container {
-        padding: 1rem;
-        border: 1px solid #ccc;
-        border-radius: 4px;
-    }
-
-    .editor-title {
-        color: rgb(51, 51, 54);
-        font-size: 2rem;
-        margin-bottom: 4px;
-    }
-
-    .editor-subtitle {
-        color: rgb(51, 51, 54);
-        font-size: 1.5rem;
-        margin-bottom: 4px;
-    }
-
-    .editor-button {
-        background-color: green;
-        color: white;
-        padding: 0.5rem 1rem;
-        border: none;
-        border-radius: 4px;
-        cursor: pointer;
-    }
-
-    .editor-button:hover {
-        background-color: darkgreen;
-    }
-    ```
-
-2.  Import the CSS file and use the classes in your component:
-
-```typescript
-  import { EditorProps } from 'document-model';
-// import { ExampleDocument, actions } from '../../document-models/example';
-import './editor.css'; // Import the CSS file
-
-export type IProps = EditorProps<any>;
-
-export default function Editor({ document, dispatch }: IProps) {
-    return (
-        <div className="editor-container"> {/* Use custom class */}
-            <h1 className="editor-title">Document Title</h1> {/* Use custom class */}
-            <h2 className="editor-subtitle">Document Subtitle</h2> {/* Default or other styles */}
-            <input 
-                type="text" 
-                placeholder="Small text input" 
-                className="w-full p-2 border rounded mb-4" // Can mix with Tailwind/defaults
-            />
-            <textarea 
-                placeholder="Large text area" 
-                rows={4} 
-                className="w-full p-2 border rounded mb-4" // Can mix with Tailwind/defaults
-            />
-            <button className="editor-button"> {/* Use custom class */}
-                Submit
-            </button>
-        </div>
-    );
-}  
-```
-</details>
- 
-*Run `ph connect` to see your custom CSS styles applied.*
-
 ---
 
 ## ToDoList Editor
@@ -200,7 +39,7 @@ These are imported from the Powerhouse Document Engineering design system (`@pow
 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.
 
-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:
+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>
@@ -277,7 +116,6 @@ Below is the complete code for the To-Do List editor. It primarily uses Tailwind
 <summary>Complete ToDoList Editor Example (using Tailwind CSS)</summary>
 
 ```typescript
-// Import necessary types and components.
 import { EditorProps } from 'document-model'; // Core type for editor components.
 import {
     ToDoListState,       // Type for the global state of the ToDoList.
@@ -286,10 +124,10 @@ import {
     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.
+} 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.
+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>;
@@ -309,41 +147,68 @@ export default function Editor(props: IProps) {
     // 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-md`: Sets a maximum width (medium size).
-        <div className="container mx-auto p-4 max-w-md">
+        // `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 (4 units). */}
+            {/* `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 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 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 mb-0.5">Remaining</div>
+                            <div className="text-lg font-semibold text-orange-600">{state.stats.unchecked}</div>
+                        </div>
+                    </div>
+                </div>
+            )}
+
             {/* 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 */}
-                <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 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. */}
@@ -373,7 +238,7 @@ export default function Editor(props: IProps) {
             {/* `p-0`: Removes default padding. */}
             <ul className="list-none p-0">
                 {/* Map over the items array in the global state to render each item */}
-                {state.items.map((item: ToDoItem) => (
+                {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).

package/docs/academy/02-MasteryTrack/02-DocumentModelCreation/02-SpecifyTheStateSchema.md

@@ -141,5 +141,5 @@ By completing these steps, you have successfully specified the data structure fo
 
 </details>
 
-For a complete, working example, you can always refer to the [Example ToDoList Repository](./07-ExampleToDoListRepository.md) which contains the full implementation of the concepts discussed in this Mastery Track.
+For a complete, working example, you can always refer to the [Example ToDoList Repository](./ExampleToDoListRepository.md) which contains the full implementation of the concepts discussed in this Mastery Track.
 

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

@@ -132,3 +132,7 @@ Implementing comprehensive tests for your document model reducers is an investme
 *   **Better Collaboration**: Tests clarify the intended behavior of the document model for all team members.
 
 By following the tutorial and applying these best practices, you can build a strong suite of tests that safeguard the integrity and functionality of your document models. This diligence is a hallmark of a "Mastery Track" developer, ensuring that the solutions you build are not just functional but also stable, maintainable, and trustworthy.
+
+## Up Next
+In the next chapter of the Mastery Track you will learn how to implement an editor 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 refer to the [Example ToDoList Repository](./ExampleToDoListRepository.md) which contains the full implementation of the concepts discussed in this Mastery Track.

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

@@ -144,26 +144,69 @@ Storybook allows you to:
     </Form>
     ```
 
-### Creating Local Wrapper Components
-Sometimes, you might want to create local wrapper components in your editor's project to encapsulate specific configurations or behaviors for library components. This was demonstrated in the "Build a ToDoList Editor" tutorial with `Checkbox.tsx` and `InputField.tsx` components, which internally used `BooleanField` and `StringField` from the `@powerhousedao/document-engineering/scalars` library.
+<details>
+<summary>Tutorial: Implementing the `ToDoList` Editor</summary>
 
-**Example: Local `Checkbox` Wrapper (conceptual)**
+## Build a ToDoList 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, 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/to-do-list` folder as `editor.tsx`.
+
+Notice the `--editor` flag which specifies the **ToDoList** document model, and the `--document-types` flag defines the document type `powerhouse/todolist`.
+
+```bash
+ph generate --editor ToDoList --document-types powerhouse/todolist
+```
+
+Once complete, navigate to the `editors/to-do-list/editor.tsx` file and open it in your editor.
+
+
+### 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 (`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.
+
+---
+
+## ToDoList Editor
+
+:::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`).   
+
+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.
+
+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/to-do-list/components/checkbox.tsx
 import { Form, BooleanField } from "@powerhousedao/document-engineering/scalars";
 
-interface CustomCheckboxProps {
+interface CheckboxProps {
   value: boolean;
   onChange: (value: boolean) => void;
-  label?: string; // Added custom prop or passed through
 }
 
-export const Checkbox = ({ value, onChange, label }: CustomCheckboxProps) => {
+export const Checkbox = ({ value, onChange }: CheckboxProps) => {
   return (
-    <Form onSubmit={() => { /* May not be needed for simple checkbox */ }}>
+    <Form onSubmit={() => {}}>
       <BooleanField 
-        name="customChecked" // Internal name for the form field
-        description={label || "Toggle state"} // Use label for description
+        name="checked"
+        description="Check this box to mark the todo as completed"
         value={value}
         onChange={onChange}
       />
@@ -171,31 +214,295 @@ export const Checkbox = ({ value, onChange, label }: CustomCheckboxProps) => {
   );
 };
 ```
-This pattern helps keep your main editor file cleaner and allows for more complex compositions.
+</details>
+
+<details>
+<summary>Inputfield</summary>
+```typescript
+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;
+}
+
+export const InputField = (props: InputFieldProps) => {
+  const { input, value, label, onKeyDown, handleInputChange } = props;
+
+  return (
+    <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);
+        }}
+      />
+    </Form>
+  );
+};
+```
+</details>
 
-## Conceptual Example: Building a ToDoList Editor
 
-Let's consider key aspects of building an editor like the `ToDoList` example:
+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.
+
+<details>
+<summary>Complete ToDoList Editor Example (using Tailwind CSS)</summary>
+
+```typescript
+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 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 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 mb-0.5">Remaining</div>
+                            <div className="text-lg font-semibold text-orange-600">{state.stats.unchecked}</div>
+                        </div>
+                    </div>
+                </div>
+            )}
+
+            {/* 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>
+    );
+}
+```
+</details>
+
+Now you can run the Connect app and see the **ToDoList** editor in action.
+
+```bash
+ph connect
+```
 
-1.  **Input for New Items**:
-    *   Use a local `useState` to manage the text of the new to-do item.
-    *   Use an `InputField` (or a `StringField` from the library) for text entry.
-    *   On "Add" button click or "Enter" key press, `dispatch` an `addTodoItem` action with the current input value.
+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.
 
-2.  **Displaying List Items**:
-    *   Map over `document.state.global.items`.
-    *   For each item, display its `text` and a `Checkbox`.
-    *   The `Checkbox` `value` should be bound to `item.checked`.
-    *   Its `onChange` handler should `dispatch` an `updateTodoItem` action to toggle the `checked` status.
+:::info
+The editor will update dynamically, so you can play around with your editor styling while seeing your results appear in Connect Studio. 
+:::
 
-3.  **Editing Items**:
-    *   Implement local state (`editingItemId`, `editedText`) to manage which item is being edited and its current text.
-    *   Conditionally render either the item text (display mode) or an input field (edit mode).
-    *   When entering edit mode, populate `editedText` with the item's current text.
-    *   On saving the edit (e.g., "Enter" key in the input), `dispatch` an `updateTodoItem` action with the new text.
+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. 
 
-4.  **Deleting Items**:
-    *   Provide a delete button/icon next to each item.
-    *   Its `onClick` handler should `dispatch` a `deleteTodoItem` action with the item's `id`.
+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!
 
-By combining local React state for UI control with dispatched actions for document state mutations, and leveraging the Powerhouse Component Library, you can build powerful and interactive document editors. Always refer to your document model's defined operations and state schema as the source of truth for how data should be structured and modified.
+</details>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powerhousedao/academy",
-  "version": "2.5.0-dev.27",
+  "version": "2.5.0-dev.28",
   "homepage": "https://powerhouse.academy",
   "repository": {
     "type": "git",