@powerhousedao/academy 3.2.0 → 3.3.0-dev.0

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

@@ -15,6 +15,22 @@ Here are the key points to understand:
 - **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?
+
+In the context of Powerhouse Builder platform, components can be thought of as reusable elements, or ready-to-use building blocks that help builders implement **document editors & viewers** with little to no effort. An important utility aspect of a component is that it serves its users as a **data input field**, providing structured ways to enter and manipulate information within your document models.
+
+## Document Editors vs Document Viewers
+
+Understanding the relationship between document editors and viewers is crucial for component usage:
+
+**Document Editor**: A specific document type that is used by one or more users to make data entries and update its state. Key utility is the ability to enter data in a structured format, making it a great tool for collaboration within a group of authorized users.
+
+**Document Viewer**: Does not allow modifications. It's a great way to inform about the state of the document type, making it a great tool for providing a broader group or public with transparent insights. Document viewers do not have to match the view of the editor one-to-one - the data presented could be framed as a specific selection, or filtered to provide desired insights.
+
+:::tip Component Behavior in Different Contexts
+The same component that will be used in a document viewer will have a **disabled state** (not allowed to edit documents). Document editors precede document viewers - you would start by creating a document editor and then, if needed, decide which viewer format is useful.
+:::
+
 ## Scalars vs. General UI Components
 
 ### Scalar Components
@@ -39,6 +55,42 @@ This category includes a broader range of UI elements such as simplified version
 **Location:** @powerhousedao/document-engineering/ui   
 https://github.com/powerhouse-inc/document-engineering
 
+## Component Types Classification
+
+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
+
+:::info Component Library Philosophy
+The Powerhouse team is building a Component library with a wide range of components embedding best UX practices & key functionality. This library establishes standards and best practices for building documents while fast-tracking the building process through facilitation of the most basic & useful component types.
+:::
+
+## 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. 
+
+**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)

package/docs/academy/07-Cookbook.md

@@ -14,7 +14,7 @@ You need to install the Powerhouse CLI (`ph-cmd`) to create and manage Powerhous
 
 ## Prerequisites
 - node.js 22 installed
-- pnpm package manager installed
+- pnpm package manager 10 installed
 - Terminal or command prompt access
 
 ## Solution
@@ -169,7 +169,7 @@ You need to access experimental features, bugfixes, or development versions of P
 
 ## Prerequisites
 - Terminal or command prompt access
-- pnpm package manager installed
+- pnpm package manager 10 installed
 - Node.js 22 installed
 
 ## Solution

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powerhousedao/academy",
-  "version": "3.2.0",
+  "version": "3.3.0-dev.0",
   "homepage": "https://powerhouse.academy",
   "repository": {
     "type": "git",
@@ -23,7 +23,7 @@
     "@docusaurus/module-type-aliases": "^3.8.0",
     "@docusaurus/tsconfig": "^3.8.0",
     "@docusaurus/types": "^3.8.0",
-    "tsx": "^4.19.4",
+    "tsx": "^4.20.3",
     "typescript": "^5.7.3"
   },
   "browserslist": {

package/src/css/custom.css

@@ -157,6 +157,21 @@ a {
   color: #003d7a; /* darker blue on hover */
 }
 
+/* Dark mode specific styles for better readability */
+[data-theme='dark'] .docs-doc-page .theme-doc-markdown a,
+[data-theme='dark'] .markdown a,
+[data-theme='dark'] details a,
+[data-theme='dark'] .theme-doc-markdown details a {
+  color: #66b3ff !important; /* lighter blue for dark mode */
+}
+
+[data-theme='dark'] .docs-doc-page .theme-doc-markdown a:hover,
+[data-theme='dark'] .markdown a:hover,
+[data-theme='dark'] details a:hover,
+[data-theme='dark'] .theme-doc-markdown details a:hover {
+  color: #99ccff !important; /* even lighter blue on hover for dark mode */
+}
+
 /* Reset styling for navigation elements, category pages, and utility links */
 .breadcrumbs a,
 .pagination-nav a,
@@ -488,14 +503,20 @@ html[data-theme='dark'] .DocSearch-Hits > *:empty {
 }
 
 .image-container {
+  box-sizing: border-box;
   border: 1px solid var(--ifm-color-emphasis-300);
   border-radius: var(--ifm-card-border-radius);
-  padding: 1rem;
+  padding: 0.5rem;
   box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
   margin-bottom: 1.5rem;
+  max-width: calc(var(--ifm-container-width-xl) - 2rem);
+  margin-left: auto;
+  margin-right: auto;
 }
 
 .image-container img {
+  width: 100%;
+  height: auto;
   border-radius: var(--ifm-card-border-radius);
 }