@powerhousedao/academy 5.0.0-staging.1 → 5.0.0-staging.11

package/docs/academy/04-APIReferences/05-PHDocumentMigrationGuide.md

@@ -15,6 +15,7 @@ Version 4.0.0 introduced a significant refactor of the `PHDocument` structure th
 The most significant change is the consolidation of document metadata into a `header` field. Previously, document properties were scattered at the root level of the document object.
 
 **Before (v3.2.0 and earlier):**
+
 ```javascript
 const document = {
   id: "doc-123",
@@ -25,10 +26,11 @@ const document = {
   name: "My Todo List",
   slug: "my-todo-list",
   // ... other properties
-}
+};
 ```
 
 **After (v4.0.0):**
+
 ```javascript
 const document = {
   header: {
@@ -41,26 +43,26 @@ const document = {
     slug: "my-todo-list",
     branch: "main",
     sig: { nonce: "", publicKey: {} },
-    meta: {}
+    meta: {},
   },
   // ... other properties
-}
+};
 ```
 
 ## Complete Property Migration Map
 
-| **Old Property** | **New Property** | **Additional Changes** |
-|------------------|------------------|------------------------|
-| `document.id` | `document.header.id` | Now an Ed25519 signature for signed documents |
-| `document.created` | `document.header.createdAtUtcIso` | **Renamed** to include UTC ISO specification |
-| `document.lastModified` | `document.header.lastModifiedAtUtcIso` | **Renamed** to include UTC ISO specification |
-| `document.revision` | `document.header.revision` | Now an **object** with scope keys (e.g., `{ global: 5, local: 0 }`) |
-| `document.documentType` | `document.header.documentType` | No additional changes |
-| `document.name` | `document.header.name` | No additional changes |
-| `document.slug` | `document.header.slug` | No additional changes |
-| `document.branch` | `document.header.branch` | Now explicitly included |
-| `document.meta` | `document.header.meta` | Now explicitly included |
-| N/A | `document.header.sig` | **New** - Signature information for document verification |
+| **Old Property**        | **New Property**                       | **Additional Changes**                                              |
+| ----------------------- | -------------------------------------- | ------------------------------------------------------------------- |
+| `document.id`           | `document.header.id`                   | Now an Ed25519 signature for signed documents                       |
+| `document.created`      | `document.header.createdAtUtcIso`      | **Renamed** to include UTC ISO specification                        |
+| `document.lastModified` | `document.header.lastModifiedAtUtcIso` | **Renamed** to include UTC ISO specification                        |
+| `document.revision`     | `document.header.revision`             | Now an **object** with scope keys (e.g., `{ global: 5, local: 0 }`) |
+| `document.documentType` | `document.header.documentType`         | No additional changes                                               |
+| `document.name`         | `document.header.name`                 | No additional changes                                               |
+| `document.slug`         | `document.header.slug`                 | No additional changes                                               |
+| `document.branch`       | `document.header.branch`               | Now explicitly included                                             |
+| `document.meta`         | `document.header.meta`                 | Now explicitly included                                             |
+| N/A                     | `document.header.sig`                  | **New** - Signature information for document verification           |
 
 ## Step-by-Step Migration Guide
 
@@ -72,6 +74,7 @@ Replace all instances of direct property access with header-based access:
 <summary>**Common Property Access Patterns**</summary>
 
 **Document ID Access:**
+
 ```javascript
 // Before
 const documentId = document.id;
@@ -81,6 +84,7 @@ const documentId = document.header.id;
 ```
 
 **Document Name Access:**
+
 ```javascript
 // Before
 const documentName = document.name;
@@ -90,6 +94,7 @@ const documentName = document.header.name;
 ```
 
 **Document Type Access:**
+
 ```javascript
 // Before
 const docType = document.documentType;
@@ -99,6 +104,7 @@ const docType = document.header.documentType;
 ```
 
 **Timestamp Access:**
+
 ```javascript
 // Before
 const created = document.created;
@@ -110,6 +116,7 @@ const lastModified = document.header.lastModifiedAtUtcIso;
 ```
 
 **Revision Access:**
