htmlbind

type ActionRef struct {
	// Component is the declaration the reference appears in.
	Component string
	// Handler is the Go function name the attribute named.
	Handler string
	// Element is the element carrying the attribute, such as form or button.
	Element string
	// Pos is the attribute position, for a diagnostic that can quote the source.
	Pos Position
}

type Annotation = syntax.Annotation

type Asset struct {
	Kind AssetKind
	// Base is the file name without its extension.
	Base string
	// Extension is css for a stylesheet and js for a script, without a dot.
	Extension string
	Content   []byte
	// URL is the reference written into the emitted link or script tag.
	URL string
}

type AssetKind string

type Attribute struct {
	Kind    string          `json:"kind"`
	Pos     Position        `json:"pos"`
	Name    string          `json:"name"`
	Boolean bool            `json:"boolean,omitempty"`
	Value   []AttributePart `json:"value,omitempty"`
}

type AttributePart struct {
	Kind       string   `json:"kind"`
	Pos        Position `json:"pos"`
	Context    string   `json:"context,omitempty"`
	Text       string   `json:"text,omitempty"`
	Expression Expr     `json:"expression,omitempty"`
}

type AwaitBinding = syntax.AwaitBinding

type AwaitNode = syntax.AwaitNode

type BinaryExpr = syntax.BinaryExpr

type Body = []Node

type BuiltinElement struct {
	// Name is the bare kebab-case element name an author writes.
	Name string
	// Params are the declared attributes, in the order a diagnostic lists them.
	Params []ElementParam
	// Context is the rule:template-context-safety insertion context this element
	// may appear in. Empty means html:child.
	Context string
	// Placement is the region that owns it. A head-only element written in the
	// body is a generation error rather than a page that half works.
	Placement ElementPlacement
	// Vary names the request properties this element's output depends on, such
	// as a cookie its provider reads.
	//
	// It is declared rather than derived, because only the implementation knows
	// what its provider reads. An undeclared axis is an invisible dependency: a
	// caller cannot build a Vary header for it and a shared cache cannot key on
	// it, and neither can find out by looking at the template.
	Vary []string
	// Assets are the static files this element requires. They join the required
	// set of every component that writes it, and their reference tags join its
	// head.
	Assets []Asset
	// Shape is how the output is produced. Empty means BuiltinMarkup.
	Shape BuiltinShape
	// Markup is the fixed output template. A hole is written {{.Name}} and names
	// either a declared parameter or a field of the provider's result; {{.}} is
	// the whole provider result, for a provider returning a bare value.
	//
	// Each hole is escaped for its position, and generation refuses a hole
	// anywhere but element text and an attribute value. That is what makes the
	// output unable to inject markup even if a provider returns hostile bytes.
	Markup string
	// Provider supplies the per-request holes. Nil means the element has none,
	// and then it costs nothing at render time: with no expression parameter
	// either, the whole thing folds into static bytes.
	Provider *ElementProvider
}

type BuiltinShape string

type CSRFMode string

type CallExpr = syntax.CallExpr

type CommentNode struct {
	Kind string   `json:"kind"`
	Pos  Position `json:"pos"`
	Text string   `json:"text"`
}

type CompileError struct {
	Filename string
	Pos      Position
	Message  string
}

type ComponentNode struct {
	Kind        string      `json:"kind"`
	Pos         Position    `json:"pos"`
	Name        string      `json:"name"`
	Arguments   []Attribute `json:"arguments,omitempty"`
	Children    []Node      `json:"children,omitempty"`
	SelfClosing bool        `json:"selfClosing,omitempty"`
}

type ConditionalExpr = syntax.ConditionalExpr

type ConversionInputs struct {
	// Sources are the authored files the conversion reads. Their contents are
	// digested into the cache key, and they are recorded as build inputs, so an
	// edit to one both invalidates the cached result and regenerates.
	Sources []string
	// Params is everything else the output depends on: the target format, the
	// quality setting, the version of the encoder doing the work. Anything left
	// out here is something a cache hit will silently ignore.
	Params string
}

type Declaration = syntax.Declaration

type DoctypeNode struct {
	Kind string   `json:"kind"`
	Pos  Position `json:"pos"`
	Text string   `json:"text"`
}

type DynamicReference struct {
	Hook      string
	Element   string
	Attribute string
	Pos       Position
}

type ElementNode struct {
	Kind        string      `json:"kind"`
	Pos         Position    `json:"pos"`
	Name        string      `json:"name"`
	Attributes  []Attribute `json:"attributes,omitempty"`
	Children    []Node      `json:"children,omitempty"`
	SelfClosing bool        `json:"selfClosing,omitempty"`
}

type ElementParam struct {
	// Name is the attribute an author writes, in kebab-case.
	Name string
	// Type is the template type name: string, int, bool, and the rest of the
	// core types.
	Type string
	// Required refuses a call site that leaves the attribute unset.
	Required bool
}

type ElementPlacement string

type ElementProvider struct {
	// Package is the import path of the package holding the function. Empty
	// means the generated package's own.
	Package string
	// Alias overrides the import name. Empty uses the last path segment.
	Alias string
	// Name is the function.
	Name string
	// Result names its first result type, qualified the same way. It is needed
	// because a hole closure has to be written down, and Go infers a call's type
	// arguments but never a function literal's parameter types.
	//
	// For a single-hole element whose provider returns a bare value rather than
	// a struct, this is that value's type and the hole is written {{.}}.
	Result string
}

type EnumDecl = syntax.EnumDecl

type EnumMember = syntax.EnumMember

type Expr = syntax.Expr

type ExpressionNode = syntax.ExpressionNode

type ExternalDecl = syntax.ExternalDecl

type Field = syntax.Field

type ForNode = syntax.ForNode

type GenerateOptions struct {
	// Package overrides the template package/module declaration.
	Package string
	// DataAttributePrefix names the generated update protocol data attributes.
	// Empty uses DefaultDataAttributePrefix.
	DataAttributePrefix string
	// Unit names the generation unit whose assets are extracted. Empty derives
	// it from the template file name.
	Unit string
	// PublicURLBase prefixes generated asset file names in head references.
	// Empty uses DefaultPublicURLBase. The value is used verbatim, so an
	// absolute URL path and a full CDN URL behave the same.
	PublicURLBase string
	// ContextExternals names the external functions whose Go implementation
	// takes a leading context.Context. Those calls receive the boundary's
	// context; every other external is called as an ordinary function.
	//
	// The caller discovers this by reading the package's Go sources, so the
	// template declaration stays the same either way and the choice belongs to
	// whoever writes the implementation.
	ContextExternals map[string]bool
	// PreserveWhitespace turns off requirement:static-whitespace-normalization,
	// so static output keeps the authoring indentation and newlines byte for
	// byte. It exists for a project comparing generated markup against
	// pre-existing golden files.
	PreserveWhitespace bool
	// ServerActions maps each handler name a template reaches through
	// ServerActionAttr to the endpoint URL the lowering writes. The caller
	// resolves it, because the URL depends on the route the template serves and
	// the compiler cannot see that; [ActionRefs] reports what needs resolving.
	//
	// A reference with no entry here is a compile error, so a template naming a
	// handler nobody resolved never silently emits a dead element.
	ServerActions map[string]string
	// ServerActionResolver answers a name ServerActions does not hold. It is what
	// lets a framework address a handler from its own route table, for a template
	// that sits outside the tree route discovery walks.
	//
	// The map wins, so configuring a resolver cannot retarget an action a
	// discovered package already declares.
	ServerActionResolver func(name string) (url string, ok bool)
	// ServerActionAttr is the attribute the lowering writes. Empty uses
	// [DefaultActionAttr]. A framework driving an existing client library points
	// it at that library's vocabulary, such as hx-post.
	ServerActionAttr string
	// ReferenceHooks rewrite the static values of the attributes they are
	// registered for, before analysis and before asset extraction, and declare
	// the conversions those rewrites depend on. They are how a build converts a
	// file the template points at, such as an image to a modern format or a
	// TypeScript entry point to JavaScript, without this package holding a
	// converter or a naming rule.
	//
	// A hook converts and returns the bytes, so it may decide the rewrite from
	// how the conversion turned out. A hook declaring a CacheKey lets the caller
	// reuse a stored result instead of converting again.
	//
	// Registering none leaves output byte-identical.
	ReferenceHooks []ReferenceHook
	// CSRFMode turns the automatic CSRF field off. Empty is [CSRFAuto], which
	// puts the hidden field in every unsafe form.
	CSRFMode CSRFMode
	// CSRFFieldName renames the hidden field. Empty uses
	// [DefaultCSRFFieldName]. It has to agree with whatever middleware reads the
	// token back out.
	CSRFFieldName string
	// BuiltinElements are the hyphenated elements a framework contributes, each
	// rewritten at generation time into plan steps. See [BuiltinElement].
	BuiltinElements []BuiltinElement
	// PassthroughElements are the hyphenated elements an application uses and
	// this package emits verbatim: its Web Components, named exactly or by a
	// prefix glob such as "sl-*".
	//
	// Registering neither leaves the hyphenated space closed and empty, so every
	// hyphenated element in a template is a generation error naming the file,
	// line, and column. That is the one behavior change for an existing project,
	// and it is the point: an unrecognized hyphenated element emitted unchanged
	// renders nothing and reports nothing.
	PassthroughElements []PassthroughElement
	// StrictReferenceHooks turns an expression-valued attribute at a registered
	// element and attribute pair into a compile error. It is off by default,
	// because a project may legitimately mix authored references with
	// user-supplied ones; [Result.DynamicReferences] reports them either way.
	StrictReferenceHooks bool
}

