Primitives / foldkit-primitives/state

Box

namespace · packages/primitives/src/state/box.ts:9

export * as Box from './box.js'

Boxes that move and resize, as pure functions over the box's numbers: the constraints (an area to stay in, a smallest and largest size, an aspect ratio, a grid), a group moved together, and the keys that nudge. The Model holds the boxes and the draft; a pointer drag's deltas (Move) and a key's (Box.moveKey, Box.resizeKey) arrive at the same moveBy and resize, so a keyboard move and a dragged one obey the same limits.

In the guides

Members

Box.Area

interface · packages/primitives/src/state/box.ts:24

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

The area a box stays inside.

Box.Box

interface · packages/primitives/src/state/box.ts:18

interface Box extends Point {
  readonly width: number
  readonly height: number
}

Where a box sits and how big it is, in the units the application uses, usually CSS pixels.

Box.Delta

interface · packages/primitives/src/state/box.ts:209

interface Delta {
  readonly dx: number
  readonly dy: number
}

Box.Handle

type · packages/primitives/src/state/box.ts:32

type Handle = 'n' | 'e' | 's' | 'w' | 'ne' | 'nw' | 'se' | 'sw'

The edge or corner a handle drags, by compass point.

Box.KeyStep

interface · packages/primitives/src/state/box.ts:202

interface KeyStep {
  readonly step?: number | undefined
  readonly largeStep?: number | undefined
}

Box.moveBy

function · packages/primitives/src/state/box.ts:114

function moveBy(box: Box, dx: number, dy: number, limits?: MoveLimits): Box

One box moved by dx, dy within the limits; the box as it was when it does not move.

Box.moveEach

function · packages/primitives/src/state/box.ts:77

function moveEach<Boxes extends Readonly<Record<string, Box>>>(
  boxes: Boxes,
  ids: ReadonlyArray<keyof Boxes & string>,
  dx: number,
  dy: number,
  limits?: MoveLimits,
): Boxes

Every box in ids moved by dx, dy, one change. The group keeps its shape: the delta is limited so the whole group stays inside bounds, rather than each box stopping alone and the group squashing against an edge. With snap, the first id lands on the grid and the others move by the same amount. Ids the record does not hold are skipped, and the record comes back as it was when nothing moves, so a no-op records no undo step.

Box.moveKey

function · packages/primitives/src/state/box.ts:223

function moveKey(press: KeyPress, options?: KeyStep): Option.Option<Delta>

What Alt with an arrow asks a box to move: ArrowRight is { dx: step, dy: 0 }, with Shift the larger step. None for any other key, and for a press with Control or Meta, whose combinations are the browser's. A held key repeats and keeps nudging, so a repeat is not filtered out here.

Box.MoveLimits

interface · packages/primitives/src/state/box.ts:34

interface MoveLimits {
  readonly bounds?: Area | undefined
  readonly snap?: number | undefined
}

Box.Point

interface · packages/primitives/src/state/box.ts:12

interface Point {
  readonly x: number
  readonly y: number
}

Box.resize

function · packages/primitives/src/state/box.ts:124

function resize(
  from: Box,
  handle: Handle,
  dx: number,
  dy: number,
  limits?: ResizeLimits,
): Box

The box a handle makes when its edges move by dx and dy, within the limits, as a drag of that handle makes it. A non-finite delta goes as far as the limits allow (Home and End use it), and the box comes back as it was if that would be no limit at all, or changes nothing.

Box.resizeKey

function · packages/primitives/src/state/box.ts:238

function resizeKey(
  press: KeyPress,
  handle: Handle,
  options?: KeyStep,
): Option.Option<Delta>

What a key on a focused handle asks it to do: an arrow moves the handle's own edges (an east handle reads Left and Right only; a corner reads all four), with Shift the larger step, and Home and End take the handle's axes to the smallest and the largest size the limits allow, which is a delta of minus and plus infinity for resize to clamp. None for any other key, and for a press with Alt, Control or Meta.

Box.ResizeLimits

interface · packages/primitives/src/state/box.ts:41

interface ResizeLimits {
  readonly bounds?: Area | undefined
  readonly min?:
    | {
        readonly width: number
        readonly height: number
      }
    | undefined
  readonly max?:
    | {
        readonly width: number
        readonly height: number
      }
    | undefined
  readonly aspect?: number | undefined
  readonly snap?: number | undefined
}