@powerhousedao/academy 2.5.0-dev.20 → 2.5.0-dev.22

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+## 2.5.0-dev.22 (2025-06-13)
+
+### 🩹 Fixes
+
+- **ci:** set proper tags for docker images ([3cab91969](https://github.com/powerhouse-inc/powerhouse/commit/3cab91969))
+- **ci:** connect deployment ([8ac8e423b](https://github.com/powerhouse-inc/powerhouse/commit/8ac8e423b))
+
+### ❤️ Thank You
+
+- Frank
+
+## 2.5.0-dev.21 (2025-06-12)
+
+This was a version bump only for @powerhousedao/academy to align it with other projects, there were no code changes.
+
 ## 2.5.0-dev.20 (2025-06-12)
 
 This was a version bump only for @powerhousedao/academy to align it with other projects, there were no code changes.

package/docs/academy/02-MasteryTrack/02-DocumentModelCreation/01-WhatIsADocumentModel.md

@@ -116,7 +116,7 @@ Every operation applied to a document is **stored as an event** in an append-onl
 
 ## **2. How Document Models Work Technically**
 
-Document models in Powerhouse rely on **event-driven architecture, event sourcing, and CQRS principles**. Here’s a step-by-step breakdown:
+Document models in Powerhouse rely on **event-driven architecture, event sourcing, and CQRS principles**. Here's a step-by-step breakdown:
 
 ### **2.1 Document Creation**
 
@@ -190,4 +190,8 @@ Document Models offer a range of features that can be leveraged to create sophis
 
 - **Version Control**: Similar to how Git manages changes to source code, Document Models in Connect will support version control, enabling users to track changes, compare different versions, and ensure data integrity over time.
 
-Document Models are a powerful primitive within the Powerhouse vision, offering a flexible, structured, and efficient way to manage business logic and data. 
+Document Models are a powerful primitive within the Powerhouse vision, offering a flexible, structured, and efficient way to manage business logic and data. 
+
+### Up Next: How to build a Document Model
+
+In the next chapters, we'll teach you how to build a ToDoList document model while explaining all of the theory that is involved. 

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

@@ -21,6 +21,8 @@ GraphQL has a set of built-in **scalar types**:
 *   `Boolean`: `true` or `false`.
 *   `ID`: A unique identifier, often used as a key for a field. It is serialized in the same way as a String; however, it is not intended to be human-readable.
 
+In addition to these standard types, the Powerhouse Document-Engineering system introduces custom scalars that are linked to reusable front-end components. These scalars are tailored for the web3 ecosystem and will be explored in the Component Library section of the documentation.
+
 ### Lists and Non-Null
 You can modify types using lists and non-null indicators:
 *   **Lists**: To indicate that a field will return a list of a certain type, you wrap the type in square brackets, e.g., `[ToDoItem!]!`. This means the field `items` in `ToDoListState` will be a list of `ToDoItem` objects.
@@ -70,3 +72,6 @@ type ToDoItem {
 6.  **Root State Type**: It's a common pattern to have a single root type for your document state (e.g., `ToDoListState`). This provides a clear entry point for accessing all document data.
 
 By carefully defining your state schema, you lay a solid foundation for your Powerhouse document model, making it robust, maintainable, and easy to work with. The schema dictates not only how data is stored but also how it can be queried and mutated through operations, which will be covered in the next section.
+
+At the end of this Document Model Creation Chapter you will find the ToDoList Repository where you can explore the code and implementation of all the items we have discussed. 
+You'll be able to run the advanced ToDoList in Connect Studio and explore the reducers and editor code. 

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

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

@@ -1,8 +1,8 @@
 # Document-Engineering
 
-The reusable components in the Document-Engineering design 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 design 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. 
 
@@ -19,29 +19,19 @@ In the next few chapters of our documentation, we will start with the simplest s
 
 ## **3 types of components**
 
-1. **Simple Component** has a scalar value as input 
+1. **Scalar Component** has a simple scalar value as input 
     - Component, Composition of smaller UI controls (e.g. Scalar component)
-    
 2. **Complex Component** has an object/array value 
     - Group of components (e.g. sidebar tree view)
-    
 3. **Layout Component** will contain other components 
     - Containers for other components, Sections (e.g. list of other components, color layouts, etc.)
+4. **fragments Component** 
 
-The documentation of each of the reusable components in the Academy documentation will be structured as follows:
-
-1. **Component Context**
-2. **Scalar Definition**
-3. **Component Storybook Base Example**
-    - Component Code
-    - Component Default Props
-4. **Component Storybook Usage Examples**
+For each of these components an implementation example will be given in our documentation. 
 
 ## 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)
+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)
 
 **Understanding the Storybook Interface:**
 
@@ -54,8 +44,8 @@ We use Storybook as an interactive catalog for our design system components. It
 Let's walk through the typical workflow for using a component from the document-engineering system, using the `Checkbox` from the [To-do List editor](/academy/GetStarted/BuildToDoListEditor).
 
 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 Resuable Components in Academy or in Storybook:**
-    *   Open the Powerhouse Storybook instance.
+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.).
@@ -85,10 +75,66 @@ Let's walk through the typical workflow for using a component from the document-
     You configure the component's appearance and behavior by passing the appropriate values to its props.
 5.  **Test and Refine:** Run your application (e.g., using `ph connect`) to see the component in context. Verify its appearance and functionality.
 
-**Storybook vs. Source Code:**
+## Usage
+
+The Document Engineering package provides several entry points for different use cases in your powerhouse project:
+
+### Main Package
+
+```typescript
+import { ... } from '@powerhousedao/document-engineering';
+```
+
+### UI Components
+
+```typescript
+import { ... } from '@powerhousedao/document-engineering/ui';
+```
+
+### Scalars
+
+For data manipulation and transformation utilities:
+
+```typescript
+import { ... } from '@powerhousedao/document-engineering/scalars';
+```
+
+### GraphQL
+
+For GraphQL related utilities and schema definitions:
+
+```typescript
+import { ... } from '@powerhousedao/document-engineering/graphql';
+```
+
+### Styles
+
+To include the package's styles:
+
+```typescript
+import '@powerhousedao/document-engineering/style.css';
+```
+
+## Import Maps
+
+Within the project, the following import maps are available:
+
+- `#assets` - Assets utilities and components
+- `#scalars` - Scalar transformations and utilities
+- `#ui` - UI components 
+- `#graphql` - GraphQL related utilities
+
+
+## **Storybook vs. Source Code:**
 
 Storybook serves as essential documentation and a usage guide. Our developers write Storybook "stories" to demonstrate components and document their common props. However, the **ultimate source of truth** for a component's capabilities is its actual source code (e.g., the `.tsx` file within the `@powerhousedao/document-engineering/scalars` package).
 While Storybook aims for accuracy, there might occasionally be discrepancies or undocumented props.
 
-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).
+
+

package/docs/academy/06-ComponentLibrary/02-CreateCustomScalars.md

@@ -0,0 +1,403 @@
+# Step 1: Create Custom Scalars
+
+This tutorial provides step-by-step instructions for creating custom scalars & components, and to contributing to the document-engineering project.
+The github repo for the Document-Engineering can be found [here](https://github.com/powerhouse-inc/document-engineering/tree/main)
+
+:::info
+When contributing as an open source developer please submit a pull request to the Powerhouse team. 
+Although a design or UI for your scalar is not mandatory, it definitely helps reviewers if there's a visual reference. 
+That said, not all scalars require a dedicated UI component. 
+Some scalars, like scalar Title or scalar Description, might both map to a string and use the same UI, in this case scalars plays more semantic role than a type definition.
+:::
+
+## Table of Contents
+
+- [Creating New GraphQL Scalars](#creating-new-graphql-scalars)
+  - [Step 1: Create the Scalar File](#step-1-create-the-scalar-file)
+    - [Key Components to Update](#key-components-to-update)
+  - [Step 2: Register the Scalar in scalars.ts](#step-2-register-the-scalar-in-scalarts)
+    - [2.1 Add Namespace Import](#21-add-namespace-import)
+    - [2.2 Add Type Export](#22-add-type-export)
+    - [2.3 Add to Export Object](#23-add-to-export-object)
+    - [2.4 Add to Custom Scalars](#24-add-to-custom-scalars)
+    - [2.5 Add to Resolvers](#25-add-to-resolvers)
+    - [2.6 Add to Type Definitions](#26-add-to-type-definitions)
+    - [2.7 Add to Generator Type Definitions](#27-add-to-generator-type-definitions)
+    - [2.8 Add to Validation Schema](#28-add-to-validation-schema)
+  - [Step 3: Create Tests for Your Scalar](#step-3-create-tests-for-your-scalar)
+    - [Required Test Cases](#required-test-cases)
+    - [Testing Best Practices](#testing-best-practices)
+    - [Example Edge Cases for Different Scalar Types](#example-edge-cases-for-different-scalar-types)
+  - [Step 4: Validate Your Implementation](#step-4-validate-your-implementation)
+  - [Common Scalar Types](#common-scalar-types)
+  - [Tips](#tips)
+
+## Creating New GraphQL Scalars
+
+GraphQL scalars are custom data types that define how data is validated, serialized, and parsed. This guide will walk you through creating a new scalar in the `src/scalars/graphql/` directory.
+
+### Step 1: Create the Scalar File
+
+Create a new TypeScript file in `src/scalars/graphql/` for your scalar. Use `EmailAddress.ts` as a reference.
+
+**Example: Creating a `PhoneNumber.ts` scalar**
+
+```typescript
+import { GraphQLError, GraphQLScalarType, type GraphQLScalarTypeConfig, Kind } from 'graphql'
+import { z } from 'zod'
+
+export interface ScalarType {
+  input: string
+  output: string
+}
+
+export const type = 'string' // TS type in string form
+
+export const typedef = 'scalar PhoneNumber'
+
+export const schema = z.string().regex(/^\+?[1-9]\d{1,14}$/, 'Invalid phone number format')
+
+export const stringSchema = 'z.string().regex(/^\\+?[1-9]\\d{1,14}$/, "Invalid phone number format")'
+
+const phoneValidation = (value: unknown): string => {
+  if (typeof value !== 'string') {
+    throw new GraphQLError(`Value is not string: ${JSON.stringify(value)}`)
+  }
+
+  const result = schema.safeParse(value)
+
+  if (result.success) return result.data
+  throw new GraphQLError(result.error.message)
+}
+
+export const config: GraphQLScalarTypeConfig<string, string> = {
+  name: 'PhoneNumber',
+  description: 'A field whose value conforms to international phone number format.',
+  serialize: phoneValidation,
+  parseValue: phoneValidation,
+  parseLiteral: (value) => {
+    if (value.kind !== Kind.STRING) {
+      throw new GraphQLError(`Can only validate strings as phone numbers but got a: ${value.kind}`, { nodes: value })
+    }
+
+    return phoneValidation(value.value)
+  },
+}
+
+export const scalar = new GraphQLScalarType(config)
+```
+
+#### Key Components to Update:
+
+1. **`type`**: The TypeScript type (usually `'string'` for text-based scalars)
+2. **`typedef`**: The GraphQL type definition (e.g., `'scalar PhoneNumber'`)
+3. **`schema`**: Zod validation schema for your data type
+4. **`stringSchema`**: String representation of the zod schema (used for code generation)
+5. **Validation function**: Custom validation logic for your scalar
+6. **`config.name`**: The name of your scalar (must match the typedef)
+7. **`config.description`**: Human-readable description of the scalar
+
+### Step 2: Register the Scalar in `scalars.ts`
+
+After creating your scalar file, you need to register it in `src/scalars/graphql/scalars.ts`. This involves updating multiple sections of the file.
+The github repo for the Document-Engineering can be found [here](https://github.com/powerhouse-inc/document-engineering/tree/main)
+
+#### 2.1 Add Namespace Import
+
+Add your scalar to the namespace imports section (around line 2):
+
+```typescript
+// namespace imports -- DO NOT REMOVE OR EDIT THIS COMMENT
+import * as Amount from './Amount.js'
+import * as AmountCrypto from './AmountCrypto.js'
+// ... other imports ...
+import * as PhoneNumber from './PhoneNumber.js' // ADD THIS LINE
+import * as URLScalar from './URL.js'
+```
+
+#### 2.2 Add Type Export
+
+Add the type export (around line 22):
+
+```typescript
+// export types -- DO NOT REMOVE OR EDIT THIS COMMENT
+export type { ScalarType as AmountScalarType } from './Amount.js'
+// ... other type exports ...
+export type { ScalarType as PhoneNumberScalarType } from './PhoneNumber.js' // ADD THIS LINE
+export type { ScalarType as URLScalarType } from './URL.js'
+```
+
+#### 2.3 Add to Export Object
+
+Add your scalar to the main export object (around line 40):
+
+```typescript
+export {
+  Amount,
+  AmountCrypto,
+  // ... other exports ...
+  PhoneNumber, // ADD THIS LINE
+  URLScalar,
+}
+```
+
+#### 2.4 Add to Custom Scalars
+
+Add your scalar to the `customScalars` object (around line 54):
+
+```typescript
+export const customScalars: Record<string, BasePHScalar<any>> = {
+  // ... other scalars ...
+  PhoneNumber, // ADD THIS LINE
+  URLScalar,
+} as const
+```
+
+#### 2.5 Add to Resolvers
+
+Add your scalar to the `resolvers` object (around line 74):
+
+```typescript
+export const resolvers = {
+  // export resolvers -- DO NOT REMOVE OR EDIT THIS COMMENT
+  AmountTokens: AmountTokens.scalar,
+  // ... other resolvers ...
+  PhoneNumber: PhoneNumber.scalar, // ADD THIS LINE
+  Amount: Amount.scalar,
+}
+```
+
+#### 2.6 Add to Type Definitions
+
+Add your typedef to the `typeDefs` array (around line 90):
+
+```typescript
+export const typeDefs = [
+  // export typedefs -- DO NOT REMOVE OR EDIT THIS COMMENT
+  AmountTokens.typedef,
+  // ... other typedefs ...
+  PhoneNumber.typedef, // ADD THIS LINE
+  Amount.typedef,
+]
+```
+
+#### 2.7 Add to Generator Type Definitions
+
+Add your scalar to the `generatorTypeDefs` object (around line 105):
+
+```typescript
+export const generatorTypeDefs = {
+  // export generator typedefs -- DO NOT REMOVE OR EDIT THIS COMMENT
+  [AmountTokens.config.name]: AmountTokens.type,
+  // ... other entries ...
+  [PhoneNumber.config.name]: PhoneNumber.type, // ADD THIS LINE
+  [Amount.config.name]: Amount.type,
+}
+```
+
+#### 2.8 Add to Validation Schema
+
+Add your scalar to the `validationSchema` object (around line 120):
+
+```typescript
+export const validationSchema = {
+  // export validation schema -- DO NOT REMOVE OR EDIT THIS COMMENT
+  [AmountTokens.config.name]: AmountTokens.stringSchema,
+  // ... other entries ...
+  [PhoneNumber.config.name]: PhoneNumber.stringSchema, // ADD THIS LINE
+  [Amount.config.name]: Amount.stringSchema,
+}
+```
+
+### Step 3: Create Tests for Your Scalar
+
+Every scalar must have comprehensive tests to ensure it works correctly. Create a test file in `src/scalars/graphql/test/` following the naming convention `YourScalar.test.ts`.
+
+**Example: Creating `PhoneNumber.test.ts`**
+
+```typescript
+import { Kind } from 'graphql'
+import { scalar } from '../PhoneNumber.js'
+
+describe('PhoneNumber Scalar', () => {
+  it('should serialize a phone number', () => {
+    const phoneNumber = '+1234567890'
+
+    expect(scalar.serialize(phoneNumber)).toBe(phoneNumber)
+  })
+
+  it('should throw an error if the value is not a string', () => {
+    const phoneNumber = 123
+
+    expect(() => scalar.serialize(phoneNumber)).toThrow()
+  })
+
+  it('should throw an error if the value is not a valid phone number', () => {
+    const phoneNumber = 'invalid-phone'
+
+    expect(() => scalar.serialize(phoneNumber)).toThrow()
+  })
+
+  it('should parse a valid phone number', () => {
+    const phoneNumber = '+1234567890'
+
+    expect(scalar.parseValue(phoneNumber)).toBe(phoneNumber)
+  })
+
+  it('should throw an error if parse a value that is not a valid phone number', () => {
+    const phoneNumber = 'invalid-phone'
+
+    expect(() => scalar.parseValue(phoneNumber)).toThrow()
+  })
+
+  it('should throw an error if parse a value that is not a string', () => {
+    const phoneNumber = 123
+
+    expect(() => scalar.parseValue(phoneNumber)).toThrow()
+  })
+
+  it('should parse a valid phone number from a literal', () => {
+    const phoneNumber = '+1234567890'
+
+    expect(
+      scalar.parseLiteral({
+        kind: Kind.STRING,
+        value: phoneNumber,
+      })
+    ).toBe(phoneNumber)
+  })
+
+  it('should throw an error if parse a literal that is not a valid phone number', () => {
+    const phoneNumber = 'invalid-phone'
+
+    expect(() =>
+      scalar.parseLiteral({
+        kind: Kind.STRING,
+        value: phoneNumber,
+      })
+    ).toThrow()
+  })
+
+  it('should throw an error if parse a literal that is not a string', () => {
+    const phoneNumber = '+1234567890'
+
+    expect(() =>
+      scalar.parseLiteral({
+        kind: Kind.INT,
+        value: phoneNumber,
+      })
+    ).toThrow()
+  })
+})
+```
+
+#### Required Test Cases
+
+Your scalar tests should cover these essential scenarios:
+
+##### Serialization Tests
+
+- ✅ **Valid values**: Test that valid inputs are serialized correctly
+- ❌ **Invalid types**: Test that non-string inputs throw errors
+- ❌ **Invalid format**: Test that strings not matching your validation throw errors
+
+##### Parse Value Tests
+
+- ✅ **Valid values**: Test that valid inputs are parsed correctly
+- ❌ **Invalid format**: Test that invalid strings throw errors
+- ❌ **Invalid types**: Test that non-string inputs throw errors
+
+##### Parse Literal Tests
+
+- ✅ **Valid STRING literals**: Test that valid string literals are parsed correctly
+- ❌ **Invalid STRING literals**: Test that invalid string literals throw errors
+- ❌ **Non-STRING literals**: Test that non-string literal kinds (INT, FLOAT, etc.) throw errors
+
+#### Testing Best Practices
+
+1. **Test edge cases**: Include boundary values and common invalid inputs
+2. **Test multiple valid formats**: If your scalar accepts different valid formats, test them all
+3. **Use descriptive test names**: Make it clear what each test is validating
+4. **Follow the naming convention**: `YourScalar.test.ts` in the `test/` directory
+
+#### Example Edge Cases for Different Scalar Types
+
+**String-based scalars (like PhoneNumber):**
+
+```typescript
+// Test empty string
+expect(() => scalar.parseValue('')).toThrow()
+
+// Test too long/short values
+expect(() => scalar.parseValue('123')).toThrow()
+expect(() => scalar.parseValue('+' + '1'.repeat(20))).toThrow()
+
+// Test special characters
+expect(() => scalar.parseValue('+1-234-567-890')).not.toThrow()
+```
+
+**Number-based scalars:**
+
+```typescript
+// Test zero
+expect(scalar.parseValue(0)).toBe(0)
+
+// Test negative numbers
+expect(() => scalar.parseValue(-1)).toThrow()
+
+// Test decimal numbers
+expect(scalar.parseValue(123.45)).toBe(123.45)
+```
+
+**Date-based scalars:**
+
+```typescript
+// Test valid ISO date
+expect(scalar.parseValue('2023-12-25T00:00:00Z')).toBe('2023-12-25T00:00:00Z')
+
+// Test invalid date format
+expect(() => scalar.parseValue('25/12/2023')).toThrow()
+```
+
+### Step 4: Validate Your Implementation
+
+After implementing your scalar and tests, make sure to:
+
+1. **Run the tests** to ensure they all pass
+2. **Build the project** to ensure there are no TypeScript errors
+3. **Test GraphQL queries** that use your new scalar
+4. **Verify code generation** works with your new scalar
+
+### Common Scalar Types
+
+Here are some common patterns for different types of scalars:
+
+#### String-based Scalars
+
+```typescript
+export const type = 'string'
+export const schema = z.string().min(1).max(100)
+```
+
+#### Number-based Scalars
+
+```typescript
+export const type = 'number'
+export const schema = z.number().positive()
+```
+
+#### Date-based Scalars
+
+```typescript
+export const type = 'string'
+export const schema = z.string().datetime()
+```
+
+### Tips
+
+- Always follow the naming convention: use PascalCase for scalar names
+- Include meaningful validation in your Zod schema
+- Write clear, descriptive error messages
+- Keep the `stringSchema` in sync with your `schema` definition
+- Test edge cases in your validation function
+- Update all required sections in `scalars.ts`

package/docs/academy/06-ComponentLibrary/03-IntegrateIntoAReactComponent.md

@@ -0,0 +1,124 @@
+# Step 2: Integrate Your Scalar into a React Component
+
+This guide explains how to use a custom scalar (created as described in the previous step) within a React component. You'll learn how to leverage the scalar's validation schema for form input, display errors, and ensure a seamless user experience.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Step 1: Import the Scalar and Dependencies](#step-1-import-the-scalar-and-dependencies)
+- [Step 2: Define Component Props](#step-2-define-component-props)
+- [Step 3: Implement the Component](#step-3-implement-the-component)
+- [Step 4: Render the Input and Error](#step-4-render-the-input-and-error)
+- [Step 5: Example Usage](#step-5-example-usage)
+- [Best Practices](#best-practices)
+- [Tips](#tips)
+
+## Overview
+
+Custom scalars provide type-safe validation and parsing for your data. Integrating them into React components ensures that user input is validated consistently with your backend and schema definitions. This is especially useful for form fields like email, phone number, Ethereum address, etc.
+
+## Step 1: Import the Scalar and Dependencies
+
+Import your scalar and React hooks. You may use any input component to capture user input. In the following example, `FormInput` is used for demonstration purposes, but you can use a standard `<input>`, a custom component, or any UI library input.
+
+```typescript
+import { useState } from "react";
+import { EthereumAddress as EthereumAddressScalar } from "@powerhousedao/document-engineering/graphql";
+// FormInput is just an example. You can use any input component you prefer.
+import { FormInput } from "@powerhousedao/design-system";
+```
+
+Replace `EthereumAddress` with your scalar's name as needed.
+
+## Step 2: Define Component Props
+
+Define the props for your component. Typically, you'll want an `onChange` callback to notify the parent of the value and its validity:
+
+```typescript
+export interface EthereumAddressProps {
+  onChange?: (address: string, isValidAddress: boolean) => void;
+}
+```
+
+Adapt the prop names and types to your scalar (e.g., `PhoneNumberProps`, `onChange(phone: string, isValid: boolean)`).
+
+## Step 3: Implement the Component
+
+Use React state to track the input value. Use the scalar's Zod schema for validation. Call `onChange` with the value and validity whenever the input changes.
+
+> **Note:** The input component in this example is `FormInput`, but you can use any input or UI component to capture user input. The key is to validate the value using the scalar's schema.
+
+```typescript
+export const EthereumAddress: React.FC<EthereumAddressProps> = ({ onChange }) => {
+  const [address, setAddress] = useState("");
+
+  // Validate using the scalar's Zod schema
+  const result = EthereumAddressScalar.schema.safeParse(address);
+  const errors = result.error?.errors.map((error) => error.message).join(", ");
+
+  // Notify parent of value and validity
+  if (onChange) {
+    onChange(address, result.success);
+  }
+
+  return (
+    <div>
+      {/* Replace FormInput with any input component you prefer */}
+      <FormInput
+        id="eth-address-input"
+        value={address}
+        onChange={(e) => setAddress(e.target.value)}
+        placeholder="0x...."
+        aria-label="Ethereum address input"
+      />
+      <label htmlFor="eth-address-input">
+        {address !== "" && errors}
+      </label>
+    </div>
+  );
+};
+```
+
+**Key Points:**
+- Use the scalar's `.schema.safeParse(value)` for validation.
+- Display error messages if validation fails.
+- Call `onChange` with both the value and its validity.
+- Use accessible labels and attributes.
+- The input component is flexible—use what fits your UI best.
+
+## Step 4: Render the Input and Error
+
+- Use any form input component (e.g., `FormInput`, `<input>`, or a custom UI input) for the field.
+- Show error messages below the input when validation fails.
+- Add accessibility attributes (`aria-label`, `htmlFor`).
+
+## Step 5: Example Usage
+
+Here's how you might use your component in a parent form:
+
+```typescript
+<EthereumAddress
+  onChange={(address, isValid) => {
+    // Handle the address and its validity
+    console.log("Address:", address, "Valid:", isValid);
+  }}
+/>
+```
+
+Replace `EthereumAddress` with your scalar component as needed.
+
+## Best Practices
+
+- **Validation:** Always use the scalar's schema for validation to ensure consistency with your backend.
+- **Accessibility:** Use proper labels, `aria-*` attributes, and keyboard navigation.
+- **Error Handling:** Display clear, user-friendly error messages.
+- **DRY Principle:** Reuse the scalar's schema and avoid duplicating validation logic.
+- **Type Safety:** Use TypeScript types for props and state.
+
+## Tips
+
+- Keep your UI clean and intuitive.
+- Sync your component with any updates to the scalar's schema.
+- Test edge cases (empty input, invalid formats, etc.).
+- Use meaningful placeholder text and labels.
+- Consider supporting additional props (e.g., `disabled`, `required`) for flexibility.

package/docs/academy/06-ComponentLibrary/04-ScalarVsUIComponents.md

@@ -0,0 +1,52 @@
+import { Tabs, TabItem } from '@theme/Tabs';
+
+# Scalar Component Example
+
+Scalars are here to help you define custom fields in your document model schema and speed up the development process.
+There are two applications of scalar components in the document model workflow:
+
+1. At the **schema definition** level where you build your schema and write your GraphQL state schema.
+2. At the **frontend / react** level where you import it and place it in your UI to represent the scalar field
+
+## Scalar Definition in the Document Model Schema
+
+As you might know, the document model schema defines the structure of the document and serves as the backbone of the document model. The GraphQL state schema defines how data is captured with the help of types & scalars. When you define a scalar in the document model schema, you are essentially defining a new field that can be used in the document model to capture data.
+
+In the Document Model Editor, you can find all the custom scalar types available under the 'Scalars' section.
+
+Insert image of the feature. @callme-t
+
+## React Component Implementation in the Frontend
+
+All of our reusable components are available in the Document-Engineering system package.
+This package comes as a dependency in your project when creating a new document model project.
+````
+import PHIDField from 'document-engineering'
+const reactComponent = () => {
+
+return (
+  <div>
+    <PHIDField
+      fetchOptionsCallback={function Js(){}}
+      fetchSelectedOptionCallback={function Js(){}}
+      label="PHID field"
+      name="phid-field"
+      placeholder="phd:"
+    />
+
+  </div>
+  
+  )
+
+}
+````
+
+## Scalars & Reusable Components
+
+To make your life easier, Powerhouse has defined all useful scalars with a set of reusable code and UI components.
+The reusable components are essentially a set 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.
+
+Read the next chapter to get familiar with our reusable components. 
+
+# PHID Field Implementation Example
+

package/docs/academy/09-AIResources.md

@@ -0,0 +1,9 @@
+# AI Resources
+
+We have a couple of AI resources to help you with your daily work or exploring our ecosystem. 
+
+| Tool | Description |
+|---|---|
+| [**Deepwiki**](https://deepwiki.com/powerhouse-inc/powerhouse) | A searchable/queriable wiki to understand our growing mono repo better. <br /> DeepWiki provides up-to-date documentation you can talk to, for every repo in the world. Think Deep Research for GitHub. |
+| [**Context7**](https://context7.com/powerhouse-inc/powerhouse) | The Powerhouse Academy is also available as context through the context7 MCP Server. <br /> LLMs rely on outdated or generic information about the libraries you use. <br /> Context7 pulls up-to-date, version-specific documentation and code examples directly from the source. <br /> Paste accurate, relevant documentation directly into tools like Cursor, Claude, or any LLM. |
+

package/package.json

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

package/sidebars.ts

@@ -120,10 +120,9 @@ const sidebars = {
             </a>
           `,
         },
-        'academy/ComponentLibrary/ScalarComponent',
-        'academy/ComponentLibrary/ComplexComponent',
-        'academy/ComponentLibrary/LayoutComponent',
-        'academy/ComponentLibrary/FragmentsComponent',
+        'academy/ComponentLibrary/CreateCustomScalars',
+        'academy/ComponentLibrary/IntegrateIntoAReactComponent',
+        'academy/ComponentLibrary/ScalarVsUIComponents',
       ],
     },
 
@@ -135,6 +134,7 @@ const sidebars = {
     },
     { type: 'doc', id: 'academy/Cookbook', label: 'Cookbook' },
     { type: 'doc', id: 'academy/Glossary', label: 'Glossary' },
+    { type: 'doc', id: 'academy/AIResources', label: 'AI Resources' },
     // ...add more as needed
   ],
 };

package/docs/academy/06-ComponentLibrary/02-ScalarComponent.mdx

@@ -1,122 +0,0 @@
-import { Tabs, TabItem } from '@theme/Tabs';
-
-# E.g. Scalar Component
-
-Scalars are here to help you define custom fields in your document model schema and speed up the development process.
-There are two applications of scalar components in the document model workflow:
-
-1. At the **schema definition** level where you build your schema and write your GraphQL state schema.
-2. At the **frontend / react** level where you import it and place it in your UI to represent the scalar field
-
-## Scalar Definition in the Document Model Schema
-
-As you might know, the document model schema defines the structure of the document and serves as the backbone of the document model. The GraphQL state schema defines how data is captured with the help of types & scalars. When you define a scalar in the document model schema, you are essentially defining a new field that can be used in the document model to capture data.
-
-In the Document Model Editor, you can find all the custom scalar types available in our documentation under the 'Scalars' section.
-
-Insert image of the feature. 
-
-````
-scalar PHID <-- imported from the design system library? not sure
-type MyType {
-  myScalar: PHID
-}   
-````
-
-## React Component Implementation in the Frontend
-
-All of our reusable components are available in the Document-Engineering design system library or package.
-This package comes as a dependency in your project when creating a new document model project.
-````
-import PHIDField from 'document-engineering'
-const reactComponent = () => {
-
-return (
-  <div>
-    <PHIDField
-      fetchOptionsCallback={function Js(){}}
-      fetchSelectedOptionCallback={function Js(){}}
-      label="PHID field"
-      name="phid-field"
-      placeholder="phd:"
-    />
-
-  </div>
-  
-  )
-
-}
-````
-
-## Scalars & Reusable Components
-
-To make your life easier, Powerhouse has defined all useful scalars with a set of reusable code and UI components.
-The reusable components are essentially a set 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.
-
-Read the next chapter to get familiar with our reusable components. 
-
-# PHID Field Example
-
-### **Scalar Definition**
-
-- **Name:** `PHID` (Powerhouse ID)
-- **Purpose:** Represents a unique identifier pointing to a document, branch, scope, or data object within the Powerhouse system.
-
-
-<details>
-<summary>**Formatting of the component:**</summary>
-    - **Basic Notation:** `phd:<documentID>`
-        - **Branch and Scope:** Optional components appended using colons `:`.
-        - **Full Notation:** `phd:<documentID>:<branch>:<scope>`
-            - **Branch:** Defaults to `main` if omitted.
-            - **Scope:** Defaults to `public` if omitted.
-    - **Data Object Reference:** `phd:<documentID>/<dataObjectID>`
-    - **URL Format:** `phd://<domain>/<documentID>`
-        - Example: `phd://switchboard.powerhouse.xyz/baefc2a4-f9a0-4950-8161-fd8d8cc7dea9`
-
-**Examples of the component formatting:**
-    - **Basic PHID:** `phd:baefc2a4-f9a0-4950-8161-fd8d8cc7dea9`
-    - **With Branch:** `phd:baefc2a4...:draft`
-    - **With Scope:** `phd:baefc2a4...::local`
-    - **With Branch and Scope:** `phd:baefc2a4...:draft:local`
-    - **With Data Object ID:** `phd:baefc2a4.../3cf05e40...`
-</details>
-
-<details>
-<summary>**Validation of the Component:**</summary>
-    - **Validate each format:**
-        1. **PHID only:** Ensure the document ID is a valid UUID.
-        2. **PHID with data element (OID):** Validate both the document ID and the data object ID.
-        3. **PHID with branch:** Validate the document ID and check if the branch is properly formatted.
-        4. **PHID with scope:** Validate the document ID and check if the scope is valid.
-        5. **PHID with branch and scope:** Validate all three components: document ID, branch, and scope.
-    - **Error Message Example:** "Invalid PHID format. Please check the document ID, branch, or scope."
-</details>
-
-The following is the UI component for the PHID field and scalar in a storybook.
-We use Storybook as our component development environment. 
-It allows us to build and test UI components in isolation, making it easier to develop, test, and document reusable components.
-In our stories you'll find first find a basic UI implementation example of the component, followed by the component's properties, events, and validation options.
-
-- A list of the **default properties** and their descriptions, and a list of the available events that can be triggered.
-- A list of the **component's specific properties** and attributes based on the components functionality. 
-- A list of **validation options**, or ways to validate the component's desired input values.
-
-Additionally, you'll find various **stories of the components in different states**.
-
-<div style={{ 
-  border: '1px solid #E5E7EB', 
-  borderRadius: '8px', 
-  padding: '16px',
-  marginBottom: '20px',
-}}>
-  <iframe
-    src="https://storybook.powerhouse.academy/iframe.html?id=scalars-phid-field--readme&viewMode=story"
-    style={{
-      width: '100%',
-      height: '4500px',
-      border: 'none',
-    }}
-    title="PhidField Component Demo"
-  />
-</div>

package/docs/academy/06-ComponentLibrary/03-ComplexComponent.mdx

@@ -1,38 +0,0 @@
-import { Tabs, TabItem } from '@theme/Tabs';
-
-# E.g. Complex Component
-
-## Sidebar
-
-### **Scalar Definition**
-
-- **Name:** `Sidebar`
-- **Purpose:** The Sidebar component can be used within a page layout to provide a sidebar navigation. It provided a tree structure of nodes that can be used to navigate the application offering customization, search and more.
-
-
-<details>
-<summary>**Formatting of the component:**</summary>
-    
-</details>
-
-<details>
-<summary>**Validation of the Component:**</summary>
-   
-</details>
-
-<div style={{ 
-  border: '1px solid #E5E7EB', 
-  borderRadius: '8px', 
-  padding: '16px',
-  marginBottom: '20px',
-}}>
-  <iframe
-    src="https://dspot-scalars-storybook.vercel.app/iframe.html?args=&id=document-engineering-complex-components-sidebar--readme&viewMode=story"
-    style={{
-      width: '100%',
-      height: '2000px',
-      border: 'none',
-    }}
-    title="Sidebar Component Demo"
-  />
-</div>

package/docs/academy/06-ComponentLibrary/04-LayoutComponent.mdx

@@ -1,58 +0,0 @@
-import { Tabs, TabItem } from '@theme/Tabs';
-
-# E.g. Layout Component 
-
-## PHID Field Example
-
-### **Scalar Definition**
-
-- **Name:** `PHID` (Powerhouse ID)
-- **Purpose:** Represents a unique identifier pointing to a document, branch, scope, or data object within the Powerhouse system.
-
-
-<details>
-<summary>**Formatting of the component:**</summary>
-    - **Basic Notation:** `phd:<documentID>`
-        - **Branch and Scope:** Optional components appended using colons `:`.
-        - **Full Notation:** `phd:<documentID>:<branch>:<scope>`
-            - **Branch:** Defaults to `main` if omitted.
-            - **Scope:** Defaults to `public` if omitted.
-    - **Data Object Reference:** `phd:<documentID>/<dataObjectID>`
-    - **URL Format:** `phd://<domain>/<documentID>`
-        - Example: `phd://switchboard.powerhouse.xyz/baefc2a4-f9a0-4950-8161-fd8d8cc7dea9`
-
-**Examples of the component formatting:**
-    - **Basic PHID:** `phd:baefc2a4-f9a0-4950-8161-fd8d8cc7dea9`
-    - **With Branch:** `phd:baefc2a4...:draft`
-    - **With Scope:** `phd:baefc2a4...::local`
-    - **With Branch and Scope:** `phd:baefc2a4...:draft:local`
-    - **With Data Object ID:** `phd:baefc2a4.../3cf05e40...`
-</details>
-
-<details>
-<summary>**Validation of the Component:**</summary>
-    - **Validate each format:**
-        1. **PHID only:** Ensure the document ID is a valid UUID.
-        2. **PHID with data element (OID):** Validate both the document ID and the data object ID.
-        3. **PHID with branch:** Validate the document ID and check if the branch is properly formatted.
-        4. **PHID with scope:** Validate the document ID and check if the scope is valid.
-        5. **PHID with branch and scope:** Validate all three components: document ID, branch, and scope.
-    - **Error Message Example:** "Invalid PHID format. Please check the document ID, branch, or scope."
-</details>
-
-<div style={{ 
-  border: '1px solid #E5E7EB', 
-  borderRadius: '8px', 
-  padding: '16px',
-  marginBottom: '20px',
-}}>
-  <iframe
-    src="https://dspot-scalars-storybook.vercel.app/iframe.html?args=name:amount-field;placeholder:test;label:Enter%20Amount%20and%20Select%20Currency;type:Amount;placeholderSelect:CUR;allowedTokens:!null;tokenIcons.Sol:1;value.amount:3454564564;value.currency:BTC&id=document-engineering-simple-components-phid-field--readme&viewMode=story"
-    style={{
-      width: '100%',
-      height: '4500px',
-      border: 'none',
-    }}
-    title="PhidField Component Demo"
-  />
-</div>

package/docs/academy/06-ComponentLibrary/05-FragmentsComponent.mdx

@@ -1,58 +0,0 @@
-import { Tabs, TabItem } from '@theme/Tabs';
-
-# E.g. Fragments Component 
-
-## PHID Field Example
-
-### **Scalar Definition**
-
-- **Name:** `PHID` (Powerhouse ID)
-- **Purpose:** Represents a unique identifier pointing to a document, branch, scope, or data object within the Powerhouse system.
-
-
-<details>
-<summary>**Formatting of the component:**</summary>
-    - **Basic Notation:** `phd:<documentID>`
-        - **Branch and Scope:** Optional components appended using colons `:`.
-        - **Full Notation:** `phd:<documentID>:<branch>:<scope>`
-            - **Branch:** Defaults to `main` if omitted.
-            - **Scope:** Defaults to `public` if omitted.
-    - **Data Object Reference:** `phd:<documentID>/<dataObjectID>`
-    - **URL Format:** `phd://<domain>/<documentID>`
-        - Example: `phd://switchboard.powerhouse.xyz/baefc2a4-f9a0-4950-8161-fd8d8cc7dea9`
-
-**Examples of the component formatting:**
-    - **Basic PHID:** `phd:baefc2a4-f9a0-4950-8161-fd8d8cc7dea9`
-    - **With Branch:** `phd:baefc2a4...:draft`
-    - **With Scope:** `phd:baefc2a4...::local`
-    - **With Branch and Scope:** `phd:baefc2a4...:draft:local`
-    - **With Data Object ID:** `phd:baefc2a4.../3cf05e40...`
-</details>
-
-<details>
-<summary>**Validation of the Component:**</summary>
-    - **Validate each format:**
-        1. **PHID only:** Ensure the document ID is a valid UUID.
-        2. **PHID with data element (OID):** Validate both the document ID and the data object ID.
-        3. **PHID with branch:** Validate the document ID and check if the branch is properly formatted.
-        4. **PHID with scope:** Validate the document ID and check if the scope is valid.
-        5. **PHID with branch and scope:** Validate all three components: document ID, branch, and scope.
-    - **Error Message Example:** "Invalid PHID format. Please check the document ID, branch, or scope."
-</details>
-
-<div style={{ 
-  border: '1px solid #E5E7EB', 
-  borderRadius: '8px', 
-  padding: '16px',
-  marginBottom: '20px',
-}}>
-  <iframe
-    src="https://dspot-scalars-storybook.vercel.app/iframe.html?args=name:amount-field;placeholder:test;label:Enter%20Amount%20and%20Select%20Currency;type:Amount;placeholderSelect:CUR;allowedTokens:!null;tokenIcons.Sol:1;value.amount:3454564564;value.currency:BTC&id=document-engineering-simple-components-phid-field--readme&viewMode=story"
-    style={{
-      width: '100%',
-      height: '4500px',
-      border: 'none',
-    }}
-    title="PhidField Component Demo"
-  />
-</div>