Primitives / foldkit-primitives/interaction

SpatialNavigation

namespace · packages/primitives/src/interaction/spatial-navigation.ts:13

export * as SpatialNavigation from './spatial-navigation.js'

Arrow keys over freely placed items (a board, a canvas, a dashboard of cards), where there are no rows or columns: each arrow moves to the nearest item drawn that way. Which item is nearest is the pure nearest. The geometry it needs is read by a Command when the key is handled, once the frame the Model last asked for is drawn, and never kept, so an item that moved between two presses is measured where it is now.

The tab stop is RovingTabindex's: the Model slice is the current item's id, and each item takes its tabindex and OnFocus from RovingTabindex.itemAttributes. Only how the next item is chosen differs.

In the guides

Members

SpatialNavigation.Args

const · packages/primitives/src/interaction/spatial-navigation.ts:104

const Args: Schema.Struct<{ readonly id: Schema.String }>

SpatialNavigation.behavior

function · packages/primitives/src/interaction/spatial-navigation.ts:280

function behavior<Field extends string>(
  declared: Declared<typeof bundle, Field>,
  args: Args,
): {
  <Slots, Input extends { readonly [K in Field]: Model }, ParentMessage>(
    bound: SlotView.Bound<Slots, Input, ParentMessage>,
  ): <
    Container extends keyof Slots & string,
    Item extends keyof Slots & string,
  >(
    options: BehaviorOptions<Input, Slots, Container, Item>,
  ) => Behavior.NamedBehavior<
    Slots,
    Input,
    ParentMessage,
    | A11y.ProvidedOn<Container, 'navigation'>
    | A11y.ProvidedOn<Item, 'focus-strategy'>
  >
  <Slots>(
    slots: SlotView.Unbound<Slots>,
  ): <Input extends { readonly [K in Field]: Model }, ParentMessage>(
    options: BehaviorOptions<Input, Slots>,
  ) => Behavior.NamedBehavior<Slots, Input, ParentMessage>
}

Wires a placed SpatialNavigation to the slots. The container is marked with the navigation's id and handles arrows, Home and End, each default-prevented; an arrow's target is measured and focused by a Command after the next frame is drawn. Each item is marked with its id (a disabled one is marked apart, so arrows pass it by) and gets RovingTabindex's tabindex and OnFocus.

SpatialNavigation.BehaviorOptions

interface · packages/primitives/src/interaction/spatial-navigation.ts:258

interface BehaviorOptions<
  Input,
  Slots,
  Container extends keyof Slots & string = keyof Slots & string,
  Item extends keyof Slots & string = keyof Slots & string,
> {
  readonly container: Container
  readonly item: Item
  readonly items: (input: Input) => Behaviors.Collection.Items<unknown>
}

SpatialNavigation.bundle

const · packages/primitives/src/interaction/spatial-navigation.ts:216

const bundle: Bundle.Bundle<
  'SpatialNavigation',
  { readonly id: string },
  { readonly current: Option.Option<string> },
  | { readonly _tag: 'Focused'; readonly id: string }
  | { readonly _tag: 'Jumped'; readonly id: string }
  | {
      readonly _tag: 'Arrowed'
      readonly direction: 'left' | 'right' | 'down' | 'up'
    }
  | { readonly _tag: 'Stayed' },
  never,
  never,
  never,
  NoView,
  {},
  {
    focus: (
      model: Model,
      id: string,
    ) => Readonly<{
      model: { readonly current: Option.Option<string> }
      commands?: Update.Commands<
        | { readonly _tag: 'Focused'; readonly id: string }
        | { readonly _tag: 'Jumped'; readonly id: string }
        | {
            readonly _tag: 'Arrowed'
            readonly direction: 'left' | 'right' | 'down' | 'up'
          }
        | { readonly _tag: 'Stayed' },
        never
      >
      outMessage?: never
    }>
  }
>

SpatialNavigation.Direction

const · packages/primitives/src/interaction/spatial-navigation.ts:26

const Direction: Schema.Literals<readonly ['up', 'down', 'left', 'right']>

A direction on screen: left is left in a right-to-left page too.

SpatialNavigation.keyMessage

function · packages/primitives/src/interaction/spatial-navigation.ts:240

function keyMessage(
  items: Behaviors.Collection.Items<unknown>,
  key: string,
  modifiers: KeyboardModifiers,
): Option.Option<Message>

The Message a key sends, or none for a key this does not handle: an arrow asks for the nearest item that way, Home and End jump to the first and last enabled item. With Ctrl, Alt or Meta held, a key is left to the page.

SpatialNavigation.Message

const · packages/primitives/src/interaction/spatial-navigation.ts:92

const Message: MessageUnion<{
  readonly Focused: { readonly id: Schema.String }
  readonly Arrowed: {
    readonly direction: Schema.Literals<
      readonly ['up', 'down', 'left', 'right']
    >
  }
  readonly Jumped: { readonly id: Schema.String }
  readonly Stayed: {}
}>

SpatialNavigation.Model

const · packages/primitives/src/interaction/spatial-navigation.ts:86

const Model: Schema.Struct<{
  readonly current: Schema.OptionFromNullOr<Schema.String>
}>

SpatialNavigation.nearest

function · packages/primitives/src/interaction/spatial-navigation.ts:59

function nearest(
  items: ReadonlyArray<Placed>,
  current: string,
  direction: Direction,
): Option.Option<string>

The item nearest current in direction, by the centres of their boxes, or none when nothing lies that way. Only an item whose centre is ahead counts. Those within 45° of the direction come first; among them, and among the rest when none is, the score is the distance ahead plus twice the distance aside, so an item straight ahead beats a nearer one off to the side. A tie goes to the item listed first. An item centred where current is lies ahead of it in no direction; a box of no size is a point. None, too, when current is not among items.

SpatialNavigation.Placed

interface · packages/primitives/src/interaction/spatial-navigation.ts:37

interface Placed {
  readonly id: string
  readonly rect: Rect
}

SpatialNavigation.Rect

interface · packages/primitives/src/interaction/spatial-navigation.ts:30

interface Rect {
  readonly left: number
  readonly top: number
  readonly right: number
  readonly bottom: number
}

A box on screen, as getBoundingClientRect() gives it.