htmxsurface

package
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 4, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func StripNameModifiers added in v0.1.23

func StripNameModifiers(name string) string

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 HeaderDef

type HeaderDef struct {
	Kind   Kind     `json:"kind"`
	Values []string `json:"values,omitempty"`
}

HeaderDef describes an HX-* response header's value grammar.

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.

func (*NameError) Error added in v0.1.23

func (e *NameError) Error() string

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

func ForVersion(version string) (*Surface, error)

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

func (s *Surface) AcceptsOnPrefix(prefix string) bool

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

func (s *Surface) AttributeNames() []string

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

func (s *Surface) EventRename(event string) (string, bool)

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

func (s *Surface) ExtensionSwapStyles() []string

ExtensionSwapStyles returns the swap styles shipped extensions add.

func (*Surface) Family added in v0.1.23

func (s *Surface) Family() string

Family returns the label of the version family ("2.0", "4.0").

func (*Surface) HasNameModifiers added in v0.1.23

func (s *Surface) HasNameModifiers() bool

HasNameModifiers reports whether the family accepts attribute-name modifiers (:inherited, :append), which is also the signal that attribute inheritance is explicit.

func (*Surface) HtmxEventNames

func (s *Surface) HtmxEventNames() []string

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

func (s *Surface) Introduced(name string) (version string, ok bool)

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

func (s *Surface) IssuesRequest(base string) bool

IssuesRequest reports whether the named attribute (by base name) makes its element issue requests.

func (*Surface) KnownExtension

func (s *Surface) KnownExtension(name string) bool

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

func (s *Surface) Migration(name string) (Migration, bool)

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

func (s *Surface) NameModifiers() []string

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) Removed

func (s *Surface) Removed(name string) (version string, ok bool)

Removed returns the version that removed the named attribute, if any.

func (*Surface) RemovedEvent added in v0.1.23

func (s *Surface) RemovedEvent(event string) (string, bool)

RemovedEvent reports advice for an htmx event a previous family had and this one dropped.

func (*Surface) RemovedPrefixHint added in v0.1.23

func (s *Surface) RemovedPrefixHint(name string) (string, bool)

RemovedPrefixHint reports migration advice for an attribute name a previous family accepted through an extension prefix (hx-target-404).

func (*Surface) ResponseHeader

func (s *Surface) ResponseHeader(name string) (HeaderDef, bool)

ResponseHeader looks up an HX-* response header definition.

func (*Surface) Suggest

func (s *Surface) Suggest(name string) []string

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

func (s *Surface) SwapModifierNames() []string

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

func (s *Surface) SwapStyleAliases() map[string]string

SwapStyleAliases returns the alias swap styles of this surface mapped to their canonical style (htmx 4: before → beforebegin, …).

func (*Surface) SwapStyles

func (s *Surface) SwapStyles() []string

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

func (s *Surface) ValidateCombination(attrs []string) []Conflict

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.

func (*Surface) Version

func (s *Surface) Version() string

Version returns the resolved htmx version.

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL