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 ConfirmOption
- type DrawerOption
- type ModalOption
- type Sender
- func (s *Sender) Confirm(sse *datastar.ServerSentEventGenerator, message string, confirmURL string, ...) error
- func (s *Sender) Download(sse *datastar.ServerSentEventGenerator, url string, filename string) error
- func (s *Sender) Drawer(sse *datastar.ServerSentEventGenerator, content templ.Component, ...) error
- func (s *Sender) HideDrawer(sse *datastar.ServerSentEventGenerator) error
- func (s *Sender) HideModal(sse *datastar.ServerSentEventGenerator) error
- func (s *Sender) Modal(sse *datastar.ServerSentEventGenerator, content templ.Component, ...) error
- func (s *Sender) Patch(sse *datastar.ServerSentEventGenerator, component templ.Component, ...) error
- func (s *Sender) Redirect(sse *datastar.ServerSentEventGenerator, url string) 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 ModalContainerID = "modal-panel"
ModalContainerID is the fixed ID of the modal 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 ConfirmOption ¶ added in v0.0.16
type ConfirmOption func(*confirmConfig)
ConfirmOption customizes the confirm dialog.
func WithCancelLabel ¶ added in v0.0.16
func WithCancelLabel(label string) ConfirmOption
WithCancelLabel sets the cancel button text (default: "Cancel").
func WithConfirmClass ¶ added in v0.0.16
func WithConfirmClass(class string) ConfirmOption
WithConfirmClass sets the confirm button class (default: "btn btn-primary").
func WithConfirmGet ¶ added in v0.0.18
func WithConfirmGet() ConfirmOption
WithConfirmGet uses GET instead of POST for the confirm action. By default, confirm uses POST with CSRF protection since confirmations typically trigger destructive/mutating operations.
func WithConfirmLabel ¶ added in v0.0.16
func WithConfirmLabel(label string) ConfirmOption
WithConfirmLabel sets the confirm button text (default: "Confirm").
func WithConfirmMaxWidth ¶ added in v0.0.16
func WithConfirmMaxWidth(class string) ConfirmOption
WithConfirmMaxWidth sets the dialog max-width class (default: "max-w-sm").
func WithConfirmTitle ¶ added in v0.0.16
func WithConfirmTitle(title string) ConfirmOption
WithConfirmTitle sets the dialog title (default: "Confirm").
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 ModalOption ¶ added in v0.0.16
type ModalOption func(*modalConfig)
ModalOption customizes modal appearance.
func WithModalMaxWidth ¶ added in v0.0.16
func WithModalMaxWidth(class string) ModalOption
WithModalMaxWidth sets the modal 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) Confirm ¶ added in v0.0.16
func (s *Sender) Confirm(sse *datastar.ServerSentEventGenerator, message string, confirmURL string, opts ...ConfirmOption) error
Confirm shows a confirmation dialog via SSE using the modal container. When the user clicks confirm, it triggers a POST request (with CSRF) to confirmURL. Use WithConfirmGet() to use GET instead. Cancel closes the dialog without any request.
func (*Sender) Download ¶ added in v0.0.16
func (s *Sender) Download(sse *datastar.ServerSentEventGenerator, url string, filename string) error
Download triggers a file download in the browser via SSE without navigating away. It creates a temporary anchor element, triggers a click, and removes it.
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) HideModal ¶ added in v0.0.16
func (s *Sender) HideModal(sse *datastar.ServerSentEventGenerator) error
HideModal patches #modal-panel back to its empty placeholder via SSE. Useful for server-initiated close (e.g. after a form submit inside the modal).
func (*Sender) Modal ¶ added in v0.0.16
func (s *Sender) Modal(sse *datastar.ServerSentEventGenerator, content templ.Component, opts ...ModalOption) error
Modal renders a templ component inside a centered modal dialog and patches it into #modal-panel via SSE.
func (*Sender) Patch ¶ added in v0.0.16
func (s *Sender) Patch(sse *datastar.ServerSentEventGenerator, component templ.Component, opts ...datastar.PatchElementOption) error
Patch renders a templ component and patches it into the DOM via SSE. The component's root element must have an id attribute for Datastar to find the target. Additional options (selector, mode) can be passed through.
func (*Sender) Redirect ¶ added in v0.0.16
func (s *Sender) Redirect(sse *datastar.ServerSentEventGenerator, url string) error
Redirect sends an SSE event that navigates the browser to the given URL. Wraps the Datastar SDK's sse.Redirect() which handles Firefox quirks automatically.
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