122 lines
4.0 KiB
Markdown
122 lines
4.0 KiB
Markdown
# Holon Shape for Canvas Website
|
|
|
|
## Overview
|
|
|
|
The Holon shape is a new tool that allows users to interact with Holon data objects through a visual interface. It provides functionality to input a Holon ID and perform put/get operations on JSON tasklists.
|
|
|
|
## Features
|
|
|
|
- **Holon ID Input**: Enter a Holon ID (e.g., -4962820663) to connect to a specific holon
|
|
- **Tasklist Management**: Load, view, and manage tasklists from the holon
|
|
- **Task Operations**: Add new tasks to existing or new tasklists
|
|
- **Task Completion**: Toggle task completion status
|
|
- **Real-time Updates**: Changes are immediately reflected in the holon data
|
|
|
|
## Usage
|
|
|
|
1. **Adding the Holon Shape**:
|
|
- Select the Holon tool from the toolbar (star icon) or context menu
|
|
- Use keyboard shortcut `Alt+H` to quickly select the Holon tool
|
|
- Click and drag on the canvas to create a new Holon shape
|
|
|
|
2. **Connecting to a Holon**:
|
|
- Enter a Holon ID in the input field
|
|
- Click "Load Tasklists" to fetch existing tasklists
|
|
|
|
3. **Managing Tasks**:
|
|
- Enter a tasklist name and task description
|
|
- Click "Add" to create a new task
|
|
- Check/uncheck tasks to mark them as complete/incomplete
|
|
|
|
## Technical Implementation
|
|
|
|
### Files Created/Modified
|
|
|
|
- `src/shapes/HolonShapeUtil.tsx` - Main shape utility with UI component and sync support
|
|
- `src/tools/HolonShapeTool.ts` - Tool definition for the Holon shape
|
|
- `src/routes/Board.tsx` - Updated to include Holon shape and tool
|
|
- `src/ui/overrides.tsx` - Added Holon tool definition with keyboard shortcut (Alt+H)
|
|
- `src/ui/CustomContextMenu.tsx` - Added Holon tool to context menu
|
|
- `src/ui/CustomToolbar.tsx` - Added Holon tool to toolbar
|
|
- `worker/TldrawDurableObject.ts` - Added Holon shape to worker schema for multiplayer sync
|
|
|
|
### HoloSphere Class
|
|
|
|
The `HoloSphere` class provides the interface for interacting with Holon data:
|
|
|
|
```typescript
|
|
class HoloSphere {
|
|
async getAll(holonId: string, dataType: string): Promise<any[]>
|
|
async put(holonId: string, dataType: string, data: any): Promise<void>
|
|
}
|
|
```
|
|
|
|
### API Endpoints
|
|
|
|
The shape currently uses these API endpoints:
|
|
- `GET https://api.holons.io/holons/{holonId}/tasklists` - Fetch tasklists
|
|
- `PUT https://api.holons.io/holons/{holonId}/tasklists` - Update tasklists
|
|
|
|
## Data Structure
|
|
|
|
Tasklists are stored as JSON arrays with the following structure:
|
|
|
|
```typescript
|
|
interface Tasklist {
|
|
name: string
|
|
tasks: Task[]
|
|
}
|
|
|
|
interface Task {
|
|
id: number
|
|
text: string
|
|
completed: boolean
|
|
}
|
|
```
|
|
|
|
## Integration with Holons i/o
|
|
|
|
This shape integrates with the Holons i/o ecosystem, allowing users to:
|
|
|
|
- Connect to their personal me-holon and we-holons
|
|
- Manage tasks across different holons
|
|
- Collaborate on shared tasklists
|
|
- Track task completion and progress
|
|
|
|
## Sync Support
|
|
|
|
The Holon shape is fully integrated with TL-Draw's sync system:
|
|
|
|
- **Multiplayer Support**: All state changes are synchronized across multiple users
|
|
- **Real-time Updates**: Task additions, completions, and Holon ID changes sync immediately
|
|
- **State Persistence**: Shape state is preserved in the room's persistent storage
|
|
- **Conflict Resolution**: Uses TL-Draw's built-in conflict resolution for concurrent edits
|
|
- **Worker Schema**: Properly registered in the worker schema for multiplayer sessions
|
|
|
|
## Future Enhancements
|
|
|
|
- Support for other Holon data types (offers, requests, expenses, etc.)
|
|
- Real-time synchronization with other users
|
|
- Integration with the Holons Bot commands
|
|
- Support for nested tasklists and subtasks
|
|
- Export/import functionality for tasklists
|
|
|
|
## Example Usage
|
|
|
|
```typescript
|
|
// Example Holon ID from the Holons i/o system
|
|
const holonId = "-4962820663"
|
|
|
|
// The shape will automatically handle:
|
|
// - Fetching existing tasklists
|
|
// - Adding new tasks
|
|
// - Updating task completion status
|
|
// - Persisting changes to the holon
|
|
```
|
|
|
|
## Notes
|
|
|
|
- The shape currently uses simulated API endpoints
|
|
- Error handling is implemented for network failures
|
|
- The UI is responsive and follows the existing design patterns
|
|
- All data operations are logged to the console for debugging |