bind

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

	// JawsGetLocked returns the bound value while the Binder lock is held.
	//
	// Callers must already hold the lock, preferring the read lock if available;
	// the method does not lock or unlock. It is the value path: it applies this
	// chain's [GetHook]s and never invokes HTML rendering ([GetHTMLHook]), so
	// calling it from within a GetHTMLHook to read the value does not recurse.
	JawsGetLocked(elem *jaws.Element) (value T)

	// JawsSetLocked stores value while the Binder write lock is held.
	//
	// Callers must already hold the write lock; the method does not lock or
	// unlock and must not be called (nor [Setter.JawsSet] called) from within a
	// hook. It applies this chain's [SetHook]s.
	//
	// The [Binder] returned by [New] stores value when it differs from the stored
	// value and returns [jaws.ErrValueUnchanged] otherwise. This comparison may
	// panic unless T is strictly comparable.
	JawsSetLocked(elem *jaws.Element, value T) (err error)

	// JawsInitialHTMLAttrLocked returns the initial HTML attribute while the
	// Binder lock is held.
	//
	// Callers must already hold the lock, preferring the read lock if available;
	// the method does not lock or unlock. It applies this chain's
	// [InitialHTMLAttrHook]s and returns an empty [html/template.HTMLAttr] when no
	// such hook is present anywhere in the chain.
	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 calls fn after a successful set.
	//
	// No locks are held when the function is called.
	// If the function returns an error, that will be returned from [Setter.JawsSet].
	//
	// The dynamic type of fn must be one of the following function types:
	//  * func()
	//  * func() error
	//  * func(*jaws.Element)
	//  * func(*jaws.Element) error
	//
	// [SuccessHook] is an alias for the last function type.
	// A value of a defined function type must be converted to the corresponding
	// function type before it is passed. Success panics if fn has any other
	// dynamic type.
	Success(fn any) (newbind Binder[T])

	// GetHTML returns a [Binder] that will call fn instead of the default
	// escaped [fmt.Sprint] 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 and [Binder.Format] are both HTML-rendering overrides resolved
	// head-first, so when a chain has more than one the most recently added wins
	// and shadows any earlier one.
	GetHTML(fn GetHTMLHook[T]) (newbind Binder[T])

	// Format returns a [Binder] that formats its bound value.
	//
	// With the Binder lock held, it calls [Formatter.Format] when T implements
	// [Formatter], or [fmt.Sprintf] otherwise, then escapes the result with
	// [html.EscapeString].
	//
	// When chained with [Binder.GetHTML], the most recently added rendering
	// override wins.
	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)