render

type Diagnostics struct {
	// Development shows a failing template in detail, with the template and
	// line, on go-partial's ext/errors error page, and makes
	// {{debug .}} show a value (ext/debug). Never in production: there a
	// failing render writes nothing and its caller answers a plain error,
	// unless the renderer has error templates (ErrorPage, ErrorFragment).
	Development bool
	// ErrorPage is a template that answers, outside development, a request
	// whose page failed, such as a theme's 500.gohtml, with status 500 and
	// never cached (go-partial's ext/errors WithTemplate). It renders on its
	// own, without the layout, as a child of the part that failed, with its
	// functions, the view's includes and models; its dot is an ext/errors
	// Data, whose Error it must not show (Data.Detailed is false; its
	// Message is a safe sentence, see ErrorMessage). ErrorFragment is the
	// same for a partial request, such as an HTMX navigation, in the place
	// of the part requested. When only one of them is set, it answers both.
	// When an error template fails itself, go-partial's own error markup
	// answers, without the error's details.
	ErrorPage     string
	ErrorFragment string
	// ErrorFlash, when set, answers a partial request that failed to render,
	// outside development, with an error message of the renderer's exp/flash
	// stage (see Renderer.Use) instead of ErrorFragment: added to the flash
	// target out of band, with the text ErrorFlash returns for the request,
	// leaving the request's own target as it is (go-partial's ext/errors
	// WithFlash). The response keeps status 500, so with HTMX 4 the
	// page lets 5xx responses swap their out-of-band parts only (the
	// clientAttrs "keepOnServerError" setting).
	ErrorFlash func(r *http.Request) string
	// ErrorMessage, when set, returns the text of the safe sentence
	// message (go-partial's ext/errors SafeMessage) for the request, such as
	// its translation in the request's language: the Message of the error
	// templates' Data, also the text of the error flash message when
	// ErrorFlash returns none (go-partial's ext/errors WithMessage). An
	// empty text keeps the sentence.
	ErrorMessage func(r *http.Request, message string) string
	// ErrorTitle, when set, returns the text of the title, the status text
	// of the error (http.StatusText), for the request, such as its
	// translation in the request's language: the heading of go-partial's
	// built-in error page, and the Title of the error templates' Data
	// (go-partial's ext/errors WithTitle). An empty text keeps the status
	// text.
	ErrorTitle func(r *http.Request, title string) string
	// ErrorLanguage, when set, returns the language of the error page for
	// the request, such as the language of the page that failed: the lang
	// attribute of go-partial's built-in error page, and the Lang of the
	// error templates' Data (go-partial's ext/errors WithLang).
	ErrorLanguage func(r *http.Request) string
	// Logger receives go-partial's warnings, such as a function it ignored;
	// nil uses slog.Default at the time of each warning. Errors are returned
	// by Render instead.
	Logger *slog.Logger
	// Stages run in every render, around the templates of the layout, the
	// content and every region, for example go-partial's exp/metrics.
	Stages []partial.RenderStage
	// Events receive go-partial's diagnostic events, for example exp/otel's
	// sink, which adds them to the request's trace span.
	Events []partial.EventSink
}

type Fragment struct {
	ID       string
	Template string
	// Data is the fragment's dot, on the page and on its own.
	Data any
	// Dot, when set, replaces Data, such as a dot computed only when the
	// fragment renders (partial.DotFuncOf): only a request for the fragment
	// pays for its data. A Dot of a known type is checked against the
	// fragment's @dot before it is computed.
	Dot partial.Dot
	// Deferred fragments load after the page, such as a panel whose data is
	// expensive: on the page, {{slot "ID"}} places a placeholder that asks
	// for the fragment from the page's own address as soon as the page
	// loads (go-partial's slots.Deferred), so the page itself never
	// computes the fragment's dot. The default placeholder is an empty
	// element with the fragment's ID. Placeholder, a template of the view's
	// file system, defers the fragment with a placeholder of the site's own,
	// whose dot is a go-partial slots.PlaceholderData and whose outer
	// element carries its ID and Attrs; it has the view's includes.
	Deferred    bool
	Placeholder string
	// PlaceholderData is the placeholder's PlaceholderData.Data, such as
	// the heading of a panel, so one placeholder template serves several
	// fragments (go-partial's slots.Data).
	PlaceholderData any
}

