render

type CodeLookup func(key string) (html string, ok bool)

type EditInfo struct {
	PageID     int64
	Slug       string // "" identifies the home page (not deletable)
	AdminPath  string
	CSRFToken  string
	Locale     string
	Status     string // "draft" or "published"
	Visibility string // "public" or "private" — who may view the page
	// HasUnpublished is true when a published page's draft content
	// differs from what is live — the editor shows "Unpublished changes"
	// and keeps Publish available.
	HasUnpublished bool
	MediaEnabled   bool
	// IsAdmin unlocks admin-only editor chrome (the page CSS & JS
	// panel); the server enforces the restriction regardless.
	IsAdmin bool
	// IsSuperadmin lets the new-page dialog offer unlisted page
	// templates and puts the development/production switch in the site
	// settings dialog; the server holds both to the same rule regardless.
	IsSuperadmin bool
	// CanPages, CanBlogs, and CanNews unlock the editor's cross-page
	// chrome: new page, menu editing, and site settings need pages;
	// creating a post needs its feed. The server enforces every one of
	// these regardless — the flags only decide what the UI offers.
	CanPages bool
	CanBlogs bool
	CanNews  bool
	// PostsEnabled shows the tool rail's "New post" button (blog & news
	// configured on the host).
	PostsEnabled bool
	// Locales is the site's configured locale list ([0] = default); more
	// than one entry shows the edit bar's locale switcher.
	Locales []string
	// Post, set when the page backs a post, enables the edit bar's
	// post-settings gear (date, summary, thumbnail, header image).
	Post     *PostInfo
	Styles   []EditorStyle  // entries for the editor's Styles menu
	Sections *SectionStyles // options for section settings
}

type EditorStyle struct {
	Label string `json:"label"`
	Class string `json:"class"`
	// Block applies the style to the whole surrounding block, converted
	// to this element ("p", "h2", ...). Empty applies the style inline
	// to the selected text.
	Block string `json:"block,omitempty"`
	// Group nests the entry in a submenu with this title. Entries
	// sharing a Group are folded together; the submenu sits where its
	// first member appears, among any ungrouped top-level entries.
	// Empty keeps the entry at the top level.
	Group string `json:"group,omitempty"`
}

type FeedPage struct {
	Feed  string     // "blog" or "news"
	Posts []PostInfo // this page's posts, newest first
	Pager
}

type Input struct {
	Page   *content.Page
	Blocks []content.Block
	// Shared holds the site's shared-region blocks — what {{cmsShared}}
	// renders. They are the same on every page, so they arrive alongside
	// the page's own rather than being looked up per region.
	Shared []content.Block
	Locale string
	Menus  map[string][]MenuEntry
	// Edit produces the editable variant of the page; see EditInfo. Nil
	// for a plain public render.
	Edit *EditInfo
	// Post is set when the page backs a blog or news post; it becomes the
	// template dot's .Post.
	Post *PostInfo
	// Posts feeds {{cmsPosts}} and {{cmsFeed}} on listing templates. Nil
	// makes both funcs return nothing.
	Posts PostLister
	// PostsPerPage sizes a {{cmsFeed}} page. Zero uses
	// DefaultPostsPerPage; a template may override it per listing.
	PostsPerPage int
	// PageNumber is the listing page this request asked for (?page=N).
	// Zero and below mean the first page, and so does a number past the
	// end — {{cmsFeed}} clamps it to a page that exists.
	PageNumber int
	// PageURL builds the URL of listing page n, for {{cmsFeed}}'s
	// prev/next and numbered links. Nil falls back to a bare "?page=n",
	// which is right for a render with no request behind it.
	PageURL func(n int) string
	// Locales is the site's configured locale list ([0] = default), for
	// {{cmsLocales}} and hreflang links. Nil or single-entry disables
	// both.
	Locales []string
	// BaseURL ("scheme://host", no trailing slash) makes hreflang
	// alternate links absolute; empty omits them.
	BaseURL string
	// Site is the stored site-wide settings ({{cmsBrand}}, {{cmsSiteName}}, nav
	// alignment). The zero value means "all defaults".
	Site content.SiteSettings
	// AdminPath is the URL prefix the admin area is mounted at, used to
	// build the optional "Log in" nav link (Site.LoginInNav). Empty
	// disables the link even when the setting is on.
	AdminPath string
	// CodeSnippets resolves the custom-code blocks a page references —
	// the admin-written markup-and-JavaScript kept out of page content
	// so the HTML sanitizer never has to carry it. Nil leaves the
	// placeholders alone, and so, in effect, does an edit render: it
	// fills them, but with every <script> parked under InertScriptType,
	// so nothing executes and the editor still saves back the
	// placeholder it was given.
	CodeSnippets CodeLookup
	// Funcs replaces the host template functions declared at construction
	// (NewWithFuncs) for this render, entry by entry: a name it does not
	// carry keeps the declared implementation. This is how a host binds
	// its functions to the request — a database query wants the request's
	// context, and a locale-aware one wants Locale — without the renderer
	// having to know what a request is.
	//
	// Only names the constructor declared can actually be called: the
	// templates were parsed against that set, so a name appearing here
	// for the first time is unreachable. Reserved cms* names are ignored.
	Funcs template.FuncMap
}

