types.go

// Package quarto generates EPUB3 files and converts them to Kobo kepub. It is a
// Go port of the @voidberg/quarto TypeScript library.
package quarto

import (
	"context"
	"net/http"
)

// RawImage is an image as bytes plus its MIME type.
type RawImage struct {
	Data []byte
	Mime string
}

// ImageTransform is a hook run on each fetched image (and the cover source)
// after download, before the core-media-type check, so it can transcode,
// resize or drop (return nil, nil) the image.
type ImageTransform func(ctx context.Context, img RawImage) (*RawImage, error)

// CoverMeta is the book metadata handed to a CoverTransform.
type CoverMeta struct {
	Title  string
	Author string
}

// CoverTransform builds the final cover after the source image has been
// downloaded and transformed. It is called even when there is no cover source
// (cover == nil), so it can compose a cover from metadata alone. Return
// (nil, nil) for no cover.
type CoverTransform func(ctx context.Context, cover *RawImage, meta CoverMeta) (*RawImage, error)

// Chapter is one content document.
type Chapter struct {
	// Title is used in the nav/TOC and rendered as the page <h1> heading.
	Title string
	// HTML is the chapter body fragment. It need not be well-formed; it is
	// parsed and re-serialized to valid XHTML.
	HTML string
	// Author, when set, renders as a byline under the title heading.
	Author string
	// ExcludeFromToc keeps the chapter in the spine (reading order) but omits
	// it from the nav doc and NCX.
	ExcludeFromToc bool
	// SkipTitle omits the auto-generated <h1> heading (and author line).
	SkipTitle bool
}

// Input describes one book. Zero values pick the quarto defaults.
type Input struct {
	// Title is the required book title.
	Title string
	// Authors is zero or more dc:creator values.
	Authors     []string
	Publisher   string
	Description string
	// Language is a BCP-47 tag; defaults to "en".
	Language string
	// ID is the unique book id; defaults to a deterministic urn:uuid derived
	// from title and authors.
	ID string
	// CoverURL is a remote cover image to download; CoverData supplies raw
	// bytes instead. CoverData wins when both are set.
	CoverURL  string
	CoverData []byte
	// CoverFromLeadImage promotes the first chapter's leading image (one that
	// appears before any text) to the cover and removes it from the body, but
	// only when no explicit cover is given.
	CoverFromLeadImage bool
	// IncludeToc controls the visible TOC page; quarto defaults to true, so
	// this field is inverted to keep the zero value meaning "default".
	NoToc bool
	// TocTitle defaults to "Table of Contents".
	TocTitle string
	// CoverBackground is a CSS color filling the letterbox bands around the
	// cover page.
	CoverBackground string
	// CSS overrides the bundled stylesheet; NoCSS ships none at all.
	CSS   string
	NoCSS bool
	// NoDownloadImages skips fetching: every non-data: <img> is dropped.
	NoDownloadImages bool
	// Date is an ISO-8601 publication date.
	Date string
	// Series and SeriesIndex emit both EPUB3 belongs-to-collection and legacy
	// calibre:series metadata. SeriesIndex is a pointer because 0 is valid.
	Series      string
	SeriesIndex *float64
	// Client is used for image downloads; defaults to http.DefaultClient.
	Client *http.Client
	// TransformImage and TransformCover are optional hooks; see their types.
	TransformImage ImageTransform
	TransformCover CoverTransform

	Chapters []Chapter
}