@powerhousedao/academy 5.1.0-staging.0 → 5.1.0

package/docs/academy/03-ExampleUsecases/TodoList/07-AddSharedComponentForShowingTodoListStats.md

@@ -1,384 +0,0 @@
-# Step 7 - Add shared component for showing TodoList stats
-
-So far we've been creating components that live in the same directories as the editors that use them. But sometimes we want to use the same component across multiple editors.
-
-Let's create a component for showing statistics about our todos. We'd like this component to work with any set of todos or todo lists, so that we can use the same one in our document editor or in our drive editor or a folder.
-
-## Creating the `<Stats />` component
-
-Create a new directory at `editors/components` and create two new files inside it: 
-
-`editors/components/Stats.tsx` with this content:
-
-```jsx
-import type {
-  TodoItem,
-  TodoListDocument,
-} from "todo-tutorial/document-models/todo-list";
-
-type Props = {
-  todos: TodoItem[] | undefined;
-  todoListDocuments?: TodoListDocument[] | undefined;
-  createdAtUtcIso?: string;
-  lastModifiedAtUtcIso?: string;
-};
-
-/** Generic component for showing statistics about todo lists and the todos they contain */
-export function Stats({
-  todos,
-  todoListDocuments,
-  createdAtUtcIso,
-  lastModifiedAtUtcIso,
-}: Props) {
-  const totalTodos = todos?.length ?? 0;
-  const totalChecked = todos?.filter((todo) => todo.checked).length ?? 0;
-  const totalUnchecked = todos?.filter((todo) => !todo.checked).length ?? 0;
-  const percentageChecked = Math.round(
-    calculatePercentage(totalTodos, totalChecked),
-  );
-  const percentageUnchecked = Math.round(
-    calculatePercentage(totalTodos, totalUnchecked),
-  );
-  const createdAt = createdAtUtcIso ? new Date(createdAtUtcIso) : null;
-  const hasCreatedAt = createdAt !== null;
-  const lastModified = lastModifiedAtUtcIso
-    ? new Date(lastModifiedAtUtcIso)
-    : null;
-  const hasLastModified = lastModified !== null;
-  const createdAtFormattedDate = createdAt
-    ? createdAt.toLocaleDateString()
-    : null;
-  const lastModifiedFormattedDate = lastModified
-    ? lastModified.toLocaleDateString()
-    : null;
-  const createdAtFormattedTime = createdAt
-    ? createdAt.toLocaleTimeString()
-    : null;
-  const lastModifiedFormattedTime = lastModified
-    ? lastModified.toLocaleTimeString()
-    : null;
-  const totalTodoListDocuments = todoListDocuments?.length ?? 0;
-  const hasTodoLists = todoListDocuments !== undefined;
-
-  return (
-    <ul className="text-sm text-gray-800 max-w-1/2">
-      {hasTodoLists && (
-        <li className="flex justify-between">
-          <span>Todo Lists:</span> <span>{totalTodoListDocuments}</span>
-        </li>
-      )}
-      <li className="flex justify-between">
-        <span>Todos:</span> <span>{totalTodos}</span>
-      </li>
-      <li className="flex justify-between">
-        <span>Checked:</span>{" "}
-        <span>
-          {totalChecked} ({percentageChecked}%)
-        </span>
-      </li>
-      <li className="flex justify-between">
-        <span>Unchecked:</span>{" "}
-        <span>
-          {totalUnchecked} ({percentageUnchecked}%)
-        </span>
-      </li>
-      {hasCreatedAt && (
-        <li className="flex justify-between">
-          <span>Created:</span>{" "}
-          <span>
-            {createdAtFormattedDate} {createdAtFormattedTime}
-          </span>
-        </li>
-      )}
-      {hasLastModified && (
-        <li className="flex justify-between">
-          <span>Last modified:</span>{" "}
-          <span>
-            {lastModifiedFormattedDate} {lastModifiedFormattedTime}
-          </span>
-        </li>
-      )}
-    </ul>
-  );
-}
-
-function calculatePercentage(total: unknown, value: unknown) {
-  if (typeof total !== "number" || typeof value !== "number") {
-    return 0;
-  }
-  const ratio = value / total;
-  if (isNaN(ratio)) {
-    return 0;
-  }
-  return ratio * 100;
-}
-```
-
-And `editors/components/index.ts` with this content:
-
-```ts
-export { Stats } from "./Stats.js";
-```
-
-The index file lets us use a nice neat import path like `todo-tutorial/editors/components` in all of our editor components.
-
-Don't be too concerned with the math and time related code you see here — those are just implementation details.
-
-## Using the  `<Stats />` component in our `TodoListEditor`
-
-Now let's use the `<Stats />` component in our `<TodoList />` component:
-
-```tsx
-import { useSelectedTodoListDocument } from "todo-tutorial/document-models/todo-list";
-// added-line
-import { Stats } from "todo-tutorial/editors/components";
-import { EditTodoListName } from "./EditName.js";
-import { Todos } from "./Todos.js";
-import { AddTodo } from "./AddTodo.js";
-import { CloseButton } from "./CloseButton.js";
-
-/** Displays the selected todo list */
-export function TodoList() {
-  const [selectedTodoList] = useSelectedTodoListDocument();
-
-  if (!selectedTodoList) return null;
-
-  const todos = selectedTodoList.state.global.items;
-  // added-start
-  const createdAtUtcIso = selectedTodoList.header.createdAtUtcIso;
-  const lastModifiedAtUtcIso = selectedTodoList.header.lastModifiedAtUtcIso;
-  // added-end
-
-  return (
-    <div>
-      <section className="mb-4 flex gap-2 items-center">
-        <div className="grow">
-          <EditTodoListName />
-        </div>
-        <div className="flex-none">
-          <CloseButton />
-        </div>
-      </section>
-      // added-start
-      <section className="mb-4">
-        <Stats
-          todos={todos}
-          createdAtUtcIso={createdAtUtcIso}
-          lastModifiedAtUtcIso={lastModifiedAtUtcIso}
-        />
-      </section>
-      // added-end
-      <section className="mb-4">
-        <Todos todos={todos} />
-      </section>
-      <section>
-        <AddTodo />
-      </section>
-    </div>
-  );
-}
-```
-
-With this, you will now see statistics about the todo items in a todo list document.
-
-And now we can also show off the flexibility of our new `<Stats />` component. Since drives are also just documents themselves, we can derive the same information about a drive too. This means we can use this same component in our drive editor as well.
-
-## Using the `<Stats />` component in our `TodoDriveExplorer`
-
-Let's add this to our `<DriveContents />` component, along with some conditional logic that either shows stats for the selected folder (if one is selected) or the selected drive otherwise.
-
-```tsx
-// added-start
-import {
-  useSelectedDrive,
-  useSelectedFolder,
-} from "@powerhousedao/reactor-browser";
-// added-end
-import { CreateDocument } from "./CreateDocument.js";
-import { EmptyState } from "./EmptyState.js";
-import { Files } from "./Files.js";
-import { Folders } from "./Folders.js";
-import { NavigationBreadcrumbs } from "./NavigationBreadcrumbs.js";
-// added-start
-import { Stats } from "todo-tutorial/editors/components";
-import {
-  useTodoListDocumentsInSelectedDrive,
-  useTodoListDocumentsInSelectedFolder,
-  type TodoItem,
-  type TodoListDocument,
-} from "todo-tutorial/document-models/todo-list";
-
-/** Small helper function to get all todo items from all todo lists */
-export function getAllTodoItemsFromTodoLists(
-  todoLists: TodoListDocument[] | undefined,
-): TodoItem[] {
-  return todoLists?.flatMap((todoList) => todoList.state.global.items) ?? [];
-}
-// added-end
-
-/** Shows the documents and folders in the selected drive */
-export function DriveContents() {
-  // added-start
-  const selectedFolder = useSelectedFolder();
-  const hasSelectedFolder = selectedFolder !== undefined;
-  // added-end
-  return (
-    <div className="space-y-6 px-6">
-      <NavigationBreadcrumbs />
-      // added-line
-      {hasSelectedFolder ? <FolderStats /> : <DriveStats />}
-      <Folders />
-      <Files />
-      <EmptyState />
-      <CreateDocument />
-    </div>
-  );
-}
-
-// added-start
-/** Shows the statistics for the selected drive */
-function DriveStats() {
-  const todoListDocumentsInSelectedDrive =
-    useTodoListDocumentsInSelectedDrive();
-  const allTodos = getAllTodoItemsFromTodoLists(
-    todoListDocumentsInSelectedDrive,
-  );
-  const [selectedDrive] = useSelectedDrive();
-  const driveCreatedAt = selectedDrive.header.createdAtUtcIso;
-  const driveLastModified = selectedDrive.header.lastModifiedAtUtcIso;
-
-  return (
-    <Stats
-      todos={allTodos}
-      todoListDocuments={todoListDocumentsInSelectedDrive}
-      createdAtUtcIso={driveCreatedAt}
-      lastModifiedAtUtcIso={driveLastModified}
-    />
-  );
-}
-
-/** Shows the statistics for the selected folder */
-function FolderStats() {
-  const todoListDocumentsInSelectedFolder =
-    useTodoListDocumentsInSelectedFolder();
-  const allTodos = getAllTodoItemsFromTodoLists(
-    todoListDocumentsInSelectedFolder,
-  );
-
-  return (
-    <Stats
-      todos={allTodos}
-      todoListDocuments={todoListDocumentsInSelectedFolder}
-    />
-  );
-}
-// added-end
-```
-
-The final result should look like this:
-
-```jsx
-import {
-  useSelectedDrive,
-  useSelectedFolder,
-} from "@powerhousedao/reactor-browser";
-import { CreateDocument } from "./CreateDocument.js";
-import { EmptyState } from "./EmptyState.js";
-import { Files } from "./Files.js";
-import { Folders } from "./Folders.js";
-import { NavigationBreadcrumbs } from "./NavigationBreadcrumbs.js";
-import { Stats } from "todo-tutorial/editors/components";
-import {
-  useTodoListDocumentsInSelectedDrive,
-  useTodoListDocumentsInSelectedFolder,
-  type TodoItem,
-  type TodoListDocument,
-} from "todo-tutorial/document-models/todo-list";
-
-/** Small helper function to get all todo items from all todo lists */
-export function getAllTodoItemsFromTodoLists(
-  todoLists: TodoListDocument[] | undefined,
-): TodoItem[] {
-  return todoLists?.flatMap((todoList) => todoList.state.global.items) ?? [];
-}
-
-/** Shows the documents and folders in the selected drive */
-export function DriveContents() {
-  const selectedFolder = useSelectedFolder();
-  const hasSelectedFolder = selectedFolder !== undefined;
-  return (
-    <div className="space-y-6 px-6">
-      <NavigationBreadcrumbs />
-      {hasSelectedFolder ? <FolderStats /> : <DriveStats />}
-      <Folders />
-      <Files />
-      <EmptyState />
-      <CreateDocument />
-    </div>
-  );
-}
-
-/** Shows the statistics for the selected drive */
-function DriveStats() {
-  const todoListDocumentsInSelectedDrive =
-    useTodoListDocumentsInSelectedDrive();
-  const allTodos = getAllTodoItemsFromTodoLists(
-    todoListDocumentsInSelectedDrive,
-  );
-  const [selectedDrive] = useSelectedDrive();
-  const driveCreatedAt = selectedDrive.header.createdAtUtcIso;
-  const driveLastModified = selectedDrive.header.lastModifiedAtUtcIso;
-
-  return (
-    <Stats
-      todos={allTodos}
-      todoListDocuments={todoListDocumentsInSelectedDrive}
-      createdAtUtcIso={driveCreatedAt}
-      lastModifiedAtUtcIso={driveLastModified}
-    />
-  );
-}
-
-/** Shows the statistics for the selected folder */
-function FolderStats() {
-  const todoListDocumentsInSelectedFolder =
-    useTodoListDocumentsInSelectedFolder();
-  const allTodos = getAllTodoItemsFromTodoLists(
-    todoListDocumentsInSelectedFolder,
-  );
-
-  return (
-    <Stats
-      todos={allTodos}
-      todoListDocuments={todoListDocumentsInSelectedFolder}
-    />
-  );
-}
-```
-
-With this update, you can now see the statistics for the todo lists and todo items for the selected drive, folder or document depending on which you select.
-
- ## Check your work
-
-To make sure all works as expected, we should:
-
-- check types
-run: `pnpm tsc`
-
-- check linting
-run: `pnpm lint`
-
-- check tests
-run: `pnpm test`
-
-- test in connect
-run: `pnpm connect` — you should now be able to see the `<Stats />` component showing the data for your drives, folder and documents.
-
-- make sure your code matches the code in the completed step branch
-run: `git diff step-7-complete-added-shared-component-for-showing-todo-list-stats`
-
-## The end
-
-Congratulations! You now have a working `TodoList` document model, and editor for those documents, and a drive editor for managing those documents. This will make a good starting point for creating your own new implementations. 
-
-We're excited to see what you build!

