layout

package
v0.20.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 20, 2026 License: MIT Imports: 23 Imported by: 0

Documentation

Overview

Package layout builds a simple visual tree from the Growse DOM.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ApplyAnimatedStyles

func ApplyAnimatedStyles(tree *Tree, styles stylemodel.Map)

ApplyAnimatedStyles applies paint and hit-test state to an existing layout tree without changing its geometry. Paint.Build and HitTest consequently observe the exact same transform matrix.

func ApplyScrollContainerOffset added in v0.19.0

func ApplyScrollContainerOffset(tree *Tree, styles stylemodel.Map, containerID dom.NodeID, scrollX, scrollY float32) []dom.NodeID

ApplyScrollContainerOffset moves a nested scroll container's contents and recomputes every sticky box attached to either of its physical axes.

func ApplyScrollOffset added in v0.17.0

func ApplyScrollOffset(tree *Tree, styles stylemodel.Map, scrollX, scrollY float32) []dom.NodeID

ApplyScrollOffset repositions viewport-attached and viewport-sticky subtrees. Normal-flow fragments remain in document coordinates; the UI scrolls them by list offset while fixed and sticky geometry is updated for paint/hit sharing.

func HitTest

func HitTest(tree *Tree, x, y float32) (dom.NodeID, bool)

HitTest returns the deepest visible DOM node at document coordinates.

func ReuseStableFragments added in v0.17.0

func ReuseStableFragments(previous, current *Tree, dirty map[dom.NodeID]bool) int

ReuseStableFragments restores immutable fragment storage for unaffected nodes whose geometry and paint inputs stayed identical.

Types

type BorderRadii

type BorderRadii struct {
	TopLeft, TopRight, BottomRight, BottomLeft CornerRadius
}

BorderRadii contains resolved radii in clockwise order.

type Box

type Box struct {
	Order       int
	StackingID  int
	NodeID      dom.NodeID
	FragmentID  uint64
	Tag         string
	Text        string
	Input       bool
	Multiline   bool
	Select      bool
	Options     []forms.Option
	Selected    int
	Checkable   bool
	Checked     bool
	InputType   string
	Disabled    bool
	ReadOnly    bool
	Button      bool
	Image       bool
	ImageURL    string
	Alt         string
	ImageRect   Rect
	ImageClip   Rect
	ImageFailed bool
	ObjectFit   stylemodel.ObjectFit
	ObjectPos   stylemodel.BackgroundPosition
	ImageBorder stylemodel.Borders
	ImageRadius BorderRadii
	Appearance  stylemodel.Appearance
	AccentColor uint32
	Cursor      stylemodel.Cursor

	X        float32
	Y        float32
	Width    float32
	Height   float32
	Baseline float32
	Clip     *Rect
	Clips    []ClipRegion
	Opacity  float32

	FontSize        float32
	Bold            bool
	FontFamilies    []string
	FontStyle       string
	FontStretch     string
	LetterSpacing   float32
	WordSpacing     float32
	VerticalOffset  float32
	Color           uint32
	Background      uint32
	Decoration      stylemodel.TextDecorationLine
	DecorationColor uint32
	TextShadows     []stylemodel.Shadow
	Transform       stylemodel.Matrix
	WritingMode     stylemodel.WritingMode
	Direction       stylemodel.Direction
	Hidden          bool
	Runs            []TextRun
}

Box is one line of visible page content.

func (Box) Rect

func (box Box) Rect() Rect

type ClipRegion

type ClipRegion struct {
	Rect
	NodeID dom.NodeID
	Radius BorderRadii
}

ClipRegion is one nested rectangular or rounded clipping boundary.

type CompositingLayer added in v0.17.0

type CompositingLayer struct {
	ID        int
	Parent    int
	NodeID    dom.NodeID
	Bounds    Rect
	Clip      *Rect
	Reasons   LayerReason
	Opacity   float32
	Transform stylemodel.Matrix
	Damage    []Rect
}

CompositingLayer is bounded page-owned compositor metadata. It contains no raster payload; Damage holds CSS-pixel rectangles for the next frame.

type CornerRadius

type CornerRadius struct{ X, Y float32 }

CornerRadius is one resolved elliptical radius in CSS pixels.

type Decoration

