@powerhousedao/academy 4.1.0-dev.9 → 5.0.0-staging.1

package/docs/academy/04-APIReferences/01-ReactHooks.md

@@ -29,185 +29,645 @@ It's important to note that a function should only be named and treated as a hoo
 
 </details>
 
-The idea is to make the usage of our hooks feel as simple and familiar as using `useState`.   
-The Powerhouse team is currently working on a happy path for builders that look like this: 
+# Editor state management hooks
 
-```js
-// in a component that only needs to read a value, you can use
-const invoiceName = useReadDocumentField('myInvoiceDocumentId', 'name') // returns a string which is the `name`
-// and for documents that need to update data as well, you would have
-const updateInvoiceName = useUpdateDocumentField('myInvoiceDocumentId', 'name') // returns a function that takes a new string for the new name and dispatches the update
-// finally, we can combine these into a single hook which works like react's useState hook returning both the value and updater function
-const [invoiceName, updateInvoiceName] = useDocumentField('myInvoiceDocumentId', 'name')
+This library provides hooks intended to be used by editors (including drive editors) which will be rendered inside of Powerhouse host-applications such as Connect, Switchboard, Fusion or a Vetra Studio Drive.
 
+Learn more about the [Editors](/academy/MasteryTrack/BuildingUserExperiences/BuildingDocumentEditors)
+Learn more about the [Drive Editors](/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer)
 
-// Read-only value
-const invoiceName = useReadDocumentField('docId', 'name')
+## Key concepts
 
-// Write-only updater
-const updateInvoiceName = useUpdateDocumentField('docId', 'name')
+### Reactor
 
-// Combined read + write (like useState)
-const [invoiceName, updateInvoiceName] = useDocumentField('docId', 'name')
+All of the data used by these hooks is ultimately derived from the `Reactor`, which manages the asynchronous eventually consistent state of drives and documents. Learn more about the [Reactor](/academy/Architecture/WorkingWithTheReactor)
+
+
+### Selected drives, folders and documents
+In the application, there are certain items that can be set as "selected". 
+
+- selected drive
+- selected folder
+- selected document
+
+We provide hooks for getting the selected item for each:
+
+`useSelectedDrive`
+`useSelectedFolder`
+`useSelectedDocument`
+
+Folders and documents are part of a given drive, so they will both be undefined if the selected drive is undefined.
+
+_Either_ a folder or a document can be selected but not both, so if one is defined then the other will be undefined.
+
+To set the selected drive, we provide a function `setSelectedDrive` which takes either a `DocumentDriveDocument` or a `DocumentDriveDocument['header']['slug']`.
+
+To set the selected document/folder, we provide a function `setSelectedNode` which returns a setter function which can be used for _both_ documents and folders. This function takes either a `Node` or a slug which can be the url slug or the node's id.
+
+## Hooks
+
+<details>
+<summary>Reactor</summary>
+```ts
+function useReactor(): Reactor | undefined
+```
+
+Returns the reactor instance. 
+
+Usage
+```jsx
+import { useReactor } from '@powerhousedao/state`
+
+function MyEditorComponent() {
+  const reactor = useReactor();
+}
 ```
-Initial documentation about the hooks can be found [here](https://github.com/powerhouse-inc/powerhouse/blob/main/packages/common/state/README.md)
+</details>
 
-### Temporary use of new hooks on custom drive editors. 
+### Drives
 
+<details>
+<summary>useDrives</summary>
 
-To use the new hooks in custom components or editors today, devs must:
+```ts
+function useDrives(): DocumentDriveDocument[] | undefined
+```
+Returns the drives for a reactor.
 
-1. Pass in the existing Reactor instance as a prop (createReactor).
-2. Call useInitializeReactor(props.createReactor, false) in the custom component.
-3. Optionally wrap dispatch() to trigger a refresh manually, using:
+Usage
 
-const refresh = useSyncDrivesAndDocumentsWithReactor();
+```jsx
+import { useDrives } from '@powerhousedao/state';
 
