@powerhousedao/academy 5.0.10 → 5.1.0-dev.0

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

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