#Geometry

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

Rectangle math, normalization, bounds and clamping, content extent, validation, and gap enforcement. These are the building blocks the solvers are made of, exported so you can build your own.

import { boundsFromCanvas, canPlaceItem, canvasesEqual, canvasInnerHeight, canvasInnerRect, canvasInnerWidth, clampItem, cloneItems, contentBottom, contentRight, createItem, enforceMinimumGaps, findLayoutViolations, fitCanvasToContent, inferGap, itemArea, itemBottom, itemRight, layoutIsValid, normalizeCanvas, normalizeItem, normalizeItems, normalizeLayout, normalizePadding, overlapArea, pointInRect, rectsOverlap, rectsViolateGap, rectToEdges, rectToViewportEdges, resizeRect, roundItem, toCanvasItem, toInnerItem } from 'gridla'
import type { LayoutViolation } from 'gridla'

#Functions

#boundsFromCanvas

Derive solver bounds from a canvas. height becomes null for scrollable canvases so items may extend below the visible height.

export function boundsFromCanvas(canvas: GridCanvas): GridBounds

#canPlaceItem

True when item fits inside bounds (within one pixel) and does not violate gap against any solid sibling.

export function canPlaceItem(
  items: readonly GridItem[],
  item: GridItem,
  bounds: GridBounds,
  gap: number,
): boolean

#canvasesEqual

True when two canvases have the same width, height, and padding on every side. heightMode is not compared.

export function canvasesEqual(a: GridCanvas, b: GridCanvas): boolean

#canvasInnerHeight

Height of the canvas inside its top and bottom padding, in pixels. Never less than 1.

export function canvasInnerHeight(canvas: GridCanvas): number

#canvasInnerRect

The area inside the canvas padding as a rectangle in canvas coordinates: origin at the padding offset, size from canvasInnerWidth and canvasInnerHeight.

export function canvasInnerRect(canvas: GridCanvas): GridRect

#canvasInnerWidth

Width of the canvas inside its left and right padding, in pixels. Never less than 1.

export function canvasInnerWidth(canvas: GridCanvas): number

#clampItem

Fit an item inside bounds without moving it more than necessary. Sizes are clamped from the current position first; the position only shifts when the minimum size would not fit otherwise.

export function clampItem<T>(item: GridItem<T>, bounds: GridBounds): GridItem<T>

#cloneItems

Shallow-copy every item into a new array. data is shared, not cloned.

export function cloneItems<T>(items: readonly GridItem<T>[]): GridItem<T>[]

#contentBottom

Lowest bottom edge among the items, in canvas coordinates. Returns the top padding when there are no items.

export function contentBottom(items: readonly GridRect[], canvas: GridCanvas): number

#contentRight

Rightmost right edge among the items, in canvas coordinates. Returns the left padding when there are no items.

export function contentRight(items: readonly GridRect[], canvas: GridCanvas): number

#createItem

Build a GridItem from an id, a size (with optional constraints), and a top-left position (default 0, 0). w and h are clamped to MIN_ITEM_SIZE; constraint fields and data are copied only when defined.

export function createItem<T = unknown>(
  id: string,
  size: GridItemSize,
  x = 0,
  y = 0,
  data?: T,
): GridItem<T>

#enforceMinimumGaps

Push and trim items so that no two neighbors sit closer than gap. Items are processed left-to-right, then top-to-bottom, and clamped to bounds.

export function enforceMinimumGaps<T>(
  items: readonly GridItem<T>[],
  bounds: GridBounds,
  gap: number,
): GridItem<T>[]

#findLayoutViolations

Report bounds and overlap violations. Ghost items and pairs of locked items are exempt from the overlap check.

export function findLayoutViolations(layout: GridLayout): LayoutViolation[]

#fitCanvasToContent

For scrollable canvases, grow height so every item fits. Bounded canvases are returned unchanged.

export function fitCanvasToContent(canvas: GridCanvas, items: readonly GridRect[]): GridCanvas

