Projection
Generated by website/scripts/generate-api.ts from packages/gridla/src. Do not edit by hand; run bun run generate in website/.
Re-fit a layout to a different canvas size. projectLayout is the entry point; the chain and segment engines and the gap utilities are exported for advanced use.
import { applyGap, preserveGaps, projectFloatingRect, projectItemsByChain, projectItemsBySegments, projectLayout, roundItemRects, scaleItems, syncFixedDimensions } from 'gridla'
import type { ApplyGapOptions, ProjectionStrategy, ProjectOptions } from 'gridla'
Functions
applyGap
function · core/projection/segments.ts:626
Re-space every chain of adjacent items so neighbors sit exactly gap
pixels apart. Rows and columns keep their structure; canvas-spanning chains
keep filling the canvas. The current spacing is read from the layout, so no
scale has to be declared for the common case.
export function applyGap<T>(
layout: GridLayout<T>,
gap: number,
options: ApplyGapOptions = {},
): GridLayout<T>
preserveGaps
function · core/projection/chain.ts:859
Restore configured gaps and canvas-edge anchors after scaleItems, then
round to whole pixels. Mutates scaled in place.
export function preserveGaps<T>(
scaled: GridItem<T>[],
canonical: readonly GridItem<T>[],
gap: number,
canvas: GridCanvas,
sourceCanvas: GridCanvas,
): void
projectFloatingRect
function · core/projection/chain.ts:387
Ratio-scale a free-floating rect within the padded inner area of one canvas
to another. Used for items that do not participate in chains.
export function projectFloatingRect(
rect: { x: number; y: number; w: number; h: number },
sourceCanvas: GridCanvas,
targetCanvas: GridCanvas,
): { x: number; y: number; w: number; h: number }
projectItemsByChain
function · core/projection/chain.ts:906
Full chain projection: scale, then preserve gaps.
export function projectItemsByChain<T>(
items: readonly GridItem<T>[],
sourceCanvas: GridCanvas,
targetCanvas: GridCanvas,
gap = 0,
): GridItem<T>[]
projectItemsBySegments
function · core/projection/segments.ts:278
Project items from one canvas to another with the segment engine.
export function projectItemsBySegments<T>(
items: readonly GridItem<T>[],
sourceCanvas: GridCanvas,
targetCanvas: GridCanvas,
): GridItem<T>[]
projectLayout
function · core/projection/index.ts:32
Project a layout onto a different canvas size. The result is a new layout
whose items keep their relationships (rows, columns, alignment, fixed sizes)
while filling the target canvas.
export function projectLayout<T>(
layout: GridLayout<T>,
targetCanvas: Partial<GridCanvas>,
options: ProjectOptions = {},
): GridLayout<T>
roundItemRects
function · core/projection/chain.ts:919
Round every item's rect to whole pixels.
export function roundItemRects<T>(items: readonly GridItem<T>[]): GridItem<T>[]
scaleItems
function · core/projection/chain.ts:354
Flex/fill projection of items from sourceCanvas to targetCanvas.
Returns fractional positions; call preserveGaps afterwards to snap gaps
and round.
export function scaleItems<T>(
items: readonly GridItem<T>[],
sourceCanvas: GridCanvas,
targetCanvas: GridCanvas,
gap = 0,
): GridItem<T>[]
syncFixedDimensions
function · core/projection/chain.ts:27
Pin w/h and min/max to fixedWidth/fixedHeight when the size mode
fixes that axis. Items without explicit fixed dimensions pass through.
export function syncFixedDimensions<T>(items: readonly GridItem<T>[]): GridItem<T>[]
Types
ApplyGapOptions
type · core/projection/segments.ts:611
Options for applyGap.
export type ApplyGapOptions = {
/**
* Extra distances the detector treats as spacing between neighbors. Every
* neighbor distance up to 64px found in the layout is recognized on its own;
* list larger distances here when they are spacing rather than white space.
*/
recognizedGaps?: readonly number[]
}
ProjectionStrategy
type · core/projection/index.ts:10
Engine used by projectLayout: chain (default) or segments. See
ProjectOptions.strategy for how they differ.
export type ProjectionStrategy = 'chain' | 'segments'
ProjectOptions
type · core/projection/index.ts:13
Options for projectLayout.
export type ProjectOptions = {
/**
* `chain` (default): rows and columns of items are treated as flex chains.
* Fixed-size items and configured gaps keep their pixel size, empty space
* scales, free items fill the remainder proportionally.
*
* `segments`: every item edge becomes a stop; segments covered by free items
* scale, everything else stays fixed. Simpler and useful for sparse layouts.
*/
strategy?: ProjectionStrategy
/** Gap between items that the chain strategy keeps at exactly this pixel size. */
gap?: number
}