@powerhousedao/academy 2.5.0-dev.21 → 2.5.0-dev.23

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+## 2.5.0-dev.23 (2025-06-13)
+
+This was a version bump only for @powerhousedao/academy to align it with other projects, there were no code changes.
+
+## 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.

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

@@ -1 +1,124 @@
-# Integrate your Scalar into a React Component
+# 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/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.21",
+  "version": "2.5.0-dev.23",
   "homepage": "https://powerhouse.academy",
   "repository": {
     "type": "git",

package/sidebars.ts

@@ -121,10 +121,8 @@ const sidebars = {
           `,
         },
         'academy/ComponentLibrary/CreateCustomScalars',
-        'academy/ComponentLibrary/ScalarComponent',
-        'academy/ComponentLibrary/ComplexComponent',
-        'academy/ComponentLibrary/LayoutComponent',
-        'academy/ComponentLibrary/FragmentsComponent',
+        'academy/ComponentLibrary/IntegrateIntoAReactComponent',
+        'academy/ComponentLibrary/ScalarVsUIComponents',
       ],
     },
 
@@ -136,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/03-ComplexComponent.mdx

@@ -1,38 +0,0 @@
-import { Tabs, TabItem } from '@theme/Tabs';
-
-# Complex Component Example
-
-## 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,5 +0,0 @@
-import { Tabs, TabItem } from '@theme/Tabs';
-
-# Layout Component Example
-
-## PHID Field Example

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

@@ -1,5 +0,0 @@
-import { Tabs, TabItem } from '@theme/Tabs';
-
-# Fragment Component Example 
-
-## PHID Field Example

package/docs/academy/09-AIResources

@@ -1,23 +0,0 @@
-# AI Resources
-
-We have a couple of AI resources to help you with your daily work.
-
-## Deepwiki
-A searchable/queriable wiki to understand our growing mono repo better.
-https://deepwiki.com/powerhouse-inc/powerhouse
-
-:::info
-What is DeepWiki?
-DeepWiki provides up-to-date documentation you can talk to, for every repo in the world. Think Deep Research for GitHub.
-:::
-
-## Context7
-The Powerhouse Academy is also available as context through the context7 MCP Server. 
-https://context7.com/powerhouse-inc/powerhouse
-
-:::info
-What is Context7?
-LLMs rely on outdated or generic information about the libraries you use.
-
-Context7 pulls up-to-date, version-specific documentation and code examples directly from the source. Paste accurate, relevant documentation directly into tools like Cursor, Claude, or any LLM. Get better answers, no hallucinations and an AI that actually understands your stack.
-:::