layout

package
v1.0.1 Latest Latest
Warning

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

Go to latest
Published: Oct 5, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package layout is the layout pipeline: it resolves styles and page sizes, drives the flexbox engine, and produces a tree of positioned boxes ready for painting. This is waffle's analogue of react-pdf's layout steps (resolveStyles → resolveInheritance → resolvePageSizes → resolveDimensions), for the View-only subset; text measurement and pagination land in later phases.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Box

type Box struct {
	Node     *tree.Node
	Style    map[string]any
	Frame    Rect
	Text     *TextInfo  // non-nil for Text boxes with renderable content
	Image    *ImageInfo // non-nil for Image boxes with a decoded source
	SVG      *tree.Node // non-nil for Svg boxes (the subtree, drawn by the renderer)
	Canvas   []any      // non-nil for Canvas boxes: the recorded painter ops
	Children []*Box
}

Box is a positioned node: its resolved style, its absolute frame, and its children.

type Cache

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

Cache memoizes render-invariant assets across renders of the same document: decoded images (whose pixel data is also already FlateDecode-compressed) and parsed font stores. A Template owns one, so repeated renders skip image decode + re-compression and font fetch + parse entirely — profiling shows those dominate render time on image-heavy documents.

Entries are keyed by source (the data-URI/URL/path string, or a hash of inline bytes), so a file or URL source is fetched once per Cache lifetime; later changes to the underlying file are not observed. All methods are safe for concurrent use and are nil-receiver safe (a nil *Cache disables caching). On a cold concurrent start the same asset may be built more than once; the results are equivalent and the last one stored wins.

func NewCache

func NewCache() *Cache

NewCache returns an empty asset cache.

type Evaluator

type Evaluator interface {
	EvalText(id string, ctx PageContext) (string, error)
	// EvalPaint runs a Canvas paint callback against a painter of size w×h and
	// returns the recorded ops ({op,args} maps) for the renderer to replay.
	EvalPaint(id string, w, h float64) ([]any, error)
}

Evaluator evaluates a function render-prop callback (identified by its $cb id) with a page context, returning the text it produces. It is backed by the live JS VM (goja). It is nil when a document has no callbacks or is rendered from a static tree with no VM — in that case callback render-props resolve to empty.

This resolves the common react-pdf idiom, a page-number footer:

<Text fixed render={({ pageNumber, totalPages }) => `${pageNumber} / ${totalPages}`} />

A callback that returns elements has their text extracted; the styling of any returned elements is not yet applied (the enclosing Text's style governs).

type ImageInfo

type ImageInfo struct {
	Spec      *pdf.ImageSpec
	ObjectFit string
}

ImageInfo is a decoded image ready to draw.

type Options

type Options struct {
	DPI     float64 // default 72
	RemBase float64 // default 18
	// Eval evaluates function render-props (render={fn}) per page. Nil for the
	// static path (such render-props then resolve to empty).
	Eval Evaluator
	// Cache memoizes decoded images and parsed fonts across renders of the same
	// document (a Template owns one and passes it here). Nil disables caching —
	// every render decodes and parses its assets from scratch.
	Cache *Cache
}

Options tune unit resolution.

type Page

type Page struct {
	Width, Height float64
	Root          *Box
}

Page is one laid-out page.

type PageContext

type PageContext struct {
	PageNumber        int
	TotalPages        int
	SubPageNumber     int
	SubPageTotalPages int
}

PageContext is the per-page context passed to a function render-prop, mirroring react-pdf's { pageNumber, totalPages, subPageNumber, subPageTotalPages }.

type Rect

type Rect struct {
	X, Y, W, H float64
}

Rect is an absolute box in page coordinates (points), border-box.

type Result

type Result struct {
	Pages    []*Page
	Warnings []string
}

Result is the laid-out document.

func Layout

func Layout(t *tree.Tree, opts Options) (*Result, error)

Layout lays out every Page in the document.

type RunFragment

type RunFragment struct {
	Text string
	X    float64
	// SpaceBefore marks that a word-space separates this fragment from the previous
	// one on the same line (false at a line start, and at a mid-word style change
	// where no space intervenes). The renderer widens exactly these gaps to justify.
	SpaceBefore   bool
	BaseFont      string
	EmbeddedFont  *pdf.EmbeddedFont
	Size          float64
	Color         string
	LetterSpacing float64
	WordSpacing   float64
	Underline     bool
	Strike        bool
}

RunFragment is one styled piece of text positioned on a line, at X points from the line's start. Exactly one of BaseFont / EmbeddedFont is set.

type TextInfo

type TextInfo struct {
	Content       string
	Lines         []string // wrapped lines
	BaseFont      string
	Size          float64
	Ascent        float64 // points from the box top to the baseline
	LineHeight    float64
	Color         string
	Orphans       int
	Widows        int
	Template      string            // string render-prop template (page numbers); "" if none
	CallbackID    string            // function render-prop callback id ($cb); "" if none
	Transform     string            // textTransform, re-applied to per-page substituted content
	LetterSpacing float64           // extra advance per character (points)
	WordSpacing   float64           // extra advance per space character (points)
	TextIndent    float64           // first-line indent (points)
	EmbeddedFont  *pdf.EmbeddedFont // registered custom font to embed; nil for standard fonts

	// RunLines holds per-line styled fragments for Text with inline runs (nested
	// styled <Text>/<Link>/<Tspan>). When non-empty the renderer paints these
	// instead of the flat Lines; Lines still carries the plain text per line for
	// pagination height math.
	RunLines [][]RunFragment
}

TextInfo is the resolved text content and typography for a Text box, ready to paint. Exactly one font source is set: BaseFont (a standard-14 font name) for standard fonts, or EmbeddedFont for a registered custom font.

Jump to

Keyboard shortcuts

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