-For maximum compatibility, consider passing data and set functions (drives, documents, etc.) directly as props instead of using the hooks inside the custom editor..
+function MyEditorComponent() {
+  const drives = useDrives();
+}
+```
+</details>
 
-Example: 
+<details>
+<summary>useDriveById</summary>
 
+```ts
+function useDriveById(id: string | null | undefined): DocumentDriveDocument | undefined
 ```
-+import { AtomStoreProvider } from "@powerhousedao/common";
 
-export default function Editor(props: IProps) {
+Returns a drive by id.
+
+Usage
+
+```jsx
+import { useDriveById } from '@powerhousedao/state';
+
+function MyEditorComponent() {
+  const driveById = useDriveById();
+}
+```
+</details>
+
+<details>
+<summary>useSelectedDrive</summary>
+
+```ts
+function useSelectedDrive(): DocumentDriveDocument | undefined
+```
+
+Returns the selected drive. You can use the selected drive with `setSelectedDrive`.
+
+Usage
+
+```jsx
+import { useSelectedDrive } from '@powerhousedao/state';
+
+function MyEditorComponent() {
+  const selectedDrive = useSelectedDrive();
+}
+```
+</details>
+
+<details>
+<summary>drive properties convenience hooks</summary>
+
+We provide hooks for accessing various properties on the drive object for your convenience. These use the above hooks to get a drive and then return properties in the object.
+
+```ts
+/** Returns the remote URL for a drive. */
+function useDriveRemoteUrl(driveId: string | null | undefined): string | undefined
+
+/** Returns the pull responder trigger for a drive. */
+function useDrivePullResponderTrigger(
+  driveId: string | null | undefined,
+): Trigger | undefined
+
+/** Returns the pull responder URL for a drive. */
+function useDrivePullResponderUrl(driveId: string | null | undefined): string | undefined
+
+/** Returns whether a drive is remote. */
+function useDriveIsRemote(driveId: string | null | undefined): boolean
+
+/** Returns the sharing type for a drive. */
+function useDriveSharingType(driveId: string | null | undefined): SharingType | undefined
+
+/** Returns  whether a drive is available offline. */
+function useDriveAvailableOffline(driveId: string | null | undefined): boolean
+```
+
+Usage
+
+```jsx
+import { 
+  useDriveRemoteUrl,
+  useDrivePullResponderTrigger,
+  useDrivePullResponderUrl,
+  useDriveIsRemote,
+  useDriveSharingType,
+  useDriveAvailableOffline,
+} from '@powerhousedao/state';
+
+function MyEditorComponent() {
+  const myDriveId = "some-drive-id";
+  const driveRemoteUrl = useDriveRemoteUrl(myDriveId);
+  const drivePullResponderTrigger = useDrivePullResponderTrigger(myDriveId);
+  const drivePullResponderUrl = useDrivePullResponderUrl(myDriveId);
+  const driveIsRemote = useDriveIsRemote(myDriveId);
+  const driveSharingType = useDriveSharingType(myDriveId);
+  const driveAvailableOffline = useDriveAvailableOffline(myDriveId);
+
+  console.log({
+    driveRemoteUrl,
+    drivePullResponderTrigger,
+    drivePullResponderUrl,
+    driveIsRemote,
+    driveSharingType,
+    driveAvailableOffline,
+  })
+}
+```
+</details>
+
+### Documents
+
+<details>
+<summary>useAllDocuments/useSelectedDriveDocuments</summary>
+
+```ts
+function useAllDocuments(): PHDocument[] | undefined
+```
+Returns all of the documents in the reactor.
+
+```ts
+function useSelectedDriveDocuments(): PHDocument[] | undefined
+```
+Returns the documents in the reactor for the selected drive.
+
+Usage
+
+```jsx
+import { useAllDocuments, useSelectedDriveDocuments } from '@powerhousedao/state';
+
+function MyEditorComponent() {
+  const allDocuments = useAllDocuments();
+  const selectedDriveDocuments = useSelectedDriveDocuments();
+}
+```
+</details>
+
+<details>
+<summary>useSelectedDocument</summary>
+
+```ts
+function useSelectedDocument(): PHDocument | undefined
+```
+Returns the selected document. You can set the selected document with `setSelectedNode`.
+
+Usage
+
+```jsx
+import { useSelectedDocument } from '@powerhousedao/state';
+
+function MyEditorComponent() {
+  const selectedDocument = useSelectedDocument();
+}
+```
+</details>
+
+<details>
+<summary>useDocumentById</summary>
+
+```ts
+function useDocumentById(id: string | null | undefined): PHDocument | undefined
+```
+Returns a document by id.
+
+Usage
+
+```jsx
+import { useDocumentById } from '@powerhousedao/state';
+
+function MyEditorComponent() {
+  const myDocumentId = 'some-document-id';
+  const documentById = useDocumentById(myDocumentId);
+}
+```
+</details>
+
+### Nodes
+
+"Nodes" refers to the items found in a given drive's `state.global.nodes` array. Nodes can represent both files (documents) and folders.
+
+A document in a drive will have a node in the drive's node list which has the same id as the document.
+
+Nodes have an optional `parentFolder` field, which is the id of a folder node in the drive when it is defined. If it is undefined, the node is a direct child of the drive.
+
+A given folder node's children are the nodes in the drive's node list which have their parent folder set to the folder node's id.
+
+```ts
+type FileNode = {
+  documentType: string;
+  id: string;
+  kind: string;
+  name: string;
+  parentFolder: string | null | undefined;
+}
+
+type FolderNode = {
+  id: string;
+  kind: string;
+  name: string;
+  parentFolder: string | null | undefined;
+}
+
+type Node = FileNode | FolderNode;
+```
+
+<details>
+<summary>useNodes</summary>
+
+Ideally you should not need to handle the list of nodes directly, since we already provide documents and folders. But these hooks are provided just in case.
+
+```ts
+function useNodes(): Node[] | undefined
+```
+Returns the nodes for a drive.
+
+Usage
+
+```jsx
+import { useNodes} from '@powerhousedao/state';
+
+function MyEditorComponent() {
+  const nodes = useNodes();
+}
+```
+</details>
+
+<details>
+<summary>useNodeById</summary>
+
+```ts
+function useNodeById(id: string | null | undefined): Node | undefined
+```
+Returns a node in the selected drive by id.
+
+Usage
+
+```jsx
+import { useNodeById } from '@powerhousedao/state';
+
+function MyEditorComponent() {
+  const myFolderId = 'some-folder-id';
+  const myDocumentId = 'some-document-id';
+  const myFolderNode = useNodeById(myFolderId);
+  const myFileNode = useNodeById(myDocumentId);
+}
+```
+</details>
+
+<details>
+<summary>useSelectedFolder</summary>
+
+```ts
+function useSelectedFolder(): FolderNode | undefined
+```
+Returns the selected folder. You can set the selected folder with `setSelectedNode`
+
+Usage
+
+```jsx
+import { useSelectedFolder } from '@powerhousedao/state';
+
+function MyEditorComponent() {
+  const selectedFolder = useSelectedFolder();
+}
+```
+</details>
+
+<details>
+<summary>useSelectedNodePath</summary>
+
+```ts
+function useSelectedNodePath(): Node[]
+```
+Returns the path to the selected node. Useful for navigational components like breadcrumbs.
+
+Usage
+
+```jsx
+import { useSelectedNodePath } from '@powerhousedao/state';
+
+function MyEditorComponent() {
+  const nodes = useSelectedNodePath();
+
+  return <Breadcrumbs nodes={nodes}>
+}
+```
+</details>
+
+<details>
+<summary>useChildNodes/useFolderChildNodes/useFileChildNodes</summary>
+
+```ts
+function useChildNodes(): Node[]
+```
+Returns the child nodes for the selected drive or folder.
+
+```ts
+function useFolderChildNodes(): FolderNode[]
+```
+Returns the folder child nodes for the selected drive or folder.
+
+```ts
+function useFileChildNodes(): FileNode[]
+```
+Returns the file (document) child nodes for the selected drive or folder.
+
+Usage
+
+```jsx
+import { useChildNodes, useFolderChildNodes, useFileChildNodes } from '@powerhousedao/state';
+
+function MyEditorComponent() {
+  const nodes = useChildNodes();
+  const fileNodes = useChildFileNodes();
+  const folderNodes = useChildFolderNodes();
+
+  return (
+    <div>
+     <FilesAndFolders nodes={nodes}>
+     <Files fileNodes={fileNodes}>
+     <Folders folderNodes={folderNodes}>
+    </div>
+ )
+}
+```
+</details>
+
+<details>
+<summary>useChildNodesForId/useFolderChildNodesForId/useFileChildNodesForId</summary>
+
+```ts
+function useChildNodesForId(id: string | null | undefined): Node[]
+```
+Returns the child nodes for a drive or folder by id.
+```ts
+function useFolderChildNodesForId(id: string | null | undefined): FolderNode[]
+```
+Returns the folder child nodes for a drive or folder by id.
+```ts
+function useFileChildNodesForId(id: string | null | undefined): FileNode[]
+```
+Returns the file (document) child nodes for a drive or folder by id.
+
+Usage
+
+```jsx
+import { useChildNodesForId, useFolderChildNodesForId, useFileChildNodesForId } from '@powerhousedao/state';
+
+function MyEditorComponent() {
+  const driveOrFolderId = 'some-drive-or-folder-id';
+  const nodes = useChildNodesForId(driveOrFolderId);
+  const fileNodes = useFileChildNodesForId(driveOrFolderId);
+  const folderNodes = useFolderChildNodesForId(driveOrFolderId);
+
   return (
-+    <AtomStoreProvider reactor={props.context.reactor}> 
-      <DriveContextProvider value={props.context}>
-        <WagmiContext>
-          <BaseEditor {...props} />
-        </WagmiContext>
-      </DriveContextProvider>
-+    </AtomStoreProvider>
-  );
+    <div>
+     <FilesAndFolders nodes={nodes}>
+     <Files fileNodes={fileNodes}>
+     <Folders folderNodes={folderNodes}>
+    </div>
+ )
+}
+```
+</details>
+
+<details>
+<summary>useNodeName/useNodeKind</summary>
+
+```ts
+function useNodeName(id: string | null | undefined): string | undefined
+```
+Returns the name of a node.
+```ts
+function useNodeKind(id: string | null | undefined): NodeKind | undefined
+```
+Returns the kind of a node.
+
+Usage
+
+```jsx
+import { useNodeName, useNodeKind } from '@powerhousedao/state';
+
+function MyEditorComponent() {
+  const nodeId = 'some-node-id';
+  const nodeName = useNodeName(nodeId);
+  const nodeKind = useNodeKind(nodeId);
+
+  if (nodeKind === 'file') {
+    return <File name={nodeName} />;
+  }
+
+  if (nodeKind === 'folder') {
+    return <Folder name={nodeName} />;
+  }
+}
+```
+</details>
+
+### Vetra packages and modules
+
+Vetra packages hold code which can plug into your Connect application. This includes common default modules like the document model document model editor and document drive document model, as well as the modules from your local project and the various packages you have installed.
+
+These modules can be for:
+
+- document models
+- editors
+- subgraphs
+- import scripts
+- processors
+
+Each Vetra package contains a `modules` field which optionally contains lists of these modules.
+
+<details>
+<summary>useVetraPackages</summary>
+
+```ts
+function useVetraPackages(): VetraPackage[] | undefined
+```
+
+Returns all of the Vetra packages in your Connect app.
+
+Usage
+
+```jsx
+import { useVetraPackages } from '@powerhousedao/state'
+
+function MyEditorComponent() {
+  const vetraPackages = useVetraPackages()
+}
+```
+</details>
+
+<details>
+<summary>useDocumentModelModules</summary>
+
+```ts
+function useDocumentModelModules(): DocumentModelModule[] | undefined
+```
+
+Returns the document model modules from your Vetra packages.
+
+Usage
+
+```jsx
+import { useDocumentModelModules } from '@powerhousedao/state'
+
+function MyEditorComponent() {
+  const documentModelModules = useDocumentModelModules()
+}
+```
+</details>
+
+<details>
+<summary>useDocumentModelModuleById</summary>
+
+```ts
+function useDocumentModelModuleById(): DocumentModelModule[] | undefined
+```
+
+Returns the document model for a given id (document type).
+*NOTE* What we call here an id is really the value in the "document type" field in the document model editor
+*NOTE* Connect assumes that these document types (ids) are unique. It is your responsibility to enforce this.
+
+Usage
+
+```jsx
+import { useDocumentModelModuleById } from '@powerhousedao/state'
+
+function MyEditorComponent() {
+  const documentType = 'my-org/my-document';
+  const documentModelModuleById = useDocumentModelModuleById(documentType)
+}
+```
+</details>
+
+<details>
+<summary>useEditorModules</summary>
+
+```ts
+function useEditorModules(): EditorModule[] | undefined
+```
+
+Returns the editor modules from your Vetra packages.
+
+Usage
+
+```jsx
+import { useEditorModules } from '@powerhousedao/state'
+
+function MyEditorComponent() {
+  const editorModules = useEditorModules()
+}
+```
+</details>
+
+<details>
+<summary>useDriveEditorModules</summary>
+
+```ts
+function useDriveEditorModules(): DriveEditorModule[] | undefined
+```
+
+Returns the drive editor modules from your Vetra packages.
+
+Usage
+
+```jsx
+import { useDriveEditorModules } from '@powerhousedao/state'
+
+function MyDriveEditorComponent() {
+  const driveEditorModules = useDriveEditorModules()
 }
 ```
+</details>
 
-Until the hooks are fully integrated and event handling is granular, the team will need to handle some of this manually or limit their use to experimental side projects and internal demos.
+<details>
+<summary>useProcessorModules</summary>
+
+```ts
+function useProcessorModules(): ProcessorModule[] | undefined
+```
 
+Returns the processor modules from your Vetra packages.
 
+Usage
 
+```jsx
+import { useProcessorModules } from '@powerhousedao/state'
 
-## An overview of currently available hooks
-
-### 1. Getting or changing data 
-These are tools you can use in your app to get or change data:
+function MyProcessorComponent() {
+  const processorModules = useProcessorModules()
+}
+```
+</details>
 
 <details>
-<summary>`useDrives`, `useDriveById(id)`: Lets you access folders (called "drives").</summary>
+<summary>useSubgraphModules</summary>
+
+```ts
+function useSubgraphModules(): SubgraphModule[] | undefined
+```
 
-### Hook Name and Signature   
-The name of the hook and its TypeScript (or JavaScript) signature.
-### Description
-A brief explanation of what the hook does and when to use it.
-### Usage Example   
-A code snippet showing how to use the hook in a real-world scenario.
-### Parameters
-A table or list describing each parameter, its type, and its purpose.
-### Return Value   
-A description (and sometimes a table) of what the hook returns.
-### Notes / Caveats   
-Any important details, gotchas, or best practices.
-### Related Hooks
-Links to other relevant hooks or documentation.
-</details>
-
-<details>
-<summary>`useDocuments`, `useDocumentById(id)`: Lets you access files (called "documents").</summary>
-
-### Hook Name and Signature   
-The name of the hook and its TypeScript (or JavaScript) signature.
-### Description
-A brief explanation of what the hook does and when to use it.
-### Usage Example   
-A code snippet showing how to use the hook in a real-world scenario.
-### Parameters
-A table or list describing each parameter, its type, and its purpose.
-### Return Value   
-A description (and sometimes a table) of what the hook returns.
-### Notes / Caveats   
-Any important details, gotchas, or best practices.
-### Related Hooks
-Links to other relevant hooks or documentation.
-</details>
-
-<details>
-<summary>`useEditorModules`, `useEditor(documentType)`: Loads the relevant editor UI/tools for a document.</summary>
-
-### Hook Name and Signature   
-The name of the hook and its TypeScript (or JavaScript) signature.
-### Description
-A brief explanation of what the hook does and when to use it.
-### Usage Example   
-A code snippet showing how to use the hook in a real-world scenario.
-### Parameters
-A table or list describing each parameter, its type, and its purpose.
-### Return Value   
-A description (and sometimes a table) of what the hook returns.
-### Notes / Caveats   
-Any important details, gotchas, or best practices.
-### Related Hooks
-Links to other relevant hooks or documentation.
-</details>
-
-<details>
-<summary>`useDocumentModule`, `useDocumentModel(documentType)`: Gets the technical model behind a document type—like its schema and operations.</summary>
-
-### Hook Name and Signature   
-The name of the hook and its TypeScript (or JavaScript) signature.
-### Description
-A brief explanation of what the hook does and when to use it.
-### Usage Example   
-A code snippet showing how to use the hook in a real-world scenario.
-### Parameters
-A table or list describing each parameter, its type, and its purpose.
-### Return Value   
-A description (and sometimes a table) of what the hook returns.
-### Notes / Caveats   
-Any important details, gotchas, or best practices.
-### Related Hooks
-Links to other relevant hooks or documentation.
-</details>
-
-### 2. Managing selection state
-You can now use the following to manage and track what's currently selected:
-
-<details>
-<summary>`useSelectedDrive` and `useSetSelectedDrive(driveId)`: Get/set the selected folder.</summary>
-
-### Hook Name and Signature   
-The name of the hook and its TypeScript (or JavaScript) signature.
-### Description
-A brief explanation of what the hook does and when to use it.
-### Usage Example   
-A code snippet showing how to use the hook in a real-world scenario.
-### Parameters
-A table or list describing each parameter, its type, and its purpose.
-### Return Value   
-A description (and sometimes a table) of what the hook returns.
-### Notes / Caveats   
-Any important details, gotchas, or best practices.
-### Related Hooks
-Links to other relevant hooks or documentation.
-</details>
-
-<details>
-<summary>`useSelectedDocument` and `useSetSelectedDocument(documentId)`: Get/set the selected file.</summary>
-
-### Hook Name and Signature   
-The name of the hook and its TypeScript (or JavaScript) signature.
-### Description
-A brief explanation of what the hook does and when to use it.
-### Usage Example   
-A code snippet showing how to use the hook in a real-world scenario.
-### Parameters
-A table or list describing each parameter, its type, and its purpose.
-### Return Value   
-A description (and sometimes a table) of what the hook returns.
-### Notes / Caveats   
-Any important details, gotchas, or best practices.
-### Related Hooks
-Links to other relevant hooks or documentation.
+Returns the subgraph modules from your Vetra packages.
+
+Usage
+
+```jsx
+import { useSubgraphModules } from '@powerhousedao/state'
+
+function MySubgraphComponent() {
+  const subgraphModules = useSubgraphModules()
+}
+```
+</details>
+
+<details>
+<summary>useImportScriptModules</summary>
+
+```ts
+function useImportScriptModules(): ImportScriptModule[] | undefined
+```
+
+Returns the import script modules from your Vetra packages.
+
+Usage
+
+```jsx
+import { useImportScriptModules } from '@powerhousedao/state'
+
+function MyImportScriptComponent() {
+  const importScriptModules = useImportScriptModules()
+}
+```
 </details>
 
 ## More documentation coming soon!