type HeadEntry struct {
	// Element is link, script, or style. Nothing else is accepted: a hook
	// naming a title, a base, or a meta charset would be rewriting the document
	// rather than loading what it produced.
	Element string
	// Attributes are the attribute values, keyed by name. A value is written as
	// a static attribute and escaped for its own position, so a transform hands
	// over a plain URL and never a pre-escaped one.
	Attributes map[string]string
}

type HeadNode struct {
	Kind     string   `json:"kind"`
	Pos      Position `json:"pos"`
	Children []Node   `json:"children,omitempty"`
}

type HookError struct {
	Hook    string
	Message string
}

type IdentifierExpr = syntax.IdentifierExpr

type IfNode = syntax.IfNode

type ImportDecl = syntax.ImportDecl

type IndexExpr = syntax.IndexExpr

type LiteralExpr = syntax.LiteralExpr

type MemberExpr = syntax.MemberExpr

type Module = syntax.Module

type Node = syntax.Node

type PackageDecl = syntax.PackageDecl

type Parameter = syntax.Parameter

type ParseError = syntax.ParseError

type PassthroughElement struct {
	Name string
}

type Position = syntax.Position

type ProducedFile struct {
	// Name is the file name relative to the output root. It may carry directory
	// separators and may not escape the root.
	Name string
	// MediaType is what the file should be served as, or empty.
	MediaType string
	Content   []byte
}

type ReferenceHook struct {
	// Name identifies the hook in diagnostics and in the rewrite report.
	Name string
	// Element is the exact lowercase element name, such as img. A hyphenated
	// name is out of scope: that space belongs to the builtin element
	// whitelist.
	Element string
	// Attribute is the exact attribute name, such as src.
	Attribute string
	// Match reports whether this hook claims a static value. A nil Match claims
	// every static value written at the pair.
	Match func(value string) bool
	// CacheKey names what a conversion of this value depends on, cheaply and
	// without converting anything. A caller holding a store of previous results
	// uses it to answer without calling Transform at all.
	//
	// A nil CacheKey means every build converts, which is correct and slow.
	//
	// The key is only as honest as what it names: an encoder upgrade that no
	// Params string mentions serves stale bytes, and that is the caller's to
	// state because only the caller knows what its converter depends on.
	CacheKey func(ReferenceRequest) (ConversionInputs, error)
	// Transform converts one claimed value and returns both the rewrite and the
	// files it produced, so the rewrite may depend on how the conversion turned
	// out.
	//
	// It is called once per distinct value in the template module being
	// compiled, so a file referenced twenty times on one page is converted once.
	// One module is the widest scope this package has, since it compiles them
	// one at a time; a caller compiling several wraps the transform in its own
	// memo, which is what the generator does.
	//
	// It must be a pure function of what it reads plus its own settings. The
	// file and position on a request are for a diagnostic; deciding an output
	// from them breaks that contract, and any cache built on CacheKey with it.
	//
	// It is called from one goroutine unless the caller asks for more: the
	// generator converts ahead of its compile when configured to, and calls
	// several transforms at once when it does. Being pure is necessary and not
	// sufficient for that - a transform holding a shared scratch buffer is pure
	// by the definition above and unsafe by this one - which is why the caller
	// opts in rather than getting concurrency by default.
	Transform func(ReferenceRequest) (ReferenceResult, error)
}

