Documentation
¶
Overview ¶
Package ds provides typed helpers for Datastar HTML attributes.
Datastar's parameterized plugins use a colon separator (e.g. data-on:click), NOT a hyphen (data-on-click). A hyphen is silently ignored as an unknown plugin. This package makes that mistake impossible by construction.
Index ¶
- Constants
- Variables
- func Attr(name, expr string) templ.Attributes
- func Bind(signal string) templ.Attributes
- func Class(value string) templ.Attributes
- func ClassToggle(name, expr string) templ.Attributes
- func Computed(name, expr string) templ.Attributes
- func Delete(url string, opts ...ActionOption) string
- func DeleteOnce(url string) string
- func Effect(expr string) templ.Attributes
- func Get(url string, opts ...ActionOption) string
- func GetOnce(url string) string
- func Indicator(name string) templ.Attributes
- func Init(expr string) templ.Attributes
- func Merge(attrs ...templ.Attributes) templ.Attributes
- func On(event, expr string) templ.Attributes
- func OnClick(expr string) templ.Attributes
- func Patch(url string, opts ...ActionOption) string
- func PatchOnce(url string) string
- func Post(url string, opts ...ActionOption) string
- func PostOnce(url string) string
- func Put(url string, opts ...ActionOption) string
- func PutOnce(url string) string
- func Ref(name string) templ.Attributes
- func Show(expr string) templ.Attributes
- func Signals(value string) templ.Attributes
- func Style(prop, expr string) templ.Attributes
- func Text(expr string) templ.Attributes
- type ActionOption
- type DrawerOption
- type Sender
- func (s *Sender) Drawer(sse *datastar.ServerSentEventGenerator, content templ.Component, ...) error
- func (s *Sender) HideDrawer(sse *datastar.ServerSentEventGenerator) error
- func (s *Sender) Toast(sse *datastar.ServerSentEventGenerator, level ToastLevel, message string, ...) error
- func (s *Sender) ToastComponent(sse *datastar.ServerSentEventGenerator, component templ.Component) error
- type ToastLevel
- type ToastOption
Constants ¶
const DrawerContainerID = "drawer-panel"
DrawerContainerID is the fixed ID of the drawer container in the base template.
const ToastContainerID = "toast-container"
ToastContainerID is the fixed ID of the toast container in the base template.
Variables ¶
var Send = &Sender{}
Send provides backend SSE operations (drawer, toast, etc.). Frontend attribute helpers remain as top-level ds.XXX functions.
Functions ¶
func Attr ¶
func Attr(name, expr string) templ.Attributes
Attr returns a data-attr:<name> attribute.
func Class ¶
func Class(value string) templ.Attributes
Class returns a data-class attribute (object syntax).
func ClassToggle ¶
func ClassToggle(name, expr string) templ.Attributes
ClassToggle returns a data-class:<name> attribute (single class toggle).
func Computed ¶
func Computed(name, expr string) templ.Attributes
Computed returns a data-computed:<name> attribute.
func Delete ¶
func Delete(url string, opts ...ActionOption) string
Delete returns a @delete('url') expression with the CSRF token header.
func DeleteOnce ¶
DeleteOnce returns a @delete('url') expression with CSRF but without retries.
func Get ¶
func Get(url string, opts ...ActionOption) string
Get returns a @get('url') expression.
ds.Get("/api/data") // → @get('/api/data')
ds.Get("/api/data", ds.WithRetries(3)) // → @get('/api/data', {retryMaxCount: 3})
func GetOnce ¶
GetOnce returns a @get('url') expression without retries.
ds.GetOnce("/api/data") // → @get('/api/data', {retryMaxCount: 0})
func Indicator ¶
func Indicator(name string) templ.Attributes
Indicator returns a data-indicator:<name> attribute.
func Merge ¶
func Merge(attrs ...templ.Attributes) templ.Attributes
Merge combines multiple templ.Attributes into one. Later values overwrite earlier ones for the same key.
func On ¶
func On(event, expr string) templ.Attributes
On returns a data-on:<event> attribute.
ds.On("click", expr) → {"data-on:click": expr}
func OnClick ¶
func OnClick(expr string) templ.Attributes
OnClick is shorthand for On("click", expr).
func Patch ¶
func Patch(url string, opts ...ActionOption) string
Patch returns a @patch('url') expression with the CSRF token header.
func Post ¶
func Post(url string, opts ...ActionOption) string
Post returns a @post('url') expression with the CSRF token header.
ds.Post("/api/submit") // → @post('/api/submit', {headers: {…}})
ds.Post("/api/submit", ds.WithRetries(5)) // → @post('/api/submit', {headers: {…}, retryMaxCount: 5})
func Put ¶
func Put(url string, opts ...ActionOption) string
Put returns a @put('url') expression with the CSRF token header.
func Signals ¶
func Signals(value string) templ.Attributes
Signals returns a data-signals attribute.
func Style ¶
func Style(prop, expr string) templ.Attributes
Style returns a data-style:<prop> attribute.
Types ¶
type ActionOption ¶
type ActionOption func(*actionConfig)
ActionOption customizes a backend action expression (@get, @post, etc.).
func WithContentType ¶
func WithContentType(ct string) ActionOption
WithContentType sets the content type for the action. Use "form" to send multipart/form-data (file uploads).
func WithRequestCancellation ¶ added in v0.0.14
func WithRequestCancellation(mode string) ActionOption
WithRequestCancellation controls whether other SSE requests cancel this one. Use "disabled" for persistent stream connections that should not be interrupted.
func WithRetries ¶
func WithRetries(n int) ActionOption
WithRetries sets the maximum number of retry attempts. Use 0 to disable retries entirely.
type DrawerOption ¶ added in v0.0.14
type DrawerOption func(*drawerConfig)
DrawerOption customizes drawer appearance.
func WithDrawerMaxWidth ¶ added in v0.0.14
func WithDrawerMaxWidth(class string) DrawerOption
WithDrawerMaxWidth sets the panel max-width class (default "max-w-lg").
type Sender ¶ added in v0.0.14
type Sender struct{}
Sender groups backend SSE operations that send events to the browser.
func (*Sender) Drawer ¶ added in v0.0.14
func (s *Sender) Drawer(sse *datastar.ServerSentEventGenerator, content templ.Component, opts ...DrawerOption) error
Drawer renders a templ component inside a slide-in drawer panel and patches it into #drawer-panel via SSE.
func (*Sender) HideDrawer ¶ added in v0.0.14
func (s *Sender) HideDrawer(sse *datastar.ServerSentEventGenerator) error
HideDrawer patches #drawer-panel back to its empty placeholder via SSE. Useful for server-initiated close (e.g. after a form submit inside the drawer).
func (*Sender) Toast ¶ added in v0.0.15
func (s *Sender) Toast(sse *datastar.ServerSentEventGenerator, level ToastLevel, message string, opts ...ToastOption) error
Toast appends a toast notification via SSE. Default behavior: auto-dismiss after 3 seconds with a close button.
func (*Sender) ToastComponent ¶ added in v0.0.15
func (s *Sender) ToastComponent(sse *datastar.ServerSentEventGenerator, component templ.Component) error
ToastComponent appends a custom templ component as a toast via SSE.
type ToastLevel ¶ added in v0.0.15
type ToastLevel string
ToastLevel represents the severity of a toast notification.
const ( ToastInfo ToastLevel = "info" ToastSuccess ToastLevel = "success" ToastWarning ToastLevel = "warning" ToastError ToastLevel = "error" )
type ToastOption ¶ added in v0.0.15
type ToastOption func(*toastConfig)
ToastOption customizes a toast notification.
func WithToastAction ¶ added in v0.0.15
func WithToastAction(label, url string) ToastOption
WithToastAction adds an action button that triggers a Datastar GET. The toast stays until the action or close button is clicked.
func WithToastDuration ¶ added in v0.0.15
func WithToastDuration(ms int) ToastOption
WithToastDuration sets the auto-dismiss duration in milliseconds. Default is 3000ms. Use WithToastPersistent() to disable auto-dismiss.
func WithToastLink ¶ added in v0.0.15
func WithToastLink(text, url string) ToastOption
WithToastLink adds a clickable link to the toast message.
func WithToastPersistent ¶ added in v0.0.15
func WithToastPersistent() ToastOption
WithToastPersistent makes the toast stay until the user clicks the close button.
Source Files