Primitives / foldkit-primitives/interaction

Reorder

namespace · packages/primitives/src/interaction/reorder.ts:16

export * as Reorder from './reorder.js'

Moving an item to another place in a list or a tree, by keyboard and by pointer, as one Bundle. Space or Enter (or the grab chords) on an item picks it up, the arrows walk it through the places it can go, Space or Enter drops it there, and Escape (or focus leaving it) puts it back. The pointer path is PointerDrag's facts, mapped onto the same Messages, so one draft has one owner whichever way it was started.

The Bundle holds the draft alone: what is held and where it would land. Nothing moves until the drop, and then only by the parent: the Moved out-fact names the item and its place, and the parent's update applies it to its own data or refuses it (a tree node dropped inside itself). Every transition is also an out-fact, so the parent can read it out through LiveAnnounce with announcement.

In the guides

Members

Reorder.announcement

function · packages/primitives/src/interaction/reorder.ts:353

function announcement(
  fact: OutMessage,
  options: {
    readonly label: (id: string) => string
    readonly words?: Partial<Words>
    readonly refuses?: (move: Move) => boolean
  },
): string

The text that reads a transition out, for LiveAnnounce's announce: label names an item by its id, as the page shows it. A placement's onOut calls it on every fact and announces the result. refuses is the test the parent's update refuses a Moved by (movesIntoItself, say): a refused move reads words.refused, not that it was dropped.

Reorder.apply

function · packages/primitives/src/interaction/reorder.ts:313

function apply(ids: ReadonlyArray<string>, moved: Move): ReadonlyArray<string>

A flat list's ids with a move applied, or ids itself when nothing changes or either id is missing. behavior never reports inside on a row that accepts nothing; given one, it is the row's own slot: after it when moving down, before it when moving up.

Reorder.behavior

function · packages/primitives/src/interaction/reorder.ts:592

function behavior<Field extends string>(
  declared: Declared<typeof bundle, Field>,
): {
  <Slots, Input extends { readonly [K in Field]: Model }, ParentMessage>(
    bound: SlotView.Bound<Slots, Input, ParentMessage>,
  ): PlaceBound<Slots, Input, ParentMessage>
  <Slots>(slots: SlotView.Unbound<Slots>): PlaceUnbound<Slots, Field>
}

