htmxsurface

package
v0.1.16 Latest Latest
Warning

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

Go to latest
Published: Aug 7, 2026 License: Apache-2.0 Imports: 9 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.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

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"`
}

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 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"`
}

Keyword is a value keyword with version metadata (e.g. the "inherit" keyword accepted by hx-include since htmx 2.0.5).

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

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

func (s *Surface) Attribute(name string) (AttributeDef, bool)

Attribute looks up an attribute by name. hx-on:<event> forms (and the dash forms hx-on-<event> / hx-on--<htmx-event>) resolve to the hx-on 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) HtmxEventNames

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

HtmxEventNames returns the kebab-case htmx event names valid in hx-on:: shorthand.

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

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

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

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

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

SwapStyles returns the 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, and enum-valued attributes; token-level checks for trigger; presence-only for JSON-ish kinds (hx-vals, hx-headers, hx-request) 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