deprecate old Component approach rather than removing it

Author: sanity

api/kweb-core.api

@@ -1720,6 +1720,10 @@ public final class kweb/routing/RouteReceiver {
 	public final fun path (Ljava/lang/String;Lkotlin/jvm/functions/Function2;)V
 }
 
+public abstract interface class kweb/state/AdvancedComponent {
+	public abstract fun render (Lkweb/ElementCreator;)Ljava/lang/Object;
+}
+
 public final class kweb/state/CloseReason {
 	public fun <init> (Ljava/lang/String;Ljava/lang/Throwable;)V
 	public synthetic fun <init> (Ljava/lang/String;Ljava/lang/Throwable;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
@@ -1734,6 +1738,10 @@ public final class kweb/state/CloseReason {
 	public fun toString ()Ljava/lang/String;
 }
 
+public abstract interface class kweb/state/Component : kweb/state/AdvancedComponent {
+	public abstract fun render (Lkweb/ElementCreator;)V
+}
+
 public class kweb/state/KVal : java/lang/AutoCloseable {
 	public fun <init> (Ljava/lang/Object;)V
 	public final fun addListener (Lkotlin/jvm/functions/Function2;)J
@@ -1853,6 +1861,7 @@ public final class kweb/state/RenderHandle {
 
 public final class kweb/state/RenderKt {
 	public static final fun closeOnElementCreatorCleanup (Lkweb/ElementCreator;Lkweb/state/KVal;)V
+	public static final fun render (Lkweb/ElementCreator;Lkweb/state/AdvancedComponent;)Ljava/lang/Object;
 	public static final fun render (Lkweb/ElementCreator;Lkweb/state/KVal;Lkotlin/jvm/functions/Function2;)Lkweb/state/RenderFragment;
 }
 

src/main/kotlin/kweb/components/Component.kt

@@ -0,0 +1,9 @@
+package kweb.components
+
+import kweb.ElementCreator
+
+/**
+ * Typealias for [ElementCreator] to simply create and manage components using an
+ * extension function
+ */
+typealias Component = ElementCreator<*>

src/main/kotlin/kweb/state/render.kt

@@ -125,10 +125,46 @@ fun ElementCreator<*>.closeOnElementCreatorCleanup(kv: KVal<*>) {
 }
 
 /**
- * Typealias for [ElementCreator] to simply create and manage components using an
- * extension function
+ * Render the value of a [KVar] into DOM elements, and automatically re-render those
+ * elements whenever the value changes.
+ */
+@Deprecated("Use kweb.components.Component instead, see: https://docs.kweb.io/book/components.html")
+fun <PARENT_ELEMENT_TYPE : Element, RETURN_TYPE> ElementCreator<PARENT_ELEMENT_TYPE>.render(
+    component: AdvancedComponent<PARENT_ELEMENT_TYPE, RETURN_TYPE>
+) : RETURN_TYPE {
+    return component.render(this)
+}
+
+
+/**
+ * [AdvancedComponent]s can be rendered into DOM elements by calling [AdvancedComponent.render].
+ *
+ * Unlike [Component], [AdvancedComponent]s allows the parent element type to be configured, and a return
+ * type to be specified.
  */
-typealias Component = ElementCreator<*>
+@Deprecated("Use kweb.components.Component instead, see: https://docs.kweb.io/book/components.html")
+interface AdvancedComponent<in PARENT_ELEMENT_TYPE : Element, out RETURN_TYPE> {
+
+    /**
+     * Render this [Component] into DOM elements, returning an arbitrary
+     * value of type [RETURN_TYPE].
+     */
+    fun render(elementCreator: ElementCreator<PARENT_ELEMENT_TYPE>) : RETURN_TYPE
+}
+
+/**
+ * [Component]s can be rendered into DOM elements by calling [Component.render].
+ *
+ * For more flexibility, see [AdvancedComponent].
+ */
+@Deprecated("Use kweb.components.Component instead, see: https://docs.kweb.io/book/components.html")
+interface Component : AdvancedComponent<Element, Unit> {
+
+    /**
+     * Render this [Component] into DOM elements
+     */
+    override fun render(elementCreator: ElementCreator<Element>)
+}
 
 class RenderFragment(val startId: String, val endId: String) {
     private val deletionListeners = ArrayList<() -> Unit>()

src/test/kotlin/kweb/docs/components.kt

@@ -2,6 +2,7 @@ package kweb.docs
 
 import kweb.*
 import kweb.InputType.text
+import kweb.components.Component
 import kweb.state.*
 import kweb.util.json