Model

Generated by website/scripts/generate-api.ts from packages/gridla/src. Do not edit by hand; run bun run generate in website/.

The public data model. Every type is a plain, serializable object; the core never reads or writes anything else. Constants and predicates here are shared by every solver.

import { DEFAULT_CANVAS, DEFAULT_SNAP_DISTANCE, EMPTY_PADDING, isFixedHeight, isFixedOnAxis, isFixedWidth, isGhost, isLocked, MIN_ITEM_SIZE } from 'gridla'
import type { GridAxis, GridBounds, GridCanvas, GridEdges, GridHeightMode, GridItem, GridItemConstraints, GridItemPolicy, GridItemSize, GridLayout, GridPadding, GridPoint, GridRect, GridResizeEdge, GridSize, GridSizeMode } from 'gridla'
ExportKindSummary
DEFAULT_CANVASconstCanvas used when none is given: 1200 x 720 pixels, no padding, bounded height mode.
DEFAULT_SNAP_DISTANCEconstDefault distance in pixels within which edges attract each other.
EMPTY_PADDINGconstZero padding on every side.
GridAxistypeHorizontal (x) or vertical (y) axis.
GridBoundstypeBounds a solver operates against.
GridCanvastypeThe rectangle items are laid out in.
GridEdgestypeEdge-based rectangle used for hit testing and viewport math.
GridHeightModetypeHow the canvas treats its vertical extent.
GridItemtypeA laid-out item.
GridItemConstraintstypeSize constraints an item may carry.
GridItemPolicytypeSolver participation policy for one item.
GridItemSizetypeSize information used when creating or placing an item.
GridLayouttypeA canvas and the items positioned inside it.
GridPaddingtypePer-side inset in pixels.
GridPointtypeA point in canvas pixel coordinates.
GridRecttypeA positioned rectangle.
GridResizeEdgetypeCompass edge or corner used to resize an item.
GridSizetypeA width and height in pixels.
GridSizeModetypeWhich axes keep their pixel size when the layout is projected to another canvas size.
isFixedHeightfunctionTrue when sizeMode pins the height (fixed-h or fixed).
isFixedOnAxisfunctionTrue when sizeMode pins the given axis: the width for x, the height for y.
isFixedWidthfunctionTrue when sizeMode pins the width (fixed-w or fixed).
isGhostfunctionTrue when the item's collision policy is ignore, so solvers move, resize, and place other items straight through it.
isLockedfunctionTrue when the item's movement policy is locked: it still blocks, but never moves or resizes as a side effect of another item's operation.
MIN_ITEM_SIZEconstSmallest width or height an item may have.

Functions

isFixedHeight

function · core/model.ts:173

True when sizeMode pins the height (fixed-h or fixed).

export function isFixedHeight(item: Pick<GridItem, 'sizeMode'>): boolean

isFixedOnAxis

function · core/model.ts:178

True when sizeMode pins the given axis: the width for x, the height for y.

export function isFixedOnAxis(item: Pick<GridItem, 'sizeMode'>, axis: GridAxis): boolean

isFixedWidth

function · core/model.ts:168

True when sizeMode pins the width (fixed-w or fixed).

export function isFixedWidth(item: Pick<GridItem, 'sizeMode'>): boolean

isGhost

function · core/model.ts:155

True when the item's collision policy is ignore, so solvers move, resize, and place other items straight through it.

export function isGhost(item: Pick<GridItem, 'policy'>): boolean

isLocked

function · core/model.ts:163

True when the item's movement policy is locked: it still blocks, but never moves or resizes as a side effect of another item's operation.

export function isLocked(item: Pick<GridItem, 'policy'>): boolean

Constants

DEFAULT_CANVAS

const · core/model.ts:138

Canvas used when none is given: 1200 x 720 pixels, no padding, bounded height mode. Frozen.

export const DEFAULT_CANVAS: Readonly<GridCanvas>

DEFAULT_SNAP_DISTANCE

const · core/model.ts:146

Default distance in pixels within which edges attract each other.

export const DEFAULT_SNAP_DISTANCE: 24

EMPTY_PADDING

const · core/model.ts:127

Zero padding on every side. Frozen; shared by DEFAULT_CANVAS.

export const EMPTY_PADDING: Readonly<GridPadding>

MIN_ITEM_SIZE

const · core/model.ts:149

Smallest width or height an item may have.

export const MIN_ITEM_SIZE: 1

Types

GridAxis

type · core/model.ts:114

Horizontal (x) or vertical (y) axis.

export type GridAxis = 'x' | 'y'

GridBounds

type · core/model.ts:120

Bounds a solver operates against. Derived from a canvas; height is null for scrollable canvases.

export type GridBounds = {
  width: number
  height: number | null
  padding: GridPadding
}
MemberTypeDescription
widthnumber
height`number \null`
paddingGridPadding

GridCanvas

type · core/model.ts:23

The rectangle items are laid out in. Items use canvas-relative pixel coordinates.