type ReferenceRequest struct {
	// Hook is the name of the hook that claimed the value.
	Hook string
	// Element and Attribute are the pair that matched.
	Element   string
	Attribute string
	// Value is the attribute value exactly as the template writes it.
	Value string
	// File and Pos locate the first occurrence, for a diagnostic the transform
	// returns.
	File string
	Pos  Position
}

type ReferenceResult struct {
	// Value replaces the attribute value. It is ignored when Skip is set.
	Value string
	// Skip leaves the attribute exactly as written.
	Skip bool
	// Reason explains a skip in the rewrite report.
	Reason string
	// Files are the files this conversion produced. They may outnumber the
	// rewrite: a source map is produced and no attribute names it.
	Files []ProducedFile
	// Read lists files the transform read beyond the sources its CacheKey
	// named, such as the modules a TypeScript entry point imports. What is
	// named by neither is not hashed, and an edit to it will not regenerate.
	Read []string
	// Head declares tags the component's head needs because of this conversion.
	//
	// A rewrite replaces one attribute on an element that already exists, so a
	// conversion producing a file nothing names has no way to get it loaded: a
	// TypeScript entry point importing a CSS module emits a companion
	// stylesheet, and no rewritten src can introduce its link. That is what
	// this is for.
	//
	// An entry joins the contributions of the component whose template held the
	// matched attribute, after everything that component's author wrote, so a
	// component rendered on one page in forty contributes to that page only. A
	// skip contributes nothing, because a conversion that declined produced no
	// file to load.
	Head []HeadEntry
}

type Result struct {
	GoSource []byte
	Assets   []Asset
	// Produced holds the files the hooks' conversions created, sorted by name.
	// They may outnumber the rewrites, because a conversion may write a file no
	// attribute names, and the caller writes them so they join the run's
	// declared outputs rather than appearing behind it.
	Produced []ProducedFile
	// Rewrites reports what the hooks did, including what they declined and
	// why. A build-time rewrite is invisible in the template, so the build is
	// the only place it can be seen.
	Rewrites []Rewrite
	// ReadSet lists the files the transforms reported reading beyond the sources
	// their cache keys named. What is named by neither is not hashed, and an
	// edit to it will not regenerate.
	ReadSet []string
	// DynamicReferences are the attributes a hook was registered for whose
	// value is an expression, and so could not be rewritten.
	DynamicReferences []DynamicReference
}

type Rewrite struct {
	Hook      string
	Element   string
	Attribute string
	// From is the authored value and To is what replaced it. To equals From for
	// a skip.
	From string
	To   string
	// Occurrences counts the attributes this one conversion rewrote. A transform
	// call count is a count of distinct values, not of elements.
	Occurrences int
	// Skipped and Reason report a declined rewrite.
	Skipped bool
	Reason  string
	// Pos is the first occurrence in the template.
	Pos Position
}

type Signature struct {
	// Name is the declaration name as written in the template.
	Name string
	// Exported reports the export modifier.
	Exported bool
	// Parameters are in declaration order.
	Parameters []SignatureParam
}

type SignatureParam struct {
	// Name is the parameter name as written in the template.
	Name string
	// GoType is the Go type of the generated parameter struct field. An async
	// parameter is already wrapped, so it reads htmlbind.Pending[T].
	GoType string
	// TemplateType is the type as written in the template, kept for diagnostics
	// that should quote the source rather than its lowering.
	TemplateType string
	// Async marks a parameter the caller settles through htmlbind.Pending.
	Async bool
	// Slot marks an html parameter, which a wrapper fills rather than a caller
	// passing data.
	Slot bool
}

type SlotNode struct {
	Kind     string   `json:"kind"`
	Pos      Position `json:"pos"`
	Name     string   `json:"name,omitempty"`
	Required bool     `json:"required,omitempty"`
	Default  []Node   `json:"default,omitempty"`
}

type TemplateDecl = syntax.TemplateDecl

type TextNode struct {
	Kind string   `json:"kind"`
	Pos  Position `json:"pos"`
	Text string   `json:"text"`
}

type TypeDecl = syntax.TypeDecl

type TypeRef = syntax.TypeRef

type UnaryExpr = syntax.UnaryExpr