Refactoring. API documentation.

2 files changed, 173 insertions, 9 deletions

diff --git a/src/main/kotlin/pl/treksoft/kvision/form/time/DateTime.kt b/src/main/kotlin/pl/treksoft/kvision/form/time/DateTime.kt
index 1750c1bd..426e0644 100644
--- a/src/main/kotlin/pl/treksoft/kvision/form/time/DateTime.kt
+++ b/src/main/kotlin/pl/treksoft/kvision/form/time/DateTime.kt
@@ -1,34 +1,76 @@
+/*
+ * 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.form.time
 
+import pl.treksoft.kvision.core.StringBoolPair
 import pl.treksoft.kvision.core.Widget
 import pl.treksoft.kvision.form.DateFormControl
 import pl.treksoft.kvision.form.FieldLabel
 import pl.treksoft.kvision.form.HelpBlock
 import pl.treksoft.kvision.panel.SimplePanel
 import pl.treksoft.kvision.utils.SnOn
-import pl.treksoft.kvision.core.StringBoolPair
 import kotlin.js.Date
 
+/**
+ * Form field date/time chooser component.
+ *
+ * @constructor
+ * @param value date/time input value
+ * @param format date/time format (default YYYY-MM-DD HH:mm)
+ * @param label label text bound to the input element
+ * @param rich determines if [label] can contain HTML code
+ */
 open class DateTime(
     value: Date? = null, format: String = "YYYY-MM-DD HH:mm", label: String? = null,
     rich: Boolean = false
 ) : SimplePanel(setOf("form-group")), DateFormControl {
 
+    /**
+     * Date/time input value.
+     */
     override var value
         get() = input.value
         set(value) {
             input.value = value
         }
+    /**
+     * Date/time format.
+     */
     var format
         get() = input.format
         set(value) {
             input.format = value
         }
+    /**
+     * The placeholder for the date/time input.
+     */
     var placeholder
         get() = input.placeholder
         set(value) {
             input.placeholder = value
         }
+    /**
+     * The name attribute of the generated HTML input element.
+     */
     var name
         get() = input.name
         set(value) {
@@ -39,56 +81,89 @@ open class DateTime(
         set(value) {
             input.disabled = value
         }
+    /**
+     * Determines if the date/time input is automatically focused.
+     */
     var autofocus
         get() = input.autofocus
         set(value) {
             input.autofocus = value
         }
+    /**
+     * Determines if the date/time input is read-only.
+     */
     var readonly
         get() = input.readonly
         set(value) {
             input.readonly = value
         }
+    /**
+     * Day of the week start. 0 (Sunday) to 6 (Saturday).
+     */
     var weekStart
         get() = input.weekStart
         set(value) {
             input.weekStart = value
         }
+    /**
+     * Days of the week that should be disabled. Multiple values should be comma separated.
+     */
     var daysOfWeekDisabled
         get() = input.daysOfWeekDisabled
         set(value) {
             input.daysOfWeekDisabled = value
         }
+    /**
+     * Determines if *Clear* button should be visible.
+     */
     var clearBtn
         get() = input.clearBtn
         set(value) {
             input.clearBtn = value
         }
+    /**
+     * Determines if *Today* button should be visible.
+     */
     var todayBtn
         get() = input.todayBtn
         set(value) {
             input.todayBtn = value
         }
+    /**
+     * Determines if the current day should be highlighted.
+     */
     var todayHighlight
         get() = input.todayHighlight
         set(value) {
             input.todayHighlight = value
         }
+    /**
+     * The increment used to build the hour view.
+     */
     var minuteStep
         get() = input.minuteStep
         set(value) {
             input.minuteStep = value
         }
+    /**
+     * Determines if meridian views are visible in day and hour views.
+     */
     var showMeridian
         get() = input.showMeridian
         set(value) {
             input.showMeridian = value
         }
+    /**
+     * The label text bound to the input element.
+     */
     var label
         get() = flabel.text
         set(value) {
             flabel.text = value
         }
+    /**
+     * Determines if [label] can contain HTML code.
+     */
     var rich
         get() = flabel.rich
         set(value) {
@@ -100,7 +175,7 @@ open class DateTime(
             input.size = value
         }
 
-    protected val idc = "kv_form_time_" + counter
+    private val idc = "kv_form_time_" + counter
     final override val input: DateTimeInput = DateTimeInput(value, format).apply { id = idc }
     final override val flabel: FieldLabel = FieldLabel(idc, label, rich)
     final override val validationInfo: HelpBlock = HelpBlock().apply { visible = false }
@@ -115,7 +190,7 @@ open class DateTime(
     }
 
     companion object {
-        var counter = 0
+        internal var counter = 0
     }
 
     override fun getSnClass(): List<StringBoolPair> {
@@ -142,10 +217,16 @@ open class DateTime(
         return this
     }
 
+    /**
+     * Open date/time chooser popup.
+     */
     open fun showPopup() {
         input.showPopup()
     }
 
+    /**
+     * Hides date/time chooser popup.
+     */
     open fun hidePopup() {
         input.hidePopup()
     }
diff --git a/src/main/kotlin/pl/treksoft/kvision/form/time/DateTimeInput.kt b/src/main/kotlin/pl/treksoft/kvision/form/time/DateTimeInput.kt
index cac9fbda..a49f1d5f 100644
--- a/src/main/kotlin/pl/treksoft/kvision/form/time/DateTimeInput.kt
+++ b/src/main/kotlin/pl/treksoft/kvision/form/time/DateTimeInput.kt
@@ -1,25 +1,53 @@
+/*
+ * 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.form.time
 
 import com.github.snabbdom.VNode
-import pl.treksoft.kvision.core.Widget
-import pl.treksoft.kvision.form.INPUTSIZE
 import pl.treksoft.kvision.core.StringBoolPair
 import pl.treksoft.kvision.core.StringPair
+import pl.treksoft.kvision.core.Widget
+import pl.treksoft.kvision.form.INPUTSIZE
 import pl.treksoft.kvision.utils.obj
 import pl.treksoft.kvision.utils.toDateF
 import pl.treksoft.kvision.utils.toStringF
 import kotlin.js.Date
 
-const val DEFAULT_MINUTE_STEP = 5
-const val MAX_VIEW = 4
+internal const val DEFAULT_MINUTE_STEP = 5
+internal const val MAX_VIEW = 4
 
+/**
+ * Basic date/time chooser component.
+ *
+ * @constructor
+ * @param value date/time input value
+ * @param format date/time format (default YYYY-MM-DD HH:mm)
+ * @param classes a set of CSS class names
+ */
 @Suppress("TooManyFunctions")
 open class DateTimeInput(
     value: Date? = null, format: String = "YYYY-MM-DD HH:mm",
     classes: Set<String> = setOf()
 ) : Widget(classes + "form-control") {
 
-
     init {
         this.setInternalEventListener<DateTimeInput> {
             change = {
@@ -28,76 +56,121 @@ open class DateTimeInput(
         }
     }
 
+    /**
+     * Date/time input value.
+     */
     var value: Date? = value
         set(value) {
             field = value
             refreshState()
         }
+    /**
+     * Date/time format.
+     */
     var format: String = format
         set(value) {
             field = value
             refreshDatePicker()
         }
+    /**
+     * The placeholder for the date/time input.
+     */
     var placeholder: String? = null
         set(value) {
             field = value
             refresh()
         }
+    /**
+     * The name attribute of the generated HTML input element.
+     */
     var name: String? = null
         set(value) {
             field = value
             refresh()
         }
+    /**
+     * Determines if the field is disabled.
+     */
     var disabled: Boolean = false
         set(value) {
             field = value
             refresh()
         }
+    /**
+     * Determines if the text input is automatically focused.
+     */
     var autofocus: Boolean? = null
         set(value) {
             field = value
             refresh()
         }
+    /**
+     * Determines if the date/time input is read-only.
+     */
     var readonly: Boolean? = null
         set(value) {
             field = value
             refresh()
         }
+    /**
+     * The size of the input.
+     */
     var size: INPUTSIZE? = null
         set(value) {
             field = value
             refresh()
         }
+    /**
+     * Day of the week start. 0 (Sunday) to 6 (Saturday).
+     */
     var weekStart: Int = 0
         set(value) {
             field = value
             refreshDatePicker()
         }
+    /**
+     * Days of the week that should be disabled. Multiple values should be comma separated.
+     */
     var daysOfWeekDisabled: Array<Int> = arrayOf()
         set(value) {
             field = value
             refreshDatePicker()
         }
+    /**
+     * Determines if *Clear* button should be visible.
+     */
     var clearBtn: Boolean = true
         set(value) {
             field = value
             refreshDatePicker()
         }
+    /**
+     * Determines if *Today* button should be visible.
+     */
     var todayBtn: Boolean = false
         set(value) {
             field = value
             refreshDatePicker()
         }
+    /**
+     * Determines if the current day should be highlighted.
+     */
     var todayHighlight: Boolean = false
         set(value) {
             field = value
             refreshDatePicker()
         }
+    /**
+     * The increment used to build the hour view.
+     */
     var minuteStep: Int = DEFAULT_MINUTE_STEP
         set(value) {
             field = value
             refreshDatePicker()
         }
+    /**
+     * Determines if meridian views are visible in day and hour views.
+     */
     var showMeridian: Boolean = false
         set(value) {
             field = value
@@ -105,7 +178,7 @@ open class DateTimeInput(
         }
 
     override fun render(): VNode {
-        return kvh("input")
+        return render("input")
     }
 
     override fun getSnClass(): List<StringBoolPair> {
@@ -170,10 +243,16 @@ open class DateTimeInput(
         }
     }
 
+    /**
+     * Open date/time chooser popup.
+     */
     open fun showPopup() {
         getElementJQueryD()?.datetimepicker("show")
     }
 
+    /**
+     * Hides date/time chooser popup.
+     */
     open fun hidePopup() {
         getElementJQueryD()?.datetimepicker("hide")
     }
@@ -216,6 +295,10 @@ open class DateTimeInput(
         })
     }
 
+    /**
+     * Get value of date/time input control as String
+     * @return value as a String
+     */
     fun getValueAsString(): String? {
         return value?.toStringF(format)
     }