type LocaleLink struct {
	Code   string // e.g. "en", "fr"
	URL    string // this page in that locale, e.g. "/fr/about"
	Active bool   // the locale of the current render
}

type MenuEntry struct {
	ID       int64 // menu item id; the editor's edit-mode marker
	Label    string
	URL      string // empty for a dropdown parent (label-only)
	NewTab   bool
	Active   bool        // this entry links to the page being rendered
	External bool        // absolute http(s) URL rather than a site page
	Children []MenuEntry // one level of dropdown items
}

type NoticeStyle struct {
	Key   string `json:"key"`
	Label string `json:"label"`
}

type PageData struct {
	Title string
	// Description is the page's description, which on a post is its
	// summary — the words its listing card and feed entry show.
	Description string
	// MetaDescription is what cmsHead publishes to search engines: the
	// page's own meta description when it has one, otherwise
	// Description. Templates need it only to do something else with the
	// same words; the meta tag itself comes from cmsHead.
	MetaDescription string
	Slug            string
	Locale          string
	// Post is set when the page is a blog or news post's backing page —
	// the post template reads its date, author, and images from here.
	// Nil on ordinary pages.
	Post *PostInfo
}

type PageLink struct {
	Number   int
	URL      string
	Current  bool
	Ellipsis bool
}

type PageTemplate struct {
	File     string `json:"file"`
	Label    string `json:"label"`
	Unlisted bool   `json:"unlisted,omitempty"`
}

type Pager struct {
	Page    int // 1-based, always within [1, TotalPages]
	PerPage int
	// Total is the list's full length and TotalPages how many pages that
	// makes. TotalPages is at least 1, so an empty list is one empty page
	// rather than a list with no pages at all.
	Total      int
	TotalPages int
	// PrevURL and NextURL are the adjacent pages, empty at either end.
	PrevURL string
	NextURL string
	// Links is the numbered bar: every page in a short list, and in a
	// long one the ends, the pages around the current one, and ellipses
	// for the gaps.
	Links []PageLink
	// PrevLabel and NextLabel caption the end buttons. NewPager writes
	// English; a caller with a translator to hand overwrites them (the
	// admin does, since its UI is bilingual).
	PrevLabel string
	NextLabel string
}

type PostImages func(md *media.Media, prefer string) *media.Image

