Placing

namespace · packages/primitives/src/interaction/placing.ts:36

export * as Placing from './placing.js'

Keeps a floating panel inside the viewport: on insert it shifts left past the right edge and flips above its trigger when the bottom overflows and the room overhead fits; on release every inline prop goes. placeFor is pure geometry over rects, so the rule is unit-tested and the Mount only reads and writes. Inert without layout (zero rects never overflow), with no timers, observers, or reposition loops.

placeAt is the other half, for a popup that must open under the trigger that opened it. It writes left and --fk-placed-top once, relative to the popup's offset parent; the panel's stylesheet reads the variable as top, so keepWithin can still replace top when it flips. Key the popup by the trigger: a Mount reads its args at insert and never again. placeAtPoint is the same write for a viewport point, when the open event carried coordinates the message builder dropped. The two mounts start together, so the fit may run before that write; the write measures again. A point that would hang past the bottom shifts up. A trigger still flips, and the panel is marked data-fk-placed="above" so a hover bridge can follow the side that opened. Zero-size rects stay at the origin, so an inert document writes nothing a layout pass would have to undo.

Three related pieces this is not:

• Anchor.behavior (foldkit-mixins-ui) binds a floating element to another element's id through floating-ui, with portals and continuous repositioning. It relocates nodes out from under the runtime (portal by default) and burns under zero geometry; reach for it when the panel must track a moving anchor, not for a popup placed once.
• KeepInView (foldkit-primitives/dom) scrolls newly marked content into view. Same verb, opposite direction: that one moves the page to the panel, this one moves the panel into the page.
• Overlay.behaviors owns dismissal, focus, scroll lock, and inertness, but no positioning; spread this alongside it for the full overlay.

In the guides

• Focus rings, overlays, selection, announcementsPrimitives / Interaction
• In the examplesPrimitives / Interaction

Members

interface AnchorRect {
  readonly left: number
  readonly top: number
  readonly bottom: number
  readonly width: number
  readonly height: number
}

const KeepWithin: Mount.MountDefinitionNoArgs<'KeepWithin', never>

function keepWithin<Slots>(
  slots: Slots,
): <Input, ParentMessage>(options: {
  readonly panel: keyof Slots & string
}) => Behavior.NamedBehavior<Slots, Input, ParentMessage>

interface OriginRect {
  readonly left: number
  readonly top: number
}

interface PanelRect {
  readonly top: number
  readonly right: number
  readonly bottom: number
  readonly height: number
}

const PlaceAt: Mount.MountDefinitionWithArgs<
  'PlaceAt',
  { triggerId: Schema.String; gap: Schema.Number },
  never
>

function placeAt(
  trigger: AnchorRect,
  origin: OriginRect,
  gap?: number,
): PlacedAt

const PlaceAtPoint: Mount.MountDefinitionWithArgs<
  'PlaceAtPoint',
  { x: Schema.Number; y: Schema.Number },
  never
>

function placeAtPoint(point: ViewportPoint, origin: OriginRect): PlacedAt

function placeAtTrigger<Slots>(
  slots: Slots,
): <Input, ParentMessage>(options: {
  readonly panel: keyof Slots & string
  readonly triggerId: (input: Input) => string
  readonly gap?: number
  readonly at?: (input: Input) => Option.Option<ViewportPoint>
}) => Behavior.NamedBehavior<Slots, Input, ParentMessage>

interface Placed {
  readonly dx: number
  readonly flip: boolean
}

const placedAbove: 'above'

interface PlacedAt {
  readonly left: number
  readonly top: number
}

const placedSide: 'data-fk-placed'

const placedTop: '--fk-placed-top'

function placeFor(rect: PanelRect, viewport: Viewport, margin?: number): Placed

function shiftIntoViewport(
  rect: {
    readonly top: number
    readonly bottom: number
  },
  viewportHeight: number,
  margin?: number,
): number

interface Viewport {
  readonly width: number
  readonly height: number
}

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