+
 ```javascript
 // Before
 const revision = document.revision; // Was a number
@@ -135,11 +142,13 @@ const allRevisions = document.header.revision; // { global: 5, local: 0, ... }
 function DocumentList({ documents }) {
   return (
     <div>
-      {documents.map(doc => (
+      {documents.map((doc) => (
         <div key={doc.id} className="document-item">
           <h3>{doc.name}</h3>
           <p>Type: {doc.documentType}</p>
-          <p>Last modified: {new Date(doc.lastModified).toLocaleDateString()}</p>
+          <p>
+            Last modified: {new Date(doc.lastModified).toLocaleDateString()}
+          </p>
           <p>Revision: {doc.revision}</p>
         </div>
       ))}
@@ -151,11 +160,14 @@ function DocumentList({ documents }) {
 function DocumentList({ documents }) {
   return (
     <div>
-      {documents.map(doc => (
+      {documents.map((doc) => (
         <div key={doc.header.id} className="document-item">
           <h3>{doc.header.name}</h3>
           <p>Type: {doc.header.documentType}</p>
-          <p>Last modified: {new Date(doc.header.lastModifiedAtUtcIso).toLocaleDateString()}</p>
+          <p>
+            Last modified:{" "}
+            {new Date(doc.header.lastModifiedAtUtcIso).toLocaleDateString()}
+          </p>
           <p>Global Revision: {doc.header.revision.global}</p>
         </div>
       ))}
@@ -218,16 +230,17 @@ interface MyDocument {
 <summary>**GraphQL Query Compatibility**</summary>
 
 **GraphQL Queries:**
+
 ```graphql
 # Your existing queries continue to work unchanged
 query GetDocument($id: ID!) {
   document(id: $id) {
-    id              # Still works due to response transformation
-    name            # Still works due to response transformation
-    documentType    # Still works due to response transformation
-    created         # Still works due to response transformation
-    lastModified    # Still works due to response transformation
-    revision        # Still works due to response transformation
+    id # Still works due to response transformation
+    name # Still works due to response transformation
+    documentType # Still works due to response transformation
+    created # Still works due to response transformation
+    lastModified # Still works due to response transformation
+    revision # Still works due to response transformation
   }
 }
 ```
@@ -238,10 +251,6 @@ query GetDocument($id: ID!) {
 
 </details>
 
-
-
-
-
 ## Common Migration Issues and Solutions
 
 ### Issue 1: Undefined Property Errors
@@ -299,15 +308,15 @@ Create tests to verify your migration:
 
 ```javascript
 // Test document property access