type Decoration struct {
	Order      int
	StackingID int
	NodeID     dom.NodeID
	FragmentID uint64
	Rect
	Background      uint32
	Image           stylemodel.BackgroundImage
	Layers          []stylemodel.BackgroundLayer
	Repeat          stylemodel.BackgroundRepeat
	Position        stylemodel.BackgroundPosition
	Size            stylemodel.BackgroundSize
	Border          stylemodel.Borders
	Padding         stylemodel.Edges
	Radius          BorderRadii
	Opacity         float32
	Clip            *Rect
	Clips           []ClipRegion
	BoxShadows      []stylemodel.Shadow
	Outline         stylemodel.BorderSide
	OutlineOffset   float32
	Filters         []stylemodel.Filter
	BackdropFilters []stylemodel.Filter
	BlendMode       stylemodel.BlendMode
	Cursor          stylemodel.Cursor
	Transform       stylemodel.Matrix
	WritingMode     stylemodel.WritingMode
	Direction       stylemodel.Direction
	Hidden          bool
}

Decoration is the border-box visual of one element. It is kept separately from line boxes so backgrounds can be painted before descendant content.

type Fallback added in v0.17.0

type Fallback struct {
	NodeID dom.NodeID
	Reason string
}

Fallback records a bounded, payload-free layout/paint safety decision.

type FontRange added in v0.15.0

type FontRange struct{ Start, End rune }

FontRange is one inclusive unicode-range interval for a web font face.

type FontSet added in v0.15.0

type FontSet struct {
	// contains filtered or unexported fields
}

FontSet is an immutable page-scoped collection of decoded web fonts. Shaping is serialized because HarfbuzzShaper retains reusable buffers.

func NewFontSet added in v0.15.0

func NewFontSet(faces []WebFontFace) *FontSet

NewFontSet creates a page-scoped font collection. Invalid faces are omitted.

func NewFontSetWithSystemFallback added in v0.16.0

func NewFontSetWithSystemFallback(faces []WebFontFace) *FontSet

NewFontSetWithSystemFallback creates a page-scoped font set whose shaping falls back from decoded Web Fonts and bundled Go fonts to operating-system glyph coverage. The set remains usable when system discovery fails.

type Hit added in v0.14.0

type Hit struct {
	NodeID   dom.NodeID
	Revision uint64
}

Hit is a hit-test result tied to the layout revision that produced it.

func HitTestWithRevision added in v0.14.0

func HitTestWithRevision(tree *Tree, x, y float32) (Hit, bool)

HitTestWithRevision returns a result that callers can compare with paint and inspector snapshots.

type ImageResource added in v0.15.0

type ImageResource struct {
	URL                             string
	IntrinsicWidth, IntrinsicHeight float32
	Alt                             string
	Loaded                          bool
	Deferred                        bool
	Error                           string
}

ImageResource is browser-decoded metadata for one replaced image element. Layout never fetches or decodes network content.

type LayerReason added in v0.17.0

type LayerReason uint16

LayerReason records why a node owns a compositor surface.

const (
	LayerTransform LayerReason = 1 << iota
	LayerOpacity
	LayerClip
	LayerScroll
	LayerFixed
	LayerSticky
	LayerFilter
)

type PaintEntry

type PaintEntry struct {
	Order, StackingID         int
	BoxIndex, DecorationIndex int
}

PaintEntry references one visual in final forward paint order.

type Rect

type Rect struct {
	X, Y, Width, Height float32
}

Rect is a document-coordinate clipping rectangle.

func UpdateCompositingLayers added in v0.17.0

func UpdateCompositingLayers(tree *Tree, styles stylemodel.Map) []Rect

UpdateCompositingLayers computes bounded damage for changed composite properties without rebuilding layout or the display list.

type ScrollContainer added in v0.19.0

type ScrollContainer struct {
	NodeID                    dom.NodeID
	Viewport                  Rect
	ScrollWidth, ScrollHeight float32
	Offset                    ScrollOffset
	OverflowX, OverflowY      stylemodel.Overflow
}

ScrollContainer shares one node's scrollport, overflow policy, extent, and current offset between layout, CSSOM, paint updates, and hit testing.

type ScrollOffset added in v0.19.0

type ScrollOffset struct{ X, Y float32 }

ScrollOffset is the physical scroll position of one nested scroll container.

type StackingContext

type StackingContext struct {
	Parent    int
	NodeID    dom.NodeID
	ZIndex    int
	Order     int
	Opacity   float32
	Offscreen bool
}

StackingContext records atomic paint-order ownership.

type StickyConstraint added in v0.19.0

type StickyConstraint struct {
	Normal            Rect
	ContainingBlock   Rect
	ContainingBlockID dom.NodeID
	XScrollContainer  dom.NodeID
	YScrollContainer  dom.NodeID
	Inset             stylemodel.Insets
	AppliedX          float32
	AppliedY          float32
}

