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'
ExportKindSummary
compactLayoutfunctionShrink items vertically until the layout fits a bounded canvas.
CompactOptionstypeOptions for compactLayout.
CompactResulttypeResult of compactLayout: the compacted layout and whether everything fit.
findContainerAtfunctionDeepest container that accepts children and contains the point.
FindContainerOptionstypeOptions for findContainerAt.
findFirstUnlockedAncestorfunctionNearest ancestor (or the item itself) that is outside every locked subtree.
FlatItemtypeOne 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.
FlatLayouttypeResult of flattenLayout: every node in paint order (each parent before its children) plus lookups by id and by parent id.
flattenLayoutfunctionFlatten a tree of nested layouts into root-relative rectangles.
FlattenOptionstypeOptions for flattenLayout.
getAncestorsfunctionAncestors of an item from parent to root.
getDescendantsfunctionAll descendants of an item in paint order.
GridNodetypeNormalized tree node.
gridNodeAdapterconstThe GridTreeAdapter for plain GridNode trees.
GridNodeBehaviortypePer-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.
GridTreeAdaptertypeCallbacks that let flattenLayout read any tree shape without conversion.
hitTestfunctionDeepest item whose rect contains the point (last in paint order wins).
isDirectChildOfContainedfunctionTrue when the item's direct parent is a contained container.
isInsideLockedSubtreefunctionTrue when the item or any ancestor is locked.
markLockedItemsfunctionMark items whose node is locked as policy.movement: 'locked' so solvers treat them as walls.
projectItemsToRootfunctionProject items expressed in a container's rendered canvas into root coordinates using the same pipeline flattenLayout uses.
projectItemToRootfunctionRoot coordinates of one item after projecting contextItems.
renderLayoutForRectfunctionProject a container's authored layout into the rectangle it renders in.
rootPointToContainerfunctionConvert a root-relative point into a container's rendered canvas coordinates.
scaleSizeBetweenContainersfunctionTranslate a size authored in source's canvas units to target's so it covers the same number of root pixels.
toRenderedLayoutfunctionBuild 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.

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
}
MemberTypeDescription
isRigid?((item: GridItem) =\> boolean)Items that keep their height. Fixed-height items always do.

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
}
MemberTypeDescription
layoutGridLayout\<T\>
fitsbooleanfalse when rigid heights, minimums, and gaps exceed the canvas.

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
}
MemberTypeDescription
inset?numberContainers other than sourceId must contain the point at least this far inside their edges. Keeps edge brushes from switching targets.
sourceId?stringContainer the interaction started in; it wins without any inset.

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
}
MemberTypeDescription
idstring
parentId`string \null`
depthnumber0 for the root, 1 for its children, and so on.
rectGridRectRectangle in root coordinates.
canonicalRect`GridRect \null`
sizing`GridItem \null`
layout`GridLayout \null`
sourceLayout`GridLayout \null`
gapnumberGap used when projecting and solving this container's children.
nodeTNode
isContainerboolean
acceptsChildrenboolean
lockedboolean
containedboolean
scrollableboolean

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[]>
}
MemberTypeDescription
rootIdstring
itemsReadonlyArray\<FlatItem\<TNode\>\>
itemsByIdReadonlyMap\<string, FlatItem\<TNode\>\>
childrenByParentId`ReadonlyMap<string \null, ReadonlyArray<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>
}
MemberTypeDescription
adapter?GridTreeAdapter\<TNode\>Reads your own tree shape. Defaults to the GridNode adapter.

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
}
MemberTypeDescription
idstring
layout?GridLayoutLayout of this node's children. Present on containers.
children?Array\<GridNode\<TData\>\>
gap?numberGap between children in pixels. Kept fixed during projection.
padding?Partial\<GridPadding\>Rendering padding for children. Overrides layout.canvas.padding.
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
}
MemberTypeDescription
container?booleanTreat the node as a container even without children. Defaults to layout !== undefined.
acceptsChildren?booleanWhether items may be dropped into this node. Defaults to container.
contained?booleanDirect children cannot leave, and outside items cannot enter.
locked?booleanThe subtree is a wall: nothing inside moves, nothing outside enters.
scrollable?booleanKeeps its height during compaction (content scrolls instead).

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
}
MemberTypeDescription
getId(node: TNode) =\> string
getChildren(node: TNode) =\> readonly TNode[]
getLayout`(node: TNode) => GridLayout \null`
getBehavior?`((node: TNode) => GridNodeBehavior \undefined)`
getGap?`((node: TNode) => number \undefined)`
getPadding?`((node: TNode) => Partial<GridPadding> \undefined)`