From b2db71d95c8bfe8ebe4ff78f77334a1cfcf7f4b2 Mon Sep 17 00:00:00 2001
From: Ian Clarke <ian.clarke@gmail.com>
Date: Thu, 24 Nov 2022 19:52:08 -0600
Subject: [PATCH] deprecate old Component approach rather than removing it

---
 api/kweb-core.api                            |  9 +++++
 src/main/kotlin/kweb/components/Component.kt |  9 +++++
 src/main/kotlin/kweb/state/render.kt         | 42 ++++++++++++++++++--
 src/test/kotlin/kweb/docs/components.kt      |  1 +
 4 files changed, 58 insertions(+), 3 deletions(-)
 create mode 100644 src/main/kotlin/kweb/components/Component.kt

diff --git a/api/kweb-core.api b/api/kweb-core.api
index eb3acf48c6..f8873603dc 100644
--- a/api/kweb-core.api
+++ b/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;
 }
 
diff --git a/src/main/kotlin/kweb/components/Component.kt b/src/main/kotlin/kweb/components/Component.kt
new file mode 100644
index 0000000000..60683ef316
--- /dev/null
+++ b/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<*>
\ No newline at end of file
diff --git a/src/main/kotlin/kweb/state/render.kt b/src/main/kotlin/kweb/state/render.kt
index 00732323aa..d2f7c2e18d 100755
--- a/src/main/kotlin/kweb/state/render.kt
+++ b/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>()
diff --git a/src/test/kotlin/kweb/docs/components.kt b/src/test/kotlin/kweb/docs/components.kt
index 168aa98513..df87c3c181 100644
--- a/src/test/kotlin/kweb/docs/components.kt
+++ b/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