# sortable

> Why JS: dragging an item between or within lists, and moving one from the keyboard, need pointer and key listeners.

```ts
import { sortable } from "@sdxc/ui/mixins";
```

Moves items within and between the lists inside the nearest SORTABLE_ATTRIBUTE root.
A mouse or pen press on an item that travels past a few pixels lifts it under a ghost, places
it between the items under the pointer, and posts its move form on release; Escape puts it
back. Shift+ArrowUp/Down move the focused item past its neighbour, and Shift+ArrowLeft/Right to
the top of the list on either side. A touch press scrolls as usual.

## Signature

```ts
sortable(options?: SortableOptions): MixinDescriptor<HTMLElement>
```

## Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `options?` | `SortableOptions` |  |

## Examples

```tsx
<span hidden mix={[sortable({ moved: "Moved to {list}" })]} />
```

## Used with it

The events, constants and types its module publishes, each imported from `@sdxc/ui/mixins` too.

### SortableMoveEvent

Dispatched on an item once it is dropped or moved by key, before its move form posts;
`preventDefault()` keeps the item in place and the form from posting, for a consumer that
saves the move itself.

#### Signature

```ts
new SortableMoveEvent(init: { item: string; from: string; to: string; before?: string | null })
```

#### Properties

| Property | Type | Description |
| --- | --- | --- |
| `item` | `readonly string` | The moved item's value. |
| `from` | `readonly string` | The list it left. |
| `to` | `readonly string` | The list it landed in, the same as `from` for a move within a list. |
| `before` | `readonly string \| null` | The item it landed before, `null` when it landed last or its form takes no position. |

### SORTABLE_ATTRIBUTE

Attribute on the element holding every list the mixin moves items between.

#### Signature

```ts
const SORTABLE_ATTRIBUTE = "data-sortable"
```

### SORTABLE_LIST_ATTRIBUTE

Attribute a list carries its value on, which a move sends in the item's form.

#### Signature

```ts
const SORTABLE_LIST_ATTRIBUTE = "data-sortable-list"
```

### SORTABLE_ITEMS_ATTRIBUTE

Attribute on the element inside a list that holds its items; the list itself without one.

#### Signature

```ts
const SORTABLE_ITEMS_ATTRIBUTE = "data-sortable-items"
```

### SORTABLE_ITEM_ATTRIBUTE

Attribute an item carries its value on, unique across the lists.

#### Signature

```ts
const SORTABLE_ITEM_ATTRIBUTE = "data-sortable-item"
```

### SORTABLE_FORM_ATTRIBUTE

Attribute an item's move form names its item with, so a move finds the form to post.

#### Signature

```ts
const SORTABLE_FORM_ATTRIBUTE = "data-sortable-form"
```

### SORTABLE_FIELD_ATTRIBUTE

Attribute a move form names its list field with. A move appends that field after the form's
own, with the list's value, and the next render of the form drops it again.

#### Signature

```ts
const SORTABLE_FIELD_ATTRIBUTE = "data-sortable-field"
```

### SORTABLE_POSITION_ATTRIBUTE

Attribute a move form names its position field with. A move sends the value of the item it
lands before in that field, or an empty value when it lands last. A form without one moves
its item only between lists, to the top.

#### Signature

```ts
const SORTABLE_POSITION_ATTRIBUTE = "data-sortable-position"
```

### SORTABLE_COUNT_ATTRIBUTE

Attribute on a list's count, which a move between lists keeps current until the page answers.

#### Signature

```ts
const SORTABLE_COUNT_ATTRIBUTE = "data-sortable-count"
```

### SORTABLE_TITLE_ATTRIBUTE

Attribute on a list's title, which a keyboard move announces.

#### Signature

```ts
const SORTABLE_TITLE_ATTRIBUTE = "data-sortable-title"
```

### SORTABLE_STATUS_ATTRIBUTE

Attribute on the live region a keyboard move is announced through.

#### Signature

```ts
const SORTABLE_STATUS_ATTRIBUTE = "data-sortable-status"
```

### SORTABLE_SCROLLER_ATTRIBUTE

Attribute on the element that scrolls while the pointer rests near its edge mid-drag.

#### Signature

```ts
const SORTABLE_SCROLLER_ATTRIBUTE = "data-sortable-scroller"
```

### SORTABLE_ACTIVE_ATTRIBUTE

Attribute set on the root for as long as a drag lasts.

#### Signature

```ts
const SORTABLE_ACTIVE_ATTRIBUTE = "data-sortable-active"
```

### SORTABLE_DRAGGING_ATTRIBUTE

Attribute set on the item being dragged, for as long as the drag lasts.

#### Signature

```ts
const SORTABLE_DRAGGING_ATTRIBUTE = "data-sortable-dragging"
```

### SORTABLE_TARGET_ATTRIBUTE

Attribute set on another list while the dragged item would land in it.

#### Signature

```ts
const SORTABLE_TARGET_ATTRIBUTE = "data-sortable-target"
```

### SORTABLE_GHOST_ATTRIBUTE

Attribute on the copy of the item that follows the pointer.

#### Signature

```ts
const SORTABLE_GHOST_ATTRIBUTE = "data-sortable-ghost"
```

### SortableOptions

Options for sortable.

#### Members

| Member | Type | Description |
| --- | --- | --- |
| `moved?` | `string` | What a keyboard move announces, with `{list}` where the list's title goes, such as "Moved to {list}". Without it a keyboard move is silent. |