StickyConstraint retains normal-flow geometry and the two independently selected scroll containers needed to recompute sticky placement without a full layout pass.

type TextRun

type TextRun struct {
	NodeID dom.NodeID
	Tag    string
	Text   string
	Width  float32
	Atomic bool
	// OffsetX/OffsetY and CrossSize describe the physical glyph rectangle for
	// vertical writing. Horizontal runs retain their compact sequential form.
	OffsetX   float32
	OffsetY   float32
	CrossSize float32

	FontSize        float32
	Bold            bool
	FontFamilies    []string
	FontStyle       string
	FontStretch     string
	LetterSpacing   float32
	WordSpacing     float32
	VerticalOffset  float32
	Color           uint32
	Background      uint32
	Baseline        float32
	Decoration      stylemodel.TextDecorationLine
	DecorationColor uint32
	Opacity         float32
	WritingMode     stylemodel.WritingMode
	Direction       stylemodel.Direction
	TextShadows     []stylemodel.Shadow
}

TextRun is a continuously styled fragment inside one line box.

type Tree

type Tree struct {
	Revision          uint64
	Width             float32
	ViewportHeight    float32
	Height            float32
	Background        uint32
	Decorations       []Decoration
	Boxes             []Box
	ScrollWidth       float32
	ScrollHeight      float32
	ScrollX           float32
	ScrollY           float32
	StackingContexts  []StackingContext
	CompositingLayers []CompositingLayer
	Parents           map[dom.NodeID]dom.NodeID
	Bounds            map[dom.NodeID]Rect
	StickyConstraints map[dom.NodeID]StickyConstraint
	ScrollContainers  map[dom.NodeID]ScrollContainer
	ScrollOffsets     map[dom.NodeID]ScrollOffset
	Fallbacks         []Fallback
}

Tree is the result of laying out one document at a specific viewport width.

func Build

func Build(document *dom.Document, computed stylemodel.Map, viewportWidth float32) *Tree

Build creates a vertical block layout with a minimal inline text flow.

func BuildAtRevision added in v0.14.0

func BuildAtRevision(document *dom.Document, computed stylemodel.Map, viewportWidth float32, revision uint64) *Tree

BuildAtRevision lays out one immutable DOM/style revision.

func BuildWithScroll

func BuildWithScroll(document *dom.Document, computed stylemodel.Map, viewportWidth, viewportHeight, scrollX, scrollY float32) *Tree

BuildWithScroll lays out viewport-attached and sticky elements at a scroll offset.

func BuildWithScrollAndImages added in v0.15.0

func BuildWithScrollAndImages(document *dom.Document, computed stylemodel.Map, images map[dom.NodeID]ImageResource, viewportWidth, viewportHeight, scrollX, scrollY float32) *Tree

BuildWithScrollAndImages lays out browser-decoded replaced image metadata.

func BuildWithScrollAndResources added in v0.15.0

func BuildWithScrollAndResources(document *dom.Document, computed stylemodel.Map, images map[dom.NodeID]ImageResource, fonts *FontSet, viewportWidth, viewportHeight, scrollX, scrollY float32) *Tree

BuildWithScrollAndResources lays out decoded images and page-scoped web fonts.

func BuildWithScrollAtRevision added in v0.14.0

func BuildWithScrollAtRevision(document *dom.Document, computed stylemodel.Map, viewportWidth, viewportHeight, scrollX, scrollY float32, revision uint64) *Tree

BuildWithScrollAtRevision lays out one immutable DOM/style revision at a scroll offset.

func BuildWithViewport

func BuildWithViewport(document *dom.Document, computed stylemodel.Map, viewportWidth, viewportHeight float32) *Tree

BuildWithViewport lays out a document with definite viewport dimensions.

func Clone

func Clone(tree *Tree) *Tree

Clone returns a frame-local copy of a layout tree. Geometry can be cached while ApplyAnimatedStyles mutates paint and hit-test state on the copy.

func (*Tree) OrderedPaintEntries

func (t *Tree) OrderedPaintEntries() []PaintEntry

OrderedPaintEntries returns the shared paint and hit-test ordering.

type WebFontFace added in v0.15.0

type WebFontFace struct {
	Family, Style, Weight string
	UnicodeRanges         []FontRange
	Face                  *textfont.Face
}

WebFontFace is a decoded face and the descriptors used to select it.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL