@powerhousedao/reactor-browser 5.0.0-staging.9 → 5.0.1-staging.10

package/README.md

@@ -8,9 +8,9 @@ This library provides hooks intended to be used by editors (including drive edit
 
 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.
 
-
 ### Selected drives, folders and documents
-In the application, there are certain items that can be set as "selected". 
+
+In the application, there are certain items that can be set as "selected".
 
 - selected drive
 - selected folder
@@ -32,15 +32,16 @@ To set the selected document/folder, we provide a function `setSelectedNode` whi
 
 ## Hooks
 
-
 ### Reactor
+
 ```ts
-function useReactor(): Reactor | undefined
+function useReactor(): Reactor | undefined;
 ```
 
-Returns the reactor instance. 
+Returns the reactor instance.
 
 ##### Usage
+
 ```jsx
 import { useReactor } from '@powerhousedao/state`
 
@@ -52,15 +53,17 @@ function MyEditorComponent() {
 ### Drives
 
 #### useDrives
+
 ```ts
-function useDrives(): DocumentDriveDocument[] | undefined
+function useDrives(): DocumentDriveDocument[] | undefined;
 ```
+
 Returns the drives for a reactor.
 
 ##### Usage
 
 ```jsx
-import { useDrives } from '@powerhousedao/state';
+import { useDrives } from "@powerhousedao/state";
 
 function MyEditorComponent() {
   const drives = useDrives();
@@ -68,8 +71,11 @@ function MyEditorComponent() {
 ```
 
 #### useDriveById
+
 ```ts
-function useDriveById(id: string | null | undefined): DocumentDriveDocument | undefined
+function useDriveById(
+  id: string | null | undefined,
+): DocumentDriveDocument | undefined;
 ```
 
 Returns a drive by id.
@@ -77,7 +83,7 @@ Returns a drive by id.
 ##### Usage
 
 ```jsx
-import { useDriveById } from '@powerhousedao/state';
+import { useDriveById } from "@powerhousedao/state";
 
 function MyEditorComponent() {
   const driveById = useDriveById();
@@ -85,8 +91,9 @@ function MyEditorComponent() {
 ```
 
 #### useSelectedDrive
+
 ```ts
-function useSelectedDrive(): DocumentDriveDocument | undefined
+function useSelectedDrive(): DocumentDriveDocument | undefined;
 ```
 
 Returns the selected drive. You can se the selected drive with `setSelectedDrive`.
@@ -94,7 +101,7 @@ Returns the selected drive. You can se the selected drive with `setSelectedDrive
 ##### Usage
 
 ```jsx
-import { useSelectedDrive } from '@powerhousedao/state';
+import { useSelectedDrive } from "@powerhousedao/state";
 
 function MyEditorComponent() {
   const selectedDrive = useSelectedDrive();
@@ -102,41 +109,48 @@ function MyEditorComponent() {
 ```
 
 #### drive properties convenience hooks
+
 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
+function useDriveRemoteUrl(
+  driveId: string | null | undefined,
+): string | undefined;
 
 /** Returns the pull responder trigger for a drive. */
 function useDrivePullResponderTrigger(
   driveId: string | null | undefined,
-): Trigger | undefined
+): Trigger | undefined;
 
 /** Returns the pull responder URL for a drive. */
-function useDrivePullResponderUrl(driveId: string | null | undefined): string | undefined
+function useDrivePullResponderUrl(
+  driveId: string | null | undefined,
+): string | undefined;
 
 /** Returns whether a drive is remote. */
-function useDriveIsRemote(driveId: string | null | undefined): boolean
+function useDriveIsRemote(driveId: string | null | undefined): boolean;
 
 /** Returns the sharing type for a drive. */
-function useDriveSharingType(driveId: string | null | undefined): SharingType | undefined
+function useDriveSharingType(
+  driveId: string | null | undefined,
+): SharingType | undefined;
 
 /** Returns  whether a drive is available offline. */
-function useDriveAvailableOffline(driveId: string | null | undefined): boolean
+function useDriveAvailableOffline(driveId: string | null | undefined): boolean;
 ```
 
 ##### Usage
 
 ```jsx
-import { 
+import {
   useDriveRemoteUrl,
   useDrivePullResponderTrigger,
   useDrivePullResponderUrl,
   useDriveIsRemote,
   useDriveSharingType,
   useDriveAvailableOffline,
-} from '@powerhousedao/state';
+} from "@powerhousedao/state";
 
 function MyEditorComponent() {
   const myDriveId = "some-drive-id";
@@ -154,68 +168,147 @@ function MyEditorComponent() {
     driveIsRemote,
     driveSharingType,
     driveAvailableOffline,
-  })
+  });
 }
 ```
 
 ### Documents
 
-#### useAllDocuments/useSelectedDriveDocuments
+#### useDocumentById
+
 ```ts
-function useAllDocuments(): PHDocument[] | undefined
+function useDocumentById(id: string | null | undefined): PHDocument | undefined;
+```
+
+Returns a document and a dispatch function by id.
+
+##### Usage
+
+```jsx
+import { useDocumentById } from "@powerhousedao/state";
+
+function MyEditorComponent() {
+  const myDocumentId = "some-document-id";
+  const [document, dispatch] = useDocumentById(myDocumentId);
+}
 ```
-Returns all of the documents in the reactor.
+
+#### useGetDocument
 
 ```ts
-function useSelectedDriveDocuments(): PHDocument[] | undefined
+function useGetDocument(id: string | null | undefined): PHDocument | undefined;
 ```
-Returns the documents in the reactor for the selected drive.
+
+Retrieves a document from the reactor and subscribes to changes using React Suspense. This hook will suspend rendering while the document is loading.
 
 ##### Usage
 
 ```jsx
-import { useAllDocuments, useSelectedDriveDocuments } from '@powerhousedao/state';
+import { useGetDocument } from "@powerhousedao/state";
 
 function MyEditorComponent() {
-  const allDocuments = useAllDocuments();
-  const selectedDriveDocuments = useSelectedDriveDocuments();
+  const documentId = "some-document-id";
+  const document = useGetDocument(documentId);
 }
 ```
 
-#### useSelectedDocument
+#### useGetDocuments
+
 ```ts
-function useSelectedDocument(): PHDocument | undefined
+function useGetDocuments(
+  ids: string[] | null | undefined,
+): PHDocument[] | undefined;
 ```
-Returns the selected document. You can set the selected document with `setSelectedNode`.
+
+Retrieves multiple documents from the reactor using React Suspense. This hook will suspend rendering while any of the documents are loading.
 
 ##### Usage
 
 ```jsx
-import { useSelectedDocument } from '@powerhousedao/state';
+import { useGetDocuments } from "@powerhousedao/state";
 
 function MyEditorComponent() {
-  const selectedDocument = useSelectedDocument();
+  const documentIds = ["doc-id-1", "doc-id-2", "doc-id-3"];
+  const documents = useGetDocuments(documentIds);
 }
 ```
 
-#### useDocumentById
+#### useGetDocumentAsync
+
+```ts
+function useGetDocumentAsync(id: string | null | undefined): {
+  status: "initial" | "pending" | "success" | "error";
+  data: PHDocument | undefined;
+  isPending: boolean;
+  error: unknown;
+  reload: (() => void) | undefined;
+};
+```
+
+Retrieves a document from the reactor without suspending rendering. Returns the current state of the document loading operation, including status, data, error, and a reload function.
+
+##### Usage
+
+```jsx
+import { useGetDocumentAsync } from "@powerhousedao/state";
+
+function MyEditorComponent() {
+  const documentId = "some-document-id";
+  const { status, data, isPending, error, reload } =
+    useGetDocumentAsync(documentId);
+
+  if (isPending) {
+    return <div>Loading...</div>;
+  }
+
+  if (error) {
+    return <div>Error: {error.message}</div>;
+  }
+
+  if (status === "success" && data) {
+    return <div>Document: {data.name}</div>;
+  }
+}
+```
+
+#### useDocumentsInSelectedDrive
+
+```ts
+function useDocumentsInSelectedDrive(): PHDocument[] | undefined;
+```
+
+Returns the documents in the reactor for the selected drive.
+
+##### Usage
+
+```jsx
+import { useDocumentsInSelectedDrive } from "@powerhousedao/state";
+
+function MyEditorComponent() {
+  const selectedDriveDocuments = useDocumentsInSelectedDrive();
+}
+```
+
+#### useSelectedDocument
+
 ```ts
-function useDocumentById(id: string | null | undefined): PHDocument | undefined
+function useSelectedDocument(): PHDocument | undefined;
 ```
-Returns a document by id.
+
+Returns the selected document. You can set the selected document with `setSelectedNode`.
 
 ##### Usage
 
 ```jsx
-import { useDocumentById } from '@powerhousedao/state';
+import { useSelectedDocument } from "@powerhousedao/state";
 
 function MyEditorComponent() {
-  const myDocumentId = 'some-document-id';
-  const documentById = useDocumentById(myDocumentId);
+  const selectedDocument = useSelectedDocument();
 }
 ```
 
 ### 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.
@@ -231,30 +324,32 @@ type FileNode = {
   kind: string;
   name: string;
   parentFolder: string | null | undefined;
-}
+};
 
 type FolderNode = {
   id: string;
   kind: string;
   name: string;
   parentFolder: string | null | undefined;
-}
+};
 
 type Node = FileNode | FolderNode;
 ```
 
 #### useNodes
+
 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
+function useNodes(): Node[] | undefined;
 ```
+
 Returns the nodes for a drive.
 
 ##### Usage
 
 ```jsx
-import { useNodes} from '@powerhousedao/state';
+import { useNodes } from "@powerhousedao/state";
 
 function MyEditorComponent() {
   const nodes = useNodes();
@@ -262,34 +357,38 @@ function MyEditorComponent() {
 ```
 
 #### useNodeById
+
 ```ts
-function useNodeById(id: string | null | undefined): Node | undefined
+function useNodeById(id: string | null | undefined): Node | undefined;
 ```
+
 Returns a node in the selected drive by id.
 
 ##### Usage
 
 ```jsx
-import { useNodeById } from '@powerhousedao/state';
+import { useNodeById } from "@powerhousedao/state";
 
 function MyEditorComponent() {
-  const myFolderId = 'some-folder-id';
-  const myDocumentId = 'some-document-id';
+  const myFolderId = "some-folder-id";
+  const myDocumentId = "some-document-id";
   const myFolderNode = useNodeById(myFolderId);
   const myFileNode = useNodeById(myDocumentId);
 }
 ```
 
 #### useSelectedFolder
+
 ```ts
-function useSelectedFolder(): FolderNode | undefined
+function useSelectedFolder(): FolderNode | undefined;
 ```
+
 Returns the selected folder. You can set the selected folder with `setSelectedNode`
 
 ##### Usage
 
 ```jsx
-import { useSelectedFolder } from '@powerhousedao/state';
+import { useSelectedFolder } from "@powerhousedao/state";
 
 function MyEditorComponent() {
   const selectedFolder = useSelectedFolder();
@@ -297,9 +396,11 @@ function MyEditorComponent() {
 ```
 
 #### useSelectedNodePath
+
 ```ts
-function useSelectedNodePath(): Node[]
+function useSelectedNodePath(): Node[];
 ```
+
 Returns the path to the selected node. Useful for navigational components like breadcrumbs.
 
 ##### Usage
@@ -317,18 +418,21 @@ function MyEditorComponent() {
 #### useChildNodes/useFolderChildNodes/useFileChildNodes
 
 ```ts
-function useChildNodes(): Node[]
+function useChildNodes(): Node[];
 ```
+
 Returns the child nodes for the selected drive or folder.
 
 ```ts
-function useFolderChildNodes(): FolderNode[]
+function useFolderChildNodes(): FolderNode[];
 ```
+
 Returns the folder child nodes for the selected drive or folder.
 
 ```ts
-function useFileChildNodes(): FileNode[]
+function useFileChildNodes(): FileNode[];
 ```
+
 Returns the file (document) child nodes for the selected drive or folder.
 
 ##### Usage
@@ -352,17 +456,23 @@ function MyEditorComponent() {
 ```
 
 #### useChildNodesForId/useFolderChildNodesForId/useFileChildNodesForId
+
 ```ts
-function useChildNodesForId(id: string | null | undefined): Node[]
+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[]
+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[]
+function useFileChildNodesForId(id: string | null | undefined): FileNode[];
 ```
+
 Returns the file (document) child nodes for a drive or folder by id.
 
 ##### Usage
@@ -387,30 +497,34 @@ function MyEditorComponent() {
 ```
 
 #### useNodeName/useNodeKind
+
 ```ts
-function useNodeName(id: string | null | undefined): string | undefined
+function useNodeName(id: string | null | undefined): string | undefined;
 ```
+
 Returns the name of a node.
+
 ```ts
-function useNodeKind(id: string | null | undefined): NodeKind | undefined
+function useNodeKind(id: string | null | undefined): NodeKind | undefined;
 ```
+
 Returns the kind of a node.
 
 ##### Usage
 
 ```jsx
-import { useNodeName, useNodeKind } from '@powerhousedao/state';
+import { useNodeName, useNodeKind } from "@powerhousedao/state";
 
 function MyEditorComponent() {
-  const nodeId = 'some-node-id';
+  const nodeId = "some-node-id";
   const nodeName = useNodeName(nodeId);
   const nodeKind = useNodeKind(nodeId);
 
-  if (nodeKind === 'file') {
+  if (nodeKind === "file") {
     return <File name={nodeName} />;
   }
 
-  if (nodeKind === 'folder') {
+  if (nodeKind === "folder") {
     return <Folder name={nodeName} />;
   }
 }
@@ -433,7 +547,7 @@ Each Vetra package contains a `modules` field which optionally contains lists of
 #### useVetraPackages
 
 ```ts
-function useVetraPackages(): VetraPackage[] | undefined
+function useVetraPackages(): VetraPackage[] | undefined;
 ```
 
 Returns all of the Vetra packages in your Connect app.
@@ -441,17 +555,17 @@ Returns all of the Vetra packages in your Connect app.
 ##### Usage
 
 ```jsx
-import { useVetraPackages } from '@powerhousedao/state'
+import { useVetraPackages } from "@powerhousedao/state";
 
 function MyEditorComponent() {
-  const vetraPackages = useVetraPackages()
+  const vetraPackages = useVetraPackages();
 }
 ```
 
 #### useDocumentModelModules
 
 ```ts
-function useDocumentModelModules(): DocumentModelModule[] | undefined
+function useDocumentModelModules(): DocumentModelModule[] | undefined;
 ```
 
 Returns the document model modules from your Vetra packages.
@@ -459,38 +573,38 @@ Returns the document model modules from your Vetra packages.
 ##### Usage
 
 ```jsx
-import { useDocumentModelModules } from '@powerhousedao/state'
+import { useDocumentModelModules } from "@powerhousedao/state";
 
 function MyEditorComponent() {
-  const documentModelModules = useDocumentModelModules()
+  const documentModelModules = useDocumentModelModules();
 }
 ```
 
 #### useDocumentModelModuleById
 
 ```ts
-function useDocumentModelModuleById(): DocumentModelModule[] | undefined
+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.
+_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'
+import { useDocumentModelModuleById } from "@powerhousedao/state";
 
 function MyEditorComponent() {
-  const documentType = 'my-org/my-document';
-  const documentModelModuleById = useDocumentModelModuleById(documentType)
+  const documentType = "my-org/my-document";
+  const documentModelModuleById = useDocumentModelModuleById(documentType);
 }
 ```
 
 #### useEditorModules
 
 ```ts
-function useEditorModules(): EditorModule[] | undefined
+function useEditorModules(): EditorModule[] | undefined;
 ```
 
 Returns the editor modules from your Vetra packages.
@@ -498,17 +612,17 @@ Returns the editor modules from your Vetra packages.
 ##### Usage
 
 ```jsx
-import { useEditorModules } from '@powerhousedao/state'
+import { useEditorModules } from "@powerhousedao/state";
 
 function MyEditorComponent() {
-  const editorModules = useEditorModules()
+  const editorModules = useEditorModules();
 }
 ```
 
 #### useDriveEditorModules
 
 ```ts
-function useDriveEditorModules(): DriveEditorModule[] | undefined
+function useDriveEditorModules(): DriveEditorModule[] | undefined;
 ```
 
 Returns the drive editor modules from your Vetra packages.
@@ -516,17 +630,17 @@ Returns the drive editor modules from your Vetra packages.
 ##### Usage
 
 ```jsx
-import { useDriveEditorModules } from '@powerhousedao/state'
+import { useDriveEditorModules } from "@powerhousedao/state";
 
 function MyDriveEditorComponent() {
-  const driveEditorModules = useDriveEditorModules()
+  const driveEditorModules = useDriveEditorModules();
 }
 ```
 
 #### useProcessorModules
 
 ```ts
-function useProcessorModules(): ProcessorModule[] | undefined
+function useProcessorModules(): ProcessorModule[] | undefined;
 ```
 
 Returns the processor modules from your Vetra packages.
@@ -534,17 +648,17 @@ Returns the processor modules from your Vetra packages.
 ##### Usage
 
 ```jsx
-import { useProcessorModules } from '@powerhousedao/state'
+import { useProcessorModules } from "@powerhousedao/state";
 
 function MyProcessorComponent() {
-  const processorModules = useProcessorModules()
+  const processorModules = useProcessorModules();
 }
 ```
 
 #### useSubgraphModules
 
 ```ts
-function useSubgraphModules(): SubgraphModule[] | undefined
+function useSubgraphModules(): SubgraphModule[] | undefined;
 ```
 
 Returns the subgraph modules from your Vetra packages.
@@ -552,17 +666,17 @@ Returns the subgraph modules from your Vetra packages.
 ##### Usage
 
 ```jsx
-import { useSubgraphModules } from '@powerhousedao/state'
+import { useSubgraphModules } from "@powerhousedao/state";
 
 function MySubgraphComponent() {
-  const subgraphModules = useSubgraphModules()
+  const subgraphModules = useSubgraphModules();
 }
 ```
 
 #### useImportScriptModules
 
 ```ts
-function useImportScriptModules(): ImportScriptModule[] | undefined
+function useImportScriptModules(): ImportScriptModule[] | undefined;
 ```
 
 Returns the import script modules from your Vetra packages.
@@ -570,9 +684,9 @@ Returns the import script modules from your Vetra packages.
 ##### Usage
 
 ```jsx
-import { useImportScriptModules } from '@powerhousedao/state'
+import { useImportScriptModules } from "@powerhousedao/state";
 
 function MyImportScriptComponent() {
-  const importScriptModules = useImportScriptModules()
+  const importScriptModules = useImportScriptModules();
 }
-```
+```

package/dist/src/actions/dispatch.d.ts

@@ -1,4 +1,4 @@
-import { type Action, type PHDocument } from "document-model";
-export declare function dispatchActions(actionOrActions: Action[] | Action | undefined, document: PHDocument | undefined): Promise<PHDocument | undefined>;
+import type { Action, PHDocument } from "document-model";
+export declare function dispatchActions<TDocument = PHDocument, TAction = Action>(actionOrActions: TAction[] | TAction | undefined, document: TDocument | undefined): Promise<PHDocument | undefined>;
 export declare function dispatchActions(actionOrActions: Action[] | Action | undefined, documentId: string): Promise<PHDocument | undefined>;
 //# sourceMappingURL=dispatch.d.ts.map

package/dist/src/actions/dispatch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../../src/actions/dispatch.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAe9D,wBAAsB,eAAe,CACnC,eAAe,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,EAC9C,QAAQ,EAAE,UAAU,GAAG,SAAS,GAC/B,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAAC;AACnC,wBAAsB,eAAe,CACnC,eAAe,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,EAE9C,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAAC"}
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../../src/actions/dispatch.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAezD,wBAAsB,eAAe,CAAC,SAAS,GAAG,UAAU,EAAE,OAAO,GAAG,MAAM,EAC5E,eAAe,EAAE,OAAO,EAAE,GAAG,OAAO,GAAG,SAAS,EAChD,QAAQ,EAAE,SAAS,GAAG,SAAS,GAC9B,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAAC;AACnC,wBAAsB,eAAe,CACnC,eAAe,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,EAE9C,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAAC"}

package/dist/src/actions/dispatch.js

@@ -3,7 +3,7 @@ import { queueActions } from "./queue.js";
 import { makeSignedActionsWithContext } from "./sign.js";
 async function getDocument(documentId) {
     try {
-        return await window.reactor?.getDocument(documentId);
+        return await window.ph?.reactor?.getDocument(documentId);
     }
     catch (error) {
         logger.debug(`Failed to get document with id ${documentId}:`, error);