@powerhousedao/academy 2.5.0-dev.4 → 2.5.0-dev.40

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

@@ -6,7 +6,8 @@ At Powerhouse, frontend development for document editors follows a simple and fa
 
 ### Development Environment
 
-Connect Studio is your primary tool for development. When you run `ph connect`, it provides a dynamic, local environment where you can define and preview your document models and their editors live. This replaces the need for tools like Storybook for editor development, though Storybook remains invaluable for exploring the [Powerhouse Component Library](#powerhouse-component-library).
+Connect Studio is your primary tool for development.   
+When you run `ph connect`, it provides a dynamic, local environment where you can define and preview your document models and their editors live. This replaces the need for tools like Storybook for editor development, though Storybook remains invaluable for exploring the [Powerhouse Component Library](#powerhouse-component-library).
 
 Key aspects of the Powerhouse development environment:
 - **React Foundation**: Build your editor UIs using React components, just as you would in any standard React project.
@@ -20,7 +21,8 @@ Powerhouse aims to keep your developer experience clean, familiar, and focused:
 
 ### Generating Your Editor Template
 
-To kickstart your editor development, Powerhouse provides a command to generate a basic editor template. This command reads your document model definition and creates the initial `editor.tsx` file.
+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/todolist`:
 ```bash
@@ -72,40 +74,6 @@ You have several options for styling your editor components:
 
 Choose the method or combination of methods that best suits your project needs and team preferences. Connect Studio (`ph connect`) will allow you to see your styles applied in real-time.
 
-<details>
-<summary>Refresher on React Hooks</summary>
-
-All of the Powerhouse React Hooks can be found here: [Powerhouse React Hooks API Reference](docs/academy/APIReferences/ReactHooks)
-
-React Hooks allow you to use various React features directly within your functional components. You can use built-in Hooks or combine them to create your own custom Hooks.
-
-**What are Custom Hooks?**
-A custom hook is a JavaScript function whose name starts with "use" and that calls other Hooks. They are used to:
-- Reuse stateful logic between components.
-- Abstract complex logic into a simpler interface.
-- Isolate side effects, particularly those managed by `useEffect`.
-
-**Key Built-in Hooks Examples:**
-- `useState`: Lets a component "remember" information (state).
-- `useEffect`: Lets a component perform side effects (e.g., data fetching, subscriptions, manually changing the DOM).
-- `useContext`: Lets a component receive information from distant parent components without explicitly passing props through every level of the component tree.
-
-**Naming Convention:**
-Hook names must always start with `use` followed by a capital letter (e.g., `useState`, `useOnlineStatus`).
-
-**Rules of Hooks:**
-1.  **Only Call Hooks at the Top Level**: Don't call Hooks inside loops, conditions, or nested functions.
-2.  **Only Call Hooks from React Functions**: Call Hooks from React functional components or from custom Hooks.
-
-It's important to note that a function should only be named and treated as a hook if it actually utilizes one or more built-in React hooks. If a function (even if named `useSomething`) doesn't call any built-in hooks, it behaves like a regular JavaScript function, and making it a "hook" offers no specific React advantages.
-
-For more details, see the official documentation and our API reference:
-- [Reusing Logic with Custom Hooks (react.dev)](https://react.dev/learn/reusing-logic-with-custom-hooks)
-- [Rules of Hooks (react.dev)](https://react.dev/reference/rules/rules-of-hooks)
-- [Powerhouse React Hooks API Reference](docs/academy/APIReferences/ReactHooks)
-
-</details>
-
 ### State Management in Editors
 
 When you build an editor in Powerhouse, your main editor component receives `EditorProps`. These props are crucial for interacting with the document:
@@ -176,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>
+
+## 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.
 
-**Example: Local `Checkbox` Wrapper (conceptual)**
+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}
       />
@@ -203,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>
+
+
+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>
 
-## Conceptual Example: Building a ToDoList Editor
+Now you can run the Connect app and see the **ToDoList** editor in action.
 
-Let's consider key aspects of building an editor like the `ToDoList` example:
+```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.
+</details>
 
-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`.
+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. 
 
-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.
+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!

package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/02-ConfiguringDrives.md

@@ -2,12 +2,13 @@
 
 A drive in Powerhouse is a container or a wrapper for documents and data. It's a place where you can organize and store your documents and share them with others. This guide will walk you through the process of configuring and managing drives in your Powerhouse environment.   
 
-## Prerequisites
+:::info **Prerequisites**
 
 Before configuring a drive, ensure you have:
 - Powerhouse [CLI installed](/academy/MasteryTrack/BuilderEnvironment/BuilderTools)
 - Access to a Powerhouse instance
 - Appropriate permissions to create and manage drives
+:::
 
 ## Understanding Drives
 
@@ -23,7 +24,7 @@ Remote drives in Powerhouse allow you to connect to and work with data stored in
 - **Cloud Storage**: For centralized, scalable data management.
 - **Decentralized Storage**: Such as Ceramic or IPFS, enabling distributed and blockchain-based storage options.
 
-:::tip
+:::tip **Explainer**
 **Powerhouse Reactors** are the nodes in the network that store and synchronise documents & drives , resolve conflicts and rerun operations to verify document event histories. 
 Reactors can be configured for local storage, centralized cloud storage or on a decentralized storage network. 
 
@@ -57,10 +58,11 @@ To create a new drive in Powerhouse, follow these steps:
 
 You can also add a new remote drive to your Connect environment programmatically using GraphQL mutations. This is especially useful for automation, scripting, or integrating with external systems.
 
-### Prerequisites
+:::info **Prerequisites**
 - Access to the Switchboard or remote reactor (server node) of your Connect instance.
 - The GraphQL endpoint for your instance. For example, for the staging environment, use: `https://staging.switchboard.phd/graphql/system` (this is a supergraph gateway).
 - Appropriate permissions to perform mutations.
+:::
 
 ### Steps
 1. **Navigate to the GraphQL Playground or use a GraphQL client**

package/docs/academy/02-MasteryTrack/05-Launch/02-PublishYourProject.md

@@ -145,9 +145,10 @@ This command will **build** the project and create a build directory with the ou
 
 This command will **start a local server** and serve the build output.
 Inspect the build output and verify that the document models are working correctly.
+Instead of `pnpm serve`, we'll be using: 
 
 ```bash
-pnpm serve (Not working yet)
+ph connect
 ```
 
 ### 1.4 Storing your project in a git repository
@@ -202,15 +203,79 @@ If you're publishing a package under a scope (like @your-org/my-package), you mi
 }
 ```
 
-For the actual publishing step, run the following command to publish your project to the npm registry:
+### 2.1 Versioning, Tagging, and Publishing Your Package
+
+Before publishing, it's crucial to version your package correctly and tag the release in your Git repository. This helps track changes and allows users to depend on specific versions.
+
+**1. Versioning with PNPM**
+
+Use the `pnpm version` command to update your package version according to semantic versioning rules (`patch` for bugfixes, `minor` for new features, `major` for breaking changes). This command will:
+- Update the `version` in your `package.json`.
+- Create a Git commit for the version change.
+- Create a Git tag for the new version (e.g., `v1.0.1`).
+
+```bash
+# For a patch release (e.g., from 1.0.0 to 1.0.1)
+pnpm version patch
+
+# For a minor release (e.g., from 1.0.1 to 1.1.0)
+pnpm version minor
+
+# For a major release (e.g., from 1.1.0 to 2.0.0)
+pnpm version major
+```
+Take note of the new version tag created (e.g., `v1.0.1`), as you'll need it in the next step.
+
+**2. Pushing Changes to Git**
+
+Next, push your commits and the new version tag to your remote Git repository:
+
+```bash
+# Push your current branch (e.g., main or master)
+# Replace 'main' with your default branch name if different
+git push origin main
+
+# Push the specific tag created by pnpm version
+# Replace vX.Y.Z with the actual tag name (e.g., v1.0.1)
+git push origin vX.Y.Z
+```
+The specific tag name (e.g., `v1.0.1`) is usually output by the `pnpm version` command. Pushing the specific tag is recommended to avoid unintentionally pushing other local tags.
+
+Alternatively, to push all new local tags (use with caution):
+```bash
+# git push --tags
+```
+
+**3. Understanding Git Tags vs. NPM Distributor Tags**
+
+It's important to distinguish between Git tags and NPM distributor tags (dist-tags):
+
+-   **Git Tags**: These are markers in your Git repository's history. They are primarily for developers to pinpoint specific release versions in the codebase (e.g., `v1.0.0`, `v1.0.1`). The `pnpm version` command creates these.
+-   **NPM Distributor Tags (dist-tags)**: These are labels used by the NPM registry to point to specific published versions of your package. Common NPM tags include:
+    -   `latest`: This is the default tag. When someone runs `pnpm install my-package`, NPM installs the version tagged as `latest`.
+    -   `beta`, `next`, `alpha`: Often used for pre-release versions.
+    When you publish a package without specifying an NPM tag, it usually gets the `latest` tag by default.
+
+**4. Publishing to NPM**
+
+Now you are ready to publish your package to the NPM registry. Ensure you are logged into NPM (the `npm login` command shown in previous steps should be used, or `pnpm login` which is an alias).
+
+```bash
+pnpm publish
+```
+This command will publish the version of your package that is currently specified in your `package.json`. By default, this will also set the `latest` NPM dist-tag for this version.
+
+If your package is scoped (e.g., `@your-org/my-package`) and intended to be public, ensure your `package.json` includes the `publishConfig` shown earlier. If this is not set in `package.json` (and your package is scoped), you might need to use:
 ```bash
-npm publish
+pnpm publish --access public
 ```
 
-Optionally, if you are publishing a scoped package and you want it public, run:
+You can also publish a version to a specific NPM dist-tag. For example, to publish a beta version:
 ```bash
-npm publish --access public
+# Ensure your package.json version reflects the beta (e.g., 1.1.0-beta.0)
+pnpm publish --tag beta
 ```
+This is useful for testing releases before making them `latest`.
 
 Now let's verify that the package(s) get published in the package repository, next to pre-existing packages that you might have been publishing before.