ember-sortable

The V2 architecture of ember-sortable is built using contextual components that follow a hierarchical structure. This design allows for composability, nesting, and customizability.

There are three primary components:

1. sortable-group: The top-level container. It manages the main sorting logic and requires a modelGroup (a shallow copy of the models to be sorted). It yields sortable-item and other properties.
2. sortable-item: Represents an individual model within the group. It yields sortable-handle and other properties.
3. sortable-handle: The entry point for sorting. This component connects a custom handle to the sortable-group mainframe. It is required to initiate drag or keyboard reordering.

This structure supports nested sortable elements, meaning a sortable-group can be rendered inside a sortable-item of another group.

{{#ember-sortable::sortable-group
  modelGroup=modelGroup
  onSubmit=(action "onSubmit")
  onDragStart=(action "onDragStart")
  onDragEnd=(action "onDragEnd")
  as |group|
}}
  {{#each group.modelGroup as |singleModel index|}}
    {{#group.item
      model=singleModel
      index=index
      as |item|
    }}
      {{!-- You can nest another "sortable-group" here --}}
      {{!-- Content goes here --}}
      {{#item.handle}}
        {{!-- Handle goes here --}}
      {{/item.handle}}
    {{/group.item}}
  {{/each}}
{{/ember-sortable::sortable-group}}

The draggable-group component (proposed as drag-drop::draggable-group in V2) allows users to reorder a collection of models using both drag-and-drop and keyboard navigation. It is designed with accessibility in mind, providing screen reader announcements and keyboard support.

Key Properties

• modelGroup: The array of models to be rearranged.
• itemName: A string name for the models, used to generate meaningful accessibility announcements (e.g., "Moving Item A").
• onSubmit: A callback invoked when a reordering action is confirmed (via drop or keyboard Enter/Space).
• onDragStart: A callback invoked when a drag operation begins.
• onDragEnd: A callback invoked when a drag operation ends.
• isKeyboardReorderModeEnabled: A boolean to enable/disable keyboard-based reordering.

Usage Pattern

The component uses a block helper pattern where it yields a hash containing an item component. You iterate over your modelGroup and wrap each item in the provided item component to enable drag functionality.

{{#drag-drop::draggable-group
  onSubmit=(action onSubmit)
  modelGroup=modelGroup
  onDragStart=(action onDragStart)
  onDragEnd=(action onDragEnd)
  itemName=itemName
  as |group|
}}
  {{#each group.modelGroup as |singleModel index|}}
    {{#group.item
      model=singleModel
      index=index
      as |item|
    }}
      {{singleModel}}
      {{#item.handle}}
        Handle
      {{/item.handle}}
    {{/group.item}}
  {{/each}}
{{/drag-drop::draggable-group}}

Ember Sortable V2 includes built-in accessibility support for keyboard-based reordering.

Keyboard Reorder Mode

1. Initiate: Focus a sortable-handle and press Enter or Space. This selects the parent sortable-item and enables sorting within the sortable-group using the Up/Down/Left/Right arrow keys.
2. Visual Indicators: While in reorder mode, a visual indicator (defaulting to arrows via CSS classes) will appear around the selected item and move as the item is reordered.
3. Commit: Press Enter or Space again to commit the new order. Focus will move from the sortable-group back to the sortable-handle.
4. Reset: Press Escape or lose focus to exit reorder mode. This resets the UI to the initial state and retains focus on the sortable-handle.

Screen Reader Support

Sorting actions are announced to screen readers. Consumers can provide a custom announceActionConfig object to map specific actions to translated text strings for i18n support.

For testing sortable functionality, ember-sortable provides acceptance test helpers to simulate user interactions like dragging, reordering, and keyboard input. These helpers are available via the ember-sortable/test-support entry point.

Available helpers:

• drag: Drags elements by a pixel offset.
• reorder: Reorders elements to a specific target state.
• keyboard: Provides keycode constants for keyboard simulation.

import { 
  drag, 
  reorder,
  ENTER_KEY_CODE,
  SPACE_KEY_CODE,
  ESCAPE_KEY_CODE,
  ARROW_KEY_CODES,
} from 'ember-sortable/test-support';

// Example: Reorder elements
await reorder('mouse', '[data-test-vertical-demo-handle]', ...order);

// Example: Drag an element with a specific offset
await drag('mouse', '[data-test-scrollable-demo-handle] .handle', () => {
  return { dy: itemHeight() * 2 + 1, dx: undefined };
});

// Example: Simulate keyboard interaction
await triggerKeyEvent('[data-test-vertical-demo-handle]', 'keydown', ENTER_KEY_CODE);