Nested
Generated by website/scripts/generate-api.ts from packages/gridla/src. Do not edit by hand; run bun run generate in website/.
Trees of layouts. flattenLayout projects every container into the rectangle its parent assigned it and returns root-relative rectangles; the rest are queries, coordinate conversions, and compaction over that flat result.
import { compactLayout, findContainerAt, findFirstUnlockedAncestor, flattenLayout, getAncestors, getDescendants, gridNodeAdapter, hitTest, isDirectChildOfContained, isInsideLockedSubtree, markLockedItems, projectItemsToRoot, projectItemToRoot, renderLayoutForRect, rootPointToContainer, scaleSizeBetweenContainers, toRenderedLayout } from 'gridla'
import type { CompactOptions, CompactResult, FindContainerOptions, FlatItem, FlatLayout, FlattenOptions, GridNode, GridNodeBehavior, GridTreeAdapter } from 'gridla'
Functions
compactLayout
function · core/nested/index.ts:585
Shrink items vertically until the layout fits a bounded canvas. Authored
gaps between rows are preserved, flexible items shrink proportionally down
to minH, rigid items keep their height. Horizontal geometry is untouched.
export function compactLayout<T>(
layout: GridLayout<T>,
options: CompactOptions = {},
): CompactResult<T>
findContainerAt
function · core/nested/index.ts:313
Deepest container that accepts children and contains the point.
export function findContainerAt<TNode>(
layout: FlatLayout<TNode>,
point: GridPoint,
options: FindContainerOptions = {},
): FlatItem<TNode> | null
findFirstUnlockedAncestor
function · core/nested/index.ts:384
Nearest ancestor (or the item itself) that is outside every locked subtree.
export function findFirstUnlockedAncestor<TNode>(
layout: FlatLayout<TNode>,
itemId: string,
): FlatItem<TNode> | undefined
flattenLayout
function · core/nested/index.ts:177
Flatten a tree of nested layouts into root-relative rectangles. Every
container's children are projected into the container's rendered rect.
export function flattenLayout<TNode = GridNode>(
root: TNode,
rootRect: GridRect,
options: FlattenOptions<TNode> = {},
): FlatLayout<TNode>
getAncestors
function · core/nested/index.ts:341
Ancestors of an item from parent to root.
export function getAncestors<TNode>(layout: FlatLayout<TNode>, itemId: string): FlatItem<TNode>[]
getDescendants
function · core/nested/index.ts:354
All descendants of an item in paint order.
export function getDescendants<TNode>(
layout: FlatLayout<TNode>,
itemId: string,
): FlatItem<TNode>[]
hitTest
function · core/nested/index.ts:290
Deepest item whose rect contains the point (last in paint order wins).
export function hitTest<TNode>(
layout: FlatLayout<TNode>,
point: GridPoint,
): FlatItem<TNode> | null
isDirectChildOfContained
function · core/nested/index.ts:397
True when the item's direct parent is a contained container.
export function isDirectChildOfContained<TNode>(
layout: FlatLayout<TNode>,
itemId: string,
): boolean
isInsideLockedSubtree
function · core/nested/index.ts:374
True when the item or any ancestor is locked.
export function isInsideLockedSubtree<TNode>(layout: FlatLayout<TNode>, itemId: string): boolean
markLockedItems
function · core/nested/index.ts:410
Mark items whose node is locked as policy.movement: 'locked' so solvers
treat them as walls. Returns the input when nothing changes.
export function markLockedItems<TNode>(
items: readonly GridItem[],
layout: FlatLayout<TNode>,
): readonly GridItem[]
projectItemsToRoot
function · core/nested/index.ts:433
Project items expressed in a container's rendered canvas into root
coordinates using the same pipeline flattenLayout uses. Pass a full
solver result so gap preservation sees every neighbor.
export function projectItemsToRoot<TNode>(
container: FlatItem<TNode>,
items: readonly GridItem[],
): Map<string, GridRect>
projectItemToRoot
function · core/nested/index.ts:465
Root coordinates of one item after projecting contextItems.
export function projectItemToRoot<TNode>(
container: FlatItem<TNode>,
item: GridItem,
contextItems: readonly GridItem[],
): GridRect
renderLayoutForRect
function · core/nested/index.ts:152
Project a container's authored layout into the rectangle it renders in.
Returns a layout whose canvas matches rect (with the node's padding) and
whose items are in that canvas's coordinates.
export function renderLayoutForRect(
layout: GridLayout,
rect: GridSize,
padding: Partial<GridPadding> | undefined,
gap: number,
): GridLayout
rootPointToContainer
function · core/nested/index.ts:487
Convert a root-relative point into a container's rendered canvas
coordinates. Returns null for leaves.
export function rootPointToContainer<TNode>(
container: FlatItem<TNode>,
point: GridPoint,
canvas: GridCanvas | null = container.layout?.canvas ?? null,
): GridPoint | null
scaleSizeBetweenContainers
function · core/nested/index.ts:512
Translate a size authored in source's canvas units to target's so it
covers the same number of root pixels.
export function scaleSizeBetweenContainers<TNode>(
source: FlatItem<TNode>,
target: FlatItem<TNode>,
size: GridSize,
): GridSize
toRenderedLayout
function · core/nested/index.ts:536
Build the layout to persist after a solve inside container: the canvas
is rebased to the container's rendered size and the items are projected
into it. Subsequent renders at the same size are then identity.
export function toRenderedLayout<TNode>(
container: FlatItem<TNode>,
items: readonly GridItem[],
): GridLayout
Constants
gridNodeAdapter
const · core/nested/index.ts:71
The GridTreeAdapter for plain GridNode trees. flattenLayout uses it
when no adapter is given.
export const gridNodeAdapter: GridTreeAdapter<GridNode<unknown>>
Types
CompactOptions
type · core/nested/index.ts:568
Options for compactLayout.
export type CompactOptions = {
/** Items that keep their height. Fixed-height items always do. */
isRigid?: (item: GridItem) => boolean
}
CompactResult
type · core/nested/index.ts:574
Result of compactLayout: the compacted layout and whether everything fit.
export type CompactResult<T = unknown> = {
layout: GridLayout<T>
/** `false` when rigid heights, minimums, and gaps exceed the canvas. */
fits: boolean
}
FindContainerOptions
type · core/nested/index.ts:302
Options for findContainerAt.
export type FindContainerOptions = {
/**
* Containers other than `sourceId` must contain the point at least this
* far inside their edges. Keeps edge brushes from switching targets.
*/
inset?: number
/** Container the interaction started in; it wins without any inset. */
sourceId?: string
}
FlatItem
type · core/nested/index.ts:101
One node of a flattened tree: its rectangle in root coordinates, its place in
the hierarchy, its rendered and authored layouts, and its resolved behavior flags.
export type FlatItem<TNode = GridNode> = {
id: string
/** Id of the enclosing container, or `null` for the root. */
parentId: string | null
/** 0 for the root, 1 for its children, and so on. */
depth: number
/** Rectangle in root coordinates. */
rect: GridRect
/** The node's item entry in its parent's authored layout. `null` for the root. */
canonicalRect: GridRect | null
/** The node's item entry in its parent's rendered layout. `null` for the root. */
sizing: GridItem | null
/**
* For containers: the authored layout projected into `rect`. Solvers and
* hit testing for children operate in this coordinate system.
*/
layout: GridLayout | null
/** The authored layout, untouched. `null` for leaves. */
sourceLayout: GridLayout | null
/** Gap used when projecting and solving this container's children. */
gap: number
node: TNode
isContainer: boolean
acceptsChildren: boolean
locked: boolean
contained: boolean
scrollable: boolean
}
FlatLayout
type · core/nested/index.ts:134
Result of flattenLayout: every node in paint order (each parent before its
children) plus lookups by id and by parent id. The root's parent id is null.
export type FlatLayout<TNode = GridNode> = {
rootId: string
items: readonly FlatItem<TNode>[]
itemsById: ReadonlyMap<string, FlatItem<TNode>>
childrenByParentId: ReadonlyMap<string | null, readonly string[]>
}
FlattenOptions
type · core/nested/index.ts:142
Options for flattenLayout.
export type FlattenOptions<TNode> = {
/** Reads your own tree shape. Defaults to the `GridNode` adapter. */
adapter?: GridTreeAdapter<TNode>
}
GridNode
type · core/nested/index.ts:44
Normalized tree node. Use GridTreeAdapter to flatten other shapes directly.
export type GridNode<TData = unknown> = {
id: string
/** Layout of this node's children. Present on containers. */
layout?: GridLayout
children?: GridNode<TData>[]
/** Gap between children in pixels. Kept fixed during projection. */
gap?: number
/** Rendering padding for children. Overrides `layout.canvas.padding`. */
padding?: Partial<GridPadding>
behavior?: GridNodeBehavior
data?: TData
}
GridNodeBehavior
type · core/nested/index.ts:30
Per-node flags that control how a node takes part in nesting: whether it is a
container, accepts drops, confines its children, is locked, or keeps its
height during compaction. Every flag is optional.
export type GridNodeBehavior = {
/** Treat the node as a container even without children. Defaults to `layout !== undefined`. */
container?: boolean
/** Whether items may be dropped into this node. Defaults to `container`. */
acceptsChildren?: boolean
/** Direct children cannot leave, and outside items cannot enter. */
contained?: boolean
/** The subtree is a wall: nothing inside moves, nothing outside enters. */
locked?: boolean
/** Keeps its height during compaction (content scrolls instead). */
scrollable?: boolean
}
GridTreeAdapter
type · core/nested/index.ts:58
Callbacks that let flattenLayout read any tree shape without conversion.
export type GridTreeAdapter<TNode> = {
getId(node: TNode): string
getChildren(node: TNode): readonly TNode[]
getLayout(node: TNode): GridLayout | null | undefined
getBehavior?(node: TNode): GridNodeBehavior | undefined
getGap?(node: TNode): number | undefined
getPadding?(node: TNode): Partial<GridPadding> | undefined
}