Use Case: Create / Edit Spatial Relationships (UC-302)

Overview

Users can create and edit spatial relationships between objects using an intuitive drag-and-drop interface with multi-zone dropzones. This enables users to organize their physical objects digitally by defining where objects should be located relative to each other.

User Story

As a Plings user
I want to create spatial relationships between my objects using drag-and-drop
So that I can organize my belongings digitally and track where things should be located

Supported Relationship Types

Container Relationships (NORMAL_IN)

  • Purpose: Define which objects belong inside which containers
  • Example: Keys belong in the key dish, tools belong in the toolbox
  • UI Interaction: Drag object to CENTER zone of target container
  • Result: (:Object)-[:NORMAL_IN]->(:Container) relationship

Positional Relationships

Objects can be positioned relative to each other:

Left/Right Positioning

  • NORMAL_LEFT_OF: Object should be positioned to the left of another object
  • NORMAL_RIGHT_OF: Object should be positioned to the right of another object
  • UI Interaction: Drag to LEFT or RIGHT zones of target object
  • Example: Mouse should be to the right of keyboard

Vertical Positioning

  • NORMAL_ABOVE: Object should be positioned above another object
  • NORMAL_UNDER: Object should be positioned below another object
  • UI Interaction: Drag to TOP or BOTTOM zones of target object
  • Example: Monitor should be above keyboard tray

User Interface

Spatial Navigator Dashboard

The primary interface for creating spatial relationships is the Spatial Navigator in the main dashboard.

Object Cards

  • Layout: Grid of object cards showing thumbnail, name, and status
  • Interaction: Cards are draggable by mouse or touch
  • Visual Feedback: Cards show opacity change when being dragged

Child Object Icons

  • Display: Small preview icons (32x32px) shown at bottom of container cards
  • Interaction: Individual child icons can be dragged to create relationships
  • Visual Feedback: Custom ghost follows mouse cursor during drag

Dropzone System

When dragging an object, target objects display 5 interactive zones:

┌─────────────────────────────┐
│        TOP (ABOVE)          │
├─────────────────────────────┤
│    │                  │    │
│LEFT│     CENTER        │RIGHT│  
│    │   (INSIDE)        │    │
│    │                  │    │
├─────────────────────────────┤
│      BOTTOM (BELOW)         │
└─────────────────────────────┘

Zone Behaviors

  • CENTER: Creates containment relationship (NORMAL_IN)
  • LEFT: Creates left positioning (NORMAL_LEFT_OF)
  • RIGHT: Creates right positioning (NORMAL_RIGHT_OF)
  • TOP: Creates above positioning (NORMAL_ABOVE)
  • BOTTOM: Creates below positioning (NORMAL_UNDER)

Visual Feedback

  • Inactive: Zones invisible until drag starts
  • Active: Semi-transparent colored overlays per zone
  • Hover: Solid highlight with relationship label
  • Invalid: Red highlight for restricted drops

Drag and Drop Workflow

  1. Initiate Drag
    • Click and hold on object card or child icon
    • Custom ghost appears following mouse cursor
    • Source card becomes semi-transparent
  2. Navigate to Target
    • Move ghost over target objects
    • Dropzones appear on valid targets
    • Hover zones for visual feedback
  3. Drop to Create Relationship
    • Release mouse over desired zone
    • Relationship created via GraphQL mutation
    • UI updates optimistically with server confirmation
  4. Error Handling
    • Invalid drops show error feedback
    • Server errors trigger rollback with user notification
    • Stuck ghosts auto-cleanup on mouse release

Restrictions and Rules

Source Object Restrictions

  • Objects cannot be dropped on themselves
  • Objects cannot be dropped on their current parent container’s dropzones
  • Objects being dragged don’t show dropzones (prevents confusion)

Relationship Validation

  • Circular containment prevention: A cannot contain B if B contains A
  • Single location enforcement: Object can only be IN one container
  • Self-containment prevention: Object cannot contain itself

Permission Requirements

  • User must have EDIT permission on the object being moved
  • User must have EDIT permission on the target object/container
  • Cross-organization moves require appropriate permissions

Technical Implementation

GraphQL Operations

# For containment relationships (CENTER zone)
mutation MoveObject($objectId: ID!, $newContainerId: ID!) {
  moveObject(objectId: $objectId, newContainerId: $newContainerId) {
    id
    spatialParent { id name }
  }
}

# For positional relationships (LEFT/RIGHT/TOP/BOTTOM zones)
mutation CreateSpatialRelationship($objectId: ID!, $targetId: ID!, $relationship: SpatialRelationshipType!) {
  createSpatialRelationship(objectId: $objectId, targetId: $targetId, relationship: $relationship) {
    id
    positionalRelationships {
      relationshipType
      relatedObject { id name }
    }
  }
}

Optimistic Updates

  • UI updates immediately on drop for responsive experience
  • Server confirmation reconciles local state
  • Automatic rollback on server errors with user notification

Browser Compatibility

  • Uses HTML5 Drag and Drop API with custom ghost images
  • Fallback handling for browsers with limited drag support
  • Touch-friendly implementation for mobile devices

User Benefits

Organization and Finding Objects

  • Digital Organization: Mirror physical object arrangements digitally
  • Expected Location Tracking: Know where objects should be located
  • Visual Hierarchy: See object containment and relationships at a glance

Inventory Management

  • Misplacement Detection: Future feature to detect when objects aren’t where they should be
  • Location History: Track where objects have been moved
  • Bulk Organization: Organize multiple related objects efficiently

Collaboration

  • Shared Understanding: Team members see consistent object organization
  • Permission Control: Restrict who can modify spatial relationships
  • Change Tracking: Future audit trail of relationship changes

Mobile Considerations

Touch Interface

  • Larger Touch Targets: Minimum 44px touch targets on mobile
  • Simplified Zones: May reduce to 3 zones (CENTER, LEFT, RIGHT) on small screens
  • Touch and Hold: Clear feedback for drag initiation

Responsive Behavior

  • Adaptive Dropzones: Zones resize based on screen size
  • Progressive Disclosure: Complex features hidden on mobile
  • Optimized Gestures: Native mobile drag behaviors where appropriate

Future Enhancements

Advanced Relationship Properties

  • Distance Measurements: Specify exact distances between objects
  • Confidence Levels: Indicate certainty of relationship accuracy
  • Temporal Aspects: Track when relationships were established

Smart Suggestions

  • Automatic Relationships: Suggest relationships based on object proximity
  • Pattern Recognition: Learn from user behavior to suggest organization
  • Conflict Detection: Alert users to potentially contradictory relationships

Real-time Collaboration

  • Live Updates: See other users’ changes in real-time
  • Conflict Resolution: Handle simultaneous edits gracefully
  • Change Notifications: Notify users of relevant spatial changes

Last Updated: 2025-07-08 - Added comprehensive drag-and-drop workflow and dropzone system documentation