SpatialNavigation.Args
const · packages/primitives/src/interaction/spatial-navigation.ts:104
const Args: Schema.Struct<{ readonly id: Schema.String }>Primitives / foldkit-primitives/interaction
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.
SpatialNavigation.Argsconst · packages/primitives/src/interaction/spatial-navigation.ts:104
const Args: Schema.Struct<{ readonly id: Schema.String }>SpatialNavigation.behaviorfunction · 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.BehaviorOptionsinterface · 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.bundleconst · 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.Directionconst · 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.keyMessagefunction · 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.Messageconst · 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.Modelconst · packages/primitives/src/interaction/spatial-navigation.ts:86
const Model: Schema.Struct<{
readonly current: Schema.OptionFromNullOr<Schema.String>
}>SpatialNavigation.nearestfunction · 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.Placedinterface · packages/primitives/src/interaction/spatial-navigation.ts:37
interface Placed {
readonly id: string
readonly rect: Rect
}SpatialNavigation.Rectinterface · 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.