#inferGap

Smallest positive distance between any two neighboring items, or 0.

export function inferGap(items: readonly GridRect[]): number

#itemArea

Area of a rectangle in square pixels (w * h).

export function itemArea(item: Pick<GridRect, 'w' | 'h'>): number

#itemBottom

Bottom edge of a rectangle (y + h).

export function itemBottom(item: Pick<GridRect, 'y' | 'h'>): number

#itemRight

Right edge of a rectangle (x + w).

export function itemRight(item: Pick<GridRect, 'x' | 'w'>): number

#layoutIsValid

True when every item in the layout can be placed.

export function layoutIsValid(
  items: readonly GridItem[],
  bounds: GridBounds,
  gap: number,
): boolean

#normalizeCanvas

Fill in defaults and clamp a canvas so it is at least one pixel larger than its padding on both axes.

export function normalizeCanvas(
  value: Partial<GridCanvas> | undefined,
  fallback: GridCanvas = DEFAULT_CANVAS,
): GridCanvas

#normalizeItem

Round an item and fit it inside a canvas, honoring min/max constraints and the canvas height mode.

export function normalizeItem<T>(item: GridItem<T>, canvas: GridCanvas): GridItem<T>

#normalizeItems

Apply normalizeItem to every item: round its geometry and clamp it into the canvas.

export function normalizeItems<T>(
  items: readonly GridItem<T>[],
  canvas: GridCanvas,
): GridItem<T>[]

#normalizeLayout

Normalize a whole layout: canvas defaults plus every item clamped to it.

export function normalizeLayout<T>(layout: GridLayout<T>): GridLayout<T>

#normalizePadding

Fill in missing sides with 0, round each side to a whole pixel, and clamp negative values to 0.

export function normalizePadding(value: Partial<GridPadding> = {}): GridPadding

#overlapArea

Area shared by two rectangles in square pixels. 0 when they do not overlap.

export function overlapArea(left: GridRect, right: GridRect): number

#pointInRect

True when the point lies inside the rectangle. Edges are inclusive.

export function pointInRect(point: GridPoint, rect: GridRect): boolean

#rectsOverlap

True when two rectangles share area. Touching edges do not count.

export function rectsOverlap(left: GridRect, right: GridRect): boolean

#rectsViolateGap

True when two rectangles are closer than gap on both axes.

export function rectsViolateGap(left: GridRect, right: GridRect, gap: number): boolean

#rectToEdges

Convert an x/y/w/h rectangle into top/right/bottom/left edges.

export function rectToEdges(rect: GridRect): GridEdges

#rectToViewportEdges

Offset a rect by a container origin, producing viewport edges.

export function rectToViewportEdges(origin: GridPoint, rect: GridRect): GridEdges

#resizeRect

Compute the rectangle produced by dragging one edge or corner of an item by a pixel delta. The opposite edge stays anchored. Constraints and bounds are respected; siblings are not considered.

export function resizeRect<T>(
  item: GridItem<T>,
  edge: GridResizeEdge,
  delta: GridPoint,
  bounds: GridBounds,
): GridItem<T>

#roundItem

Round an item's geometry and constraints to whole pixels.

export function roundItem<T>(item: GridItem<T>): GridItem<T>

#toCanvasItem

Translate an item from inner coordinates back to canvas coordinates.

export function toCanvasItem<T>(item: GridItem<T>, canvas: GridCanvas): GridItem<T>

#toInnerItem

Translate an item from canvas coordinates to padding-relative inner coordinates.

export function toInnerItem<T>(item: GridItem<T>, canvas: GridCanvas): GridItem<T>

#Types

#LayoutViolation

One problem reported by findLayoutViolations: an item outside the canvas bounds, or two solid items that overlap.

export type LayoutViolation =
  | { kind: 'out-of-bounds'; itemId: string }
  | { kind: 'overlap'; itemId: string; otherId: string }