type Region struct {
	ID       string
	Template string
	Files    fs.FS
	Data     any
	// Dot, when set, replaces Data, such as a dot computed only when the
	// region renders; see View.Dot.
	Dot partial.Dot
}

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

type View struct {
	// Template is the content template path.
	Template string
	// Includes are the templates the content, regions and fragments can
	// call, as fs.Glob patterns, such as "partials/*.gohtml" (go-partial's
	// SetChildIncludes on the page); the layout has none. The error
	// templates of Diagnostics get them too.
	Includes []string
	// Files overrides the renderer's file system for the content template.
	Files fs.FS
	// Data is the content template's dot; Shell is the layout's dot.
	Data  any
	Shell any
	// Dot and ShellDot, when set, replace Data and Shell with a go-partial
	// Dot, such as one computed only when the content or the layout renders
	// (partial.DotFuncOf), so a request for a fragment or region alone,
	// which leaves them out, costs nothing of theirs. A Dot given to several
	// parts of the page, such as the layout and its regions, is computed
	// once per response. An error fails the render.
	Dot      partial.Dot
	ShellDot partial.Dot
	// Models are the values templates can name with @model, matched by
	// type: the layout, the content and every partial, as go-partial's
	// SetModel does. A partial.ModelFuncOf is computed only when a template
	// calls it, once per response.
	Models []any
	// ContentID is the element ID HTMX swaps; "content" when empty.
	ContentID string
	// Status is the response status, also of a response for a region or a
	// fragment alone; zero is 200 OK. An error page keeps its own.
	Status int
	// Regions are layout parts updated alongside content, such as a header.
	// An HTMX response sends them out of band in this order, then those of
	// RegionFiles in the order of their file names, the same on every
	// render, so its bytes and ETag are too.
	Regions []Region
	// Fragments are parts of the page HTMX can ask for on their own by ID;
	// see Fragment.
	Fragments []Fragment
	// FragmentRegions sends the regions out of band with a fragment asked
	// for on its own, as with the content, rather than the fragment alone:
	// for a page whose fragments come from a new address, such as the
	// results of a live search that replaces the address while the visitor
	// types, so the head region's title and links and a language switch
	// follow it.
	FragmentRegions bool
	// RegionFiles and FragmentFiles add a region, with the layout's dot, or
	// a fragment, with the content's dot, for every template the fs.Glob
	// pattern finds in the renderer's file system, such as
	// "regions/*.gohtml": named after the file without its extension, such
	// as "menu" for regions/menu.gohtml (go-partial's slots.Glob). With the
	// template cache the files are found once; without (see SetReload), at
	// every render, so new files show.
	RegionFiles   string
	FragmentFiles string
	// RegionElements, by region name, are the IDs of the elements of a
	// region an HTMX request gets out of band instead of the whole region,
	// such as the menu items that change with a navigation (go-partial's
	// SetOOBElements): IDs that are not in the region's output are left
	// out, and when none of them is, the whole region goes. A full page is
	// not affected.
	RegionElements map[string][]string
	// RegionElementsFunc, by region name, chooses those IDs per request,
	// only when the region actually goes out of band (go-partial's
	// SetOOBElementsFunc), and names the request headers the choice
	// depends on, which the response's Vary header then lists. It replaces
	// RegionElements of the same region.
	RegionElementsFunc map[string]func(*http.Request) partial.OOBElements
	// HeadRegion names the region, of Regions or RegionFiles, that the
	// layout places in <head>, such as "head" for regions/head.gohtml
	// with the canonical, alternate and feed links of the page (go-partial's
	// exp/head): on a full page its elements sit between two empty
	// <template> markers, and out of band they replace the elements
	// between those markers, so the head keeps no element of the page
	// left. Its <title> goes on its own, which htmx sets as the document's
	// title.
	HeadRegion string
}