package/docs/academy/03-ExampleUsecases/TodoList/_category_.json

@@ -1,8 +0,0 @@
-{
-  "label": "Todo List",
-  "position": 3,
-  "link": {
-    "type": "generated-index"
-  }
-}
-  

package/docs/academy/03-ExampleUsecases/VetraPackageLibrary/VetraPackageLibrary.md

@@ -1,7 +0,0 @@
----
-title: Vetra Package Library
----
-
-The Vetra package library is your best source to explore packages built by different builder teams on the Powerhouse Vetra platform. Through the packages you'll find the GitHub repository with the source code of each package.   
-
-You can get access to the [package library here.](https://vetra.io/packages)

package/docs/academy/03-ExampleUsecases/VetraPackageLibrary/_category_.json

@@ -1,9 +0,0 @@
-{
-  "label": "Vetra Package Library",
-  "position": 2,
-  "link": {
-    "type": "doc",
-    "id": "academy/ExampleUsecases/VetraPackageLibrary/VetraPackageLibrary"
-  }
-}
-

package/docs/academy/04-APIReferences/06-VetraRemoteDrive.md

@@ -1,160 +0,0 @@
-# Vetra Remote Drive
-
-These commands enable collaborative development using Vetra remote drives. Instead of working with local drives only, you can connect your Powerhouse project to a remote drive that syncs across team members.
-
-## Commands Overview
-
-### `ph init --remote-drive`
-
-**Purpose:** Create a new Powerhouse project and connect it to a remote Vetra drive.
-
-**When to use:** You're starting a NEW project that will be shared via a remote drive.
-
-**How it works:**
-
-1. Validates the remote drive URL and checks that no GitHub URL is configured yet
-2. Creates a standard Powerhouse project from the boilerplate
-3. Adds Vetra configuration to `powerhouse.config.json`:
-   ```json
-   {
-     "vetra": {
-       "driveId": "abc123",
-       "driveUrl": "https://vetra.example.com/d/abc123"
-     }
-   }
-   ```
-
-**Usage:**
-```bash
-ph init my-project --remote-drive https://vetra.example.com/d/abc123
-```
-
-**After initialization:**
-- Create a GitHub repository
-- Commit and push your code
-- Run `ph vetra` to configure the GitHub URL in the remote drive
-
----
-
-### `ph checkout --remote-drive`
-
-**Purpose:** Clone an existing Powerhouse project that's already connected to a remote drive.
-
-**When to use:** You're joining an EXISTING project that someone else initialized.
-
-**How it works:**
-
-1. Queries the remote drive to find the configured GitHub URL
-2. Clones the repository from GitHub
-3. Installs dependencies
-4. The project is already configured to use the remote drive
-
-**Usage:**
-```bash
-ph checkout --remote-drive https://vetra.example.com/d/abc123
-```
-
-**Requirements:**
-- The remote drive must have a GitHub URL configured (done during `ph vetra` after init)
-
----
-
-### `ph vetra`
-
-**Purpose:** Start the Vetra development environment with Switchboard and Connect Studio.
-
-**When to use:** After initializing or checking out a project, to start development.
-
-**How it works:**
-
-1. Reads the remote drive URL from `powerhouse.config.json` (or `--remote-drive` flag)
-2. Starts Switchboard connected to the remote drive (syncs automatically)
-3. Prompts to configure GitHub URL if not set (first time after init)
-4. Starts Connect Studio pointing to the drive(s)
-
-**With `--watch` flag:**
-- Creates a second "Vetra Preview" drive for testing local changes
-- Dynamically loads your local document models and editors
-- Main drive stays stable, preview drive for experimentation
-
-**Usage:**
-```bash
-# Basic usage (uses config from powerhouse.config.json)
-ph vetra
-
-# With watch mode for development
-ph vetra --watch
-
-# Override remote drive URL
-ph vetra --remote-drive https://vetra.example.com/d/abc123
-
-# Disable Connect Studio
-ph vetra --disable-connect
-```
-
-**Key options:**
-- `--watch` - Enable dynamic loading and create preview drive
-- `--remote-drive <url>` - Specify remote drive URL
-- `--switchboard-port <port>` - Custom Switchboard port (default: 4001)
-- `--connect-port <port>` - Custom Connect Studio port (default: 3000)
-- `--disable-connect` - Skip Connect Studio
-- `--interactive` - Enable interactive mode for code generation
-
----
-
-## Workflows
-
-### Starting a New Project (Owner)
-
-```bash
-# 1. Initialize with remote drive
-ph init my-project --remote-drive https://vetra.example.com/d/abc123
-
-# 2. Create GitHub repo and push
-cd my-project
-git add .
-git commit -m "Initial commit"
-git remote add origin https://github.com/user/my-project.git
-git push -u origin main
-
-# 3. Start Vetra and configure GitHub URL
-ph vetra
-# (Select option to use detected GitHub URL when prompted)
-
-# 4. Start developing with watch mode
-ph vetra --watch
-```
-
-### Joining an Existing Project (Collaborator)
-
-```bash
-# 1. Checkout from remote drive
-ph checkout --remote-drive https://vetra.example.com/d/abc123
-
-# 2. Navigate to project
-cd project-name
-
-# 3. Start Vetra environment
-ph vetra
-
-# You're now synced with the remote drive
-```
-
----
-
-## Key Concepts
-
-**Remote Drive vs Local Drive:**
-- Without remote drive: `ph vetra` creates a local drive on your machine only
-- With remote drive: `ph vetra` connects to a shared drive that syncs across team members
-
-**When to use each command:**
-- Use `ph init --remote-drive` when starting a NEW project (no GitHub URL configured in drive yet)
-- Use `ph checkout --remote-drive` when joining an EXISTING project (GitHub URL already configured)
-- Use `ph vetra` to start development after either init or checkout
-
-**Preview Drive (`--watch` mode):**
-- Main "Vetra" drive: syncs with remote, contains stable package configuration
-- "Vetra Preview" drive: created locally with `--watch`, for testing local document models
-- Without `--watch`: safer, prevents untested code from affecting Connect
-- With `--watch`: enables rapid development and testing