Ux Sortable Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require aymericcucherousset/ux-sortable
   

   Ensure symfony/stimulus-bundle and symfony/ux-live-component are installed.

2. Register Stimulus Bundle Add to config/bundles.php:

   Symfony\Stimulus\Bridge\SymfonyBridge::class => ['all' => true],
   

3. First Use Case: Basic Sortable List Create a Twig component (TestList.html.twig) with sortable_attributes:

   <ul {{ sortable_attributes({ animation: 200 }) }}>
       {% for item in items %}
           <li data-id="{{ item.id }}">{{ item.name }}</li>
       {% endfor %}
   </ul>
   

4. LiveComponent Integration Add a LiveListener in your component class to handle reorder events:

   #[LiveListener('reorder.end')]
   public function onReorder(array $order): void {
       // Update state or persist changes
   }
   

Implementation Patterns

Core Workflows

1. Dynamic List Reordering

   • Use sortable_attributes with a prefix (e.g., reorder) to customize event names.
   • Example: {{ sortable_attributes({ prefix: 'task' }) }} emits task.end.

2. State Management

   • LiveComponent State: Update $items array in LiveListener to reflect changes.
   • Database Sync: Trigger API calls or queue jobs in reorder.end to persist order.

3. Nested Sorting

   • Wrap nested lists in <ul> tags and apply sortable_attributes to each level.
   • Use unique data-id attributes for hierarchical items.

Integration Tips

• Twig Extensions: Extend Twig to auto-register sortable_attributes for reusable templates.
• Stimulus Controllers: Customize behavior by extending the default Stimulus controller (if needed).
• Validation: Validate data-id uniqueness to prevent sorting errors.

Example: CRUD Integration

#[LiveListener('reorder.end')]
public function updateOrder(array $order): void {
    $this->items = array_map(fn($id) => $this->findItem($id), $order);
    $this->persistOrder($this->items); // Call API or save to DB
}

Gotchas and Tips

Pitfalls

1. Event Prefix Conflicts

   • Ensure prefix in sortable_attributes doesn’t clash with other Stimulus controllers.
   • Debug with browser dev tools: Check emitted events under Custom Events.

2. Missing data-id

   • Error: Sorting fails silently if data-id is missing.
   • Fix: Validate presence in Twig:

     {% if not item.id %}{{ abort(400, 'Missing ID') }}{% endif %}
     

3. Animation Lag

   • High animation values (e.g., 500) may cause UI jank.
   • Tip: Use 0 for instant transitions in performance-critical apps.

Debugging

• Event Listener Not Triggering?

  • Verify LiveListener event name matches sortable_attributes prefix (e.g., reorder.end).
  • Check Stimulus controller registration in browser console:

    console.log(Stimulus.controllers);
    

• State Not Updating?

  • Ensure LiveProp is marked as writable: true:

    #[LiveProp(writable: true)]
    public array $items = [];
    

Extension Points

1. Custom Stimulus Controller Override default behavior by extending the Stimulus controller:

   // assets/controllers/sortable_controller.js
   import { SortableController } from '@symfony/ux-sortable';
   
   export default class extends SortableController {
       connect() {
           super.connect();
           this.element.addEventListener('click', () => console.log('Custom logic'));
       }
   }
   

2. Twig Global Helper Add to TwigExtension for project-wide usage:

   $twig->addFunction(new \Twig\TwigFunction('sortable', [$this, 'renderSortable']));
   

3. Server-Side Validation Validate reorder payloads in LiveListener:

   #[LiveListener('reorder.end')]
   public function validateOrder(array $order): void {
       if (count($order) !== count($this->items)) {
           throw new \RuntimeException('Invalid order length');
       }
   }
   

Performance

• Large Lists: Use handle: 'float' for smoother drag-and-drop with many items.
• Lazy Loading: Implement infinite scroll or pagination for lists exceeding 100 items.