Wires a placed Reorder to the slots. The container gets the pointer path (PointerDrag, its facts sent as this Bundle's Messages). Each item gets the mark the pointer finds it by, data-reorder="held" while it is held, and data-reorder-over with the zone while it is the place the held item would land: style the drop line on those. The handle gets the key route and puts a key grab back when focus leaves it; under handle: routed the placement hands the route back instead (Routed), for the container's own Keys.behavior.

Nothing moves while an item is held, so focus stays where it is. When the parent applies Moved, a keyed list moves the element, and the browser drops its focus: give the handle FocusRecovery's same step to keep it.

Reorder.BehaviorOptions

type · packages/primitives/src/interaction/reorder.ts:526

type BehaviorOptions<Input, Slots> =
  HandleOptions<Input, Slots> | RoutedOptions<Input, Slots>

Reorder.bundle

const · packages/primitives/src/interaction/reorder.ts:171

const bundle: Bundle.Bundle<"Reorder", void, { readonly held: Option.Option<{ readonly id: string; readonly by: "keys" | "pointer"; }>; readonly over: Option.Option<{ readonly id: string; readonly zone: "after" | "before" | "inside"; readonly part?: string; }>; }, { readonly _tag: "Grabbed"; readonly id: string; readonly by: "keys" | "pointer"; readonly at: Option.Option<{ readonly id: string; readonly zone: "after" | "before" | "inside"; readonly part?: string; }>; } | { readonly _tag: "Released"; readonly over: Option.Option<{ readonly id: string; readonly zone: "after" | "before" | "inside"; readonly part?: string; }>; } | { readonly _tag: "Left"; readonly id: string; } | { readonly _tag: "Stepped"; readonly step: "first" | "next" | "last" | "previous"; readonly places: readonly { readonly id: string; readonly zone: "after" | "before" | "inside"; readonly part?: string; }[]; } | { readonly _tag: "PointedAt"; readonly over: Option.Option<{ readonly id: string; readonly zone: "after" | "before" | "inside"; readonly part?: string; }>; } | { readonly _tag: "Dropped"; } | { readonly _tag: "Cancelled"; } | { readonly _tag: "LeftList"; }, { readonly _tag: "Moved"; readonly id: string; readonly by: "keys" | "pointer"; readonly to: { readonly id: string; readonly zone: "after" | "before" | "inside"; readonly part?: string; }; } | { readonly _tag: "PickedUp"; readonly id: string; readonly by: "keys" | "pointer"; } | { readonly _tag: "PassedOver"; readonly id: string; readonly by: "keys" | "pointe …;

Reorder.By

const · packages/primitives/src/interaction/reorder.ts:35

const By: Schema.Literals<readonly ['keys', 'pointer']>

How the held item was picked up: a key on it, or a pointer pressed on it and moved.

Reorder.HandleOptions

interface · packages/primitives/src/interaction/reorder.ts:508

interface HandleOptions<Input, Slots>
  extends PlaceOptions<Input>, KeyOptions<Input>, SlotOptions<Slots> {
  readonly handle: keyof Slots & string
}

A handle per item: a grip button in the row, or the row itself, takes the keys.

Reorder.KeyOptions

interface · packages/primitives/src/interaction/reorder.ts:383

interface KeyOptions<Input> {
  readonly orientation?: Orientation
  readonly direction?: (input: Input) => Direction
  readonly grab?: readonly [
    Behaviors.Keys.Chord,
    ...ReadonlyArray<Behaviors.Keys.Chord>,
  ]
}

Reorder.Message

const · packages/primitives/src/interaction/reorder.ts:49

const Message: MessageUnion<{
  readonly Grabbed: {
    readonly id: Schema.String
    readonly by: Schema.Literals<readonly ['keys', 'pointer']>
    readonly at: Schema.OptionFromNullOr<
      Schema.Struct<{
        readonly id: Schema.String
        readonly zone: Schema.Literals<readonly ['before', 'inside', 'after']>
        readonly part: Schema.optionalKey<Schema.String>
      }>
    >
  }
  readonly PointedAt: {
    readonly over: Schema.OptionFromNullOr<
      Schema.Struct<{
        readonly id: Schema.String
        readonly zone: Schema.Literals<readonly ['before', 'inside', 'after']>
        readonly part: Schema.optionalKey<Schema.String>
      }>
    >
  }
  readonly Stepped: {
    readonly step: Schema.Literals<
      readonly ['previous', 'next', 'first', 'last']
    >
    readonly places: Schema.$Array<
      Schema.Struct<{
        readonly id: Schema.String
        readonly zone: Schema.Literals<readonly ['before', 'inside', 'after']>
        readonly part: Schema.optionalKey<Schema.String>
      }>
    >
  }
  readonly Dropped: {}
  readonly Released: {
    readonly over: Schema.OptionFromNullOr<
      Schema.Struct<{
        readonly id: Schema.String
        readonly zone: Schema.Literals<readonly ['before', 'inside', 'after']>
        readonly part: Schema.optionalKey<Schema.String>
      }>
    >
  }
  readonly Cancelled: {}
  readonly Left: { readonly id: Schema.String }
  readonly LeftList: {}
}>

Reorder.Model

const · packages/primitives/src/interaction/reorder.ts:38

const Model: Schema.Struct<{
  readonly held: Schema.OptionFromNullOr<
    Schema.Struct<{
      readonly id: Schema.String
      readonly by: Schema.Literals<readonly ['keys', 'pointer']>
    }>
  >
  readonly over: Schema.OptionFromNullOr<
    Schema.Struct<{
      readonly id: Schema.String
      readonly zone: Schema.Literals<readonly ['before', 'inside', 'after']>
      readonly part: Schema.optionalKey<Schema.String>
    }>
  >
}>

Reorder.Move

interface · packages/primitives/src/interaction/reorder.ts:302

interface Move {
  readonly id: string
  readonly to: Place
}

A move as Moved carries it, for apply, movesIntoItself and a parent's own refusal.

Reorder.movesIntoItself

function · packages/primitives/src/interaction/reorder.ts:230

function movesIntoItself(options: {
  readonly id: string
  readonly to: Place
  readonly parent: (id: string) => Option.Option<string>
}): boolean

Whether a move lands in the moved item's own subtree: on it, or before, after or inside one of its descendants. A pointer can report such a place, and only the parent knows the tree, so its update refuses Moved when this holds. The keyboard never offers one.

Reorder.OptionsFor

type · packages/primitives/src/interaction/reorder.ts:546

type OptionsFor<Input, Slots, H extends HandleOf<Slots>> = [H] extends [
  typeof routed,
]
  ? RoutedOptions<Input, Slots>
  : HandleOptions<Input, Slots> & {
      readonly current?: never
    }

The options for a handle H: RoutedOptions for routed, else HandleOptions with no current.

Reorder.OutMessage

const · packages/primitives/src/interaction/reorder.ts:77

const OutMessage: MessageUnion<{
  readonly PickedUp: {
    readonly id: Schema.String
    readonly by: Schema.Literals<readonly ['keys', 'pointer']>
  }
  readonly PassedOver: {
    readonly id: Schema.String
    readonly by: Schema.Literals<readonly ['keys', 'pointer']>
    readonly over: Schema.OptionFromNullOr<
      Schema.Struct<{
        readonly id: Schema.String
        readonly zone: Schema.Literals<readonly ['before', 'inside', 'after']>
        readonly part: Schema.optionalKey<Schema.String>
      }>
    >
  }
  readonly Moved: {
    readonly id: Schema.String
    readonly by: Schema.Literals<readonly ['keys', 'pointer']>
    readonly to: Schema.Struct<{
      readonly id: Schema.String
      readonly zone: Schema.Literals<readonly ['before', 'inside', 'after']>
      readonly part: Schema.optionalKey<Schema.String>
    }>
  }
  readonly PutBack: {
    readonly id: Schema.String
    readonly by: Schema.Literals<readonly ['keys', 'pointer']>
  }
}>

Reorder.Place

const · packages/primitives/src/interaction/reorder.ts:31

const Place: Schema.Struct<{
  readonly id: Schema.String
  readonly zone: Schema.Literals<readonly ['before', 'inside', 'after']>
  readonly part: Schema.optionalKey<Schema.String>
}>

Where an item would land: before or after the item id, or inside it (as its last child). The pointer's places are PointerDrag's, unchanged.

Reorder.PlaceBound

type · packages/primitives/src/interaction/reorder.ts:558

type PlaceBound<Slots, Input, ParentMessage> = <
  const H extends HandleOf<Slots>,
>(
  options: {
    readonly handle: H
  } & OptionsFor<Input, Slots, H>,
) => Placed<Slots, Input, ParentMessage, H>

Reorder.behavior(Declared)(bound): a routed placement hands back its route too.

Reorder.Placed

type · packages/primitives/src/interaction/reorder.ts:551

type Placed<Slots, Input, ParentMessage, H extends HandleOf<Slots>> = [
  H,
] extends [typeof routed]
  ? Routed<Slots, Input, ParentMessage>
  : Behavior.NamedBehavior<Slots, Input, ParentMessage>

What a placement gives: Routed for routed, else the Behavior alone.

Reorder.PlaceOptions

interface · packages/primitives/src/interaction/reorder.ts:190

interface PlaceOptions<Input> {
  readonly items: (input: Input) => ReadonlyArray<string>
  readonly parent?: (input: Input, id: string) => Option.Option<string>
  readonly accepts?: (input: Input, id: string) => boolean
}

Reorder.Places

interface · packages/primitives/src/interaction/reorder.ts:183

interface Places {
  readonly places: ReadonlyArray<Place>
  readonly origin: Option.Option<Place>
}

The places a held item can go, and the one it already holds.

Reorder.places

function · packages/primitives/src/interaction/reorder.ts:243

function places(options: {
  readonly items: ReadonlyArray<string>
  readonly held: string
  readonly parent?: (id: string) => Option.Option<string>
  readonly accepts?: (id: string) => boolean
}): Places

The places held can go, in walking order. For each row that shows, but the held one and its own rows: before it, then inside it when it accepts items (or is the held one's parent) and shows none of its own; after the last row of a branch, after each level that ends there. So a list of n rows offers n places (the gaps around the others), and no two places are the same position.

Reorder.PlaceUnbound

interface · packages/primitives/src/interaction/reorder.ts:567

interface PlaceUnbound<Slots, Field extends string> {
  <
    Input extends {
      readonly [K in Field]: Model
    },
    ParentMessage,
  >(
    options: RoutedOptions<Input, Slots>,
  ): Routed<Slots, Input, ParentMessage>
  <
    Input extends {
      readonly [K in Field]: Model
    },
    ParentMessage,
  >(
    options: HandleOptions<Input, Slots> & {
      readonly current?: never
    },
  ): Behavior.NamedBehavior<Slots, Input, ParentMessage>
}

Reorder.behavior(Declared)(slots)<Model, Message>: as PlaceBound. The input and Message are given, so the handle cannot be inferred beside them: an overload each.

Reorder.Routed

interface · packages/primitives/src/interaction/reorder.ts:538

interface Routed<Slots, Input, ParentMessage> {
  readonly behavior: Behavior.NamedBehavior<Slots, Input, ParentMessage>
  readonly keys: Behaviors.Keys.Route<Input, ParentMessage>
}

A routed placement: the Behavior to attach, and the key route to list in the container's Keys.behavior, first: Keys.first(placed.keys, ListNavigation.keys(…)(…)).

Reorder.routed

const · packages/primitives/src/interaction/reorder.ts:492

const routed: unique symbol

handle: Reorder.routed: the keys are a route in a Keys.behavior of the caller's.

Reorder.RoutedOptions

interface · packages/primitives/src/interaction/reorder.ts:519

interface RoutedOptions<Input, Slots>
  extends PlaceOptions<Input>, KeyOptions<Input>, SlotOptions<Slots> {
  readonly handle: typeof routed
  readonly current: (input: Input) => Option.Option<string>
}

The container routes keys already (a roving tab stop, ListNavigation): the placement hands back its route, built from these same options, for the caller's Keys.behavior.

Reorder.Step

const · packages/primitives/src/interaction/reorder.ts:46

const Step: Schema.Literals<readonly ['previous', 'next', 'first', 'last']>

Reorder.stepOf

function · packages/primitives/src/interaction/reorder.ts:404

function stepOf(
  key: string,
  orientation: Orientation,
  direction: Direction,
): Option.Option<Step>

The step an arrow, Home or End takes, under an orientation and a direction.

Reorder.Words

type · packages/primitives/src/interaction/reorder.ts:340

type Words = {
  readonly [K in keyof typeof words]: string
}

Reorder.words

const · packages/primitives/src/interaction/reorder.ts:326

const words = {
  pickedUp,
  pickedUpByKeys,
  before,
  inside,
  after,
  nowhere,
  movedBefore,
  movedInside,
  movedAfter,
  putBack,
  refused,
}

What an announcement says. {item} and {target} are filled with the labels.