export type GridCanvas = {
  width: number
  height: number
  padding: GridPadding
  heightMode: GridHeightMode
}
MemberTypeDescription
widthnumber
heightnumber
paddingGridPadding
heightModeGridHeightMode

GridEdges

type · core/model.ts:103

Edge-based rectangle used for hit testing and viewport math.

export type GridEdges = {
  top: number
  right: number
  bottom: number
  left: number
}
MemberTypeDescription
topnumber
rightnumber
bottomnumber
leftnumber

GridHeightMode

type · core/model.ts:20

How the canvas treats its vertical extent.

  • bounded: items must fit inside height.
  • scrollable: items may extend below height; the canvas grows to fit.
export type GridHeightMode = 'bounded' | 'scrollable'

GridItem

type · core/model.ts:80

A laid-out item. data is caller-owned and passes through untouched.

export type GridItem<TData = unknown> = GridRect &
  GridItemConstraints & {
    id: string
    policy?: GridItemPolicy
    data?: TData
  }
MemberTypeDescription
xnumber
ynumber
wnumber
hnumber
minW?number
minH?number
maxW?number
maxH?number
sizeMode?GridSizeMode
fixedWidth?numberPixel width to pin when sizeMode fixes the width. Falls back to w.
fixedHeight?numberPixel height to pin when sizeMode fixes the height. Falls back to h.
idstring
policy?GridItemPolicy
data?TData

GridItemConstraints

type · core/model.ts:67

Size constraints an item may carry.

export type GridItemConstraints = {
  minW?: number
  minH?: number
  maxW?: number
  maxH?: number
  sizeMode?: GridSizeMode
  /** Pixel width to pin when `sizeMode` fixes the width. Falls back to `w`. */
  fixedWidth?: number
  /** Pixel height to pin when `sizeMode` fixes the height. Falls back to `h`. */
  fixedHeight?: number
}
MemberTypeDescription
minW?number
minH?number
maxW?number
maxH?number
sizeMode?GridSizeMode
fixedWidth?numberPixel width to pin when sizeMode fixes the width. Falls back to w.
fixedHeight?numberPixel height to pin when sizeMode fixes the height. Falls back to h.

GridItemPolicy

type · core/model.ts:42

Solver participation policy for one item.

export type GridItemPolicy = {
  /**
   * `solid` (default): the item occupies space and blocks other items.
   * `ignore`: the item is a ghost. Solvers move, resize and place other items
   * straight through it. Useful for reserved slots and floating items.
   */
  collision?: 'solid' | 'ignore'
  /**
   * `movable` (default): the solver may push, swap, shrink or reorder the item
   * to make room for another item.
   * `locked`: the item is a wall. It still blocks, but never moves or resizes
   * as a side effect of another item's operation.
   */
  movement?: 'movable' | 'locked'
}
MemberTypeDescription
collision?`"solid" \"ignore"`
movement?`"movable" \"locked"`

GridItemSize

type · core/model.ts:88

Size information used when creating or placing an item.

export type GridItemSize = Pick<GridItem, 'w' | 'h'> & GridItemConstraints
MemberTypeDescription
wnumber
hnumber
minW?number
minH?number
maxW?number
maxH?number
sizeMode?GridSizeMode
fixedWidth?numberPixel width to pin when sizeMode fixes the width. Falls back to w.
fixedHeight?numberPixel height to pin when sizeMode fixes the height. Falls back to h.

GridLayout

type · core/model.ts:91

A canvas and the items positioned inside it.

export type GridLayout<TData = unknown> = {
  canvas: GridCanvas
  items: GridItem<TData>[]
}
MemberTypeDescription
canvasGridCanvas
itemsArray\<GridItem\<TData\>\>

GridPadding

type · core/model.ts:7

Per-side inset in pixels.

export type GridPadding = {
  top: number
  right: number
  bottom: number
  left: number
}
MemberTypeDescription
topnumber
rightnumber
bottomnumber
leftnumber

GridPoint

type · core/model.ts:97

A point in canvas pixel coordinates.

export type GridPoint = { x: number; y: number }
MemberTypeDescription
xnumber
ynumber

GridRect

type · core/model.ts:59

A positioned rectangle.

export type GridRect = {
  x: number
  y: number
  w: number
  h: number
}
MemberTypeDescription
xnumber
ynumber
wnumber
hnumber

GridResizeEdge

type · core/model.ts:111

Compass edge or corner used to resize an item.

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

GridSize

type · core/model.ts:100

A width and height in pixels.

export type GridSize = { w: number; h: number }
MemberTypeDescription
wnumber
hnumber

GridSizeMode

type · core/model.ts:39

Which axes keep their pixel size when the layout is projected to another canvas size.

  • free (default): both axes scale.
  • fixed-w: width stays constant, height scales.
  • fixed-h: height stays constant, width scales.
  • fixed: neither axis scales.
export type GridSizeMode = 'free' | 'fixed-w' | 'fixed-h' | 'fixed'