-describe('Document Migration', () => {
-  it('should access document properties correctly', () => {
+describe("Document Migration", () => {
+  it("should access document properties correctly", () => {
     const mockDocument = {
       header: {
-        id: 'test-id',
-        name: 'Test Document',
-        documentType: 'powerhouse/test',
-        createdAtUtcIso: '2023-01-01T00:00:00.000Z',
-        lastModifiedAtUtcIso: '2023-01-01T12:00:00.000Z',
+        id: "test-id",
+        name: "Test Document",
+        documentType: "powerhouse/test",
+        createdAtUtcIso: "2023-01-01T00:00:00.000Z",
+        lastModifiedAtUtcIso: "2023-01-01T12:00:00.000Z",
         revision: { global: 5, local: 0 },
         // ... other header properties
       },
@@ -315,8 +324,8 @@ describe('Document Migration', () => {
     };
 
     // Test property access
-    expect(mockDocument.header.id).toBe('test-id');
-    expect(mockDocument.header.name).toBe('Test Document');
+    expect(mockDocument.header.id).toBe("test-id");
+    expect(mockDocument.header.name).toBe("Test Document");
     expect(mockDocument.header.revision.global).toBe(5);
   });
 });
@@ -324,8 +333,6 @@ describe('Document Migration', () => {
 
 </details>
 
-
-
 ## Related Documentation
 
 - [PHDocument Architecture](/academy/Architecture/PowerhouseArchitecture)
@@ -334,4 +341,4 @@ describe('Document Migration', () => {
 
 ---
 
-*This migration guide covers the major changes in v4.0.0. For additional technical details, refer to the [RELEASE-NOTES.md](https://github.com/powerhouse-dao/powerhouse/blob/main/RELEASE-NOTES.md) in the main repository.* 
+_This migration guide covers the major changes in v4.0.0. For additional technical details, refer to the [RELEASE-NOTES.md](https://github.com/powerhouse-dao/powerhouse/blob/main/RELEASE-NOTES.md) in the main repository._

package/docs/academy/04-APIReferences/_category_.json

@@ -1,7 +1,7 @@
 {
-    "label": "API References",
-    "link": {
-      "type": "generated-index",
-      "description": "A reference for the Powerhouse API."
-    }
-  }
+  "label": "API References",
+  "link": {
+    "type": "generated-index",
+    "description": "A reference for the Powerhouse API."
+  }
+}

package/docs/academy/05-Architecture/00-PowerhouseArchitecture.md

@@ -14,7 +14,6 @@ Each application is designed to be modular yet complementary, ensuring smooth da
 
 ![Powerhouse Host Apps Interaction](./images/PowerhouseArchitecture.png)
 
-
 ## How the Five Applications Work Together
 
 The Powerhouse ecosystem functions as a decentralized operating system, where each of the four core applications works in synergy to ensure seamless collaboration, structured data management, and automated workflows. Each application has a distinct purpose, yet their interconnectivity is what makes the system powerful.
@@ -50,4 +49,4 @@ Renown is the trust and identity layer, ensuring security, reputation tracking,
 
 - It acts as the authentication gateway, determining who has permission to view, edit, or execute specific operations within the system.
 - Every action performed in Connect is tracked in the document history, making it fully auditable through Switchboard.
-- Fusion utilizes Renown to verify contributor credibility, ensuring that data-driven decisions are based on trusted and authenticated inputs.
+- Fusion utilizes Renown to verify contributor credibility, ensuring that data-driven decisions are based on trusted and authenticated inputs.

package/docs/academy/05-Architecture/01-WorkingWithTheReactor.md

@@ -2,15 +2,15 @@
 
 :::tip
 Document models are the common design pattern that is used for all documents and files.  
-DocSync is a decentralized synchronization protocol that is storage agnostic.  
+DocSync is a decentralized synchronization protocol that is storage agnostic.
 
 **Document Models** are _what_ is synced and **DocSync** is _how_ document models are synced.  
-But who is doing the syncing?  
+But who is doing the syncing?
 
 We call these participants **Reactors**.
 :::
 
-### Powerhouse Reactors 
+### Powerhouse Reactors
 
 **What is a Reactor?**
 Powerhouse Reactors are the nodes in the network that store documents, 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. A Reactor is essentially a storage node used in Powerhouse's framework to handle documents and traditional files. It supports multiple storage solutions, including:
@@ -20,29 +20,32 @@ Powerhouse Reactors are the nodes in the network that store documents, resolve c
 - **Decentralized Storage**: Such as Ceramic or IPFS, enabling distributed and blockchain-based storage options.
 
 ### Core Functions of Reactors
+
 - **Data Synchronization**: Reactors ensure that all data, whether local or distributed, remains up-to-date and consistent across the system.
 - **Modular Storage Adapters**: They support integration with different storage backends depending on organizational needs.
 - **Collaboration Support**: Reactors facilitate document sharing and peer-to-peer collaboration across contributors within the network.
 
 :::tip
-The DocSync protocol *sends updates from one reactor to another* - **smashing document operations into one another** - to ensure all data is synced.
+The DocSync protocol _sends updates from one reactor to another_ - **smashing document operations into one another** - to ensure all data is synced.
 :::
 
 A **reactor** is responsible for storing data and resolving merge conflicts.  
-Editing data and submitting new operations must be done through Powerhouse's native applications (Connect, Switchboard, Fusion). Each instance of these applications contains a Reactor that is responsible for storing data and syncing data through DocSync. In other words, Powerhouse applications are how Reactors can be accessed, manipulated, steered, visualized and modified. A local Connect desktop application's reactor can therefore sync with the Reactor of a remote drive (e.g. Switchboard instance). 
+Editing data and submitting new operations must be done through Powerhouse's native applications (Connect, Switchboard, Fusion). Each instance of these applications contains a Reactor that is responsible for storing data and syncing data through DocSync. In other words, Powerhouse applications are how Reactors can be accessed, manipulated, steered, visualized and modified. A local Connect desktop application's reactor can therefore sync with the Reactor of a remote drive (e.g. Switchboard instance).
 
 <img src="/img/Powerhouse Website Drive.png" alt="Powerhouse Storage Layer"/>
 
 ### Why Are Reactors Important?
+
 They are key to ensuring the scalability and resilience of decentralized operations.
 By acting as the backbone for document models in the Powerhouse framework, they enable seamless version control and event-driven updates.
 Reactors provide the foundation for advanced features like real-time collaboration, history tracking, and decentralized audits.
 This modular, flexible infrastructure enables organizations to build efficient and robust decentralized systems, tailored for modern network organizations
 
 ## Configuring your reactor
- 
-In addition to the choice of storage, Reactors also have other configurations. 
-- The **operational data** and **read models** associated with the document models inside a reactor allow to query the gathered data inside a document model or quickly visualize the crucial insights at a glance. 
+
+In addition to the choice of storage, Reactors also have other configurations.
+
+- The **operational data** and **read models** associated with the document models inside a reactor allow to query the gathered data inside a document model or quickly visualize the crucial insights at a glance.
 - **Listeners**, which continuously listen to any changes in a document model, help us to connect additional tools such as codegenerators and scripts to the reactors and the document models it holds
 
 > Jump to: Configure a listener for your reactor and add a codegenerator

package/docs/academy/05-Architecture/05-DocumentModelTheory/_category_.json

@@ -5,4 +5,4 @@
     "type": "generated-index",
     "description": "Intro to Document Models"
   }
-}
+}

package/docs/academy/05-Architecture/_category_.json

@@ -1,7 +1,7 @@
 {
-    "label": "Architecture",
-    "link": {
-      "type": "generated-index",
-      "description": "Learn about the architecture of Powerhouse."
-    }
-  }
+  "label": "Architecture",
+  "link": {
+    "type": "generated-index",
+    "description": "Learn about the architecture of Powerhouse."
+  }
+}

package/docs/academy/06-ComponentLibrary/00-DocumentEngineering.md

@@ -1,19 +1,19 @@
 # Document-Engineering
 
-The reusable components in the Document-Engineering system are a set of of front-end components based on graphQL scalars. 
+The reusable components in the Document-Engineering system are a set of of front-end components based on graphQL scalars.
 Powerhouse also has a set of custom scalars that are not part of the graphQL standard but are specific to the web3 ecosystem.
-These components are offered through the **Powerhouse Document-Engineering system** with the help of storybook & the Academy documentation. 
+These components are offered through the **Powerhouse Document-Engineering system** with the help of storybook & the Academy documentation.
 
-It provides a collection of pre-built, reusable UI components designed for consistency and efficiency across Powerhouse applications and editors. Think of it as a toolkit of standard UI elements like buttons, inputs, and checkboxes with many of these components based on graphql scalars. 
+It provides a collection of pre-built, reusable UI components designed for consistency and efficiency across Powerhouse applications and editors. Think of it as a toolkit of standard UI elements like buttons, inputs, and checkboxes with many of these components based on graphql scalars.
 
 :::info
-A GraphQL scalar is essentially a primitive, indivisible value in the GraphQL type system. 
+A GraphQL scalar is essentially a primitive, indivisible value in the GraphQL type system.
 Here are the key points to understand:
 
 - **Basic Building Blocks:** Scalars are the basic data types—like String, Int, Float, Boolean, and ID—that represent atomic values.
 - **Leaf Nodes:** Scalars are the "leaves" of a GraphQL query. They can't have any sub-fields, meaning once you hit a scalar in a query, that's the final value.
-- **Custom Scalars:** Besides the built-in scalars, you can define custom scalars (e.g., a Date type) if you need to handle more specific formats or validations. Powerhouse does this specific for the web3 ecosystem. 
-:::
+- **Custom Scalars:** Besides the built-in scalars, you can define custom scalars (e.g., a Date type) if you need to handle more specific formats or validations. Powerhouse does this specific for the web3 ecosystem.
+  :::
 
 ## What are Components?
 
@@ -43,7 +43,7 @@ There are two applications of scalar components in the document model workflow:
 
 These are specialized form components, each corresponding to a GraphQL scalar type (e.g., String, Number, Boolean, Currency, PHID). They are built on top of react-hook-form, offering out-of-the-box validation but must be wrapped with a Form component in order to work properly.
 
-**Location:** @powerhousedao/document-engineering/scalars    
+**Location:** @powerhousedao/document-engineering/scalars  
 https://github.com/powerhouse-inc/document-engineering
 
 **Key Feature**: Must be used within a Form component provided by this library.
@@ -52,7 +52,7 @@ https://github.com/powerhouse-inc/document-engineering
 
 This category includes a broader range of UI elements such as simplified versions of the Scalar components (which don't require a Form wrapper but lack built-in validation), as well as other versatile components like Dropdown, Tooltip, Sidebar, ObjectSetTable and more. These are designed for crafting diverse and complex user interfaces.
 
-**Location:** @powerhousedao/document-engineering/ui   
+**Location:** @powerhousedao/document-engineering/ui  
 https://github.com/powerhouse-inc/document-engineering
 
 ## Component Types Classification
@@ -60,18 +60,22 @@ https://github.com/powerhouse-inc/document-engineering
 Inspired by atomic design methodology, Powerhouse classifies components into the following categories:
 
 ### Fragment
+
 The smallest element that combined together makes up a scalar or other simple component.
 **Examples:** Character counter, Checkbox field, Label
 
 ### Scalar (Simple Component)
+
 The simplest component that contains the basic input field for one-dimensional data type (single value).
 **Examples:** Integer, Boolean, String, Powerhouse ID (PHID)
 
 ### Complex Component
+
 Compound component that has an object/array value. It's made up of multiple scalars combined to serve a specific function.
 **Examples:** Sidebar (tree structure navigation component with content-style navigation for hierarchical data)
 
 ### Layout Component
+
 Purpose-specific container for other components like lists of other components, color layouts, sections, etc.
 **Examples:** Homepage section layout
 
@@ -81,16 +85,16 @@ The Powerhouse team is building a Component library with a wide range of compone
 
 ## Component Behavior & UX Principles
 
-Besides the ability to input data, components have another crucial utility: they describe the mechanism of user interaction through implementing a defined set of behavior rules. 
+Besides the ability to input data, components have another crucial utility: they describe the mechanism of user interaction through implementing a defined set of behavior rules.
 
 **Best Practices for Component Behavior:**
+
 - Implementing behaviors at a component level is much more efficient than at the document level
 - Good component behavior feels natural to the user and is easily understood
 - Components should be intuitive and not require additional tutorials or explanations
 - Start with the most simple/basic behaviors first, then layer additional behaviors on top
 - Keep behaviors as simple as needed - less is more
 
-
 ## Exploring Components with Storybook
 
 We use Storybook as an interactive catalog for our design system components. It allows you to visually explore each component, interact with different states, and understand how to integrate them into your projects. [https://storybook.powerhouse.academy](https://storybook.powerhouse.academy)
@@ -112,13 +116,13 @@ Let's walk through the typical workflow for using a component from the document-
 
 1.  **Identify the Need:** While building your feature (e.g., the To-do List editor in `editor.tsx`), you determine the need for a standard UI element, like a checkbox.
 2.  **Consult the Document Engineering Components in Storybook:**
-    *   Open the Powerhouse Storybook instance. [https://storybook.powerhouse.academy](https://storybook.powerhouse.academy)
-    *   Navigate or search to find the `Checkbox` component.
-    *   Review the visual examples and interactive demo.
-    *   Examine the "Usage" snippet and the **Props table** to understand the basic implementation and available configuration options (`label`, `value`, `onChange`, etc.).
+    - Open the Powerhouse Storybook instance. [https://storybook.powerhouse.academy](https://storybook.powerhouse.academy)
+    - Navigate or search to find the `Checkbox` component.
+    - Review the visual examples and interactive demo.
+    - Examine the "Usage" snippet and the **Props table** to understand the basic implementation and available configuration options (`label`, `value`, `onChange`, etc.).
 3.  **Import the Component:** In your code editor, open the relevant file (e.g., `editors/to-do-list/editor.tsx`). Add an import statement at the top to bring the component into your file's scope:
     ```typescript
-    import { Checkbox } from '@powerhousedao/document-engineering/scalars';
+    import { Checkbox } from "@powerhousedao/document-engineering/scalars";
     // Or import other components as needed:
     // import { Checkbox, InputField, Button } from '@powerhousedao/document-engineering/scalars';
     ```
@@ -128,9 +132,9 @@ Let's walk through the typical workflow for using a component from the document-
     // Example from the To-do List Editor:
     <Checkbox
         // Bind the checked state to data within editor.tsx
-        value={item.checked} 
+        value={item.checked}
         // Provide a function from editor.tsx to handle changes
-        onChange={() => { 
+        onChange={() => {
             dispatch(actions.updateTodoItem({
                 id: item.id,
                 checked: !item.checked,
@@ -179,7 +183,7 @@ import { ... } from '@powerhousedao/document-engineering/graphql';
 To include the package's styles:
 
 ```typescript
-import '@powerhousedao/document-engineering/style.css';
+import "@powerhousedao/document-engineering/style.css";
 ```
 
 ## Import Maps
@@ -188,14 +192,12 @@ Within the project, the following import maps are available:
 
 - `#assets` - Assets utilities and components
 - `#scalars` - Scalar transformations and utilities
-- `#ui` - UI components 
+- `#ui` - UI components
 - `#graphql` - GraphQL related utilities
 
-Please don't hesitate to reach out in our discord channels with any questions.    
-Happy designing! 
+Please don't hesitate to reach out in our discord channels with any questions.  
+Happy designing!
 
 ### Up next: Create Custom Scalars
 
 You can learn how to do so in our guide on [Creating Custom Scalars](/academy/ComponentLibrary/CreateCustomScalars).
-
-