Documentation
¶
Overview ¶
Package htmxsurface embeds the version-keyed htmx attribute surface set (DATA-006, solution design D8) and provides per-version validation of hx-* attribute names, values, and combinations.
The embedded data is the authority for FR-024, FR-041, FR-044, FR-052, and FR-082. Generation performs no network I/O: the surface set ships inside the binary. An htmx version bump is a data update, not a compiler change: each major line is one family file under data/, and every behaviour that differs between families (attribute-name modifiers, listener prefixes, migration hints) is keyed off fields that are absent from the families that do not have it.
Index ¶
- func StripNameModifiers(name string) string
- func SupportedRanges() []string
- func SupportedVersions() []string
- type AttributeDef
- type Conflict
- type FamilyInfo
- type HeaderDef
- type Keyword
- type Kind
- type Migration
- type NameError
- type NameReason
- type ParsedName
- type Surface
- func (s *Surface) AcceptsOnPrefix(prefix string) bool
- func (s *Surface) Attribute(name string) (AttributeDef, bool)
- func (s *Surface) AttributeNames() []string
- func (s *Surface) Definition(name string) (AttributeDef, bool)
- func (s *Surface) EventRename(event string) (string, bool)
- func (s *Surface) ExtensionSwapStyles() []string
- func (s *Surface) Family() string
- func (s *Surface) HasNameModifiers() bool
- func (s *Surface) HtmxEventNames() []string
- func (s *Surface) Introduced(name string) (version string, ok bool)
- func (s *Surface) IssuesRequest(base string) bool
- func (s *Surface) KnownExtension(name string) bool
- func (s *Surface) Migration(name string) (Migration, bool)
- func (s *Surface) NameModifiers() []string
- func (s *Surface) ParseName(name string) (ParsedName, *NameError)
- func (s *Surface) Removed(name string) (version string, ok bool)
- func (s *Surface) RemovedEvent(event string) (string, bool)
- func (s *Surface) RemovedPrefixHint(name string) (string, bool)
- func (s *Surface) ResponseHeader(name string) (HeaderDef, bool)
- func (s *Surface) Suggest(name string) []string
- func (s *Surface) SwapModifierNames() []string
- func (s *Surface) SwapStyleAliases() map[string]string
- func (s *Surface) SwapStyles() []string
- func (s *Surface) ValidateCombination(attrs []string) []Conflict
- func (s *Surface) ValidateValue(attr string, value string) *ValueError
- func (s *Surface) Version() string
- type ValueError
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func StripNameModifiers ¶ added in v0.1.23
StripNameModifiers removes trailing attribute-name modifiers from name (hx-target:inherited:append → hx-target) without consulting a surface, for passes that run before or without one. Only the modifier words are stripped, so hx-sse:connect and hx-on:… stay whole.
func SupportedRanges ¶ added in v0.1.23
func SupportedRanges() []string
SupportedRanges renders each family's version range for messages and documentation: "2.0.0 – 2.0.10" for a multi-version family, the bare version for a single-version one.
func SupportedVersions ¶
func SupportedVersions() []string
SupportedVersions returns every htmx version the embedded set covers, in ascending order.
Types ¶
type AttributeDef ¶
type AttributeDef struct {
Name string `json:"-"`
Kind Kind `json:"kind"`
Verb string `json:"verb,omitempty"`
Values []string `json:"values,omitempty"`
Inherited bool `json:"inherited,omitempty"`
Deprecated string `json:"deprecated,omitempty"`
Introduced string `json:"introduced,omitempty"`
Removed string `json:"removed,omitempty"`
Prefix bool `json:"prefix,omitempty"`
ExtraKeywords []Keyword `json:"extraKeywords,omitempty"`
// Hint is migration advice for an attribute the family removed or
// whose meaning changed (shown alongside the diagnostic).
Hint string `json:"hint,omitempty"`
// RenamedTo names the attribute that replaced a removed one.
RenamedTo string `json:"renamedTo,omitempty"`
// SuffixPattern is a regular expression the text after "name:" must
// match (hx-status:422, hx-live:disabled). With Prefix set the bare
// name is invalid; without it both the bare and the suffixed forms are.
SuffixPattern string `json:"suffixPattern,omitempty"`
// IssuesRequest marks attributes whose presence means the element
// itself issues requests (verbs, hx-action, hx-boost, hx-ws:send…), so
// its own inheritable attributes are not inheritance.
IssuesRequest bool `json:"issuesRequest,omitempty"`
// RequiresValue rejects the bare boolean form of an attribute whose
// value is required (htmx 4 hx-disable, which was a flag in htmx 2).
RequiresValue bool `json:"requiresValue,omitempty"`
// Extension names the shipped extension that defines the attribute,
// when it is not core htmx.
Extension string `json:"extension,omitempty"`
// contains filtered or unexported fields
}
AttributeDef describes one hx-* attribute for a version family.
type Conflict ¶
type Conflict struct {
Attrs []string `json:"attrs"`
AtMostOne bool `json:"atMostOne,omitempty"`
Message string `json:"message"`
}
Conflict is a mutually incompatible attribute combination (FR-044).
type FamilyInfo ¶ added in v0.1.23
type FamilyInfo struct {
// Name is the family label, e.g. "2.0" or "4.0".
Name string
// Versions are the family's versions in ascending order.
Versions []string
}
FamilyInfo describes one embedded version family.
func Families ¶ added in v0.1.23
func Families() []FamilyInfo
Families returns the embedded version families in ascending order.
type Keyword ¶
type Keyword struct {
Value string `json:"value"`
Introduced string `json:"introduced,omitempty"`
Removed string `json:"removed,omitempty"`
// Hint is the migration advice shown when the keyword was removed.
Hint string `json:"hint,omitempty"`
}
Keyword is a value keyword with version metadata (e.g. the "inherit" keyword accepted by hx-include since htmx 2.0.5, and gone in 4.0).
type Kind ¶
type Kind string
Kind classifies an attribute's value grammar.
const ( KindURL Kind = "url" KindOn Kind = "on" KindBoolOrURL Kind = "bool-or-url" KindSelector Kind = "selector" KindSelectorList Kind = "selector-list" KindSwap Kind = "swap" KindSwapOOB Kind = "swap-oob" KindExtendedSelector Kind = "extended-selector" KindTrigger Kind = "trigger" KindJSON Kind = "json" KindEnum Kind = "enum" KindString Kind = "string" KindFlag Kind = "flag" KindAttrList Kind = "attr-list" KindExtList Kind = "ext-list" KindParams Kind = "params" KindRequest Kind = "request" KindSync Kind = "sync" KindTriggerEvents Kind = "trigger-events" KindURLOrJSON Kind = "url-or-json" // KindStatusConfig is the hx-status:<code> value grammar of htmx 4: // space-separated key:value pairs configuring the swap for one status. KindStatusConfig Kind = "status-config" )
type Migration ¶ added in v0.1.23
type Migration struct {
// RemovedIn is the version that removed the attribute.
RemovedIn string
// RenamedTo is the replacement attribute, when there is a direct one.
RenamedTo string
// Hint is free-form migration advice.
Hint string
}
Migration describes what became of an attribute this version removed.
type NameError ¶ added in v0.1.23
type NameError struct {
Reason NameReason
// Base is the defined attribute the name was resolved against, or the
// whole name when nothing matched.
Base string
// Modifier is the offending modifier or suffix, when there is one.
Modifier string
}
NameError explains why ParseName rejected a name.
type NameReason ¶ added in v0.1.23
type NameReason int
NameReason classifies why an attribute name did not resolve.
const ( // NameUnknown: no definition matches the name. NameUnknown NameReason = iota // NameBarePrefix: a suffixed attribute (hx-on, hx-status) used without // its suffix. NameBarePrefix // NameBadSuffix: the suffix does not match the attribute's grammar // (hx-status:42). NameBadSuffix // NameModifiersUnsupported: the name carries an attribute-name // modifier (:inherited, :append) the configured family does not have. NameModifiersUnsupported // NameUnknownModifier: an attribute-name modifier the family does not // define. NameUnknownModifier // NameModifierNotInheritable: :inherited or :append on an attribute // that does not inherit. NameModifierNotInheritable // NameDuplicateModifier: the same modifier twice. NameDuplicateModifier )
type ParsedName ¶ added in v0.1.23
type ParsedName struct {
// Base is the defined attribute name ("hx-swap", "hx-on", "hx-status",
// "hx-sse:connect").
Base string
// Suffix is the text after the base for suffixed attributes: the event
// of hx-on (":after:swap", "click"), the code of hx-status ("422"), the
// bound attribute of hx-live ("disabled").
Suffix string
// Inherited and Append report the htmx 4 :inherited / :append
// attribute-name modifiers.
Inherited bool
Append bool
}
ParsedName is an attribute name resolved to its definition.
type Surface ¶
type Surface struct {
// contains filtered or unexported fields
}
Surface is the attribute surface of one specific htmx version, resolved from the embedded family data by filtering introduced/removed metadata.
func ForVersion ¶
ForVersion resolves the surface for the given htmx version. A version outside the supported range is an error naming the range (GHTMX-E0502 content contract).
func (*Surface) AcceptsOnPrefix ¶ added in v0.1.23
AcceptsOnPrefix reports whether the family spells hx-on listeners with the given prefix ("hx-on:" always; "hx-on-" only in htmx 2).
func (*Surface) Attribute ¶
func (s *Surface) Attribute(name string) (AttributeDef, bool)
Attribute looks up an attribute by name, resolving hx-on:<event> forms, suffixed attributes, and attribute-name modifiers to their definition. A bare "hx-on" or an empty event suffix is invalid — htmx 2 removed the 1.x hx-on="..." attribute.
func (*Surface) AttributeNames ¶
AttributeNames returns the sorted names of all attributes valid at this version (for completion, FR-082).
func (*Surface) Definition ¶ added in v0.1.23
func (s *Surface) Definition(name string) (AttributeDef, bool)
Definition returns the definition registered under exactly name, with no prefix, suffix, or modifier resolution — for tooling that iterates AttributeNames and needs each entry's metadata (prefix, extension).
func (*Surface) EventRename ¶ added in v0.1.23
EventRename reports the current name of an htmx event a previous family spelled differently (after-swap → after:swap).
func (*Surface) ExtensionSwapStyles ¶ added in v0.1.23
ExtensionSwapStyles returns the swap styles shipped extensions add.
func (*Surface) Family ¶ added in v0.1.23
Family returns the label of the version family ("2.0", "4.0").
func (*Surface) HasNameModifiers ¶ added in v0.1.23
HasNameModifiers reports whether the family accepts attribute-name modifiers (:inherited, :append), which is also the signal that attribute inheritance is explicit.
func (*Surface) HtmxEventNames ¶
HtmxEventNames returns the htmx event names valid in hx-on:: shorthand: kebab-case in htmx 2, colon-separated (after:swap) in htmx 4.
func (*Surface) Introduced ¶
Introduced returns the version that introduced the named attribute, where the embedded metadata records one. ok is false when the attribute is unknown to the family entirely.
func (*Surface) IssuesRequest ¶ added in v0.1.23
IssuesRequest reports whether the named attribute (by base name) makes its element issue requests.
func (*Surface) KnownExtension ¶
KnownExtension reports whether the attribute name is claimed by a known htmx extension. Extension attributes pass name validation; their values are not constrained by the core surface.
func (*Surface) Migration ¶ added in v0.1.23
Migration reports the migration record of an attribute the family knows but this version has removed. ok is false for attributes that are valid, unknown, or merely not yet introduced.
func (*Surface) NameModifiers ¶ added in v0.1.23
NameModifiers returns the attribute-name modifiers of the family.
func (*Surface) ParseName ¶ added in v0.1.23
func (s *Surface) ParseName(name string) (ParsedName, *NameError)
ParseName resolves an attribute name to its definition: an exact name, an hx-on listener, a suffixed attribute (hx-status:422, hx-live:disabled), or a name with attribute-name modifiers (hx-target:inherited, hx-vals:inherited:append). The hot path — an exact name — allocates nothing.
func (*Surface) RemovedEvent ¶ added in v0.1.23
RemovedEvent reports advice for an htmx event a previous family had and this one dropped.
func (*Surface) RemovedPrefixHint ¶ added in v0.1.23
RemovedPrefixHint reports migration advice for an attribute name a previous family accepted through an extension prefix (hx-target-404).
func (*Surface) ResponseHeader ¶
ResponseHeader looks up an HX-* response header definition.
func (*Surface) Suggest ¶
Suggest returns up to three known attribute names closest to the unknown name by edit distance, for did-you-mean diagnostics (FR-024).
func (*Surface) SwapModifierNames ¶
SwapModifierNames returns the hx-swap modifier names of this surface, sorted. The root package's typed modifier constructors are asserted against this set in tests.
func (*Surface) SwapStyleAliases ¶ added in v0.1.23
SwapStyleAliases returns the alias swap styles of this surface mapped to their canonical style (htmx 4: before → beforebegin, …).
func (*Surface) SwapStyles ¶
SwapStyles returns the core hx-swap styles of this surface, in data order. The root package's typed SwapStyle constants are asserted against this set in tests so they cannot drift from the pinned surface.
func (*Surface) ValidateCombination ¶
ValidateCombination checks the attribute names present on one element against the conflict rules (FR-044) and returns every violated rule.
func (*Surface) ValidateValue ¶
func (s *Surface) ValidateValue(attr string, value string) *ValueError
ValidateValue checks a constant attribute value against the attribute's grammar. Only constant values are ever validated: any value containing an interpolated expression is exempt from analysis entirely, mirroring the FR-042 conservatism. A nil return means the value is valid.
Validation depth (MVP): full grammar for swap, sync, params, status configs, and enum-valued attributes; token-level checks for trigger; presence-only for JSON-ish kinds (hx-vals, hx-headers, hx-config — JSON, HCON, and js: forms alike) and free-form kinds.
type ValueError ¶
type ValueError struct {
Message string
// Valid lists the valid values or forms, for the FR-024 message
// contract ("listing the valid values").
Valid []string
}
ValueError describes an invalid constant attribute value.
func (*ValueError) Error ¶
func (e *ValueError) Error() string