Refactoring. API documentation.

6 files changed, 318 insertions, 40 deletions

diff --git a/src/main/kotlin/pl/treksoft/kvision/html/Button.kt b/src/main/kotlin/pl/treksoft/kvision/html/Button.kt
index bb48558f..874c4182 100644
--- a/src/main/kotlin/pl/treksoft/kvision/html/Button.kt
+++ b/src/main/kotlin/pl/treksoft/kvision/html/Button.kt
@@ -1,13 +1,37 @@
+/*
+ * Copyright (c) 2017-present Robert Jaros
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
 package pl.treksoft.kvision.html
 
 import com.github.snabbdom.VNode
 import org.w3c.dom.events.MouseEvent
 import pl.treksoft.kvision.core.ResString
-import pl.treksoft.kvision.core.Widget
 import pl.treksoft.kvision.core.StringBoolPair
 import pl.treksoft.kvision.core.StringPair
+import pl.treksoft.kvision.core.Widget
 
-enum class BUTTONSTYLE(val className: String) {
+/**
+ * Button styles.
+ */
+enum class BUTTONSTYLE(internal val className: String) {
     DEFAULT("btn-default"),
     PRIMARY("btn-primary"),
     SUCCESS("btn-success"),
@@ -17,46 +41,81 @@ enum class BUTTONSTYLE(val className: String) {
     LINK("btn-link")
 }
 
-enum class BUTTONSIZE(val className: String) {
+/**
+ * Button sizes.
+ */
+enum class BUTTONSIZE(internal val className: String) {
     LARGE("btn-lg"),
     SMALL("btn-sm"),
     XSMALL("btn-xs")
 }
 
+/**
+ * Button component.
+ *
+ * @constructor
+ * @param text button label
+ * @param icon button icon
+ * @param style button style
+ * @param disabled button state
+ * @param classes a set of CSS class names
+ */
 open class Button(
     text: String, icon: String? = null, style: BUTTONSTYLE = BUTTONSTYLE.DEFAULT,
     disabled: Boolean = false, classes: Set<String> = setOf()
 ) : Widget(classes) {
+
+    /**
+     * Button label.
+     */
     var text = text
         set(value) {
             field = value
             refresh()
         }
+    /**
+     * Button icon.
+     */
     var icon = icon
         set(value) {
             field = value
             refresh()
         }
+    /**
+     * Button style.
+     */
     var style = style
         set(value) {
             field = value
             refresh()
         }
+    /**
+     * Determines if button is disabled.
+     */
     var disabled = disabled
         set(value) {
             field = value
             refresh()
         }
+    /**
+     * Button image.
+     */
     var image: ResString? = null
         set(value) {
             field = value
             refresh()
         }
+    /**
+     * Button size.
+     */
     var size: BUTTONSIZE? = null
         set(value) {
             field = value
             refresh()
         }
+    /**
+     * Determines if the button takes all the space horizontally.
+     */
     var block = false
         set(value) {
             field = value
@@ -65,7 +124,7 @@ open class Button(
 
     override fun render(): VNode {
         val t = createLabelWithIcon(text, icon, image)
-        return kvh("button", t)
+        return render("button", t)
     }
 
     override fun getSnClass(): List<StringBoolPair> {
@@ -88,6 +147,9 @@ open class Button(
         return super.getSnAttrs() + ("type" to "button")
     }
 
+    /**
+     * A convenient helper for easy setting onClick event handler.
+     */
     open fun onClick(handler: Button.(MouseEvent) -> Unit): Button {
         this.setEventListener<Button> {
             click = { e ->
diff --git a/src/main/kotlin/pl/treksoft/kvision/html/Image.kt b/src/main/kotlin/pl/treksoft/kvision/html/Image.kt
index 38b8825a..9321b4dc 100644
--- a/src/main/kotlin/pl/treksoft/kvision/html/Image.kt
+++ b/src/main/kotlin/pl/treksoft/kvision/html/Image.kt
@@ -1,49 +1,99 @@
+/*
+ * Copyright (c) 2017-present Robert Jaros
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
 package pl.treksoft.kvision.html
 
 import com.github.snabbdom.VNode
 import pl.treksoft.kvision.core.ResString
-import pl.treksoft.kvision.core.Widget
 import pl.treksoft.kvision.core.StringBoolPair
 import pl.treksoft.kvision.core.StringPair
+import pl.treksoft.kvision.core.Widget
 
-enum class IMAGESHAPE(val className: String) {
+/**
+ * Image shapes.
+ */
+enum class IMAGESHAPE(internal val className: String) {
     ROUNDED("img-rounded"),
     CIRCLE("img-circle"),
     THUMBNAIL("img-thumbnail")
 }
 
+/**
+ * Image component.
+ *
+ * @constructor
+ * @param src image URL
+ * @param alt alternative text
+ * @param responsive determines if the image is rendered as responsive
+ * @param shape image shape
+ * @param centered determines if the image is rendered centered
+ * @param classes a set of CSS class names
+ */
 open class Image(
     src: ResString, alt: String? = null, responsive: Boolean = false, shape: IMAGESHAPE? = null,
     centered: Boolean = false, classes: Set<String> = setOf()
 ) : Widget(classes) {
-    internal var src = src
+    /**
+     * URL of the image.
+     */
+    var src = src
         set(value) {
             field = value
             refresh()
         }
-    private var alt = alt
+    /**
+     * The alternative text of the image.
+     */
+    var alt = alt
         set(value) {
             field = value
             refresh()
         }
-    private var responsive = responsive
+    /**
+     * Determines if the image is rendered as responsive.
+     */
+    var responsive = responsive
         set(value) {
             field = value
             refresh()
         }
-    private var shape = shape
+    /**
+     * The shape of the image.
+     */
+    var shape = shape
         set(value) {
             field = value
             refresh()
         }
-    private var centered = centered
+    /**
+     * Determines if the image is rendered as centered.
+     */
+    var centered = centered
         set(value) {
             field = value
             refresh()
         }
 
     override fun render(): VNode {
-        return kvh("img")
+        return render("img")
     }
 
     override fun getSnAttrs(): List<StringPair> {
diff --git a/src/main/kotlin/pl/treksoft/kvision/html/Label.kt b/src/main/kotlin/pl/treksoft/kvision/html/Label.kt
index 3ce23639..1701150e 100644
--- a/src/main/kotlin/pl/treksoft/kvision/html/Label.kt
+++ b/src/main/kotlin/pl/treksoft/kvision/html/Label.kt
@@ -1,6 +1,31 @@
+/*
+ * Copyright (c) 2017-present Robert Jaros
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
 package pl.treksoft.kvision.html
 
-import pl.treksoft.kvision.html.TAG
-import pl.treksoft.kvision.html.Tag
-
+/**
+ * Simple label component rendered as *span*.
+ *
+ * @constructor
+ * @param text label text
+ * @param rich determines if [text] can contain HTML code
+ */
 open class Label(text: String, rich: Boolean = false) : Tag(TAG.SPAN, text, rich)
diff --git a/src/main/kotlin/pl/treksoft/kvision/html/Link.kt b/src/main/kotlin/pl/treksoft/kvision/html/Link.kt
index 83f03676..ad8897d5 100644
--- a/src/main/kotlin/pl/treksoft/kvision/html/Link.kt
+++ b/src/main/kotlin/pl/treksoft/kvision/html/Link.kt
@@ -1,30 +1,73 @@
+/*
+ * Copyright (c) 2017-present Robert Jaros
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
 package pl.treksoft.kvision.html
 
 import com.github.snabbdom.VNode
 import pl.treksoft.kvision.core.ResString
-import pl.treksoft.kvision.panel.SimplePanel
 import pl.treksoft.kvision.core.StringPair
+import pl.treksoft.kvision.panel.SimplePanel
 
+/**
+ * Link component.
+ *
+ * @constructor
+ * @param label link label
+ * @param url link URL address
+ * @param icon link icon
+ * @param image link image
+ * @param classes a set of CSS class names
+ */
 open class Link(
     label: String, url: String, icon: String? = null, image: ResString? = null,
     classes: Set<String> = setOf()
 ) : SimplePanel(classes) {
-    private var label = label
+    /**
+     * Link label.
+     */
+    var label = label
         set(value) {
             field = value
             refresh()
         }
-    private var url = url
+    /**
+     * Link URL address.
+     */
+    var url = url
         set(value) {
             field = value
             refresh()
         }
-    private var icon = icon
+    /**
+     * Link icon.
+     */
+    var icon = icon
         set(value) {
             field = value
             refresh()
         }
-    private var image = image
+    /**
+     * Link image.
+     */
+    var image = image
         set(value) {
             field = value
             refresh()
@@ -32,7 +75,7 @@ open class Link(
 
     override fun render(): VNode {
         val t = createLabelWithIcon(label, icon, image)
-        return kvh("a", t + childrenVNodes())
+        return render("a", t + childrenVNodes())
     }
 
     override fun getSnAttrs(): List<StringPair> {
diff --git a/src/main/kotlin/pl/treksoft/kvision/html/List.kt b/src/main/kotlin/pl/treksoft/kvision/html/List.kt
index c4aed749..c8252080 100644
--- a/src/main/kotlin/pl/treksoft/kvision/html/List.kt
+++ b/src/main/kotlin/pl/treksoft/kvision/html/List.kt
@@ -1,12 +1,37 @@
+/*
+ * Copyright (c) 2017-present Robert Jaros
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
 package pl.treksoft.kvision.html
 
 import com.github.snabbdom.VNode
 import com.github.snabbdom.h
 import pl.treksoft.kvision.KVManager
-import pl.treksoft.kvision.panel.SimplePanel
+import pl.treksoft.kvision.core.Component
 import pl.treksoft.kvision.core.StringBoolPair
+import pl.treksoft.kvision.panel.SimplePanel
 
-enum class LIST(val tagName: String) {
+/**
+ * HTML list types.
+ */
+enum class LISTTYPE(internal val tagName: String) {
     UL("ul"),
     OL("ol"),
     UNSTYLED("ul"),
@@ -15,21 +40,42 @@ enum class LIST(val tagName: String) {
     DL_HORIZ("dl")
 }
 
+/**
+ * HTML list component.
+ *
+ * The list component can be populated directly from *elements* parameter or manually by adding
+ * any [Component] to the container.
+ *
+ * @constructor
+ * @param type list type
+ * @param elements optional list of elements
+ * @param rich determines if [elements] can contain HTML code
+ * @param classes a set of CSS class names
+ */
 open class ListTag(
-    type: LIST, elements: List<String>? = null, rich: Boolean = false,
+    type: LISTTYPE, elements: List<String>? = null, rich: Boolean = false,
     classes: Set<String> = setOf()
 ) : SimplePanel(classes) {
+    /**
+     * List type.
+     */
     var type = type
         set(value) {
             field = value
             refresh()
         }
-    private var elements = elements
+    /**
+     * List of elements.
+     */
+    var elements = elements
         set(value) {
             field = value
             refresh()
         }
-    private var rich = rich
+    /**
+     * Determines if [elements] can contain HTML code.
+     */
+    var rich = rich
         set(value) {
             field = value
             refresh()
@@ -37,29 +83,31 @@ open class ListTag(
 
     override fun render(): VNode {
         val childrenElements = when (type) {
-            LIST.UL, LIST.OL, LIST.UNSTYLED, LIST.INLINE -> elements?.map { el -> element("li", el, rich) }
-            LIST.DL, LIST.DL_HORIZ -> elements?.mapIndexed { index, el ->
+            LISTTYPE.UL, LISTTYPE.OL, LISTTYPE.UNSTYLED, LISTTYPE.INLINE -> elements?.map { el ->
+                element("li", el, rich)
+            }
+            LISTTYPE.DL, LISTTYPE.DL_HORIZ -> elements?.mapIndexed { index, el ->
                 element(if (index % 2 == 0) "dt" else "dd", el, rich)
             }
         }?.toTypedArray()
         return if (childrenElements != null) {
-            kvh(type.tagName, childrenElements + childrenVNodes())
+            render(type.tagName, childrenElements + childrenVNodes())
         } else {
-            kvh(type.tagName, childrenVNodes())
+            render(type.tagName, childrenVNodes())
         }
     }
 
     override fun childrenVNodes(): Array<VNode> {
         val childrenElements = children.filter { it.visible }
         val res = when (type) {
-            LIST.UL, LIST.OL, LIST.UNSTYLED, LIST.INLINE -> childrenElements.map { v ->
+            LISTTYPE.UL, LISTTYPE.OL, LISTTYPE.UNSTYLED, LISTTYPE.INLINE -> childrenElements.map { v ->
                 if (v is Tag && v.type == TAG.LI) {
                     v.renderVNode()
                 } else {
                     h("li", arrayOf(v.renderVNode()))
                 }
             }
-            LIST.DL, LIST.DL_HORIZ -> childrenElements.mapIndexed { index, v ->
+            LISTTYPE.DL, LISTTYPE.DL_HORIZ -> childrenElements.mapIndexed { index, v ->
                 if (v is Tag && v.type == TAG.LI) {
                     v.renderVNode()
                 } else {
@@ -82,9 +130,9 @@ open class ListTag(
         val cl = super.getSnClass().toMutableList()
         @Suppress("NON_EXHAUSTIVE_WHEN")
         when (type) {
-            LIST.UNSTYLED -> cl.add("list-unstyled" to true)
-            LIST.INLINE -> cl.add("list-inline" to true)
-            LIST.DL_HORIZ -> cl.add("dl-horizontal" to true)
+            LISTTYPE.UNSTYLED -> cl.add("list-unstyled" to true)
+            LISTTYPE.INLINE -> cl.add("list-inline" to true)
+            LISTTYPE.DL_HORIZ -> cl.add("dl-horizontal" to true)
         }
         return cl
     }
diff --git a/src/main/kotlin/pl/treksoft/kvision/html/Tag.kt b/src/main/kotlin/pl/treksoft/kvision/html/Tag.kt
index 11c935b2..557784b0 100644
--- a/src/main/kotlin/pl/treksoft/kvision/html/Tag.kt
+++ b/src/main/kotlin/pl/treksoft/kvision/html/Tag.kt
@@ -1,12 +1,36 @@
+/*
+ * Copyright (c) 2017-present Robert Jaros
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
 package pl.treksoft.kvision.html
 
 import com.github.snabbdom.VNode
 import pl.treksoft.kvision.KVManager
-import pl.treksoft.kvision.panel.SimplePanel
 import pl.treksoft.kvision.core.StringBoolPair
+import pl.treksoft.kvision.panel.SimplePanel
 
+/**
+ * HTML tags.
+ */
 @Suppress("EnumNaming")
-enum class TAG(val tagName: String) {
+enum class TAG(internal val tagName: String) {
     H1("h1"),
     H2("h2"),
     H3("h3"),
@@ -43,6 +67,9 @@ enum class TAG(val tagName: String) {
     LI("li")
 }
 
+/**
+ * CSS align attributes.
+ */
 enum class ALIGN(val className: String) {
     LEFT("text-left"),
     CENTER("text-center"),
@@ -51,25 +78,48 @@ enum class ALIGN(val className: String) {
     NOWRAP("text-nowrap")
 }
 
+/**
+ * HTML tag component.
+ *
+ * @constructor
+ * @param type tag type
+ * @param text text content of the tag
+ * @param rich determines if [text] can contain HTML code
+ * @param align text align
+ * @param classes a set of CSS class names
+ */
 open class Tag(
     type: TAG, text: String? = null, rich: Boolean = false, align: ALIGN? = null,
     classes: Set<String> = setOf()
 ) : SimplePanel(classes) {
+
+    /**
+     * Tag type.
+     */
     var type = type
         set(value) {
             field = value
             refresh()
         }
+    /**
+     * Text content of the tag.
+     */
     var text = text
         set(value) {
             field = value
             refresh()
         }
+    /**
+     * Determines if [text] can contain HTML code.
+     */
     var rich = rich
         set(value) {
             field = value
             refresh()
         }
+    /**
+     * Text align.
+     */
     var align = align
         set(value) {
             field = value
@@ -79,12 +129,12 @@ open class Tag(
     override fun render(): VNode {
         return if (text != null) {
             if (rich) {
-                kvh(type.tagName, arrayOf(KVManager.virtualize("<span>$text</span>")) + childrenVNodes())
+                render(type.tagName, arrayOf(KVManager.virtualize("<span>$text</span>")) + childrenVNodes())
             } else {
-                kvh(type.tagName, childrenVNodes() + arrayOf(text))
+                render(type.tagName, childrenVNodes() + arrayOf(text))
             }
         } else {
-            kvh(type.tagName, childrenVNodes())
+            render(type.tagName, childrenVNodes())
         }
     }