dom

type CSSRenderer interface {
	Component
	RenderCSS() string
}

type Component interface {
	// HandlerName returns the unique identifier of the component's root element.
	HandlerName() string

	// RenderHTML returns the full HTML string of the component.
	// The root element of this HTML MUST have the id returned by HandlerName().
	RenderHTML() string
}

type DOM interface {
	// Get retrieves an element by its ID.
	// It uses an internal cache to avoid repeated DOM lookups.
	// Returns the element and a boolean indicating if it was found.
	Get(id string) (Element, bool)

	// Mount injects a component into a parent element.
	// 1. It calls component.RenderHTML()
	// 2. It sets the InnerHTML of the parent element (found by parentID)
	// 3. It calls component.OnMount() to bind events
	Mount(parentID string, component Component) error

	// Unmount removes a component from the DOM (by clearing the parent's HTML or removing the node)
	// and cleans up any event listeners registered via the Element interface.
	Unmount(component Component)

	// Log provides logging functionality using the log function passed to New.
	Log(v ...any)
}

type Element interface {

	// SetText sets the text content of the element.
	// Accepts variadic arguments that are concatenated without spaces.
	//
	// Examples:
	//   elem.SetText("Count: ", 42)              // -> "Count: 42"
	//   elem.SetText(D.Hello, " ", D.User)       // -> "Hello User" (localized)
	SetText(v ...any)

	// SetHTML sets the inner HTML of the element.
	// Accepts variadic arguments that are concatenated without spaces.
	// Supports format strings with % specifiers.
	//
	// Examples:
	//   elem.SetHTML("<div>", "content", "</div>")  // -> "<div>content</div>"
	//   elem.SetHTML("<h1>%v</h1>", 42)             // -> "<h1>42</h1>"
	//   elem.SetHTML("<span>%L</span>", D.Hello)    // -> "<span>Hello</span>" (localized)
	SetHTML(v ...any)

	// AppendHTML adds HTML to the end of the element's content.
	// Useful for adding items to a list without re-rendering the whole list.
	// Accepts variadic arguments that are concatenated without spaces.
	//
	// Examples:
	//   elem.AppendHTML("<li>", item, "</li>")
	//   elem.AppendHTML("<div class='%s'>%v</div>", "item", count)
	AppendHTML(v ...any)

	// Remove removes the element from the DOM.
	Remove()

	// AddClass adds a CSS class to the element.
	AddClass(class string)

	// RemoveClass removes a CSS class from the element.
	RemoveClass(class string)

	// ToggleClass toggles a CSS class.
	ToggleClass(class string)

	// SetAttr sets an attribute value.
	// Accepts variadic arguments that are concatenated without spaces.
	//
	// Examples:
	//   elem.SetAttr("id", "item-", 42)           // -> id="item-42"
	//   elem.SetAttr("href", "/page/", pageNum)   // -> href="/page/5"
	//   elem.SetAttr("title", D.Hello)            // -> title="Hello" (localized)
	SetAttr(key string, v ...any)

	// GetAttr retrieves an attribute value.
	GetAttr(key string) string

	// RemoveAttr removes an attribute.
	RemoveAttr(key string)

	// Value returns the current value of an input/textarea/select.
	Value() string

	// SetValue sets the value of an input/textarea/select.
	// Accepts variadic arguments that are concatenated without spaces.
	//
	// Examples:
	//   elem.SetValue("default value")
	//   elem.SetValue("Item ", 42)                // -> "Item 42"
	SetValue(v ...any)

	// Click registers a click event handler.
	// The handler is automatically tracked and removed when the component is unmounted.
	Click(handler func(event Event))

	// On registers a generic event handler (e.g., "change", "input", "keydown").
	On(eventType string, handler func(event Event))

	// Focus sets focus to the element.
	Focus()
}

type Event interface {
	// PreventDefault prevents the default action of the event.
	PreventDefault()
	// StopPropagation stops the event from bubbling up the DOM tree.
	StopPropagation()
	// TargetValue returns the value of the event's target element.
	// Useful for input, textarea, and select elements.
	TargetValue() string
	// TargetID returns the ID of the event's target element.
	TargetID() string
}

type JSRenderer interface {
	Component
	RenderJS() string
}