add docs for graph package (#603)graph-docs

1 files changed, 334 insertions, 0 deletions

diff --git a/apps/docs/memory-graph/api-reference.mdx b/apps/docs/memory-graph/api-reference.mdx
new file mode 100644
index 00000000..92641a74
--- /dev/null
+++ b/apps/docs/memory-graph/api-reference.mdx
@@ -0,0 +1,334 @@
+---
+title: 'API Reference'
+description: 'Complete reference for Memory Graph props and types'
+---
+
+## Component Props
+
+### MemoryGraph
+
+The main graph component.
+
+#### Core Props
+
+<ParamField path="documents" type="DocumentWithMemories[]" required>
+  Array of documents to display in the graph. Each document must include its memory entries.
+</ParamField>
+
+<ParamField path="isLoading" type="boolean" default="false">
+  Shows a loading indicator when true.
+</ParamField>
+
+<ParamField path="error" type="Error | null" default="null">
+  Error object to display. Shows an error message overlay when set.
+</ParamField>
+
+<ParamField path="variant" type='"console" | "consumer"' default='"console"'>
+  Visual variant:
+  - `console`: Full-featured dashboard view (0.8x zoom, space selector visible)
+  - `consumer`: Embedded widget view (0.5x zoom, space selector hidden)
+</ParamField>
+
+<ParamField path="children" type="ReactNode">
+  Content to render when no documents exist. Useful for empty states.
+</ParamField>
+
+#### Pagination Props
+
+<ParamField path="isLoadingMore" type="boolean" default="false">
+  Shows a subtle indicator when loading additional documents.
+</ParamField>
+
+<ParamField path="hasMore" type="boolean" default="false">
+  Whether more documents are available to load.
+</ParamField>
+
+<ParamField path="totalLoaded" type="number">
+  Total number of documents currently loaded. Shown in loading indicator.
+</ParamField>
+
+<ParamField path="loadMoreDocuments" type="() => Promise<void>">
+  Callback to load more documents. Called automatically when viewport shows most documents.
+</ParamField>
+
+<ParamField path="autoLoadOnViewport" type="boolean" default="true">
+  Automatically load more documents when 80% are visible in viewport.
+</ParamField>
+
+#### Display Props
+
+<ParamField path="showSpacesSelector" type="boolean">
+  Show or hide the space filter dropdown. Defaults to `true` for console variant, `false` for consumer.
+</ParamField>
+
+<ParamField path="highlightDocumentIds" type="string[]" default="[]">
+  Array of document IDs to highlight with a pulsing outline. Accepts both `customId` and internal `id`.
+</ParamField>
+
+<ParamField path="highlightsVisible" type="boolean" default="true">
+  Controls whether highlights are shown. Useful for toggling highlights without changing the array.
+</ParamField>
+
+<ParamField path="occludedRightPx" type="number" default="0">
+  Pixels occluded on the right side (e.g., by a sidebar). Graph auto-fits accounting for this space.
+</ParamField>
+
+<ParamField path="legendId" type="string">
+  Custom ID for the legend component. Useful for testing or styling.
+</ParamField>
+
+#### Controlled State Props
+
+<ParamField path="selectedSpace" type="string">
+  Currently selected space. When provided, makes space selection controlled. Use `"all"` for all spaces.
+</ParamField>
+
+<ParamField path="onSpaceChange" type="(spaceId: string) => void">
+  Callback when space selection changes. Required when using `selectedSpace`.
+</ParamField>
+
+<ParamField path="memoryLimit" type="number">
+  Maximum memories to show per document when a specific space is selected. Only applies when `selectedSpace !== "all"`.
+</ParamField>
+
+<ParamField path="isExperimental" type="boolean" default="false">
+  Enable experimental features. Currently unused but reserved for future features.
+</ParamField>
+
+## Data Types
+
+### DocumentWithMemories
+
+```typescript
+interface DocumentWithMemories {
+  id: string;
+  customId?: string | null;
+  contentHash: string | null;
+  orgId: string;
+  userId: string;
+  connectionId?: string | null;
+  title?: string | null;
+  content?: string | null;
+  summary?: string | null;
+  url?: string | null;
+  source?: string | null;
+  type?: string | null;
+  status: 'pending' | 'processing' | 'done' | 'failed';
+  metadata?: Record<string, string | number | boolean> | null;
+  processingMetadata?: Record<string, unknown> | null;
+  raw?: string | null;
+  tokenCount?: number | null;
+  wordCount?: number | null;
+  chunkCount?: number | null;
+  averageChunkSize?: number | null;
+  summaryEmbedding?: number[] | null;
+  summaryEmbeddingModel?: string | null;
+  createdAt: string | Date;
+  updatedAt: string | Date;
+  memoryEntries: MemoryEntry[];
+}
+```
+
+### MemoryEntry
+
+```typescript
+interface MemoryEntry {
+  id: string;
+  customId?: string | null;
+  documentId: string;
+  content: string | null;
+  summary?: string | null;
+  title?: string | null;
+  url?: string | null;
+  type?: string | null;
+  metadata?: Record<string, string | number | boolean> | null;
+  embedding?: number[] | null;
+  embeddingModel?: string | null;
+  tokenCount?: number | null;
+  createdAt: string | Date;
+  updatedAt: string | Date;
+
+  // Fields from join relationship
+  sourceAddedAt?: Date | null;
+  sourceRelevanceScore?: number | null;
+  sourceMetadata?: Record<string, unknown> | null;
+  spaceContainerTag?: string | null;
+
+  // Version chain fields
+  updatesMemoryId?: string | null;
+  nextVersionId?: string | null;
+  relation?: 'updates' | 'extends' | 'derives' | null;
+
+  // Memory status fields
+  isForgotten?: boolean;
+  forgetAfter?: Date | string | null;
+  isLatest?: boolean;
+
+  // Space/container fields
+  spaceId?: string | null;
+
+  // Legacy fields (for backwards compatibility)
+  memory?: string | null;
+  memoryRelations?: Array<{
+    relationType: 'updates' | 'extends' | 'derives';
+    targetMemoryId: string;
+  }> | null;
+  parentMemoryId?: string | null;
+}
+```
+
+### GraphNode
+
+Internal type for rendered nodes:
+
+```typescript
+interface GraphNode {
+  id: string;
+  type: 'document' | 'memory';
+  x: number;
+  y: number;
+  data: DocumentWithMemories | MemoryEntry;
+  size: number;
+  color: string;
+  isHovered: boolean;
+  isDragging: boolean;
+}
+```
+
+### GraphEdge
+
+Internal type for connections:
+
+```typescript
+interface GraphEdge {
+  id: string;
+  source: string;
+  target: string;
+  similarity: number;
+  edgeType: 'doc-memory' | 'doc-doc' | 'version';
+  relationType?: 'updates' | 'extends' | 'derives';
+  color: string;
+  visualProps: {
+    opacity: number;
+    thickness: number;
+    glow: number;
+    pulseDuration: number;
+  };
+}
+```
+
+## Exported Components
+
+Besides `MemoryGraph`, the package exports individual components for advanced use cases:
+
+### GraphCanvas
+
+Low-level canvas renderer. Not recommended for direct use.
+
+```typescript
+import { GraphCanvas } from '@supermemory/memory-graph';
+```
+
+### Legend
+
+Graph legend showing node types and counts.
+
+```typescript
+import { Legend } from '@supermemory/memory-graph';
+```
+
+### LoadingIndicator
+
+Loading state indicator with progress counter.
+
+```typescript
+import { LoadingIndicator } from '@supermemory/memory-graph';
+```
+
+### NodeDetailPanel
+
+Side panel showing node details when clicked.
+
+```typescript
+import { NodeDetailPanel } from '@supermemory/memory-graph';
+```
+
+### SpacesDropdown
+
+Space filter dropdown.
+
+```typescript
+import { SpacesDropdown } from '@supermemory/memory-graph';
+```
+
+## Exported Hooks
+
+### useGraphData
+
+Processes documents into graph nodes and edges.
+
+```typescript
+import { useGraphData } from '@supermemory/memory-graph';
+
+const { nodes, edges } = useGraphData(
+  data,
+  selectedSpace,
+  nodePositions,
+  draggingNodeId,
+  memoryLimit
+);
+```
+
+### useGraphInteractions
+
+Handles pan, zoom, and node interactions.
+
+```typescript
+import { useGraphInteractions } from '@supermemory/memory-graph';
+
+const {
+  panX,
+  panY,
+  zoom,
+  selectedNode,
+  handlePanStart,
+  handleWheel,
+  // ... more interaction handlers
+} = useGraphInteractions('console');
+```
+
+## Constants
+
+### colors
+
+Color palette used throughout the graph:
+
+```typescript
+import { colors } from '@supermemory/memory-graph';
+
+colors.document.primary;   // Document fill color
+colors.memory.primary;     // Memory fill color
+colors.connection.strong;  // Strong edge color
+```
+
+### GRAPH_SETTINGS
+
+Initial zoom and pan settings for variants:
+
+```typescript
+import { GRAPH_SETTINGS } from '@supermemory/memory-graph';
+
+GRAPH_SETTINGS.console.initialZoom;   // 0.8
+GRAPH_SETTINGS.consumer.initialZoom;  // 0.5
+```
+
+### LAYOUT_CONSTANTS
+
+Spatial layout configuration:
+
+```typescript
+import { LAYOUT_CONSTANTS } from '@supermemory/memory-graph';
+
+LAYOUT_CONSTANTS.clusterRadius;       // Memory orbit radius
+LAYOUT_CONSTANTS.documentSpacing;     // Distance between documents
+```