pda-explorer-react 0.1.0

package/README.md

@@ -0,0 +1,159 @@
+# PDA Explorer
+
+Interactive visualization tool for Solana Program Derived Address (PDA) hierarchies.
+
+![PDA Explorer Screenshot](./docs/screenshot.png)
+
+## Why?
+
+Solana's PDA model can be challenging to reason about:
+
+- PDAs form hierarchical trees where child addresses depend on parent data
+- Relationships are implicit in seed derivation patterns
+- Discovery requires knowing the exact seed structure
+
+PDA Explorer makes these relationships **visual and interactive**, helping developers understand their program's account model.
+
+## Installation
+
+```bash
+npm install @pda-explorer/react
+```
+
+## Usage
+
+```tsx
+import { PdaExplorer } from "@pda-explorer/react";
+import "@pda-explorer/react/styles.css";
+
+// Define your program's PDA schema
+const mySchema = {
+  programName: "My Program",
+  programId: "MyProgram111111111111111111111111111111111",
+  accounts: {
+    UserAccount: {
+      id: "UserAccount",
+      name: "User Account",
+      seeds: [
+        { name: "prefix", type: "literal", value: "user" },
+        { name: "authority", type: "pubkey", source: "User's wallet" },
+      ],
+      parent: null,
+      children: ["UserData"],
+      description: "Main user account",
+      color: "#8B5CF6",
+    },
+    UserData: {
+      id: "UserData",
+      name: "User Data",
+      seeds: [
+        { name: "prefix", type: "literal", value: "data" },
+        { name: "user", type: "pubkey", source: "UserAccount PDA" },
+        { name: "index", type: "u64", source: "Data index" },
+      ],
+      parent: "UserAccount",
+      children: [],
+      description: "User's data entries",
+      color: "#10B981",
+    },
+  },
+};
+
+function App() {
+  return (
+    <PdaExplorer
+      schema={mySchema}
+      height={600}
+      showLegend={true}
+      showPanel={true}
+    />
+  );
+}
+```
+
+## Schema Format
+
+### PdaSchema
+
+| Field         | Type                            | Description                    |
+| ------------- | ------------------------------- | ------------------------------ |
+| `programName` | `string`                        | Display name of your program   |
+| `programId`   | `string?`                       | Base58 program ID              |
+| `description` | `string?`                       | Program description            |
+| `accounts`    | `Record<string, PdaAccountType>` | Account type definitions       |
+
+### PdaAccountType
+
+| Field               | Type              | Description                              |
+| ------------------- | ----------------- | ---------------------------------------- |
+| `id`                | `string`          | Unique identifier                        |
+| `name`              | `string`          | Display name                             |
+| `seeds`             | `SeedComponent[]` | Seed derivation pattern                  |
+| `parent`            | `string \| null`  | Parent account ID (null for root)        |
+| `children`          | `string[]`        | Child account IDs                        |
+| `description`       | `string`          | What this account stores                 |
+| `color`             | `string`          | Hex color for visualization              |
+| `deriveFunctionName`| `string?`         | Name of derive function (for reference)  |
+
+### SeedComponent
+
+| Field    | Type       | Description                              |
+| -------- | ---------- | ---------------------------------------- |
+| `name`   | `string`   | Seed name (for display)                  |
+| `type`   | `SeedType` | `literal`, `pubkey`, `u8`-`u64`          |
+| `value`  | `string?`  | For literal seeds: the string value      |
+| `source` | `string?`  | Human-readable description of data source|
+
+## Component Props
+
+### PdaExplorer
+
+| Prop          | Type                | Default                    | Description                     |
+| ------------- | ------------------- | -------------------------- | ------------------------------- |
+| `schema`      | `PdaSchema`         | required                   | The PDA schema to visualize     |
+| `title`       | `string?`           | `{programName} PDA Explorer`| Custom title                   |
+| `description` | `string?`           | Schema description          | Custom description             |
+| `showLegend`  | `boolean`           | `true`                     | Show quick-select legend        |
+| `showPanel`   | `boolean`           | `true`                     | Show seed details panel         |
+| `panelWidth`  | `number \| string`  | `320`                      | Panel width                     |
+| `height`      | `number \| string`  | `600`                      | Component height                |
+| `className`   | `string`            | `""`                       | Additional CSS classes          |
+
+## Exports
+
+### Components
+
+- `PdaExplorer` - Main visualization component
+- `PdaGraph` - Graph canvas (for custom layouts)
+- `SeedPanel` - Seed details panel (for custom layouts)
+- `AccountNode` - Individual node component
+
+### Types
+
+- `PdaSchema`, `PdaAccountType`, `SeedComponent`, `SeedType`
+- `PdaNode`, `PdaNodeData`, `PdaEdge`, `PdaEdgeData`
+
+### Helpers
+
+- `getRootAccounts(schema)` - Get root-level accounts
+- `getChildren(schema, id)` - Get children of an account
+- `getParent(schema, id)` - Get parent of an account
+- `formatSeedPattern(account)` - Format seeds as `["prefix", pubkey, u64_le]`
+- `validateSchema(schema)` - Validate schema for errors
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run demo app
+npm run dev
+
+# Build library
+npm run build
+```
+
+## License
+
+MIT

package/dist/components/AccountNode.d.ts

@@ -0,0 +1,17 @@
+import { PdaNodeData } from '../types';
+
+interface AccountNodeProps {
+    data: PdaNodeData;
+    selected?: boolean;
+}
+/**
+ * Custom node component for PDA accounts in the graph
+ *
+ * Displays:
+ * - Account name with color-coded background
+ * - Seed count badge
+ * - Connection handles for edges
+ */
+declare function AccountNodeComponent({ data, selected }: AccountNodeProps): import("react/jsx-runtime").JSX.Element;
+export declare const AccountNode: import('react').MemoExoticComponent<typeof AccountNodeComponent>;
+export {};

package/dist/components/PdaExplorer.d.ts

@@ -0,0 +1,29 @@
+import { PdaSchema } from '../types';
+
+export interface PdaExplorerProps {
+    /** The PDA schema to visualize */
+    schema: PdaSchema;
+    /** Optional title override (defaults to schema.programName) */
+    title?: string;
+    /** Optional description override */
+    description?: string;
+    /** Show the legend/quick select bar (default: true) */
+    showLegend?: boolean;
+    /** Show the seed details panel (default: true) */
+    showPanel?: boolean;
+    /** Panel width in pixels or CSS value (default: 320) */
+    panelWidth?: number | string;
+    /** Custom class name for the container */
+    className?: string;
+    /** Height of the explorer (default: 600px) */
+    height?: number | string;
+}
+/**
+ * PDA Explorer - Interactive visualization of a Solana program's account model
+ *
+ * Shows all PDA account types with their:
+ * - Hierarchical relationships (parent-child)
+ * - Seed derivation patterns
+ * - Derive function references
+ */
+export declare function PdaExplorer({ schema, title, description, showLegend, showPanel, panelWidth, className, height, }: PdaExplorerProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/PdaGraph.d.ts

@@ -0,0 +1,18 @@
+import { PdaSchema } from '../types';
+
+interface PdaGraphProps {
+    schema: PdaSchema;
+    onNodeSelect: (nodeId: string | null) => void;
+    selectedNodeId: string | null;
+    /** Edge color (default: #6B7280) */
+    edgeColor?: string;
+    /** Show minimap (default: true) */
+    showMinimap?: boolean;
+    /** Show controls (default: true) */
+    showControls?: boolean;
+}
+/**
+ * Main graph visualization component using React Flow
+ */
+export declare function PdaGraph({ schema, onNodeSelect, selectedNodeId, edgeColor, showMinimap, showControls, }: PdaGraphProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/SeedPanel.d.ts

@@ -0,0 +1,11 @@
+import { PdaSchema, PdaAccountType } from '../types';
+
+interface SeedPanelProps {
+    schema: PdaSchema;
+    account: PdaAccountType | null;
+}
+/**
+ * Side panel showing seed derivation details for a selected account
+ */
+export declare function SeedPanel({ schema, account }: SeedPanelProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/index.d.ts

@@ -0,0 +1,5 @@
+export { PdaExplorer } from './PdaExplorer';
+export type { PdaExplorerProps } from './PdaExplorer';
+export { PdaGraph } from './PdaGraph';
+export { SeedPanel } from './SeedPanel';
+export { AccountNode } from './AccountNode';