type PostInfo struct {
	ID          int64  // post id, for the editor's settings API
	Feed        string // "blog" or "news"
	Title       string
	Summary     string
	URL         string // site-relative, e.g. "/blog/launch-day"
	PublishedAt time.Time
	// Author is the byline to print: empty when the post has none, and
	// equally empty when the post is set to publish without one, so
	// {{with .Author}} is all a template needs for either.
	Author string
	// HideAuthor is that setting, and AuthorName the name behind it —
	// the recorded author whether or not it is shown. Templates want
	// .Author; these two are for the editor's settings gear, which has
	// to name the byline it is offering to switch off.
	HideAuthor bool
	AuthorName string

	// Thumbnail is the post's listing image with every rendition resolved
	// — src, srcset, and intrinsic size — and is nil when the post has
	// none. Prefer it to the bare URL: a listing card that uses
	// .Thumbnail gets an image sized for a card, where .ThumbnailURL
	// alone leaves the browser to download a full-width one and scale it
	// down. A post's banner is not here — it is a section in the post
	// template's header region.
	Thumbnail *media.Image
	// ThumbnailURL is that image's default src, for templates that want
	// one string. "" when the post has no thumbnail.
	ThumbnailURL string
	// The library id behind it, 0 when the image is external or unset.
	// The in-place editor's post-settings dialog round-trips it.
	ThumbnailMediaID int64

	Draft bool // only ever true on editor renders
}

type PostLister func(feed string, limit, offset int, count bool) (posts []PostInfo, total int)

type Region struct {
	Name string
	Kind string // "text", "html", "image", "sections", or "shared"
}

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

type SectionOption struct {
	Key          string `json:"key"`
	Label        string `json:"label"`
	Class        string `json:"class"`
	ContentClass string `json:"contentClass,omitempty"`
}

type SectionStyles struct {
	Backgrounds []SectionOption `json:"backgrounds"`
	Widths      []SectionOption `json:"widths"`
	Corners     []SectionOption `json:"corners"`

	// Paddings is the vertical breathing room around a section's
	// content, as its own axis.
	//
	// It is separate from Widths because they answer different
	// questions, and bundling them — the obvious shortcut, since a width
	// preset is already a class string and can just carry a py-* — makes
	// one unanswerable: "the same measure, but tighter" then has no
	// expression except a second width option, and the option list
	// multiplies by every spacing anyone wants.
	//
	// It is also separate from the height setting, which is a min-height
	// and can only ever make a section taller. An editor looking for less
	// space reaches for height first, finds "Auto" already selected, and
	// concludes the CMS cannot do it.
	//
	// Optional: a nil list leaves sections exactly as they render today,
	// so hosts that keep their padding in the width presets are
	// unaffected. When set, the first entry is the default for content
	// saved before the axis existed — make it match whatever padding the
	// width presets used to carry, and nothing shifts.
	Paddings []SectionOption `json:"paddings"`

	// Sizes is the section's text size, as its own axis: one setting
	// that scales the whole section's typography — headings, body,
	// lists, and their leading together — rather than a size picker on
	// every element.
	//
	// That framing is the point. Font size is the one control where
	// per-element freedom reliably produces worse pages than no control
	// at all: a paragraph bumped two steps beside headings the theme
	// set does not read as emphasis, it reads as broken. Scaling the
	// container keeps the ratios the theme chose and moves everything
	// with them, so the worst an editor can do is a section that is
	// bigger or smaller — never one that is internally inconsistent.
	//
	// The default classes are Tailwind Typography's size modifiers,
	// which is why they go on the content container: it is the element
	// the width presets already put prose on, and a modifier with no
	// prose beside it styles nothing. A host whose widths don't carry
	// prose wants its own list here — container-level text-* classes,
	// or nothing.
	//
	// Optional, and the first entry is the default that content saved
	// before the axis existed resolves to, so it must contribute no
	// class: unlike spacing, there is no size the old markup was
	// implicitly carrying, and anything else moves every published
	// section the moment the axis appears.
	Sizes []SectionOption `json:"sizes"`
}