diff --git a/README.md b/README.md index 801c4c4..30d789e 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# typed-htmx-go +# typed-htmx-go/hx Well-documented Go functions for building [HTMX](https://htmx.org) attributes. @@ -9,10 +9,90 @@ Well-documented Go functions for building [HTMX](https://htmx.org) attributes. However, when using it I constantly have to have the [docs](https://htmx.org/reference) open, to look up the specifics of each modifier. I wanted the simplicity of HTMX, the editor support of Go, and beautiful integration with Templ, without sacrificing performance. I built typed-htmx-go. -typed-htmx-go provides a builder struct that wraps all documented [HTMX attributes](https://htmx.org/reference/) with Go functions, and `.Build()` returns a map that conforms to [templ.Attributes](https://templ.guide/syntax-and-usage/attributes). This allows the result to be spread into a Templ element or be passed to a Templ component. However this library has no actual dependency of Templ, and can be used by anything that can render a `map[string]any` to HTML attributes. You can also use `.String()` to get a formatted string of HTML attributes to directly render in a template. +`hx` provides a builder struct that wraps all documented [HTMX attributes](https://htmx.org/reference/) with Go functions, and `.Build()` returns a map that conforms to [templ.Attributes](https://templ.guide/syntax-and-usage/attributes). This allows the result to be spread into a Templ element or be passed to a Templ component. However this library has no actual dependency of Templ, and can be used by anything that can render a `map[string]any` to HTML attributes. You can also use `.String()` to get a formatted string of HTML attributes to directly render in a template. Each function and option includes a Godoc comment copied from the extensive HTMX docs, so you can access that documentation right from the comfort of your editor. +## Goals + +The project has some specific goals that drive the API. + +### Complete HTMX attribute support + +Every documented HTMX attribute and modifier should have a corresponding Go function. If we're missing something please submit an issue or a PR! And in the meantime, you can always drop back to a raw HTML attribute. + +### No stringly-typed options + +Many HTMX attributes (like hx-swap and hx-trigger) support a complex syntax of methods, modifiers, and selectors in the attribute string (like `hx-trigger='click[isActive] consume from:(#parent > #child) queue:first target:#element'`). + +That's necessary for a tool that embeds in standard HTML attributes, but it requires a lot of studying the docs to get exactly right. + +`hx` strives to provide function signatures and typed options that ensure you're passing the right options to the right modifiers. + +Sometimes that means that `hx` will provide multiple functions for a single attribute. For instance, `hx-target` has three methods to stop you from doing `hx-target='this #element'` (which is invalid), and instead guide you towards valid options like: + +- `hx-target="#element'` (`.Target("#element")`) +- `hx-target='this'` (`.TargetNonStandard(hx.TargetThis)`) +- `hx-target='next #element'` (`.TargetRelative(hx.TargetSelectorNext, "#element")`) + +As a corollary to this goal, it should also be difficult to create an invalid attribute. So if modifier must be accompanied by a selector (like the `next` in `hx-target`), then it must be exposed through a two argument function. + +### Full documentation in-editor + +The [HTMX References](https://htmx.org/reference/) are through and readable (otherwise this project wouldn't have been possible!) However, having those great docs at your fingertips as you write, instead of in a separate tab, is even better. + +`hx` strives to have a Go-adjusted copy of every line of documentation from the HTMX References, including examples, included in the godocs of functions and options. + +Note: This work is on going. If you see something missing, please submit a PR! + +### Transferable HTMX skills + +As much as possible, it should be the case that if you know HTMX, you can use `hx`, and using `hx` should prepare you to use raw HTMX. That means that attributes functions should match their true HTMX counterparts, arguments should match names in the docs, and arguments should occur in the order they are printed in the HTML. + +This also means that written `hx` attributes should look like HTMX attributes. So if in HTMX you would write: + +```html +
+``` + +The `hx` equivalent should take the same names and values in the same order: + +```go +