layout

type Align int

type Area struct {
	// Width is the available horizontal space in PDF points.
	Width float64
	// Height is the remaining vertical space on the current page in PDF points.
	Height float64
}

type Block struct {
	// X and Y are the position of this block within its parent coordinate space,
	// measured in PDF points from the top-left corner.
	X, Y float64
	// Width and Height are the block's dimensions in PDF points.
	Width, Height float64
	// Draw is the rendering closure. It captures all layout data needed to
	// emit PDF content and calls Renderer methods when invoked.
	Draw func(r Renderer)
	// Children holds nested blocks, enabling a recursive block tree for
	// PDF/UA tagged PDF structure (P, H1, Table, etc.).
	Children []Block
	// Tag is the PDF structure element tag (e.g. "P", "H1", "Table", "TD").
	// Empty string means untagged.
	Tag string
	// AltText is the accessibility alternative text for images and figures.
	AltText string
	// Links contains clickable regions within this block.
	Links []LinkArea
	// contains filtered or unexported fields
}

type BorderEdges struct {
	// Top is the top border.
	Top BorderSide
	// Right is the right border.
	Right BorderSide
	// Bottom is the bottom border.
	Bottom BorderSide
	// Left is the left border.
	Left BorderSide
}

type BorderSide struct {
	// Width is the border line width in PDF points.
	Width float64
	// Color is the border line color.
	Color Color
}

type Box struct {
	// Children are the contained elements laid out according to Direction.
	Children []Element
	// Direction controls whether children stack vertically or horizontally.
	Direction Direction
	// Style contains typographic and box-model properties.
	Style Style
	// Width is the explicit width of the box. Auto means use available width.
	Width Value
	// Height is the explicit height of the box. Auto means content-driven.
	Height Value
}

type Color struct {
	// R is the red component in [0, 1].
	R float64
	// G is the green component in [0, 1].
	G float64
	// B is the blue component in [0, 1].
	B float64
}

type ColumnDef struct {
	// Width specifies the column width using Value units.
	// UnitAuto means the column sizes itself to its content.
	// UnitFr distributes the remaining space fractionally.
	Width Value
}

type Direction int

type Edges struct {
	// Top is the top edge value.
	Top Value
	// Right is the right edge value.
	Right Value
	// Bottom is the bottom edge value.
	Bottom Value
	// Left is the left edge value.
	Left Value
}

type Element interface {
	PlanLayout(area Area) Plan
}

type FontRef struct {
	// Family is the font family name (e.g. "Helvetica", "Inter", "Times New Roman").
	Family string
	// Weight selects the font weight within the family.
	Weight FontWeight
	// Style selects the font style (normal or italic/oblique).
	Style FontStyle
}

type FontResolver interface {
	// MeasureString returns the width of text rendered at the given font and size,
	// in PDF points. It must NOT include trailing whitespace width.
	MeasureString(font FontRef, text string, size float64) float64
	// LineHeight returns the total line height (ascender + descender + leading)
	// for the given font and size, in PDF points.
	LineHeight(font FontRef, size float64) float64
	// Ascender returns the ascender height above the baseline for the given
	// font and size, in PDF points.
	Ascender(font FontRef, size float64) float64
	// Descender returns the magnitude of the descender below the baseline
	// for the given font and size, in PDF points. Always a positive value.
	Descender(font FontRef, size float64) float64
	// LineBreak splits text into lines that each fit within maxWidth points
	// when rendered at the given font and size. It wraps at word boundaries
	// where possible; it may split mid-word only when a single word exceeds
	// maxWidth. Returns at least one element even for empty text.
	LineBreak(font FontRef, text string, size float64, maxWidth float64) []string
}

type FontStyle int

type FontWeight int

type LinkArea struct {
	// X and Y are the offset from the parent Block's top-left corner.
	X, Y float64
	// Width and Height define the clickable region.
	Width, Height float64
	// URL is the target of the hyperlink.
	URL string
}

type Measurable interface {
	// MinWidth returns the minimum width the element can occupy without
	// losing content (e.g. width of the longest unbreakable word).
	MinWidth() float64
	// MaxWidth returns the width the element would occupy if given
	// unlimited horizontal space (e.g. full text on one line).
	MaxWidth() float64
}

type MockFontResolver struct{}

type PageDef struct {
	// Size is the physical page dimensions in PDF points.
	Size Size
	// Margins is the spacing between the page edge and the content area.
	Margins Edges
	// Header contains elements rendered at the top of every page.
	// The header is laid out with unlimited height to measure it, then
	// subtracted from the body area.
	Header []Element
	// Footer contains elements rendered at the bottom of every page.
	Footer []Element
	// Content contains the main body elements to paginate.
	Content []Element
}

type PageLayout struct {
	// Size is the physical page dimensions in PDF points.
	Size Size
	// Blocks contains all content blocks for this page, with coordinates
	// measured from the top-left corner of the page.
	Blocks []Block
}

type PageNumber struct {
	// Format is the format string. Use PageNumberPlaceholder and
	// TotalPagesPlaceholder as substitution markers.
	// Example: PageNumberPlaceholder + " / " + TotalPagesPlaceholder
	Format string
	// Style controls the appearance of the page number text.
	Style Style
	// Fonts is the font resolver.
	Fonts FontResolver
}

type Paginator struct {
	// Fonts is the font resolver used by all layout operations.
	// If nil, MockFontResolver is used (suitable for tests).
	Fonts FontResolver
}

type Plan struct {
	// Status indicates how much content fit in the available area.
	Status Status
	// Consumed is the vertical space used by this plan in PDF points.
	Consumed float64
	// Blocks holds the positioned, ready-to-render content atoms.
	Blocks []Block
	// Overflow carries the portion of the element that did not fit.
	// It is nil when Status == Full.
	Overflow Element
}

type Renderer interface {
	// DrawText renders a text string at the given position using the
	// specified font, size, and color with optional decoration options.
	DrawText(text string, x, y float64, font FontRef, size float64, color Color, options TextDrawOptions)
	// DrawRect renders a filled and/or stroked rectangle.
	DrawRect(x, y, width, height float64, fill *Color, stroke *Color, strokeWidth float64)
	// DrawLine renders a line segment.
	DrawLine(x1, y1, x2, y2 float64, color Color, width float64)
	// DrawImage renders image data (PNG, JPEG) scaled to the given bounds.
	DrawImage(data []byte, x, y, width, height float64)
	// PushState saves the current graphics state.
	PushState()
	// PopState restores the most recently saved graphics state.
	PopState()
	// SetClipRect defines a rectangular clipping region.
	SetClipRect(x, y, width, height float64)
}

type ResolvedEdges struct {
	// Top is the top edge in points.
	Top float64
	// Right is the right edge in points.
	Right float64
	// Bottom is the bottom edge in points.
	Bottom float64
	// Left is the left edge in points.
	Left float64
}

type RichText struct {
	// Fragments is the ordered sequence of inline text segments. Each fragment
	// carries its own style (font, size, color, decoration). Together they form
	// a single paragraph.
	Fragments []RichTextFragment
	// Align controls horizontal alignment for every line in the paragraph.
	Align Align
	// LineHeight is a multiplier applied to the tallest font size on each line
	// to compute the line's vertical extent. Defaults to 1.2 when zero.
	LineHeight float64
	// Fonts is the font resolver used for measurement. When nil, the internal
	// mock approximation (0.5 * fontSize per character) is used.
	Fonts FontResolver
}

type RichTextFragment struct {
	// Text is the content of this fragment.
	Text string
	// Style controls the typographic and decorative properties of this fragment.
	// FontSize, Font, Color, Bold, Italic, Underline, and Strikethrough are all
	// honored at the fragment level.
	Style Style
	// URL, when non-empty, makes the fragment a hyperlink. The renderer will
	// record this as a LinkArea on the containing Block.
	URL string
}

type Size struct {
	// Width in PDF points.
	Width float64
	// Height in PDF points.
	Height float64
}

type Status int

type Style struct {

	// Font identifies the typeface to use for text within this element.
	Font FontRef
	// FontSize is the text size in PDF points. Defaults to 12 when zero.
	FontSize float64
	// Color is the foreground text color.
	Color Color
	// Background is the optional fill color for the element's background.
	// Nil means transparent.
	Background *Color
	// TextAlign controls horizontal text alignment within the element.
	TextAlign Align

	// LineHeight is a multiplier applied to FontSize to compute inter-line
	// spacing. A value of 1.2 (20% leading) is the default.
	LineHeight float64
	// LetterSpacing adds extra spacing between characters in PDF points.
	LetterSpacing float64

	// Margin is the space outside the border, separating this element from
	// adjacent elements.
	Margin Edges
	// Padding is the space inside the border, between the border and content.
	Padding Edges
	// Border defines the four border sides.
	Border BorderEdges

	// Bold applies bold weight to the font. Overrides Font.Weight.
	Bold bool
	// Italic applies italic style to the font. Overrides Font.Style.
	Italic bool
	// Underline adds an underline decoration to text.
	Underline bool
	// Strikethrough adds a strikethrough decoration to text.
	Strikethrough bool

	// KeepWithNext prevents a page break between this element and the next
	// sibling element.
	KeepWithNext bool
	// KeepTogether prevents this element from being split across pages.
	// If the element does not fit on the current page, it is pushed to the
	// next page as a whole. If it does not fit on a fresh page either, it
	// is placed anyway (forced layout).
	KeepTogether bool

	// VerticalAlign controls how content is aligned vertically within its
	// container (applies to table cells and columns).
	VerticalAlign VAlign
}

type Table struct {
	// Columns defines the width specification for each column.
	// The number of entries here determines the column count.
	Columns []ColumnDef
	// Header rows are placed at the top of every page (repeated on overflow).
	Header []TableRow
	// Body rows form the main content; they split across pages.
	Body []TableRow
	// Footer rows are placed at the bottom of every page.
	Footer []TableRow
	// Style is applied to the whole table (background, border).
	Style Style
	// Fonts is the font resolver used by cell content measurement.
	// If nil, the MockFontResolver approximation is used.
	Fonts FontResolver
}

type TableCell struct {
	// Content is the list of elements rendered inside the cell.
	// Cells support any Element (Text, nested Table, Image, etc.).
	Content []Element
	// ColSpan is the number of columns this cell spans. 1 is normal.
	ColSpan int
	// RowSpan is the number of rows this cell spans. 1 is normal.
	RowSpan int
	// Style provides cell-level styling: padding, border, background, vertical align.
	Style Style
}

type TableRow struct {
	// Cells is the ordered list of cells in this row.
	Cells []TableCell
	// Style applies row-level styling (background color).
	Style Style
}

type Text struct {
	// Content is the text string to lay out. Newlines are treated as hard breaks.
	Content string
	// Style controls typography, alignment, and box-model properties.
	Style Style
	// Fonts is the font resolver used for measurement and line breaking.
	// If nil, an internal approximation is used.
	Fonts FontResolver
}

type TextDrawOptions struct {
	// LetterSpacing adds extra spacing between each character in points.
	LetterSpacing float64
	// WordSpacing adds extra spacing between words in points (used for justification).
	WordSpacing float64
	// Underline requests an underline decoration.
	Underline bool
	// Strikethrough requests a strikethrough decoration.
	Strikethrough bool
}

type Unit int

type VAlign int

type Value struct {
	// Amount is the numeric quantity in the specified Unit.
	Amount float64
	// Unit specifies how Amount should be interpreted.
	Unit Unit
}