open-index/open-npm huggingface dataset:
npm package: @principal-ai/principal-view-core
Description: Core logic and types for graph-based principal view framework
Latest version: 0.26.23

# @principal-ai/visual-validation-core

Core logic library for the Visual Validation Framework - **framework-agnostic**.

## Features

- 📋 TypeScript type definitions for graph configurations and events
- ⚙️ Event processing engine
- ✅ Validation engine with rule checking
- 📊 Graph state management
- 🧪 Test instrumentation helpers

**Zero UI dependencies** - can be used in Node.js, tests, or any JavaScript environment.

## Installation

```bash
npm install @principal-ai/visual-validation-core
# or
bun add @principal-ai/visual-validation-core
```

## Usage

### Define Configuration

```typescript
import type { GraphConfiguration } from '@principal-ai/visual-validation-core';

const config: GraphConfiguration = {
  metadata: {
    name: 'Control Tower',
    version: '1.0.0',
  },
  nodeTypes: {
    user: {
      shape: 'circle',
      color: '#4CAF50',
      dataSchema: {
        userId: { type: 'string', required: true },
      },
      states: {
        online: { color: '#4CAF50' },
        offline: { color: '#9E9E9E' },
      },
    },
    server: {
      shape: 'hexagon',
      color: '#9C27B0',
      dataSchema: {
        uptime: { type: 'number' },
      },
    },
  },
  edgeTypes: {
    connection: {
      style: 'solid',
      directed: true,
    },
  },
  allowedConnections: [{ from: 'user', to: 'server', via: 'connection' }],
  validation: {
    stateTransitions: {
      user: [
        { from: 'offline', to: ['online'] },
        { from: 'online', to: ['offline'] },
      ],
    },
  },
};
```

### Process Events

```typescript
import { EventProcessor } from '@principal-ai/visual-validation-core';

const processor = new EventProcessor(config);

// Process events
const result = processor.processEvent({
  id: 'evt-1',
  type: 'user_connected',
  timestamp: Date.now(),
  category: 'node',
  operation: 'create',
  payload: {
    operation: 'create',
    nodeId: 'user-1',
    nodeType: 'user',
    data: { userId: 'alice' },
  },
  expected: true,
});

console.log('Valid:', result.validation.valid);
console.log('Violations:', result.validation.violations);
```

### Test Instrumentation

```typescript
import { GraphInstrumentationHelper } from '@principal-ai/visual-validation-core';

describe('My system test', () => {
  it('should handle user connections', () => {
    const helper = new GraphInstrumentationHelper(config);

    // Emit events from your test
    helper.emitNodeCreated('server-1', 'server', { uptime: 0 });
    helper.emitNodeCreated('user-alice', 'user', { userId: 'alice' });
    helper.emitEdgeCreated('conn-1', 'connection', 'user-alice', 'server-1');
    helper.emitStateChange('user-alice', 'online');
  });
});
```

## API

See the main [README](../../README.md) for full documentation.

## License

MIT
npm package: @principal-ai/principal-view-react
Description: React components for graph-based principal view framework
Latest version: 0.14.22

# @principal-ai/visual-validation-react

React UI **component library** for the Visual Validation Framework.

This library provides **building blocks** for creating graph visualization applications. The actual "panel" application should be built separately using these components.

## Features

- 🎨 `GraphRenderer` - Interactive graph visualization with @xyflow/react
  - Custom node shapes (circle, rectangle, hexagon, diamond)
  - State-based node styling
  - Animated and styled edges
  - Auto-layout algorithms (hierarchical, circular)
  - Zoom, pan, drag interactions
  - Minimap and controls
- 🎭 `CustomNode` / `CustomEdge` - Configurable xyflow renderers

## Installation

```bash
npm install @principal-ai/visual-validation-react
# or
bun add @principal-ai/visual-validation-react
```

## Peer Dependencies

```json
{
  "react": "^18.0.0 || ^19.0.0",
  "react-dom": "^18.0.0 || ^19.0.0"
}
```

## Usage

These are **building block components**. You compose them to build your panel application:

```typescript
import { GraphRenderer } from '@principal-ai/visual-validation-react';
import type { ExtendedCanvas } from '@principal-ai/principal-view-core';

const canvas: ExtendedCanvas = {
  // ... your canvas data
};

function MyPanel() {
  return (
    <GraphRenderer
      canvas={canvas}
      width="100%"
      height="600px"
    />
  );
}
```

**Building a Complete Panel:**
For a complete panel application with all features (playback controls, filters, etc.), you should create a separate project using a panel starter template and compose these components together.

## Documentation

Comprehensive guides with Mermaid diagrams:

- **[Configuration Guide](../../docs/CONFIGURATION.md)** - Define your graph structure, node/edge types, and validation rules
- **[Event System Guide](../../docs/EVENT_SYSTEM.md)** - Stream events to update your graph in real-time
- **[Usage Guide](../../docs/USAGE.md)** - Build complete panels with React components

Or browse the [full documentation index](../../docs/README.md).

## Storybook

Interactive component examples:

```bash
bun run storybook
```

## Status

**Alpha** - Core placeholder implemented. Full visualization features coming soon.

### TODO

- ✅ Integrate xyflow for graph visualization
- ✅ Implement node renderers with shapes and states
- ✅ Implement edge renderers with styles and animations
- ✅ Add auto-layout algorithms
- ✅ Add Storybook stories

## License

MIT