bind

type Binder[T comparable] interface {
	RWLocker
	Setter[T]
	tag.TagGetter
	jaws.ClickHandler
	jaws.ContextMenuHandler
	jaws.InitialHTMLAttrHandler

	JawsGetLocked(elem *jaws.Element) (value T)
	JawsSetLocked(elem *jaws.Element, value T) (err error)

	// JawsInitialHTMLAttrLocked returns the initial HTML attribute while
	// the Binder lock is held.
	JawsInitialHTMLAttrLocked(elem *jaws.Element) (s template.HTMLAttr)

	// SetLocked returns a [Binder] that will call fn instead of [Binder.JawsSetLocked].
	//
	// The lock will be held at this point.
	// Do not lock or unlock the [Binder] within fn. Do not call [Setter.JawsSet].
	//
	// The bind argument to the function is the previous Binder in the chain,
	// and you probably want to call its [Binder.JawsSetLocked] first.
	SetLocked(fn SetHook[T]) (newbind Binder[T])

	// GetLocked returns a [Binder] that will call fn instead of [Binder.JawsGetLocked].
	//
	// The lock will be held at this point, preferring RLock over Lock, if available.
	// Do not lock or unlock the [Binder] within fn. Do not call [Getter.JawsGet].
	//
	// The bind argument to the function is the previous Binder in the chain,
	// and you probably want to call its [Binder.JawsGetLocked] first.
	GetLocked(fn GetHook[T]) (newbind Binder[T])

	// Success returns a [Binder] that will call fn after the value has been set
	// with no errors. No locks are held when the function is called.
	// If the function returns an error, that will be returned from [Setter.JawsSet].
	//
	// The function must have one of the following signatures:
	//  * func()
	//  * func() error
	//  * func(*jaws.Element)
	//  * func(*jaws.Element) error
	Success(fn any) (newbind Binder[T])

	// GetHTML returns a [Binder] that will call fn instead of the default
	// escaped fmt.Sprint(JawsGetLocked(elem)) HTML rendering.
	//
	// The lock will be held at this point, preferring RLock over Lock, if available.
	// Do not lock or unlock the [Binder] within fn. Do not call [Getter.JawsGet].
	//
	// Unlike [Binder.GetLocked] and [Binder.SetLocked], the bind argument to fn is
	// the current Binder, not the previous one; read the value with its
	// JawsGetLocked to render it. See [GetHTMLHook].
	GetHTML(fn GetHTMLHook[T]) (newbind Binder[T])

	// Format returns a [Binder] that implements [HTMLGetter] and
	// calls html.EscapeString on either fmt.Sprintf(format, JawsGetLocked(elem))
	// or, if T implements [Formatter], T.Format(format).
	Format(format string) (newbind Binder[T])

	// Clicked returns a [Binder] that will call fn when [jaws.ClickHandler.JawsClick] is invoked.
	//
	// The [Binder] locks are not held when the function is called.
	Clicked(fn ClickedHook[T]) (newbind Binder[T])

	// ContextMenu returns a [Binder] that will call fn when
	// [jaws.ContextMenuHandler.JawsContextMenu] is invoked.
	//
	// The [Binder] locks are not held when the function is called.
	ContextMenu(fn ContextMenuHook[T]) (newbind Binder[T])

	// InitialHTMLAttr returns a [Binder] that will call fn when
	// [jaws.InitialHTMLAttrHandler.JawsInitialHTMLAttr] is invoked.
	//
	// The lock will be held at this point, preferring RLock over Lock, if available.
	// Do not lock or unlock the [Binder] within fn. Do not call [Getter.JawsGet].
	// To call the previous handler in the chain, call [Binder.JawsInitialHTMLAttrLocked].
	InitialHTMLAttr(fn InitialHTMLAttrHook[T]) (newbind Binder[T])
}

type ClickedHook[T comparable] func(bind Binder[T], elem *jaws.Element, click jaws.Click) (err error)

type ContextMenuHook[T comparable] func(bind Binder[T], elem *jaws.Element, click jaws.Click) (err error)

type Formatter interface {
	Format(string) string
}

type GetHTMLHook[T comparable] func(bind Binder[T], elem *jaws.Element) (s template.HTML)

type GetHook[T comparable] func(bind Binder[T], elem *jaws.Element) (value T)

type Getter[T comparable] interface {
	JawsGet(elem *jaws.Element) (value T)
}

type HTMLGetter interface {
	JawsGetHTML(elem *jaws.Element) template.HTML
}

type InitialHTMLAttrHook[T comparable] func(bind Binder[T], elem *jaws.Element) (s template.HTMLAttr)

type RWLocker interface {
	sync.Locker
	RLock()
	RUnlock()
}

type SetHook[T comparable] func(bind Binder[T], elem *jaws.Element, value T) (err error)

type Setter[T comparable] interface {
	Getter[T]
	// JawsSet may return [jaws.ErrValueUnchanged] to indicate value was already set.
	JawsSet(elem *jaws.Element, value T) (err error)
}

type SuccessHook func(elem *jaws.Element) (err error)