@powerhousedao/academy 5.1.0-dev.9 → 5.1.0

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

@@ -36,503 +36,713 @@ It's important to note that a function should only be named and treated as a hoo
 
 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)
+Learn more about the [Editors](/academy/MasteryTrack/BuildingUserExperiences/BuildingDocumentEditors)
+Learn more about the [Drive Editors](/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer)
 
 ## Key concepts
 
 ### Reactor
 
 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)
-# Reactor Browser Hooks API Documentation
 
-This document contains all documentation comments for the hooks exported from `packages/reactor-browser/src/hooks/index.ts`.
-
-## Table of Contents
-
-- [Allowed Document Model Modules](#allowed-document-model-modules)
-- [Child Nodes](#child-nodes)
-- [Config: Editor](#config-editor)
-- [Config: Set Config by Object](#config-set-config-by-object)
-- [Config: Use Value by Key](#config-use-value-by-key)
-- [Document by ID](#document-by-id)
-- [Document Cache](#document-cache)
-- [Document of Type](#document-of-type)
-- [Document Types](#document-types)
-- [Drives](#drives)
-- [Items in Selected Drive](#items-in-selected-drive)
-- [Items in Selected Folder](#items-in-selected-folder)
-- [Modals](#modals)
-- [Node by ID](#node-by-id)
-- [Node Path](#node-path)
-- [Revision History](#revision-history)
-- [Selected Document](#selected-document)
-- [Selected Drive](#selected-drive)
-- [Selected Folder](#selected-folder)
-- [Selected Node](#selected-node)
-- [Selected Timeline Item](#selected-timeline-item)
-- [Supported Document Types](#supported-document-types)
-- [Timeline Revision](#timeline-revision)
-- [Use Get Switchboard Link](#use-get-switchboard-link)
-- [Vetra Packages](#vetra-packages)
-
----
-
-## Allowed Document Model Modules
-
-### `useAllowedDocumentModelModules`
-
-No documentation available.
-
----
-
-## Child Nodes
-
-### `useNodesInSelectedDriveOrFolder`
-
-Returns the child nodes for the selected drive or folder.
-
----
-
-## Document by ID
-
-### `useDocumentById`
-
-Returns a document by id.
-
-### `useDocumentsByIds`
-
-Returns documents by ids.
-
----
-
-## Document Cache
-
-### `useDocumentCache`
-
-Returns all documents in the reactor.
-
-### `setDocumentCache`
-
-Sets all of the documents in the reactor.
+<details>
+<summary>useReactor</summary>
 
-### `addDocumentCacheEventHandler`
+```ts
+function useReactor(): Reactor | undefined;
+```
 
-Adds an event handler for all of the documents in the reactor.
+Returns the reactor instance.
 
-### `useGetDocument`
+Usage
 
-Retrieves a document from the reactor and subscribes to changes using React Suspense.
-This hook will suspend rendering while the document is loading.
+```jsx
+import { useReactor } from "@powerhousedao/state";
 
-**Parameters:**
-- `id` - The document ID to retrieve, or null/undefined to skip retrieval
+function MyEditorComponent() {
+  const reactor = useReactor();
+}
+```
 
-**Returns:** The document if found, or undefined if id is null/undefined
+</details>
 
-### `useGetDocuments`
+### Drives
 
-Retrieves multiple documents from the reactor using React Suspense.
-This hook will suspend rendering while any of the documents are loading.
+<details>
+<summary>useDrives</summary>
 
-**Parameters:**
-- `ids` - Array of document IDs to retrieve, or null/undefined to skip retrieval
+```ts
+function useDrives(): DocumentDriveDocument[] | undefined;
+```
 
-**Returns:** An array of documents if found, or undefined if ids is null/undefined
+Returns the drives for a reactor.
 
-### `useGetDocumentAsync`
+Usage
 
-Retrieves a document from the reactor without suspending rendering.
-Returns the current state of the document loading operation.
+```jsx
+import { useDrives } from "@powerhousedao/state";
 
-**Parameters:**
-- `id` - The document ID to retrieve, or null/undefined to skip retrieval
+function MyEditorComponent() {
+  const drives = useDrives();
+}
+```
 
-**Returns:** An object containing:
-- `status`: "initial" | "pending" | "success" | "error"
-- `data`: The document if successfully loaded
-- `isPending`: Boolean indicating if the document is currently loading
-- `error`: Any error that occurred during loading
-- `reload`: Function to force reload the document from cache
+</details>
 
----
+<details>
+<summary>useDriveById</summary>
 
-## Document of Type
+```ts
+function useDriveById(
+  id: string | null | undefined,
+): DocumentDriveDocument | undefined;
+```
 
-### `useDocumentOfType`
+Returns a drive by id.
 
-Returns a document of a specific type, throws an error if the found document has a different type.
+Usage
 
----
+```jsx
+import { useDriveById } from "@powerhousedao/state";
 
-## Document Types
+function MyEditorComponent() {
+  const driveById = useDriveById("some-id");
+}
+```
 
-### `useDocumentTypes`
+</details>
 
-Returns the document types a drive editor supports.
+<details>
+<summary>useSelectedDrive</summary>
 
-If present, uses the `allowedDocumentTypes` config value.
-Otherwise, uses the supported document types from the reactor.
+```ts
+function useSelectedDrive(): DocumentDriveDocument | undefined;
+```
 
----
+Returns the selected drive. You can set the selected drive with `setSelectedDrive`.
 
-## Drives
+Usage
 
-### `useDrives`
+```jsx
+import { useSelectedDrive } from "@powerhousedao/state";
 
-Returns all of the drives in the reactor.
+function MyEditorComponent() {
+  const selectedDrive = useSelectedDrive();
+}
+```
 
-### `setDrives`
+</details>
 
-Sets the drives in the reactor.
+<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,
+  });
+}
+```
 
-### `addDrivesEventHandler`
+</details>
 
-Adds an event handler for the drives.
+### Documents
 
----
+<details>
+<summary>useAllDocuments/useSelectedDriveDocuments</summary>
 
-## Items in Selected Drive
+```ts
+function useAllDocuments(): PHDocument[] | undefined;
+```
 
-### `useNodesInSelectedDrive`
+Returns all of the documents in the reactor.
 
-Returns the nodes in the selected drive.
+```ts
+function useSelectedDriveDocuments(): PHDocument[] | undefined;
+```
 
-### `useFileNodesInSelectedDrive`
+Returns the documents in the reactor for the selected drive.
 
-Returns the file nodes in the selected drive.
+Usage
 
-### `useFolderNodesInSelectedDrive`
+```jsx
+import {
+  useAllDocuments,
+  useSelectedDriveDocuments,
+} from "@powerhousedao/state";
 
-Returns the folder nodes in the selected drive.
+function MyEditorComponent() {
+  const allDocuments = useAllDocuments();
+  const selectedDriveDocuments = useSelectedDriveDocuments();
+}
+```
 
-### `useDocumentsInSelectedDrive`
+</details>
 
-Returns the documents in the selected drive.
+<details>
+<summary>useSelectedDocument</summary>
 
-### `useDocumentTypesInSelectedDrive`
+```ts
+function useSelectedDocument(): PHDocument | undefined;
+```
 
-Returns the document types supported by the selected drive, as defined by the document model documents present in the drive.
+Returns the selected document. You can set the selected document with `setSelectedNode`.
 
----
+Usage
 
-## Items in Selected Folder
+```jsx
+import { useSelectedDocument } from "@powerhousedao/state";
 
-### `useNodesInSelectedFolder`
+function MyEditorComponent() {
+  const selectedDocument = useSelectedDocument();
+}
+```
 
-Returns the nodes in the selected folder.
+</details>
 
-### `useFileNodesInSelectedFolder`
+<details>
+<summary>useDocumentById</summary>
 
-Returns the file nodes in the selected folder.
+```ts
+function useDocumentById(id: string | null | undefined): PHDocument | undefined;
+```
 
-### `useFolderNodesInSelectedFolder`
+Returns a document by id.
 
-Returns the folder nodes in the selected folder.
+Usage
 
-### `useDocumentsInSelectedFolder`
+```jsx
+import { useDocumentById } from "@powerhousedao/state";
 
-Returns the documents in the selected folder.
+function MyEditorComponent() {
+  const myDocumentId = "some-document-id";
+  const documentById = useDocumentById(myDocumentId);
+}
+```
 
----
+</details>
 
-## Modals
+### Nodes
 
-### `usePHModal`
+"Nodes" refers to the items found in a given drive's `state.global.nodes` array. Nodes can represent both files (documents) and folders.
 
-Returns the current modal.
+A document in a drive will have a node in the drive's node list which has the same id as the document.
 
-### `setPHModal`
+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.
 
-Sets the current modal.
+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.
 
-### `addModalEventHandler`
+```ts
+type FileNode = {
+  documentType: string;
+  id: string;
+  kind: string;
+  name: string;
+  parentFolder: string | null | undefined;
+};
 
-Adds an event handler for the modal.
+type FolderNode = {
+  id: string;
+  kind: string;
+  name: string;
+  parentFolder: string | null | undefined;
+};
 
-### `showPHModal`
+type Node = FileNode | FolderNode;
+```
 
-Shows a modal.
+<details>
+<summary>useNodes</summary>
 
-### `closePHModal`
+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.
 
-Closes the current modal.
+```ts
+function useNodes(): Node[] | undefined;
+```
 
-### `showCreateDocumentModal`
+Returns the nodes for a drive.
 
-Shows the create document modal.
+Usage
 
-### `showDeleteNodeModal`
+```jsx
+import { useNodes } from "@powerhousedao/state";
 
-Shows the delete node modal.
+function MyEditorComponent() {
+  const nodes = useNodes();
+}
+```
 
----
+</details>
 
-## Node by ID
+<details>
+<summary>useNodeById</summary>
 
-### `useNodeById`
+```ts
+function useNodeById(id: string | null | undefined): Node | undefined;
+```
 
 Returns a node in the selected drive by id.
 
----
-
-## Node Path
+Usage
 
-### `useNodePathById`
+```jsx
+import { useNodeById } from "@powerhousedao/state";
 
-Returns the path to a node in the selected drive.
+function MyEditorComponent() {
+  const myFolderId = "some-folder-id";
+  const myDocumentId = "some-document-id";
+  const myFolderNode = useNodeById(myFolderId);
+  const myFileNode = useNodeById(myDocumentId);
+}
+```
 
-### `useSelectedNodePath`
-
-Returns the path to the currently selected node in the selected drive.
+</details>
 
----
+<details>
+<summary>useSelectedFolder</summary>
 
-## Revision History
+```ts
+function useSelectedFolder(): FolderNode | undefined;
+```
 
-### `useRevisionHistoryVisible`
+Returns the selected folder. You can set the selected folder with `setSelectedNode`
 
-Returns whether revision history is visible.
+Usage
 
-### `setRevisionHistoryVisible`
+```jsx
+import { useSelectedFolder } from "@powerhousedao/state";
 
-Sets revision history visibility.
+function MyEditorComponent() {
+  const selectedFolder = useSelectedFolder();
+}
+```
 
-### `addRevisionHistoryVisibleEventHandler`
+</details>
 
-Adds event handler for revision history visibility.
+<details>
+<summary>useSelectedNodePath</summary>
 
-### `showRevisionHistory`
+```ts
+function useSelectedNodePath(): Node[];
+```
 
-Shows the revision history.
+Returns the path to the selected node. Useful for navigational components like breadcrumbs.
 
-### `hideRevisionHistory`
+Usage
 
-Hides the revision history.
+```jsx
+import { useSelectedNodePath } from "@powerhousedao/state";
 
----
+function MyEditorComponent() {
+  const nodes = useSelectedNodePath();
 
-## Selected Document
+  return <Breadcrumbs nodes={nodes} />;
+}
+```
 
-### `useSelectedDocumentId`
+</details>
 
-Returns the selected document id.
+<details>
+<summary>useChildNodes/useFolderChildNodes/useFileChildNodes</summary>
 
-### `useSelectedDocument`
+```ts
+function useChildNodes(): Node[];
+```
 
-Returns the selected document.
+Returns the child nodes for the selected drive or folder.
 
-### `useSelectedDocumentOfType`
+```ts
+function useFolderChildNodes(): FolderNode[];
+```
 
-Returns the selected document of a specific type, throws an error if the found document has a different type.
+Returns the folder child nodes for the selected drive or folder.
 
----
+```ts
+function useFileChildNodes(): FileNode[];
+```
 
-## Selected Drive
+Returns the file (document) child nodes for the selected drive or folder.
 
-### `useSelectedDriveId`
+Usage
 
-Returns the selected drive id.
+```jsx
+import {
+  useChildNodes,
+  useFolderChildNodes,
+  useFileChildNodes,
+} from "@powerhousedao/state";
 
-### `setSelectedDriveId`
+function MyEditorComponent() {
+  const nodes = useChildNodes();
+  const fileNodes = useFileChildNodes();
+  const folderNodes = useFolderChildNodes();
 
-Sets the selected drive id.
+  return (
+    <div>
+      <FilesAndFolders nodes={nodes} />
+      <Files fileNodes={fileNodes} />
+      <Folders folderNodes={folderNodes} />
+    </div>
+  );
+}
+```
 
-### `addSelectedDriveIdEventHandler`
+</details>
 
-Adds an event handler for the selected drive id.
+<details>
+<summary>useChildNodesForId/useFolderChildNodesForId/useFileChildNodesForId</summary>
 
-### `useSelectedDrive`
+```ts
+function useChildNodesForId(id: string | null | undefined): Node[];
+```
 
-Returns the selected drive.
+Returns the child nodes for a drive or folder by id.
 
-### `useSelectedDriveSafe`
+```ts
+function useFolderChildNodesForId(id: string | null | undefined): FolderNode[];
+```
 
-Returns the selected drive, or undefined if no drive is selected.
+Returns the folder child nodes for a drive or folder by id.
 
----
+```ts
+function useFileChildNodesForId(id: string | null | undefined): FileNode[];
+```
 
-## Selected Folder
+Returns the file (document) child nodes for a drive or folder by id.
 
-### `useSelectedFolder`
+Usage
 
-Returns the selected folder.
+```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);
 
-## Selected Node
+  return (
+    <div>
+      <FilesAndFolders nodes={nodes} />
+      <Files fileNodes={fileNodes} />
+      <Folders folderNodes={folderNodes} />
+    </div>
+  );
+}
+```
 
-### `useSelectedNode`
+</details>
 
-Returns the selected node.
+<details>
+<summary>useNodeName/useNodeKind</summary>
 
-### `setSelectedNode`
+```ts
+function useNodeName(id: string | null | undefined): string | undefined;
+```
 
-Sets the selected node (file or folder).
+Returns the name of a node.
 
----
+```ts
+function useNodeKind(id: string | null | undefined): NodeKind | undefined;
+```
 
-## Selected Timeline Item
+Returns the kind of a node.
 
-### `useSelectedTimelineItem`
+Usage
 
-Returns the selected timeline item.
+```jsx
+import { useNodeName, useNodeKind } from "@powerhousedao/state";
 
-### `setSelectedTimelineItem`
+function MyEditorComponent() {
+  const nodeId = "some-node-id";
+  const nodeName = useNodeName(nodeId);
+  const nodeKind = useNodeKind(nodeId);
 
-Sets the selected timeline item.
+  if (nodeKind === "file") {
+    return <File name={nodeName} />;
+  }
 
-### `addSelectedTimelineItemEventHandler`
+  if (nodeKind === "folder") {
+    return <Folder name={nodeName} />;
+  }
+}
+```
 
-Adds event handler for selected timeline item.
+</details>
 
----
+### Vetra Packages and Modules
 
-## Supported Document Types
+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.
 
-### `useSupportedDocumentTypesInReactor`
+These modules can be for:
 
-Returns the supported document types for the reactor (derived from the document model modules).
+- document models
+- editors
+- subgraphs
+- import scripts
+- processors
 
----
+Each Vetra package contains a `modules` field which optionally contains lists of these modules.
 
-## Timeline Revision
+<details>
+<summary>useVetraPackages</summary>
 
-### `useSelectedTimelineRevision`
+```ts
+function useVetraPackages(): VetraPackage[] | undefined;
+```
 
-Returns the selected timeline revision.
+Returns all of the Vetra packages in your Connect app.
 
-### `setSelectedTimelineRevision`
+Usage
 
-Sets the selected timeline revision.
+```jsx
+import { useVetraPackages } from "@powerhousedao/state";
 
-### `addSelectedTimelineRevisionEventHandler`
+function MyEditorComponent() {
+  const vetraPackages = useVetraPackages();
+}
+```
 
-Adds an event handler for the selected timeline revision.
+</details>
 
----
+<details>
+<summary>useDocumentModelModules</summary>
 
-## Use Get Switchboard Link
+```ts
+function useDocumentModelModules(): DocumentModelModule[] | undefined;
+```
 
-### `useGetSwitchboardLink`
+Returns the document model modules from your Vetra packages.
 
-Hook that returns a function to generate a document's switchboard URL.
-Only returns a function for documents in remote drives.
-Returns null for local drives or when the document/drive cannot be determined.
+Usage
 
-The returned function generates a fresh bearer token and builds the switchboard URL
-with authentication when called.
+```jsx
+import { useDocumentModelModules } from "@powerhousedao/state";
 
-**Parameters:**
-- `document` - The document to create a switchboard URL generator for
+function MyEditorComponent() {
+  const documentModelModules = useDocumentModelModules();
+}
+```
 
-**Returns:** An async function that returns the switchboard URL, or null if not applicable
+</details>
 
----
+<details>
+<summary>useDocumentModelModuleById</summary>
 
-## Vetra Packages
+```ts
+function useDocumentModelModuleById(): DocumentModelModule[] | undefined;
+```
 
-### `useVetraPackages`
+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.
 
-Returns all of the Vetra packages loaded by the Connect instance.
+Usage
 
-### `addVetraPackagesEventHandler`
+```jsx
+import { useDocumentModelModuleById } from "@powerhousedao/state";
 
-Adds the Vetra packages event handler.
+function MyEditorComponent() {
+  const documentType = "my-org/my-document";
+  const documentModelModuleById = useDocumentModelModuleById(documentType);
+}
+```
 
-### `setVetraPackages`
+</details>
 
-Sets the Vetra packages for the Connect instance.
+<details>
+<summary>useEditorModules</summary>
 
----
+```ts
+function useEditorModules(): EditorModule[] | undefined;
+```
 
+Returns the editor modules from your Vetra packages.
 
-## Config: Editor
+Usage
 
-### `setIsExternalControlsEnabled`
+```jsx
+import { useEditorModules } from "@powerhousedao/state";
 
-Sets whether external controls are enabled for a given editor.
+function MyEditorComponent() {
+  const editorModules = useEditorModules();
+}
+```
 
-### `useIsExternalControlsEnabled`
+</details>
 
-Gets whether external controls are enabled for a given editor.
+<details>
+<summary>useDriveEditorModules</summary>
 
-### `addIsExternalControlsEnabledEventHandler`
+```ts
+function useDriveEditorModules(): DriveEditorModule[] | undefined;
+```
 
-Adds an event handler for when the external controls enabled state changes.
+Returns the drive editor modules from your Vetra packages.
 
-### `setIsDragAndDropEnabled`
+Usage
 
-Sets whether drag and drop is enabled for a given drive editor.
+```jsx
+import { useDriveEditorModules } from "@powerhousedao/state";
 
-### `useIsDragAndDropEnabled`
+function MyDriveEditorComponent() {
+  const driveEditorModules = useDriveEditorModules();
+}
+```
 
-Gets whether drag and drop is enabled for a given drive editor.
+</details>
 
-### `addIsDragAndDropEnabledEventHandler`
+<details>
+<summary>useProcessorModules</summary>
 
-Adds an event handler for when the drag and drop enabled state changes.
+```ts
+function useProcessorModules(): ProcessorModule[] | undefined;
+```
 
-### `setAllowedDocumentTypes`
+Returns the processor modules from your Vetra packages.
 
-Sets the allowed document types for a given drive editor.
+Usage
 
-### `useAllowedDocumentTypes`
+```jsx
+import { useProcessorModules } from "@powerhousedao/state";
 
-Defines the document types a drive supports.
+function MyProcessorComponent() {
+  const processorModules = useProcessorModules();
+}
+```
 
-Defaults to all of the document types registered in the reactor.
+</details>
 
-### `addAllowedDocumentTypesEventHandler`
+<details>
+<summary>useSubgraphModules</summary>
 
-Adds an event handler for when the allowed document types for a given drive editor changes.
+```ts
+function useSubgraphModules(): SubgraphModule[] | undefined;
+```
 
----
+Returns the subgraph modules from your Vetra packages.
 
-## Config: Set Config by Object
+Usage
 
-### `setPHDriveEditorConfig`
+```jsx
+import { useSubgraphModules } from "@powerhousedao/state";
 
-Sets the global drive config.
+function MySubgraphComponent() {
+  const subgraphModules = useSubgraphModules();
+}
+```
 
-Pass in a partial object of the global drive config to set.
+</details>
 
-### `setPHDocumentEditorConfig`
+<details>
+<summary>useImportScriptModules</summary>
 
-Sets the global document config.
+```ts
+function useImportScriptModules(): ImportScriptModule[] | undefined;
+```
 
-Pass in a partial object of the global document config to set.
+Returns the import script modules from your Vetra packages.
 
-### `useSetPHDriveEditorConfig`
+Usage
 
-Wrapper hook for setting the global drive editor config.
+```jsx
+import { useImportScriptModules } from "@powerhousedao/state";
 
-Automatically sets the global drive editor config when the component mounts.
+function MyImportScriptComponent() {
+  const importScriptModules = useImportScriptModules();
+}
+```
 
-Pass in a partial object of the global drive editor config to set.
+</details>
 
-### `useSetPHDocumentEditorConfig`
+## More documentation coming soon!
 
-Wrapper hook for setting the global document editor config.
+Global access to drive state: A top-level, possibly context-based, way to introspect and interact with any document and its state tree without manually passing things around.
 
-Automatically sets the global document editor config when the component mounts.
+Global dispatcher access: A utility or API (probably a hook or service function) where they give a document ID and get back all the relevant dispatch functions — kind of like a command palette for document ops.
 
-Pass in a partial object of the global document editor config to set.
+### Core Hooks & Patterns
 
----
+- useDocumentField
+- useReadDocumentField
+- useUpdateDocumentField
+- useDocumentDispatch(docId): updateX, delete, ...
 
-## Config: Use Value by Key
+### Global Drive Access
 
-### `usePHDriveEditorConfigByKey`
+- How to access and manipulate the global document tree
+- How to inspect children from parent context
+- Tree traversal utilities (if any)
 
-Gets the value of an item in the global drive config for a given key.
+### Convenience APIs
 
-Strongly typed, inferred from type definition for the key.
+- Utility functions like getDispatchFunctions(docId)
+- "Quick Start" to manipulate any document like a pro
 
-### `usePHDocumentEditorConfigByKey`
+### Working with Context
 
-Gets the value of an item in the global document config for a given key.
+- DriveContext: what lives there, how to use it
+- Example: using context to get current doc, sibling docs
 
-Strongly typed, inferred from type definition for the key.
+### Best Practices & Patterns
 
----
+- When to use useDocumentField vs getDispatch
+- Composing document fields into custom logic