package export

import "github.com/carlosframework/docs/internal/pdf"

// PageOne is the geometry of the first page of a document: where every
// line of text actually landed, in points, measured from the top-left
// of the page.
//
// It exists for the document list's thumbnails (internal/docs's
// preview.go); spec §11.4 is where the argument for drawing line boxes
// rather than rasterizing them lives, and it is not repeated here.
//
// Real is the whole point, and it is why this is a sink on the
// exporter's own layout rather than a second, simpler one beside it.
// The line breaking here is done by the same code that breaks lines for
// the PDF, measuring with the same font programs the browser is served,
// against the same page geometry views/show.html sets — so a thumbnail
// shows the document's actual first page, wrapped where it actually
// wraps. A separate estimator ("about sixty characters to a line")
// would have been a second opinion about the document, free to drift
// from the first, and drift is exactly what the list would show.
//
// What is elided, and should be said plainly: the glyphs. This draws
// where the text is, not the text.
//
// This is page one of a PDF of THIS Document, title included — it runs
// the same layout.document PDF does, so whatever the exporter puts on a
// first page is what this reports. A caller that wants the paper
// without the title passes a Document with an empty Title; the document
// list does exactly that, and preview.go says why.
//
// What it bounds is the LAYOUT: stopAfterPage ends that after the first
// page, so a four-hundred-page document costs one page of it. The rest
// of the work is not bounded and it would be wrong to imply otherwise —
// the caller has already replayed and serialised the whole document to
// get here, Parse decodes all of it, and the paragraph in progress is
// measured in full before its first line is drawn. Measured on the seed
// documents, the two halves are the same order: about 0.5-3ms to reach
// the tree and 0.3-2ms to lay the page out.
func PageOne(doc Document) []LineBox {
	var lines []LineBox
	l := &layout{
		b:             pdf.New(PageWidthPt, PageHeightPt),
		missing:       map[rune]bool{},
		stopAfterPage: 1,
		sink:          func(b LineBox) { lines = append(lines, b) },
	}
	l.newPage()
	l.document(doc)
	return lines
}

// LineBox is one laid-out line of text, in points from the top-left of
// the page. It carries no text: a consumer of this is drawing where the
// words are, and the words themselves never leave the layout.
//
// Lines only. A list's bullets and numbers are drawn beside their
// item's first line rather than as lines of their own, so they never
// reach the sink and a list reports as indented lines with no markers.
// At thumbnail scale a marker would be well under a pixel, so this is
// not worth fixing — but it is worth knowing before someone reads a
// list preview as a run of short paragraphs.
//
// That is a property worth keeping rather than an accident. It is what
// lets the document list cache a preview in memory without holding any
// of the document's prose, and it is why a preview built from these is
// not a plaintext derivative of the document (see preview.go's own
// note on what it is, and is not, safe to write down).
type LineBox struct {
	// Left and Top are the top-left corner of the line box. Left
	// already accounts for alignment, list and quote indents — it is
	// where the line starts, not where its column does.
	Left, Top float64

	// Width is the measured width of the text on the line, which for a
	// wrapped line is short of the column and for the last line of a
	// paragraph is usually well short of it. This is what makes a
	// thumbnail read as prose rather than as a solid block.
	Width float64

	// Height is the line box's height — the leading, not the glyphs.
	Height float64

	// Size is the largest type size on the line, in points. A heading
	// reports a bigger one than body text, which lets a drawing
	// consumer weight it accordingly without knowing what a heading is.
	Size float64
}